feat(core): verify_registry() release-startup collision check + opt-in ctor (#133)

Store::open refuses linked EventKind collisions (FailFast), but a RELEASE binary
that registers colliding payloads and never opens a Store got no check (the derive's
collision check is cfg(test)-only). The derive's inventory registration is already
unconditional, so no derive change is needed — only a scan-invocation path.

Two paths (owner: A4 + optional ctor):
- verify_registry() — a documented public alias over validate_event_payload_registry()
  (re-exported at event::payload / event / prelude). Call it once at startup if your
  binary registers EventPayload types but may not open a Store. Portable, no dep.
- `startup-registry-check` (NON-default) cargo feature -> optional `ctor` dep + one
  central #[ctor] fn that scans at load and, on a collision, writes a diagnostic via
  stderr().write_all (not eprintln — print_stderr is banned) then process::abort().
  Native automatic life-before-main; the default build pulls NO ctor (cargo tree
  confirmed).

Red fixtures (crates/core/fixtures/registry-startup-{collision,ctor}/ + driver
event_payload_registry_startup.rs, --release subprocess, mirroring the downstream
fixture precedent): collide_verify -> exit 1 + "duplicate kind assignment" stderr;
collide_ctor (--features) -> SIGABRT before main; clean_verify (control) -> exit 0.

Baseline +3 (verify_registry at the 3 paths); syncbat/netbat byte-identical. Both
builds green: fmt, clippy x2, build x2 (no ctor by default), structural ok. ctor
clears cargo-deny (MIT/Apache).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NHio8XCrH89gdEcycCumr6

Author: heyoub

bpk-lib/Cargo.lock

@@ -38,6 +38,15 @@ dangerous-test-hooks = ["dep:fastrand", "batpak-testkit/dangerous-test-hooks"]
 # OOM-handling paths deterministically. Neither alters production behavior.
 alloc-count = []
 fault-alloc = []
+# Opt-in automation for the register-but-never-open collision check (item #133).
+# When enabled, ONE process-wide `#[ctor::ctor]` constructor runs
+# `verify_registry()` before `main` and aborts on a linked `EventKind`
+# collision, so a release binary that registers colliding `EventPayload` types
+# and never opens a `Store` still fails fast. NOT a default feature: the
+# always-on, portable path is the explicit `verify_registry()` call, which needs
+# no constructor and no extra dependency. `dep:ctor` keeps `ctor` out of a
+# default build entirely.
+startup-registry-check = ["dep:ctor"]
 # Gauntlet Phase 0B sentinel RED fixtures are gated behind the
 # `--cfg gauntlet_red_fixture` compile flag, NOT a Cargo feature. A red fixture
 # is designed to FAIL (it asserts the illegal/old behavior), so it must never be
@@ -76,6 +85,10 @@ tempfile = ">=3.24, <3.25"
 libc = "0.2"
 ed25519-compact = { version = "2.2.0", default-features = false, features = ["std"] }
 zeroize = "1"
+# Optional: only pulled in by the non-default `startup-registry-check` feature,
+# which installs a before-`main` constructor that runs the payload-registry
+# collision check (item #133). MIT OR Apache-2.0, clears deny.toml.
+ctor = { version = "0.2", optional = true }
 # NO TOKIO. Invariant 1.
 
 [dev-dependencies]

bpk-lib/crates/core/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "batpak-registry-startup-collision"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+# Nested workspace: keeps this fixture out of the parent batpak workspace so its
+# deliberately-colliding registrations never leak into the crate's own build.
+[workspace]
+
+# `collide_verify`: a NON-test binary that registers two colliding EventPayload
+# kinds and calls `verify_registry()` in `main` (the always-on A4 path).
+[[bin]]
+name = "collide_verify"
+path = "src/collide_verify.rs"
+
+# `clean_verify`: identical shape with NON-colliding registrations. Exits 0,
+# proving the collide_verify exit-1 is caused by the collision (confirms RED).
+[[bin]]
+name = "clean_verify"
+path = "src/clean_verify.rs"
+
+[dependencies]
+batpak = { path = "../.." }

bpk-lib/crates/core/fixtures/registry-startup-collision/Cargo.toml

@@ -0,0 +1,44 @@
+//! GREEN control for the item #133 RED fixture.
+//!
+//! Same shape as `collide_verify`, but the two registrations use DISTINCT
+//! `(category, type_id)` pairs, so `verify_registry()` returns `Ok` and `main`
+//! exits 0. The driver asserts this exit-0 to prove the sibling `collide_verify`
+//! exit-1 is caused by the seeded collision and not by the harness or a broken
+//! entry point (this is how RED is confirmed).
+
+use std::io::Write;
+use std::process::ExitCode;
+
+const CATEGORY: u8 = 0xE;
+const KIND_A: u16 = ((CATEGORY as u16) << 12) | 0x331;
+const KIND_B: u16 = ((CATEGORY as u16) << 12) | 0x332;
+
+batpak::__private::inventory::submit! {
+    batpak::__private::EventPayloadRegistration {
+        kind_bits: KIND_A,
+        payload_version: 1,
+        type_name: "registry_startup_clean::FirstDistinct",
+    }
+}
+
+batpak::__private::inventory::submit! {
+    batpak::__private::EventPayloadRegistration {
+        kind_bits: KIND_B,
+        payload_version: 1,
+        type_name: "registry_startup_clean::SecondDistinct",
+    }
+}
+
+fn main() -> ExitCode {
+    match batpak::event::verify_registry() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(error) => {
+            // Never expected: a clean registry must verify cleanly.
+            let message = format!("registry-startup-clean UNEXPECTED collision: {error}\n");
+            let mut stderr = std::io::stderr();
+            let _ = stderr.write_all(message.as_bytes());
+            let _ = stderr.flush();
+            ExitCode::from(2)
+        }
+    }
+}

