Release v0.2.3

Author: janbalangue

CHANGELOG.md

@@ -1,10 +1,10 @@
 # Changelog
 
-All notable, user-visible changes to runtime behavior and public APIs
-are documented in this file.
+All notable, user-visible changes to runtime behavior and public APIs are documented in this file.
 
-Until version `1.0.0`, all releases are **pre-stable** and may introduce
-breaking changes. Any such changes will be explicitly documented.
+This changelog documents only **user-visible changes** to runtime behavior, public APIs, and operational guarantees; internal refactors and implementation details are omitted unless they affect those guarantees.
+
+Until version `1.0.0`, all releases are **pre-stable** and may introduce breaking changes. Any such changes will be explicitly documented.
 
 ---
 
@@ -24,14 +24,24 @@ breaking changes. Any such changes will be explicitly documented.
 
 ## Publication note
 
-Some early 0.1.x versions were affected by cancelled or incomplete Maven Central publication attempts.
-Because Maven Central does not allow reuse of version numbers once a deployment is cancelled or rejected,
+Some early 0.1.x versions were affected by cancelled or incomplete Maven Central publication attempts. Because Maven Central does not allow reuse of version numbers once a deployment is cancelled or rejected,
 those versions should be considered **non-canonical**.
 
 The first fully published and supported release series begins with 0.1.7.
 
 ---
 
+## [0.2.3] - 2026-01-05
+### Documentation
+- Rewrote README.md to align strictly with DESIGN.md semantics.
+- Clarified the core invariant: in-flight means admitted until terminal.
+- Explicitly documented fail-fast, unordered admission and terminal-based capacity release.
+- Added a concise comparison section explaining differences from framework-based and reactive bulkheads.
+- Tightened wording around cancellation, rejection, and capacity lifetime.
+- No runtime, API, or behavioral changes.
+
+---
+
 ## [0.2.2] - 2026-01-05
 
 ### Fixed
@@ -54,12 +64,9 @@ The first fully published and supported release series begins with 0.1.7.
 
 ### Changed
 - Defined **cancellation** of the returned `CompletionStage` as a **terminal outcome** that releases capacity.
-- Defined **permit lifetime** strictly from successful admission until the returned `CompletionStage` reaches a
-  terminal state (success, exceptional completion, or cancellation).
-- Guaranteed **exactly-once permit release** across all races between completion, exceptional completion, and
-  cancellation.
-- Tightened admission semantics: capacity is acquired **only at the moment of submission**; there is no deferred,
-  waiting, or speculative admission.
+- Defined **permit lifetime** strictly from successful admission until the returned `CompletionStage` reaches a terminal state (success, exceptional completion, or cancellation).
+- Guaranteed **exactly-once permit release** across all races between completion, exceptional completion, and cancellation.
+- Tightened admission semantics: capacity is acquired **only at the moment of submission**; there is no deferred, waiting, or speculative admission.
 
 ### Clarified
 - Formalized the core invariant: *in-flight means admitted until terminal*.
@@ -68,8 +75,7 @@ The first fully published and supported release series begins with 0.1.7.
 - Clarified that `BulkheadRejectedException` indicates **capacity exhausted and no work started**.
 
 ### Documentation
-- Significantly expanded and refined **DESIGN.md** to explicitly define semantics, invariants, races, cancellation
-  behavior, and non-goals.
+- Significantly expanded and refined **DESIGN.md** to explicitly define semantics, invariants, races, cancellation behavior, and non-goals.
 - Pruned and refocused **README.md** to serve as a high-level entry point aligned with v0.2 semantics.
 - Added explicit **production guidance and failure modes** documentation.
 
@@ -105,10 +111,8 @@ The first fully published and supported release series begins with 0.1.7.
 - **Yanked / not published** (Maven Central deploy was cancelled; version cannot be reused).
 
 ### Fixed
