release: 0.3.0

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -15,7 +15,15 @@ body:
         This includes Miri runs in *your* project — a test that drives the ring
         from two threads will report UB pointing into this crate. See the
         `seq_ring` module docs for why, and for the alternatives. `EventBuf`
-        has no such caveat.
+        and `LatestBuf` have no such caveat — both pass Miri with the race
+        detector on.
+
+        Finally, the **counter-width span boundaries** are documented
+        limitations, not bugs: `SeqRing` loss accounting, `LatestBuf::skipped`,
+        and `BlockBuilder` contiguity are each exact below one `2^32 − 1`
+        span and alias beyond it — see "Known issues" in the changelog and the
+        module docs for the reachability arithmetic. A case that misbehaves
+        *within* a documented bound is very much a bug; please file it.
 
   - type: textarea
     id: what-happened
@@ -40,7 +48,7 @@ body:
     id: version
     attributes:
       label: ph-eventing version
-      placeholder: "0.1.3"
+      placeholder: "0.3.0"
     validations:
       required: true
 

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -11,9 +11,13 @@ body:
         Constraints any proposal has to live within:
 
         - `#![no_std]`, zero heap allocation, and **zero runtime dependencies**.
-        - Fixed-size, `T: Copy`, stack-allocated.
-        - The buffers are SPSC by design. Multi-producer or multi-consumer is a
-          different data structure, not a flag on this one.
+        - Fixed-size and zero-allocation; payload-carrying types are `T: Copy`.
+        - The concurrent primitives are SPSC by design. Multi-producer or
+          multi-consumer is a different data structure, not a flag on one of
+          these.
+        - Every guarantee ships with measured evidence: expect a proposal to be
+          asked for its cost story (code size, cycles) across targets, not
+          just its API.
 
   - type: textarea
     id: problem
@@ -36,7 +40,12 @@ body:
       label: Alternatives considered
       description: >
         Including whether an existing type already covers it — `RingBuf`,
-        `SeqRing`, and `EventBuf` deliberately trade off differently.
+        `SeqRing`, `EventBuf`, `LatestBuf`, `EventFlags`, `CountedSignal`, and
+        the `Block`/`BlockBuilder` composition deliberately trade off
+        differently. If this is a zero-copy / direct-to-slot request, note
+        that a `SlotPool` design was evaluated in full and deferred with an
+        adopter-gated reopening trigger (`docs/proposals/slot-pool.md`) — a
+        real adopter naming that trigger reopens it.
 
   - type: checkboxes
     id: constraints

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,13 +14,22 @@ assuming a green check covers them.
 - [ ] `./scripts/ci.sh` — all checks pass, **no `SKIP` lines**
       (a skipped check is not a passed check; install the tool and re-run)
 
-If this touches atomics, orderings, fences, `unsafe`, or anything in
-`seq_ring.rs` / `event_buf.rs` / `sync.rs`:
+If this touches atomics, orderings, fences, `unsafe`, or anything in the
+concurrent modules (`seq_ring.rs`, `event_buf.rs`, `latest_buf.rs`,
+`event_flags.rs`, `counted_signal.rs`, `sync.rs`):
 
 - [ ] `./scripts/miri.sh` — clean
-- [ ] `./scripts/loom.sh` — all models verified
+- [ ] `./scripts/loom.sh` — all models verified (run via the script: it sets
+      the preemption bound the gate uses)
 - [ ] Ordering changes are justified in a comment, not just in this PR
 
+If this changes an API shape or a hot path:
+
+- [ ] `./scripts/codesize.sh` (plus the relevant matrix mode) — numbers pasted
+      or baseline deliberately re-blessed with the reasoning stated
+- [ ] `./scripts/cycles.sh` for hot-path changes — compared inside the
+      reference image when measuring against documented numbers
+
 If this touches `Cargo.toml`:
 
 - [ ] `cargo deny check` passes

CONTRIBUTING.md

@@ -87,8 +87,9 @@ decision, not a formality.
 
 ### Concurrency changes
 
-If you touch atomics, orderings, fences, or unsafe blocks in `SeqRing` or
-`EventBuf`, `cargo test` passing is not evidence — a strongly-ordered x86 host
+If you touch atomics, orderings, fences, or unsafe blocks in any concurrent
+primitive — `SeqRing`, `EventBuf`, `LatestBuf`, `EventFlags`, or
+`CountedSignal` — `cargo test` passing is not evidence — a strongly-ordered x86 host
 cannot exhibit the bugs that appear on ARM and RISC-V. Run both checkers:
 
 ```bash
@@ -129,10 +130,17 @@ If you change an API shape that embedded callers reach for -- especially
 anything touching atomics -- measure it before arguing about it:
 
 ```bash