bpk-lib/crates/core/fixtures/registry-startup-collision/src/clean_verify.rs

@@ -0,0 +1,52 @@
+//! RED fixture for item #133 (A4, always-on path).
+//!
+//! A non-test binary that registers TWO `EventPayload` kinds claiming the same
+//! `(category, type_id)` and NEVER opens a `Store`. Because this is a `[[bin]]`
+//! target, `cfg(test)` is false, so the `#[derive(EventPayload)]` per-type
+//! collision test (which is `#[cfg(test)]`-only) is absent here exactly as it is
+//! in a release binary. `main` calls the portable `verify_registry()` entry
+//! point and fails the process on the collision, proving a release binary can
+//! catch a linked-kind collision it otherwise would not see.
+//!
+//! The colliding registrations are emitted directly via `inventory::submit!`
+//! (rather than `#[derive(EventPayload)]`) so this binary carries a real
+//! link-time collision without also pulling in the derive's generated
+//! `#[cfg(test)]` collision test.
+
+use std::io::Write;
+use std::process::ExitCode;
+
+const COLLIDING_CATEGORY: u8 = 0xE;
+const COLLIDING_TYPE_ID: u16 = 0x321;
+const COLLIDING_KIND_BITS: u16 = ((COLLIDING_CATEGORY as u16) << 12) | COLLIDING_TYPE_ID;
+
+batpak::__private::inventory::submit! {
+    batpak::__private::EventPayloadRegistration {
+        kind_bits: COLLIDING_KIND_BITS,
+        payload_version: 1,
+        type_name: "registry_startup_collision::FirstColliding",
+    }
+}
+
+batpak::__private::inventory::submit! {
+    batpak::__private::EventPayloadRegistration {
+        kind_bits: COLLIDING_KIND_BITS,
+        payload_version: 1,
+        type_name: "registry_startup_collision::SecondColliding",
+    }
+}
+
+// `std::process::exit` is a repo-banned method (LAW-001: it skips Drop). Returning
+// `ExitCode` propagates a non-zero status cleanly instead.
+fn main() -> ExitCode {
+    match batpak::event::verify_registry() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(error) => {
+            let message = format!("registry-startup-collision: {error}\n");
+            let mut stderr = std::io::stderr();
+            let _ = stderr.write_all(message.as_bytes());
+            let _ = stderr.flush();
+            ExitCode::from(1)
+        }
+    }
+}

bpk-lib/crates/core/fixtures/registry-startup-collision/src/collide_verify.rs