-- Release workflow: corrected `GPG_PRIVATE_KEY` environment scoping so the key imports correctly in CI and signatures
-  (`.asc`) are produced.
-- Release signing: ensured `.asc` signature artifacts are generated as part of the release build (via the `release`
-  profile).
+- Release workflow: corrected `GPG_PRIVATE_KEY` environment scoping so the key imports correctly in CI and signatures (`.asc`) are produced.
+- Release signing: ensured `.asc` signature artifacts are generated as part of the release build (via the `release` profile).
 
 ### Build
 - Minor CI/release reliability improvements around non-interactive GPG usage.
@@ -132,9 +136,7 @@ The first fully published and supported release series begins with 0.1.7.
 ## [0.1.3] – 2025-12-30
 
 ### Fixed
-- Corrected Maven Central publishing configuration (release deployment no longer depends on
-  `distributionManagement`; 
-  no API or semantic changes).
+- Corrected Maven Central publishing configuration (release deployment no longer depends on `distributionManagement`; no API or semantic changes).
 
 ### Build
 - Added a tag-gated release workflow suitable for CI publishing.

README.md

@@ -2,35 +2,29 @@
 
 ⚠️ **Early-stage, design-first project (pre-1.0)**
 
-This repository provides a small, opinionated **async bulkhead** for Java with
-explicit, test-backed semantics around overload behavior.
+This repository provides a small, opinionated **async bulkhead** for Java with explicit, test-backed semantics around overload behavior.
 
 The goal is to make overload **bounded, visible, and predictable**.
 
 ---
 
 ## Why another bulkhead?
 
-Most Java bulkhead implementations are part of **larger resilience frameworks** and make
-reasonable tradeoffs at that scale, but undesirable ones when you want a **single,
-well-defined primitive**.
+Most Java bulkhead implementations are part of **larger resilience frameworks** and make reasonable tradeoffs at that scale, but undesirable ones when you want a **single, well-defined primitive**.
 
 This project exists because many existing bulkheads:
 - mix **admission control** with execution concerns (thread pools, schedulers)
 - introduce **queues**, **timeouts**, or **retries** that hide overload instead of surfacing it
 - provide unclear semantics around when capacity is consumed and released
 - couple behavior to specific frameworks or reactive abstractions
 
-This bulkhead is intentionally different.
-
 It focuses on **one thing only**:
 - bounding the number of **in-flight async operations**
 - **failing fast** when saturated
 - never starting work it cannot admit
 - making rejection an **explicit, composable signal**
 
 There is no queue.  
-There is no waiting.  
 There is no internal execution model.
 
 ---
@@ -39,7 +33,7 @@ There is no internal execution model.
 
 - Admission is **fail-fast** and **non-blocking**
 - Admission is **unordered** (no FIFO, no fairness guarantees)
-- A operation is considered *in-flight* from successful admission until its
+- An operation is considered *in-flight* from successful admission until its
   returned `CompletionStage` reaches a **terminal state**
   (success, failure, or cancellation)
 - Capacity is released **only** at terminal completion
@@ -68,6 +62,146 @@ Out of scope for v0.x:
 
 ---
 
