refactor: Drive OpenApiServer from a list of SpecBinding

The constructor now takes List<SpecBinding> instead of Spec; the Builder
synthesises a single-element list so the public API is unchanged.
HandlerConfig drops the handlers and securityValidators fields (moved to
SpecBinding). The not-found catch-all context is registered only when no
binding has a root base path.

Author: thced

docs/superpowers/plans/2026-05-22-multiple-specs.md

@@ -111,7 +111,7 @@ git commit -m "refactor: Add SpecBinding record for per-spec server state"
 
 The goal here is purely structural: the constructor stops taking a `Spec` and instead takes `List<SpecBinding>`. The Builder still produces a list of size 1. No public API change yet.
 
-- [ ] **Step 1: Update `OpenApiServer` constructor signature and body**
+- [x] **Step 1: Update `OpenApiServer` constructor signature and body**
 
 Replace the constructor (currently lines 73–157) with a version that loops over bindings:
 
@@ -207,7 +207,7 @@ OpenApiServer(
 }
 ```
 
-- [ ] **Step 2: Drop the now-unused `handlers` field from `HandlerConfig`**
+- [x] **Step 2: Drop the now-unused `handlers` field from `HandlerConfig`**
 
 In `OpenApiServer.java`, change the `HandlerConfig` record to remove `handlers` (it's per-binding now):
 
@@ -223,7 +223,7 @@ record HandlerConfig(
 
 Also drop the per-binding `securityValidators` from `HandlerConfig` (they live on each `SpecBinding` now). Update every callsite of `HandlerConfig` accordingly.
 
-- [ ] **Step 3: Update `Builder.build()` to construct one binding and pass `List.of(binding)`**
+- [x] **Step 3: Update `Builder.build()` to construct one binding and pass `List.of(binding)`**
 
 In `Builder.build()` (currently lines 364–402), replace the construction of `HandlerConfig` and the call to `new OpenApiServer(...)` with:
 
@@ -268,17 +268,17 @@ public OpenApiServer build() throws IOException {
 }
 ```
 