@@ -0,0 +1,20 @@
+[package]
+name = "batpak-registry-startup-ctor"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+# Nested workspace: isolates the `startup-registry-check` feature (and its ctor)
+# to this fixture only, so the crate's own test binaries never link the ctor.
+[workspace]
+
+# `collide_ctor`: TWO colliding registrations + an effectively-empty `main`.
+# Built with batpak's `startup-registry-check` feature, so the library's
+# before-`main` constructor detects the collision and aborts. If `main` is
+# reached (constructor failed to fire) it prints a sentinel and exits 0.
+[[bin]]
+name = "collide_ctor"
+path = "src/collide_ctor.rs"
+
+[dependencies]
+batpak = { path = "../..", features = ["startup-registry-check"] }

bpk-lib/crates/core/fixtures/registry-startup-ctor/Cargo.toml

@@ -0,0 +1,44 @@
+//! RED fixture for item #133 (opt-in `startup-registry-check` / ctor path).
+//!
+//! Registers TWO colliding `EventPayload` kinds and has an effectively-empty
+//! `main`. This crate depends on batpak with `features = ["startup-registry-check"]`,
+//! so the library installs one process-wide `#[ctor::ctor]` constructor that runs
+//! `verify_registry()` BEFORE `main`, writes a diagnostic to stderr, and aborts
+//! on the collision.
+//!
+//! Because `main` would exit 0 if it were ever reached, a non-zero / aborting
+//! exit PROVES the constructor fired before `main`. If the constructor failed to
+//! run, `main` prints the `REACHED_MAIN_WITHOUT_ABORT` sentinel so the driver can
+//! distinguish that failure from a correct abort.
+
+use std::io::Write;
+use std::process::ExitCode;
+
+const COLLIDING_CATEGORY: u8 = 0xE;
+const COLLIDING_TYPE_ID: u16 = 0x654;
+const COLLIDING_KIND_BITS: u16 = ((COLLIDING_CATEGORY as u16) << 12) | COLLIDING_TYPE_ID;
+
+batpak::__private::inventory::submit! {
+    batpak::__private::EventPayloadRegistration {
+        kind_bits: COLLIDING_KIND_BITS,
+        payload_version: 1,
+        type_name: "registry_startup_ctor::FirstColliding",
+    }
+}
+
+batpak::__private::inventory::submit! {
+    batpak::__private::EventPayloadRegistration {
+        kind_bits: COLLIDING_KIND_BITS,
+        payload_version: 1,
+        type_name: "registry_startup_ctor::SecondColliding",
+    }
+}
+
+fn main() -> ExitCode {
+    // Reaching this line means the startup constructor did NOT fire, which is the
+    // bug this fixture guards against. Emit a sentinel so the driver sees it.
+    let mut stdout = std::io::stdout();
+    let _ = stdout.write_all(b"REACHED_MAIN_WITHOUT_ABORT\n");
+    let _ = stdout.flush();
+    ExitCode::SUCCESS
+}

bpk-lib/crates/core/fixtures/registry-startup-ctor/src/collide_ctor.rs

@@ -18,8 +18,8 @@ pub use hash::HashChain;
 pub use header::EventHeader;
 pub use kind::{EventKind, EventKindError};
 pub use payload::{
-    revalidate_event_payload_registry, validate_event_payload_registry, EventPayload,
-    EventPayloadKindCollision, EventPayloadRegistryError, EventPayloadValidation,
+    revalidate_event_payload_registry, validate_event_payload_registry, verify_registry,
+    EventPayload, EventPayloadKindCollision, EventPayloadRegistryError, EventPayloadValidation,
 };
 pub use sourcing::{
     EventSourced, JsonValueInput, MultiDispatchError, MultiReactive, ProjectionEvent,

bpk-lib/crates/core/src/event/mod.rs

@@ -66,6 +66,11 @@ pub trait EventPayload: Serialize + DeserializeOwned {
 /// signing-policy and receipt-hashing idiom: the safe behavior is the default
 /// and the looser behavior is an explicit escape hatch.
 ///
+/// This policy only runs at `Store::open`. A binary that registers colliding
+/// payloads but **never opens a store** is not covered here; call
+/// [`verify_registry`] once at startup (or enable the non-default
+/// `startup-registry-check` feature) to catch that case in a release build.
+///
 /// Set via
 /// [`StoreConfig::with_event_payload_validation`](crate::store::StoreConfig::with_event_payload_validation).
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
@@ -175,6 +180,60 @@ pub fn validate_event_payload_registry() -> Result<(), EventPayloadRegistryError
     }
 }
 