+## Comparison with other bulkheads
+
+This bulkhead is intentionally **narrower and more explicit** than most existing Java bulkhead implementations.
+
+Its behavior follows a single design invariant defined in **DESIGN.md**:
+
+> In-flight means admitted until terminal.
+
+All other semantics derive from this invariant.
+
+---
+
+### High-level comparison
+
+Dimension              | This bulkhead            | Resilience4j bulkhead | Hystrix (legacy)    | Reactive bulkheads (e.g. Project Reactor)
+-----------------------|--------------------------|-----------------------|---------------------|------------------------------------------
+Primary concern        | Admission control        | Execution isolation   | Execution isolation | Stream backpressure
+Queuing                | None                     | Optional              | Internal            | Implicit
+Waiting for capacity   | Never                    | Sometimes             | Often               | Framework-defined
+Async-first            | Yes                      | Mixed                 | Mostly sync         | Yes
+In-flight definition   | Explicit, terminal-based | Implicit              | Thread-based        | Subscription-based
+Cancellation semantics | Terminal & defined       | Often implicit        | Weak / unclear      | Framework-specific
+Ordering/fairness      | None                     | Limited               | Limited             | Often ordered
+Scope                  | Single primitive         | Resilience suite      | Full framework      | Reactive pipelines
+
+---
+
+### Core design differences
+
+#### Admission control, not execution control
+
+Most bulkheads control **how work executes**:
+* thread pools
+* schedulers
+* executor queues
+
+This bulkhead controls **whether work may start**.
+
+It does **not**:
+* execute tasks
+* manage threads
+* delay, buffer, or retry submissions
+
+Admission is atomic and has exactly two outcomes:
+* **admitted** (permit acquired, supplier invoked)
+* **rejected** (no permit, supplier not invoked)
+
+There is no intermediate state.
+
+---
+
+#### Fail fast, never wait
+
+This bulkhead **never waits for capacity**.
+
+If capacity is unavailable at submission time:
+* the operation is rejected immediately
+* no work is started
+* rejection is surfaced synchronously as a failed `CompletionStage`
+
+There is:
+* no queue
+* no reservation
+* no deferred admission
+
+This is a deliberate design choice to make overload **explicit and visible**.
+
+---
+
+#### Explicit in-flight semantics
+
+This bulkhead defines *in-flight* precisely:
+> An operation is **in-flight** from successful admission until the returned `CompletionStage` reaches a **terminal state**.
+
+Terminal states are strictly defined as:
+* successful completion
+* exceptional completion
+* cancellation
+
+Capacity is released **only** when one of these states is observed.
+
+This definition is documented, test-backed, and invariant under concurrency races.
+
+---
+
+#### Cancellation is a first-class terminal outcome
+
+If the returned `CompletionStage` is cancelled:
+* capacity is released exactly once
+* no retries or restarts occur
+* admission semantics remain unchanged
+
+The bulkhead does **not** propagate cancellation downstream; it only observes it to maintain correct admission accounting.
+
+---
+
+#### Unordered, opportunistic admission
+
+Admission is **not ordered**.
+
+The bulkhead does not guarantee:
+* FIFO behavior
+* fairness
+* eventual admission after rejection
+
+Concurrent submissions race for available capacity.
+Rejection under contention is expected and correct behavior.
+
+---
+
+#### Small by design, composable by intent
+
+This library is **not** a resilience framework.
+
+It intentionally excludes:
+* queues or blocking admission
+* retries or fallbacks
+* circuit breakers
+* adaptive or auto-tuned limits
+* reactive framework integrations
+
+Those concerns are meant to be composed *around* this primitive.
+
+---
+
+### When this bulkhead fits
+* You want **explicit, bounded admission control**
+* You need to reason clearly about **what is actually in-flight**
+* You want overload to be **visible, not hidden**
+* You already own execution, retries, and timeouts
+
+
+### When it does not
+* You need queuing or load smoothing
+* You want framework-managed execution
+* You require fairness or ordering
+* You want a full resilience toolkit
+
+---
+
 ## Design & production guidance
 
 This README intentionally stays high level.

bulkhead-core/pom.xml

@@ -10,7 +10,7 @@
     <parent>
         <groupId>io.github.janbalangue</groupId>
         <artifactId>async-bulkhead</artifactId>
-        <version>0.2.2</version>
+        <version>0.2.3</version>
     </parent>
 
 

pom.xml

@@ -9,7 +9,7 @@
 
     <groupId>io.github.janbalangue</groupId>
     <artifactId>async-bulkhead</artifactId>
-    <version>0.2.2</version>
+    <version>0.2.3</version>
     <packaging>pom</packaging>
 
     <name>Async Bulkhead</name>