-- [ ] **Step 4: Run the full unit test suite**
+- [x] **Step 4: Run the full unit test suite**
 
 Run: `mvn -q test`
 Expected: BUILD SUCCESS. All 440 existing tests pass with no edits. (If anything fails, it's a refactoring mistake — fix before moving on.)
 
-- [ ] **Step 5: Run the integration test suite**
+- [x] **Step 5: Run the integration test suite**
 
 Run: `mvn -q verify -DskipITs=false`
 Expected: BUILD SUCCESS.
 
-- [ ] **Step 6: Commit**
+- [x] **Step 6: Commit**
 
 ```bash
 git add src/main/java/com/retailsvc/http/OpenApiServer.java

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

@@ -11,16 +11,15 @@
 import com.retailsvc.http.internal.PemSslContext;
 import com.retailsvc.http.internal.RequestPreparationFilter;
 import com.retailsvc.http.internal.ResponseRenderer;
-import com.retailsvc.http.internal.Router;
 import com.retailsvc.http.internal.SecurityFilter;
+import com.retailsvc.http.internal.SpecBinding;
 import com.retailsvc.http.internal.TextTypeMapper;
 import com.retailsvc.http.internal.TlsHttpsConfigurator;
 import com.retailsvc.http.internal.gson.GsonJsonMapper;
 import com.retailsvc.http.spec.Operation;
 import com.retailsvc.http.spec.Spec;
 import com.retailsvc.http.spec.security.SecurityRequirement;
 import com.retailsvc.http.spec.security.SecurityScheme;
-import com.retailsvc.http.validate.DefaultValidator;
 import com.sun.net.httpserver.HttpContext;
 import com.sun.net.httpserver.HttpServer;
 import com.sun.net.httpserver.HttpsServer;
@@ -60,17 +59,15 @@ public class OpenApiServer implements AutoCloseable {
 
   /** Internal grouping of handler-related configuration to keep the constructor signature small. */
   record HandlerConfig(
-      Map<String, RequestHandler> handlers,
       List<RequestInterceptor> interceptors,
       List<ResponseDecorator> decorators,
       ExceptionHandler exceptionHandler,
       Map<String, RequestHandler> extras,
-      Map<String, SchemeValidator> securityValidators,
       boolean externalAuth,
       List<AfterResponseHook> afterHooks) {}
 
   OpenApiServer(
-      Spec spec,
+      java.util.List<SpecBinding> bindings,
       Map<String, TypeMapper> bodyMappers,
       HandlerConfig handlerConfig,
       int port,
@@ -79,17 +76,14 @@ record HandlerConfig(
       SSLContext sslContext)
       throws IOException {
 
-    requireNonNull(spec, "Spec must not be null");
+    requireNonNull(bindings, "bindings must not be null");
+    if (bindings.isEmpty()) {
+      throw new IllegalStateException("at least one spec binding is required");
+    }
     requireNonNull(bodyMappers, "bodyMappers must not be null");
-    requireNonNull(handlerConfig.handlers(), "handlers must not be null");
     ExceptionHandler exceptionHandler = handlerConfig.exceptionHandler();
 
     long t0 = System.currentTimeMillis();
-    Router router = new Router(spec.operations());
-    Map<String, Operation> operationsById =
-        spec.operations().stream()
-            .collect(Collectors.toUnmodifiableMap(Operation::operationId, op -> op));
-    DefaultValidator validator = new DefaultValidator(spec::resolveSchema);
 
     InetSocketAddress socketAddress =
         (bindAddress == null)
@@ -106,39 +100,47 @@ record HandlerConfig(
 
     ResponseRenderer renderer = new ResponseRenderer(bodyMappers);
 
-    String basePath = Optional.ofNullable(spec.basePath()).orElse("/");
-    HttpContext ctx = httpServer.createContext(basePath);
-    ctx.getFilters()
-        .add(
-            new RequestPreparationFilter(
-                spec,
-                router,
-                validator,
-                bodyMappers,
-                exceptionHandler,
-                renderer,
-                handlerConfig.afterHooks()));
-    ctx.getFilters()
-        .add(
-            new SecurityFilter(
-                operationsById,
-                spec.securitySchemes(),
-                spec.security(),
-                handlerConfig.securityValidators(),
-                handlerConfig.externalAuth()));
-    ctx.setHandler(
-        new DispatchHandler(
-            handlerConfig.handlers(),
-            handlerConfig.interceptors(),
-            handlerConfig.decorators(),
-            renderer));
-
-    if (!"/".equals(basePath)) {
+    boolean anyBindingAtRoot = false;
+    for (SpecBinding binding : bindings) {
+      String basePath = Optional.ofNullable(binding.spec().basePath()).orElse("/");
+      anyBindingAtRoot |= "/".equals(basePath);
+      Map<String, Operation> operationsById =
+          binding.spec().operations().stream()
+              .collect(Collectors.toUnmodifiableMap(Operation::operationId, op -> op));
+      HttpContext ctx = httpServer.createContext(basePath);
+      ctx.getFilters()
+          .add(
+              new RequestPreparationFilter(
+                  binding.spec(),
+                  binding.router(),
+                  binding.validator(),
+                  bodyMappers,
+                  exceptionHandler,
+                  renderer,
+                  handlerConfig.afterHooks()));
+      ctx.getFilters()
+          .add(
+              new SecurityFilter(
+                  operationsById,
+                  binding.spec().securitySchemes(),
+                  binding.spec().security(),
+                  binding.securityValidators(),
+                  handlerConfig.externalAuth()));
+      ctx.setHandler(
+          new DispatchHandler(
+              binding.handlers(),
+              handlerConfig.interceptors(),
+              handlerConfig.decorators(),
+              renderer));
+    }
+
+    if (!anyBindingAtRoot) {
       ExtrasRouter extrasRouter = new ExtrasRouter(handlerConfig.extras(), renderer);
       HttpContext extrasCtx = httpServer.createContext("/", extrasRouter);
       extrasCtx.getFilters().add(new ExceptionFilter(exceptionHandler, renderer));
     } else if (!handlerConfig.extras().isEmpty()) {
-      throw new IllegalStateException("extras cannot be registered when basePath is '/'");
+      throw new IllegalStateException(
+          "extras cannot be registered when a binding owns basePath '/'");
     }
     httpServer.start();
 
@@ -377,19 +379,18 @@ public OpenApiServer build() throws IOException {
           exceptionHandler != null ? exceptionHandler : Handlers.defaultExceptionHandler();
       HandlerConfig handlerConfig =
           new HandlerConfig(
-              handlers,
               interceptors,
               decorators,
               effectiveExceptionHandler,
               extras,
-              Map.copyOf(securityValidators),
               externalAuth,
               List.copyOf(afterHooks));
+      SpecBinding binding = SpecBinding.of(spec, handlers, securityValidators);
       int resolvedPort = resolvePort();
       SSLContext sslContext =
           httpsCertChain != null ? PemSslContext.load(httpsCertChain, httpsPrivateKey) : null;
       return new OpenApiServer(
-          spec,
+          java.util.List.of(binding),
           resolved,
           handlerConfig,
           resolvedPort,