+/// Release-startup entry point: verify the linked `EventPayload` registry has no
+/// duplicate-kind collisions.
+///
+/// Call this once at process startup **if your binary registers `EventPayload`
+/// types (directly or through a dependency crate) but may never open a
+/// [`Store`](crate::store::Store)**. `Store::open` already runs this same check
+/// under the default [`EventPayloadValidation::FailFast`] policy, so a binary
+/// that opens a store is covered. A binary that registers colliding payloads and
+/// never opens a store would otherwise get **no** collision check in a release
+/// build: the `#[derive(EventPayload)]` macro's own collision test is
+/// `#[cfg(test)]`-only and is absent from a non-test binary. This entry point
+/// closes that gap and catches the linked-kind collision a release build would
+/// not see.
+///
+/// For automatic enforcement without a manual call, enable the non-default
+/// `startup-registry-check` feature: it installs one process-wide startup
+/// constructor that runs this check and aborts on a collision before `main`.
+///
+/// This is a thin, clearly-named alias for
+/// [`validate_event_payload_registry`]; the two are interchangeable.
+///
+/// # Errors
+/// Returns [`EventPayloadRegistryError`] if two or more linked payload types
+/// register the same `(category, type_id)` pair.
+pub fn verify_registry() -> Result<(), EventPayloadRegistryError> {
+    validate_event_payload_registry()
+}
+
+/// Process-wide startup constructor installed by the non-default
+/// `startup-registry-check` feature.
+///
+/// Runs before `main`, so a release binary that registers colliding
+/// `EventPayload` kinds and never opens a `Store` still fails fast: it writes a
+/// diagnostic to `stderr` and aborts the process. One central constructor covers
+/// the whole binary (the derive emits no per-type startup hook), so this is
+/// idempotent by construction. The diagnostic is written with `write_all` on
+/// `std::io::stderr()` rather than `eprintln!` to honor the crate's
+/// no-`print_stderr` discipline, and the write result is deliberately ignored:
+/// if `stderr` itself is unwritable the process must still abort so the collision
+/// can never be silently accepted at startup.
+#[cfg(feature = "startup-registry-check")]
+#[ctor::ctor]
+fn __batpak_verify_registry_at_startup() {
+    use std::io::Write;
+
+    if let Err(error) = verify_registry() {
+        let message = format!("batpak startup-registry-check: aborting before main: {error}\n");
+        let mut stderr = std::io::stderr();
+        let _ = stderr.write_all(message.as_bytes());
+        let _ = stderr.flush();
+        std::process::abort();
+    }
+}
+
 /// Re-scan the linked payload registry and refresh the cached open-time result.
 ///
 /// Most applications never need this because registrations are static once the

bpk-lib/crates/core/src/event/payload.rs

@@ -69,7 +69,12 @@
 //! [`EventPayloadValidation`](crate::event::EventPayloadValidation) defaults to
 //! `FailFast`, so a duplicate-kind collision or an incomplete upcast chain is
 //! rejected at [`Store::open`](crate::store::Store::open) (opt out explicitly
-//! with `Warn`/`Silent`). Receipt signing is governed by
+//! with `Warn`/`Silent`). A binary that registers `EventPayload` types but may
+//! never open a store should call
+//! [`verify_registry`](crate::event::verify_registry) once at startup (or enable
+//! the non-default `startup-registry-check` feature for automatic enforcement),
+//! since the derive's own collision test is `#[cfg(test)]`-only and a release
+//! binary would otherwise see no check. Receipt signing is governed by
 //! [`SigningPolicy`](crate::store::SigningPolicy): the default `Optional`
 //! permits a keyless store, while `Required` refuses to open without a signing
 //! key so an unsigned receipt is never accepted. A configured signer fails the