fix: Address final-review feedback for after-response hooks

Author: thced

README.md

@@ -368,7 +368,7 @@ Map<String, RequestHandler> handlers = Map.of(
 ```
 
 Global hooks run first (registration order), then per-request runnables (FIFO). Pre-request
-failures (404, 405, validation) do not fire hooks.
+failures (404, 405, validation) do not fire hooks. On the error path (when a handler throws), `Response#body()` is `null` and the bytes have already been streamed; use `Response#status()` to detect errors.
 
 ### End-to-end example
 

src/main/java/com/retailsvc/http/Request.java

@@ -270,7 +270,11 @@ public void afterResponse(Runnable runnable) {
     afterHooks.add(runnable);
   }
 
-  /** Internal accessor for the after-hook queue; used by RequestPreparationFilter. */
+  /**
+   * Returns an unmodifiable view of the queued after-response runnables. Intended for the framework
+   * runner; consumers should use {@link #afterResponse(Runnable)} to register runnables rather than
+   * inspecting this list directly.
+   */
   public List<Runnable> afterHooks() {
     return Collections.unmodifiableList(afterHooks);
   }

src/test/java/com/retailsvc/http/AfterResponseHookIT.java

@@ -205,8 +205,6 @@ void preRequestFailureSkipsHooks() throws Exception {
                   BodyHandlers.discarding());
 
       assertThat(resp.statusCode()).isEqualTo(HTTP_NOT_FOUND);
-      // Give the server-side thread a moment to complete any potential async work
-      Thread.sleep(100);
       assertThat(log).isEmpty();
     }
   }
@@ -246,4 +244,33 @@ void hookSeesScopedRequestAndSameThreadAsHandler() throws Exception {
       assertThat(hookThread.get()).isSameAs(handlerThread.get());
     }
   }
+
+  @Test
+  void hookFiresWhenHandlerIsMissing() throws Exception {
+    CountDownLatch latch = new CountDownLatch(1);
+    AtomicReference<Response> capturedResponse = new AtomicReference<>();
+
+    try (OpenApiServer server =
+        baseBuilder()
+            .handlers(Map.of()) // no handler registered for OK_OPERATION_ID
+            .afterResponseHook(
+                (req, resp) -> {
+                  capturedResponse.set(resp);
+                  latch.countDown();
+                })
+            .build()) {
+
+      HttpResponse<Void> resp =
+          HttpClient.newHttpClient()
+              .send(
+                  HttpRequest.newBuilder(uri(server, OK_PATH)).GET().build(),
+                  BodyHandlers.discarding());
+
+      assertThat(latch.await(5, TimeUnit.SECONDS)).isTrue();
+      assertThat(resp.statusCode()).isEqualTo(HTTP_INTERNAL_ERROR);
+      assertThat(capturedResponse.get()).isNotNull();
+      assertThat(capturedResponse.get().status()).isEqualTo(HTTP_INTERNAL_ERROR);
+      assertThat(capturedResponse.get().body()).isNull();
+    }
+  }
 }