-./scripts/codesize.sh              # 8 upstream targets
-XTENSA=1 ./scripts/codesize.sh     # plus ESP32, needs the esp-rs fork
+./scripts/codesize.sh                     # 8 upstream targets, default API rows
+./scripts/codesize.sh block-matrix        # Block completion/publication shapes
+./scripts/codesize.sh latest-matrix       # LatestBuf payload matrix
+./scripts/codesize.sh latest-block-matrix # LatestBuf/Block composition matrix
+XTENSA=1 ./scripts/codesize.sh            # plus ESP32, needs the esp-rs fork
 ```
 
+Each mode gates against its own committed `baseline*.tsv` and `ci.sh` runs all
+of them — growth past the tolerance fails, and a re-bless is a deliberate,
+reviewed act, never a side effect.
+
 A design that looks cheaper on Cortex-M4 can be markedly worse on Cortex-M0+,
 where portable-atomic turns each read-modify-write into an interrupt-disable
 critical section, or on RISC-V, where `compare_exchange` lowers to an LR/SC
@@ -146,17 +154,21 @@ that `rust-toolchain.toml` already declares.
 If you change a hot path, measure the time cost as well as the size cost:
 
 ```bash
-./scripts/cycles.sh
+./scripts/cycles.sh                      # default hot-path regions
+./scripts/cycles.sh block-matrix         # and the three matrix modes,
+./scripts/cycles.sh latest-matrix        # same names as codesize.sh
+./scripts/cycles.sh latest-block-matrix
 ```
 
 Needs `qemu-system-arm` (`sudo apt-get install qemu-system-arm`); it skips
 cleanly without it. It is deliberately **not** part of `./scripts/ci.sh` —
 every other check is satisfied by the pinned toolchain alone, and a check most
 contributors cannot run would make a green `ci.sh` mean less rather than more.
 
-The counts are deterministic per QEMU build, not across builds (two of the
-eighteen regions were observed to shift by one instruction between builds), so
-when comparing against the documented numbers, run inside the reference
+The counts are deterministic per QEMU build, not across builds (regions have
+been observed to shift by one instruction between builds), and the merged
+binary's layout matters too — the documented numbers are measured on the
+assembled release tree. When comparing against them, run inside the reference
 environment below.
 
 Paste the numbers into your PR, as with `codesize.sh`.
@@ -168,7 +180,8 @@ matrix with zero SKIPs — are measured in one pinned Docker image, so that
 anyone can reproduce the evidence rather than take the README's word for it:
 
 ```bash
-./scripts/verify.sh            # ci + miri + loom + cycles, all inside the image
+./scripts/verify.sh            # ci + miri + loom + all four cycle modes +
+                               # the EventFlags atomic-window gate, in the image
 ./scripts/verify.sh cycles     # just one of them
 ./scripts/verify.sh shell      # look around
 ```

Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "ph-eventing"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.92.0"
 # no-std and zero-allocation are the entry fee, not the value -- plenty of
 # crates clear that bar. Lead with what is actually on offer: predictable
 # behaviour and a cost you can measure. See AGENTS.md § What this crate
 # optimises for.
-description = "Deterministic zero-allocation ring buffers for no-std embedded targets: bounded behaviour, no hidden cost, Loom-verified orderings"
+description = "Deterministic zero-allocation SPSC primitives for no-std embedded targets — ring buffers, a latest-value snapshot channel, condition flags, saturating counters, and complete sample blocks: bounded behaviour, measured cost, Loom-verified orderings"
 authors = ["Steven Giacomelli <steve@giacomelli.ca>"]
 license = "MIT"
 repository = "https://github.com/photon-circus/ph-eventing"
@@ -35,7 +35,9 @@ include = [
     "build.rs",
     "Cargo.toml",
     "LICENSE",
-    "README.md",
+    # Root-anchored: a bare `README.md` is gitignore-style and matches every
+    # README.md in the tree (e.g. docs/records/README.md), which must not ship.
+    "/README.md",
 ]
 
 [dependencies]
@@ -54,6 +56,11 @@ portable-atomic = { version = "1.13", optional = true, default-features = false,
 # crate. Test combinations individually — `scripts/ci.sh` does.
 [features]
 default = []
+# Internal, underscore-prefixed, and not part of the public contract: lets the
+# QEMU cycle probe (scripts/cycles) construct a saturated CountedSignal so the
+# sentinel arm of `increment` is a measured region rather than a source-review
+# claim. Enables one #[doc(hidden)] constructor; nothing else.
+_cycles-probe = []
 portable-atomic = ["dep:portable-atomic"]
 portable-atomic-unsafe-assume-single-core = [
     "portable-atomic",