bmad-method-quarkus 1.0.1 → 1.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-quarkus",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "BMAD Method with Quarkus support",
   "keywords": [
     "agile",

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-error-handling-i18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quarkus-error-handling-i18n
-description: Unified (single) global exception handler and internationalized (i18n) API responses for Quarkus backend services, aligned to TM Forum error schema (TMF630). Use this skill whenever the user mentions exception handling, error responses, ExceptionMapper, error codes, Problem Details, localization, i18n, translations, Accept-Language, message bundles, or when creating/reviewing ANY REST endpoint that can fail — errors and locale handling must always go through this standard, never ad-hoc try/catch in resources. Also defines exception class naming and the English-identifiers/localized-messages rule.
+description: Unified (single) global exception handler and internationalized (i18n) API responses for Quarkus backend services, aligned to TM Forum error schema (TMF630). Use this skill whenever the user mentions exception handling, error responses, ExceptionMapper, error codes, Problem Details, localization, i18n, translations, Accept-Language, message bundles, or when creating/reviewing ANY REST endpoint that can fail — errors and locale handling must always go through this standard, never ad-hoc try/catch in resources. Also defines the single BusinessException type (code + args, never a pre-rendered message), the ErrorCatalog/MessageResolver machinery in common/, and the English-identifiers/localized-messages rule.
 ---
 
 # Unified Exception Handler + i18n Responses (Quarkus, TMF-aligned)
@@ -24,33 +24,42 @@ All error responses use `application/json` with the TMF Error structure (interop
 }
 ```
 
-- `code`: stable, machine-readable, defined in the **domain exception**, format `<MOD>-<HTTP>-<seq>` where `<MOD>` is a short module/domain code (the BC code in DDD projects). Never reworded, never localized.
+- `code`: stable, machine-readable, carried by the thrown `BusinessException`, format `<MOD>-<HTTP>-<seq>` where `<MOD>` is a short uppercase code derived from the semantic module name or its main entity (`IAM`, `USR`, `PTY` — never a `bcNN` inventory code; see quarkus-hexagonal-core skill). It is also the **bundle key**. Never reworded, never localized.
 - `message`: human-readable, **localized** via bundles.
 - `referenceError`: link to error catalog docs.
 - Add `traceId` propagation via response header `X-Trace-Id` (see observability skill), not in the body.
 
-## Exception hierarchy (domain layer, framework-free)
+## One business exception (`common/exception`)
+
+The vertical-slice standard uses a **single** business exception carrying a stable code plus interpolation arguments — not a subclass per error. The subclass hierarchy bought nothing that the code does not already express, and cost one file per error:
 
 ```java
-// domain/exception
-public abstract class DomainException extends RuntimeException {
+// common/exception
+public class BusinessException extends RuntimeException {
     private final String code;          // "USR-404-001"
-    private final Object[] messageArgs; // interpolated into localized message
-    protected DomainException(String code, Object... args) {
-        super(code);
+    private final Object[] messageArgs; // interpolated into the localized message
+    public BusinessException(String code, Object... args) {
+        super(code);                    // super message = the code; the human text is resolved at the edge
         this.code = code;
         this.messageArgs = args;
     }
+    public BusinessException(String code, Throwable cause, Object... args) { ... }
     public String code() { return code; }
     public Object[] messageArgs() { return messageArgs; }
 }
+```
 
-public final class UserNotFoundException extends DomainException {
-    public UserNotFoundException(UserId id) { super("USR-404-001", id.value()); }
-}
+Thrown from the slice `Handler` and nowhere else:
+
+```java
+throw new BusinessException("USR-404-001", userId);
 ```
 
-HTTP status is NOT known by the domain. The mapping code→status lives in the handler via a registry (an enum or properties-driven map in infrastructure).
+**The thrower never formats or translates the message.** A `Handler` that injects a `ResourceBundle` and passes a rendered string silently pins every response to one language, defeating `Accept-Language`. Resolution happens once, at the edge, in `GlobalExceptionHandler` / `GrpcExceptionInterceptor`.
+
+HTTP status is not known by the `Handler` either. The mapping code→status lives in `ErrorCatalog` (`common/error`).
+
+One sibling, not a subclass: `StaleVersionException` (optimistic-lock conflict) is the only other code-carrying exception. It is NOT a `BusinessException` subtype and NOT part of the `PersistenceException` family — a version conflict is a client-actionable 409, not an infrastructure failure hidden behind a 500. It is thrown by the `Handler` when a versioned `UPDATE` returns 0 rows (never by `SqlStateTranslator` — there is no `SQLException` involved) and mapped by its own dedicated mapper below.
 
 ### Naming
 
@@ -58,21 +67,24 @@ Canonical rules in the quarkus-hexagonal-core skill; the error/i18n specifics:
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Domain exception | `<Thing><Problem>Exception`, in `domain/exception` | `UserNotFoundException`, `DuplicateEmailException` |
-| Base class | `DomainException` | |
-| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `StaleVersionException` | |
-| Single REST handler | `GlobalExceptionHandler` (the only sanctioned `*Handler`) | |
-| gRPC counterpart | `GrpcExceptionInterceptor` | |
+| Business exception | `BusinessException` — one class, in `common/exception` | thrown with `("USR-404-001", id)` |
+| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `PersistenceTimeoutException`, in `common/exception` | |
+| Concurrency-conflict exception | `StaleVersionException` — standalone, code-carrying (`code + args`, like `BusinessException`), in `common/exception` | thrown with `("PTY-409-001", id)` |
+| SQLState translator | `SqlStateTranslator`, in `common/error` | |
+| Single REST handler | `GlobalExceptionHandler`, in `common/error` | |
+| gRPC counterpart | `GrpcExceptionInterceptor`, in `common/error` | |
 | i18n components | `MessageResolver`, `ErrorCatalog` | |
-| Error DTO | `ErrorDto` | |
+| Error DTO | `ErrorDto` (TMF630 Error shape) | |
 | Bundle files | `messages/errors[_<lang>].properties` | `errors_en.properties` |
 | Bundle key | the error code itself, never a prose key | `USR-404-001` |
 
-Never name an exception after the HTTP status (`NotFoundException`, `BadRequestException`) — the domain does not know about HTTP, and the status is resolved by `ErrorCatalog`. Never shadow a JDK type (`ConcurrentModificationException` → `StaleVersionException`).
+`GlobalExceptionHandler` is no longer "the only sanctioned `*Handler`" — under the slice standard `*Handler` is the business-logic class of every slice (`CreatePartyIndividualHandler`). What stays true is that there is exactly **one** global exception handler per transport, both in `common/error`, and that no `Resource`, `GrpcService` or `Consumer` builds an error response itself.
 
-**Language rule:** class, method and field names are English; the *messages* are localized per bundle, with **English as the default locale** and other languages (es, pt, ...) added per project need. `UserNotFoundException` with a Spanish translation `El usuario {0} no existe.` in `errors_es.properties` is correct — `UsuarioNoEncontradoException` is not.
+Never name an exception after the HTTP status (`NotFoundException`, `BadRequestException`) — the status is resolved by `ErrorCatalog`. Never shadow a JDK type (`ConcurrentModificationException` → `StaleVersionException`).
 
-## The single global handler (infrastructure/rest)
+**Language rule:** class, method and field names are English; the *messages* are localized per bundle, with **English as the default locale** and other languages (es, pt, ...) added per project need. A slice named `create_party_individual` throwing `PTY-400-001`, translated as `El campo ''{0}'' es obligatorio.` in `errors_es.properties`, is correct — a class or key named `crear_persona.campo_obligatorio` is not.
+
+## The single global handler (`common/error`)
 
 Exactly ONE class. Use `@ServerExceptionMapper` (Quarkus REST) — build-time wired, native-friendly:
 
@@ -89,13 +101,27 @@ public class GlobalExceptionHandler {
     }
 
     @ServerExceptionMapper
-    public RestResponse<ErrorDto> map(DomainException e, HttpHeaders headers) {
+    public RestResponse<ErrorDto> map(BusinessException e, HttpHeaders headers) {
         var status = catalog.statusOf(e.code());               // e.g. 404
         var msg = messages.resolve(e.code(), headers, e.messageArgs());
         return RestResponse.status(status,
             ErrorDto.of(e.code(), status, msg));
     }
 
+    @ServerExceptionMapper
+    public RestResponse<ErrorDto> map(StaleVersionException e, HttpHeaders headers) {
+        // optimistic-lock conflict: 409 per catalog, client-visible and localized like a business error
+        var status = catalog.statusOf(e.code());               // 409
+        var msg = messages.resolve(e.code(), headers, e.messageArgs());
+        return RestResponse.status(status, ErrorDto.of(e.code(), status, msg));
+    }
+
+    @ServerExceptionMapper
+    public RestResponse<ErrorDto> map(PersistenceException e, HttpHeaders headers) {
+        // technical failures: 500/503 per catalog, stack trace to logs only
+        ...
+    }
+
     @ServerExceptionMapper
     public RestResponse<ErrorDto> map(ConstraintViolationException e, HttpHeaders headers) {
         // 400, code "GEN-400-001", join violations into localized detail
@@ -114,7 +140,7 @@ public class GlobalExceptionHandler {
 Rules:
 - Catch-all `Exception` mapper is mandatory: internal details/stack traces NEVER reach the client. Log with full context (trace_id lands in the log automatically via MDC).
 - Validation errors (Bean Validation) map to 400 with one generic code + per-field details array.
-- Resources and use cases must NOT catch-and-format errors themselves — throw domain exceptions and let the handler translate.
+- `Resource`, `GrpcService`, `Consumer` and `Handler` classes must NOT catch-and-format errors themselves — throw `BusinessException` with a code and let the handler translate. A `try { ... } catch (BusinessException e) { return Response.status(400)... }` inside a `Resource` is the anti-pattern this skill exists to prevent: it bypasses the catalog, the locale and the trace header.
 - `ErrorDto` is `@RegisterForReflection` (native).
 
 ## i18n resolution from Accept-Language
@@ -135,17 +161,23 @@ quarkus.default-locale=en
 ```properties
 # errors.properties (en, default)
 USR-404-001=User {0} does not exist.
+PTY-400-001=The ''{0}'' field is required.
 GEN-400-001=The request contains invalid data.
 GEN-500-001=Internal error. Contact support with the trace identifier.
 ```
 
+Bundles are **per application, keyed by error code** — not per slice, not keyed by prose. A slice contributes rows to the same files, which is what keeps "every code exists in every locale" a single testable invariant. (`''` escapes a literal apostrophe for `MessageFormat`.)
+
 ```properties
 # errors_es.properties
 USR-404-001=El usuario {0} no existe.
+PTY-400-001=El campo ''{0}'' es obligatorio.
 GEN-400-001=La solicitud contiene datos inválidos.
 GEN-500-001=Error interno. Contacte a soporte con el identificador de traza.
 ```
 
+Quality bar per language — Spanish: formal or infinitive, precise, no vague `Error de validación`. English: direct declarative, no vague `something went wrong`. Same key order in every file so diffs stay readable.
+
 For native: `quarkus.native.resources.includes=messages/*.properties`.
 
 ### Resolver
@@ -175,7 +207,9 @@ Success-path localizable strings (notification texts, report labels) use the sam
 
 ## Checklist when adding a new error
 
-1. Create domain exception extending `DomainException`, named `<Thing><Problem>Exception`, with new code `<MOD>-<HTTP>-<seq>`.
-2. Register code → status/reason in `ErrorCatalog`.
-3. Add the message key to ALL locale bundles (build fails a test if a code is missing in any bundle — write that test once: iterate catalog codes × locales).
-4. Document in the error catalog page referenced by `referenceError`.
+1. Pick the next code `<MOD>-<HTTP>-<seq>` — no new exception class.
+2. Throw `new BusinessException(code, args...)` from the slice `Handler` (`validate()` or `execution()`), with the interpolation args and no rendered text.
+3. Register code → status/reason in `ErrorCatalog`.
+4. Add the message key to ALL locale bundles (a test fails the build if a code is missing in any bundle — write it once: iterate catalog codes × locales).
+5. Document in the error catalog page referenced by `referenceError`, and add the row to the slice `README.md` "Business errors" table.
+6. Assert the code (not the message) in the `HandlerTest`; assert the localized body in the `Resource` `@QuarkusTest`.

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-grpc-services/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quarkus-grpc-services
-description: Standard for internal microservice-to-microservice communication using gRPC in Quarkus native services — proto conventions, Mutiny services, clients, deadlines, error mapping to domain exceptions, health checks, and native-image setup. Use this skill whenever the user mentions gRPC, protobuf, .proto files, internal service calls, synchronous inter-service communication, service clients, or "call service X from service Y" — internal synchronous calls are ALWAYS gRPC, never internal REST. Includes proto and gRPC adapter/client/mapper naming conventions.
+description: Standard for internal microservice-to-microservice communication using gRPC in Quarkus native services — proto conventions, Mutiny services, clients, deadlines, error mapping to BusinessException codes, health checks, and native-image setup. Use this skill whenever the user mentions gRPC, protobuf, .proto files, internal service calls, synchronous inter-service communication, service clients, or "call service X from service Y" — internal synchronous calls are ALWAYS gRPC, never internal REST. Includes proto and gRPC adapter/client naming conventions for the vertical-slice layout (the GrpcService lives in the slice folder and delegates to the slice Handler; outbound stubs are wrapped by capability-named beans in common/client).
 ---
 
 # gRPC Standard for Inter-Service Communication (Quarkus)
@@ -11,12 +11,12 @@ Extension: `quarkus-grpc` (fully native-compatible; code generation is build-tim
 
 ## Proto conventions
 
-Location: `src/main/proto/`. One package per service/module + major version (the module segment is the BC code in DDD projects, the service name otherwise):
+Location: `src/main/proto/<module>/v<major>/`, one file per capability group, published to the monorepo `contracts/` folder. One proto package per service/module + major version (the module segment is the module's semantic name — `iam`, `customer` — see quarkus-hexagonal-core skill, or the service name):
 
 ```protobuf
 syntax = "proto3";
-package alva.bc05.v1;
-option java_package = "com.alva.bc05.grpc.v1";
+package alva.iam.v1;
+option java_package = "com.alva.iam.grpc.v1";
 option java_multiple_files = true;
 
 service UserService {
@@ -36,27 +36,32 @@ Rules:
 - Proto files are contracts: keep them in a shared `contracts/` module (or a dedicated repo) consumed by both sides; do NOT copy-paste protos between services.
 - Streaming RPCs only with a justified use case (bulk export, watch); default is unary.
 
-## Server (inbound adapter, `infrastructure/grpc`)
+## Server (inbound adapter, in the slice folder)
 
 ```java
 @GrpcService
 public class UserGrpcService implements UserService {   // Mutiny-generated interface
 
-    private final GetUserUseCase getUser;   // inbound port from application layer
-
-    public UserGrpcService(GetUserUseCase getUser) { this.getUser = getUser; }
+    @Inject FindUserHandler findUser;      // the slice's Handler, blocking
 
     @Override
     public Uni<GetUserResponse> getUser(GetUserRequest req) {
-        return Uni.createFrom().item(() -> getUser.byId(new UserId(UUID.fromString(req.getUserId()))))
-            .runSubscriptionOn(Infrastructure.getDefaultWorkerPool())  // JDBC below → worker thread
-            .map(UserGrpcMapper::toResponse);
+        return Uni.createFrom().item(() -> {
+                var request = FindUserRequestDto.builder().userId(req.getUserId()).build();
+                var result = findUser.process(request);           // blocking JDBC
+                return GetUserResponse.newBuilder()
+                    .setUser(User.newBuilder().setId(result.getId()).setEmail(result.getEmail()))
+                    .build();
+            })
+            .runSubscriptionOn(Infrastructure.getDefaultWorkerPool());  // JDBC → worker thread
     }
 }
 ```
 
-- gRPC service = thin adapter: map proto ↔ command/result, delegate to the use case. No business logic.
-- Blocking work (JDBC) either `@Blocking` on the method or explicit worker pool as above.
+- gRPC service = thin adapter: convert proto ↔ DTO, delegate to the slice `Handler`. No business logic, no JDBC, no `Connection`.
+- **Proto ↔ DTO conversion happens inline, inside the `item(() -> ...)` lambda.** There is no `*GrpcMapper` class — `*Mapper` is a banned suffix (see quarkus-hexagonal-core skill).
+- This class and the integration beans in `common/client` are the **only** two places Mutiny is allowed; the ArchUnit rule `reactiveIsQuarantined` enforces it. Never let `Uni`/`Multi` reach a `Handler` or `Sql`.
+- Blocking work (JDBC) either `@Blocking` on the method or the explicit worker pool as above.
 
 ### Naming
 
@@ -68,60 +73,73 @@ Canonical rules in the quarkus-hexagonal-core skill; gRPC specifics:
 | Proto RPC | `<Verb><Entity>` | `GetUser`, `ValidateCredentials` |
 | Proto messages | `<Rpc>Request` / `<Rpc>Response`, one pair per RPC | `GetUserRequest` |
 | Proto fields | `snake_case` | `user_id` |
-| Server adapter | `<ProtoService>GrpcService` | `UserGrpcService` |
-| Client adapter | `Grpc<Port>` — port name from `application/port/out` | `GrpcCredentialsValidator` |
-| Proto ↔ domain mapper | `<Entity>GrpcMapper` | `UserGrpcMapper` |
-| Global error interceptor | `GrpcExceptionInterceptor` | |
-| Client config key | `<module>-<entity>` kebab-case, matching `@GrpcClient` | `bc05-users` |
+| Server adapter | `<ProtoService>GrpcService`, in the slice folder | `UserGrpcService` |
+| Outbound integration bean | capability noun, **no technology**, in `common/client` | `CredentialsValidator` |
+| Global error interceptor | `GrpcExceptionInterceptor`, in `common/error` | |
+| Client config key | `<module>-<entity>` kebab-case, matching `@GrpcClient` | `iam-users` |
+
+`*GrpcService` is the **only** class allowed to end in `Service` under the slice standard — it mirrors the proto service name, which is not ours to rename (ArchUnit rule `serviceSuffixIsReserved`). There is no `Grpc<Port>` client adapter and no `*GrpcMapper`: the outbound bean is named after the capability it provides, and only its internals reveal that gRPC is the transport.
 
-`*GrpcService` is the one place outside `application/usecase` where the `*Service` suffix is allowed — it mirrors the proto service name, which is not ours to rename. The client adapter is never called `UserServiceClient`: it implements a domain-named port, and only the `Grpc` prefix reveals the transport.
-- Separate gRPC server port (default `9000`) or unified with HTTP via `quarkus.grpc.server.use-separate-server=false` — pick one per platform and keep it consistent.
+Separate gRPC server port (default `9000`) or unified with HTTP via `quarkus.grpc.server.use-separate-server=false` — pick one per platform and keep it consistent.
 
-## Error mapping (domain exception → gRPC status)
+## Error mapping (`BusinessException` → gRPC status)
 
-One `ExceptionHandlerProvider`-style mapping, symmetric to the REST unified handler:
+One `ExceptionHandlerProvider`-style mapping, symmetric to the REST unified handler. The status is derived from the code's entry in `ErrorCatalog`, not from the exception class:
 
-| Domain situation | gRPC status |
+| Situation (per `ErrorCatalog`) | gRPC status |
 |---|---|
 | Not found | `NOT_FOUND` |
 | Validation / bad argument | `INVALID_ARGUMENT` |
 | Business rule conflict | `FAILED_PRECONDITION` |
-| Duplicate / concurrency | `ALREADY_EXISTS` / `ABORTED` |
+| Duplicate | `ALREADY_EXISTS` |
+| Stale version / concurrency (`StaleVersionException`) | `ABORTED` |
 | Auth | `UNAUTHENTICATED` / `PERMISSION_DENIED` |
 | Anything unexpected | `INTERNAL` (no details leaked) |
 
-Attach the stable error code in trailers metadata key `error-code` so callers can map back to their own domain exceptions. Implement once as a global gRPC exception interceptor (`GrpcExceptionInterceptor`, the counterpart of `GlobalExceptionHandler` — see quarkus-error-handling-i18n skill); individual services never build `StatusRuntimeException` by hand.
+Attach the stable error code in trailers metadata key `error-code` so callers can map it back through their own `ErrorCatalog`. Implement once as a global gRPC exception interceptor (`GrpcExceptionInterceptor` in `common/error`, the counterpart of `GlobalExceptionHandler` — see quarkus-error-handling-i18n skill); it resolves the localized message the same way, from the request's locale metadata. Individual services never build `StatusRuntimeException` by hand, and no `GrpcService` catches `BusinessException`.
 
-## Client (outbound adapter)
+## Client (outbound integration bean, `common/client`)
 
-Define an outbound port in `application/port/out` (e.g., `CredentialsValidator`); the gRPC client is its adapter:
+A slice `Handler` must never hold a `@GrpcClient` stub: the generated stub returns `Uni`, which would drag Mutiny into the business logic and break the `reactiveIsQuarantined` rule. Wrap it in a capability-named bean that `await()`s internally and exposes plain types:
 
 ```java
+// common/client — named for what it provides, not for how
 @ApplicationScoped
-public class GrpcCredentialsValidator implements CredentialsValidator {
+public class CredentialsValidator {
 
-    @GrpcClient("bc05-users") UserService client;   // Mutiny stub
+    @GrpcClient("iam-users") UserService client;   // Mutiny stub, contained here
 
-    @Override
-    public boolean validate(Credentials c) {
-        return client.validateCredentials(toRequest(c))
+    public boolean validate(String username, String password) {
+        return client.validateCredentials(
+                ValidateCredentialsRequest.newBuilder()
+                    .setUsername(username).setPassword(password).build())
             .map(ValidateCredentialsResponse::getValid)
-            .await().atMost(Duration.ofSeconds(2));
+            .await().atMost(Duration.ofSeconds(2));   // deadline also set in config
     }
 }
 ```
 
+The `Handler` then injects it like any other collaborator:
+
+```java
+@Inject CredentialsValidator credentials;   // returns boolean, knows nothing about gRPC
+```
+
+The bean always lives in `common/client`, even when only one slice calls it today — that is the package the `reactiveIsQuarantined` ArchUnit rule exempts (see quarkus-hexagonal-core skill), and it saves relocating the bean the day a second slice needs it. It is mocked in `HandlerTest` exactly like the `Sql` class.
+
+An interface is warranted only under the core skill's "when to add an interface back" rule — a second real implementation, a cross-module boundary, or a `common/` consumer that must not see the slice.
+
 ```properties
-quarkus.grpc.clients.bc05-users.host=bc05-users.internal
-quarkus.grpc.clients.bc05-users.port=9000
-quarkus.grpc.clients.bc05-users.deadline=2s
+quarkus.grpc.clients.iam-users.host=iam-users.internal
+quarkus.grpc.clients.iam-users.port=9000
+quarkus.grpc.clients.iam-users.deadline=2s
 ```
 
 Rules:
 - **Deadline on every client** (config `deadline` or per-call). No unbounded internal calls, ever — cascading hangs kill native pods just as well.
 - Retries only for idempotent RPCs and only `UNAVAILABLE`/`DEADLINE_EXCEEDED`, with budget — prefer platform/mesh retry policy over hand-rolled loops.
 - TLS/mTLS per platform standard (`quarkus.grpc.clients.*.ssl.*` / mesh-provided).
-- Translate `StatusRuntimeException` back into the caller's domain exceptions at the adapter — gRPC types never cross into application/domain.
+- Translate `StatusRuntimeException` into a `BusinessException` carrying the caller's own error code, inside the integration bean — gRPC types (and `Uni`) never reach a `Handler`. Read the upstream code from the `error-code` trailer and map it through the caller's `ErrorCatalog`.
 
 ## Health & reflection
 
@@ -134,8 +152,9 @@ Tracing is automatic when `quarkus-opentelemetry` is present — `traceparent` p
 
 ## Checklist for a new RPC
 
-1. Proto in shared contracts module, package `vN`, dedicated Request/Response.
-2. Server adapter delegating to a use case; blocking handled explicitly.
-3. Client behind an outbound port, deadline configured.
-4. Error mapping covered by the global interceptor (add new code if needed).
+1. Proto in `src/main/proto/<module>/v<major>/`, published to `contracts/`, dedicated Request/Response pair.
+2. `<ProtoService>GrpcService` in the slice folder delegating to the slice `Handler`; proto ↔ DTO conversion inline; blocking handled by `runSubscriptionOn` or `@Blocking`.
+3. Outbound calls wrapped in a capability-named bean in `common/client` that `await()`s and returns plain types; deadline configured.
+4. Error mapping covered by the global interceptor (register any new code in `ErrorCatalog` + all locale bundles).
 5. Contract check in CI (buf breaking-change detection or equivalent).
+6. No `Uni` outside the `GrpcService` and the integration bean — `reactiveIsQuarantined` proves it.