bmad-method-quarkus 1.0.4 → 1.0.6

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-temporal-workflows/SKILL.md

@@ -0,0 +1,616 @@
+---
+name: quarkus-temporal-workflows
+description: Standard for durable orchestration and distributed sagas in Quarkus native services using the Temporal Java SDK — plain `io.temporal:temporal-sdk` (1.27.0+) with NO Quarkiverse extension, manual CDI bootstrap (`@Produces WorkflowClient` + `@Observes StartupEvent` starting the `WorkerFactory`), the `io.temporal.workflow.Saga` compensation pattern, Java records as `@RegisterForReflection` payloads, the GraalVM Netty/gRPC native fix, and `TestWorkflowEnvironment` in-memory testing. Workflows are invoked predominantly over gRPC — inbound through a `*GrpcService` that starts the workflow without waiting, outbound from activities through `common/client` beans — so it also covers the deadline-vs-activity-timeout ordering and the stacked-retry trap. Use this skill whenever the user mentions Temporal, temporal-sdk, workflow orchestration, durable execution, saga, compensation, compensating transaction, activity/activities, WorkflowClient, WorkerFactory, task queue, workflow id, signal/query, `@WorkflowInterface`/`@ActivityInterface`, TestWorkflowEnvironment, long-running or multi-step business processes spanning several slices or services, or "roll back what already committed in another service". Covers BOTH topologies and says which to pick — a standalone **worker-only project** (the default — an independent deployable named with the `-worker` suffix, with no REST layer, no vertical slices and no datasource, where the REST/OpenAPI/slice/SQL standards do not apply) and an embedded worker inside a normal slice app. Use it as well whenever the user asks about a Temporal-only project, an orchestrator service, a worker deployable, or whether a workflow project needs REST endpoints or slices. Applies ONLY to projects that use Temporal; it never applies to a single-slice operation that one `Handler` and one database transaction already cover.
+---
+
+# Temporal Durable Orchestration Standard (Quarkus)
+
+Applies to any Quarkus backend project **that uses Temporal**; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults where they conflict.
+
+Temporal is for the work a single `@Transactional Handler.process()` cannot make atomic: a business process that spans several slices, several services, or a span of time (minutes to months), where a failure halfway through must **undo** what already committed elsewhere. A JTA transaction already gives you all-or-nothing inside one database — reach for Temporal only when the operation crosses that boundary. Wrapping a one-slice insert in a workflow buys nothing and costs a worker, a task queue and a replay contract.
+
+**Two topologies, and §3 is the first decision you make.** The default is a **worker-only project**: an independent deployable that hosts workflows and activities and has no REST layer, no slices and no database — the shape to reach for when the process spans services. The alternative is an **embedded worker** inside a normal slice-architecture app. §3 gives the layout for each and, for worker-only projects, states which house standards go quiet: no `Resource`, no `<Slice>Handler`/`<Slice>Sql`, no OpenAPI, usually no datasource.
+
+**Scope inside a slice architecture (embedded only):** Temporal is quarantined to `orchestration/` and `common/temporal`, the same way Mutiny is quarantined to `*GrpcService` and `common/client` (see quarkus-hexagonal-core skill). No `io.temporal.*` type ever appears in a slice folder, a `Handler`, a `Sql` class or a slice DTO. A slice stays fully testable and deployable with Temporal absent from the classpath.
+
+## 1. Dependencies — plain SDK, no Quarkiverse extension
+
+```xml
+<properties>
+  <temporal.version>1.27.0</temporal.version>
+</properties>
+
+<dependencies>
+  <dependency>
+    <groupId>io.temporal</groupId>
+    <artifactId>temporal-sdk</artifactId>
+    <version>${temporal.version}</version>
+  </dependency>
+  <dependency>
+    <groupId>io.temporal</groupId>
+    <artifactId>temporal-opentracing</artifactId>      <!-- trace propagation — see §10 -->
+    <version>${temporal.version}</version>
+  </dependency>
+  <dependency>
+    <groupId>io.temporal</groupId>
+    <artifactId>temporal-testing</artifactId>
+    <version>${temporal.version}</version>
+    <scope>test</scope>
+  </dependency>
+</dependencies>
+```
+
+- **`io.temporal:temporal-sdk` 1.27.0 or newer.** Pin an explicit version — the Quarkus BOM does not manage Temporal, so nothing else will.
+- **Do not use a Quarkiverse Temporal extension.** The SDK is wired by hand (§2). The trade is explicit and worth naming: no extension means no build-time wiring, so the CDI bootstrap and the native-image flags (§8) are *yours* to maintain — and in exchange the SDK version moves independently of the Quarkus platform release, which is what a durable-execution dependency needs.
+- `temporal-testing` is `test` scope only. It must never reach the runtime classpath.
+- The code you write follows the patterns in Temporal's official Java samples — interface + implementation pair, activity stubs built inside the workflow, `Saga` for compensation. Do not invent a house abstraction over the SDK; a wrapper around `Workflow.newActivityStub` hides the options that make a workflow correct.
+
+## 2. Bootstrap: one CDI bean owns the client and the worker
+
+There is no extension to start the worker, so exactly one `@ApplicationScoped` bean in `common/temporal` produces the `WorkflowClient` and starts the `WorkerFactory` on `StartupEvent`.
+
+```java
+// common/temporal
+@ApplicationScoped
+public class TemporalBootstrap {
+
+    @Inject TemporalConfig config;
+
+    private WorkerFactory factory;
+
+    @Produces
+    @ApplicationScoped
+    public WorkflowServiceStubs serviceStubs() {
+        return WorkflowServiceStubs.newServiceStubs(
+            WorkflowServiceStubsOptions.newBuilder()
+                .setTarget(config.target())
+                .build());
+    }
+
+    @Produces
+    @ApplicationScoped
+    public WorkflowClient workflowClient(WorkflowServiceStubs stubs) {
+        return WorkflowClient.newInstance(stubs,
+            WorkflowClientOptions.newBuilder()
+                .setNamespace(config.namespace())
+                .build());
+    }
+
+    void onStart(@Observes StartupEvent event,
+                 WorkflowClient client,
+                 PartyOnboardingActivitiesImpl activities) {
+        factory = WorkerFactory.newInstance(client);
+        Worker worker = factory.newWorker(config.taskQueue());
+        worker.registerWorkflowImplementationTypes(PartyOnboardingWorkflowImpl.class);  // by CLASS
+        worker.registerActivitiesImplementations(activities);                           // by INSTANCE
+        factory.start();
+    }
+
+    void onStop(@Observes ShutdownEvent event, WorkflowServiceStubs stubs) {
+        if (factory != null) {
+            factory.shutdown();                                     // stop polling
+            factory.awaitTermination(20, TimeUnit.SECONDS);         // drain in-flight tasks
+        }
+        stubs.shutdown();
+    }
+}
+```
+
+The two registration calls are **not** symmetrical, and the asymmetry is the rule that trips people:
+
+| Registration | Form | Why |
+|---|---|---|
+| Workflows | `registerWorkflowImplementationTypes(XImpl.class)` — a **class** | Temporal instantiates a fresh workflow object per execution and replays it. **CDI cannot inject into a workflow implementation**; a field injected once would not survive replay. Its only dependencies are activity stubs it builds itself (§4). |
+| Activities | `registerActivitiesImplementations(bean)` — an **instance** | Activities are ordinary side-effecting beans. Pass the CDI-managed instance so `@Inject`ed `Handler`s are wired normally. |
+
+Rules:
+- **One bootstrap bean per app.** A second one registering a second worker on the same task queue is a duplicate-poller bug, not scaling — scale with replicas.
+- `onStop` matters: `factory.shutdown()` + `awaitTermination` lets in-flight activity tasks finish instead of being abandoned to a timeout-and-retry cycle. Budget it inside the pod's grace period alongside the telemetry flush (see quarkus-observability-otel skill, "The shutdown budget").
+- Connection settings come from `@ConfigMapping` (`<Area>Config`, per the hexagonal-core naming table), never from literals:
+
+```java
+@ConfigMapping(prefix = "temporal")
+public interface TemporalConfig {
+    String target();
+    String namespace();
+    String taskQueue();
+}
+```
+
+```properties
+temporal.target=${TEMPORAL_TARGET:localhost:7233}
+temporal.namespace=${TEMPORAL_NAMESPACE:default}
+temporal.task-queue=alva.customer.party-onboarding.v1
+```
+
+The endpoint, namespace and any mTLS certificate path are environment-specific: `.env` locally, platform vault in deployed environments, `${VAR}` in properties — see quarkus-security-standards skill §1–2. A Temporal Cloud client certificate is a secret and is never committed.
+
+## 3. Topology: a worker-only project (default), or an embedded worker
+
+Decide this **before** the first file, and record it in the app's `README.md` — the two shapes have different layouts and suspend different house rules.
+
+### A. Worker-only project — the default
+
+A deployable that hosts workflows and activities **and nothing else**: no REST, no slices, and normally no database. Every side effect is a remote call to the service that owns that data (§7). This is the right shape whenever the process spans services, for two reasons that matter in production:
+
+- Workflow code is **replay-sensitive** (§4). Keeping it in its own deployable means a workflow change is released on its own cadence instead of riding along with an unrelated business-service deploy — and a business service can be redeployed freely without touching in-flight executions.
+- Workers scale on **task-queue backlog**, not on request rate. A pod sized for orchestration has nothing in common with one sized for an API.
+
+```
+apps/customer-onboarding-worker/                     # worker-only deployable — note the -worker suffix
+├── src/main/java/com/alva/customer/onboarding/
+│   ├── common/
+│   │   ├── temporal/TemporalConfig.java             # @ConfigMapping
+│   │   ├── temporal/TemporalBootstrap.java          # §2 — the only class touching WorkerFactory
+│   │   ├── client/PartyRegistrar.java               # gRPC beans — how activities reach other services
+│   │   ├── client/WalletOpener.java
+│   │   └── exception/BusinessException.java         # the house error taxonomy still applies (§9)
+│   └── orchestration/
+│       └── party_onboarding/                        # snake_case, capability-named
+│           ├── dto/
+│           │   ├── PartyOnboardingRequestDto.java   # record + @RegisterForReflection
+│           │   └── PartyOnboardingResultDto.java
+│           ├── PartyOnboardingWorkflow.java         # @WorkflowInterface — the contract
+│           ├── PartyOnboardingWorkflowImpl.java     # the saga; deterministic, zero I/O
+│           ├── PartyOnboardingActivities.java       # @ActivityInterface
+│           ├── PartyOnboardingActivitiesImpl.java   # injects common/client beans — no local Handler
+│           └── README.md                            # steps, compensations, timeouts, task queue
+├── src/main/proto/                                  # ONLY if this app owns the trigger RPC (below)
+├── Dockerfile · service.yaml · README.md
+```
+
+There is no `Resource`, no `@Path`, no slice folder, no `Sql` class and no `db/` migration. **Do not scaffold them "for later"** — an unused datasource is a connection pool, a credential and a readiness dependency bought for nothing.
+
+**The deployable carries the `-worker` suffix, never `-ms`** — `{module}-{capability}-worker`, e.g. `customer-onboarding-worker` (see the suffix table in the quarkus-hexagonal-core skill). The suffix is a deploy-time contract, and this kind of app contradicts everything `-ms` implies: no ingress, no HTTP route to probe, no API to publish, and scaling driven by task-queue backlog instead of request rate. Naming it `-ms` would hand the platform a service it would try to route to and scale on RPS it never receives. Its `service.yaml` matches: no provided APIs, task queues listed instead.
+
+**Which monorepo owns it:** the domain that owns the business **process**, even when most steps call other domains. Cross-domain calls go through contracts published in `contracts/`, exactly like any other inter-domain call.
+
+#### What does *not* apply in a worker-only project
+
+Marcus reads eight universal standards; several of them have nothing to govern here. Applying them anyway produces a REST layer nobody calls and a database nobody reads.
+
+| Standard | Status in a worker-only project |
+|---|---|
+| `quarkus-openapi-tmforum` | **Does not apply.** No `Resource`, no OpenAPI document, no Swagger. The only HTTP surface is `/q/health` and `/q/metrics`. |
+| Vertical slices (`quarkus-hexagonal-core`) | **Does not apply.** No slice folders, no `<Slice>Handler`, no `<Slice>Sql`. `orchestration/` + `common/` *is* the structure. |
+| `quarkus-sql-jdbc-agroal` | **Usually does not apply** — Temporal holds the process state, so there is no datasource. If the app genuinely owns a table (an idempotency/dedup ledger), its SQL follows that skill, with one adjustment: there is no `Handler` below the activity, so **the activity itself plays the Handler role** — it carries the `@Transactional`, opens the single `Connection` and passes it to every `Sql` call. That is the only case where an activity is transactional. |
+| `quarkus-grpc-services` | **Applies fully** — it is how activities reach every other service (§7), and how the trigger RPC is exposed when this app owns one. |
+| `quarkus-error-handling-i18n` | Error codes and the `BusinessException` taxonomy apply (§9). The REST edge mapper is absent; the gRPC interceptor applies only if the app exposes an RPC. |
+| `quarkus-observability-otel` | **Applies fully, and matters more** — there is no request log to fall back on when a workflow misbehaves. |
+| `quarkus-security-standards` | **Applies fully** — Temporal endpoint, namespace and mTLS certificates are secrets (§2). |
+| `quarkus-kafka-messaging` | Applies when a workflow is triggered by, or emits, domain events. |
+| Rest of `quarkus-hexagonal-core` | Naming, `apps/` layout, Java 25, native build + Dockerfile, `service.yaml` + README: **all unchanged**. |
+
+ArchUnit ships a **subset**: `bannedSuffixes` (with the `..orchestration..` `*Impl` carve-out below), `reactiveIsQuarantined`, `noOrm`, the DTO rules, plus `workflowsDoNoIo`. Drop `slicesAreIndependent`, `onlyHandlersTouchSql`, `transactionalOnlyOnProcess`, `handlersExposeOnlyProcess`, `restResources` and `transportHasNoJdbc` — with no slices to match they can never fail, and a rule that cannot fail is noise that makes the suite look stronger than it is.
+
+#### Who starts the workflow
+
+- **Default: the calling service does.** The worker exposes **no inbound API at all** — it polls its task queue and nothing else. The service that owns the triggering business event holds its own `*Starter` bean (§6); the workflow id and the payload record are the contract between them. Nothing to route, nothing to secure at the edge.
+- **Alternative: the worker owns the trigger RPC.** Then it has `src/main/proto/` and one `*GrpcService`, and that adapter calls the `*Starter` **directly — with no `Handler` in between.** This is a deliberate deviation from "a transport adapter always delegates to a `Handler`": a `Handler` exists to hold business logic and a transaction, and a trigger RPC has neither. An empty pass-through `Handler` would be pure ceremony. The adapter still does only proto↔DTO translation plus the start call.
+
+Readiness reflects the **worker**, not a route: can it reach the Temporal frontend, and is the factory polling. Scale on task-queue backlog (§10), never on RPS.
+
+### B. Embedded worker — the exception
+
+A normal `-ms` app that also hosts a worker — and it **stays `-ms`**, because it still serves an API; the `-worker` suffix is reserved for deployables that serve none. Use it only when every step of the saga is a capability **this same app already owns**, and Temporal is there for durability, retries or long waits rather than for crossing a service boundary. The cost is that the app now has two runtime roles and a replay-sensitive workflow tied to the service's release cadence.
+
+```
+src/main/java/com/<company>/<module>/
+├── common/temporal/…                            # as above, plus PartyOnboardingStarter (§6)
+├── orchestration/
+│   └── party_onboarding/…                       # same contents; activities call local Handlers
+└── create_party_individual/                     # slices — untouched, no Temporal import
+```
+
+Here the dependency direction is deliberately **one-way**: `orchestration/` may depend on slice `Handler`s and slice DTOs; a slice may never depend on `orchestration/`. A slice that imports a workflow has been made un-deployable without a Temporal cluster. Extend `slicesAreIndependent` with the single asymmetric exemption shown below, and keep every other slice rule intact — in this topology they all still bite.
+
+### Naming
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Workflow interface | `<Capability>Workflow`, `@WorkflowInterface` | `PartyOnboardingWorkflow` |
+| Workflow implementation | `<Capability>WorkflowImpl` | `PartyOnboardingWorkflowImpl` |
+| Activity interface | `<Capability>Activities`, `@ActivityInterface` | `PartyOnboardingActivities` |
+| Activity implementation | `<Capability>ActivitiesImpl` | `PartyOnboardingActivitiesImpl` |
+| Workflow method | imperative verb, `@WorkflowMethod` | `onboard` |
+| Signal / Query | `<verb>` / `get<Noun>` | `approve` / `getStatus` |
+| Starter bean | capability noun in `common/temporal` | `PartyOnboardingStarter` |
+| Payload DTO | `*Dto` **record** in `dto/` | `PartyOnboardingRequestDto` |
+| Task queue | `<org>.<module>.<capability-kebab>.v<major>` | `alva.customer.party-onboarding.v1` |
+| Workflow id | `<capability-kebab>-<business-id>` — deterministic | `party-onboarding-9f3e…` |
+
+**`*Impl` is banned everywhere else in this codebase and sanctioned here.** The SDK builds its client stubs from the annotated interface, so the interface/implementation pair is structural, not stylistic, and the official samples name it `*Impl`. Carve it out of the ArchUnit `bannedSuffixes` rule **by package**, exactly as `common/util/StringUtils` and the `Jdbc` helper are carved out — never by weakening the rule:
+
+```java
+@ArchTest
+static final ArchRule bannedSuffixesOutsideOrchestration = noClasses()
+    .that().resideOutsideOfPackage("..orchestration..")
+    .should().haveSimpleNameEndingWith("Impl");   // …plus the existing suffixes
+
+// Temporal stays quarantined
+@ArchTest
+static final ArchRule temporalIsQuarantined = noClasses()
+    .that().resideOutsideOfPackage("..orchestration..")
+    .and().resideOutsideOfPackage("..common.temporal..")
+    .should().dependOnClassesThat().resideInAPackage("io.temporal..");
+
+// A workflow implementation performs no I/O of its own (§4)
+@ArchTest
+static final ArchRule workflowsDoNoIo = noClasses()
+    .that().haveSimpleNameEndingWith("WorkflowImpl")
+    .should().dependOnClassesThat().resideInAnyPackage(
+        "java.sql..", "javax.sql..", "jakarta.ws.rs..", "io.quarkus.grpc..");
+```
+
+Extend the existing `slicesAreIndependent` rule with **one** asymmetric exemption — orchestration may reach into slices, never the reverse:
+
+```java
+    .ignoreDependency(resideInAPackage("..orchestration.."), alwaysTrue())
+```
+
+## 4. The workflow implementation: deterministic, and that is a hard constraint
+
+Temporal replays workflow code from its event history after every worker restart. Replay must produce the identical sequence of commands, so a workflow implementation is **pure orchestration**: it calls activity stubs and does nothing else.
+
+Banned inside a `*WorkflowImpl`, with the replacement the SDK provides:
+
+| Never | Always |
+|---|---|
+| `System.currentTimeMillis()`, `LocalDateTime.now()` | `Workflow.currentTimeMillis()` |
+| `UUID.randomUUID()`, `Math.random()` | `Workflow.randomUUID()`, `Workflow.newRandom()` |
+| `Thread.sleep(…)` | `Workflow.sleep(Duration…)` |
+| `new Thread(…)`, executor services | `Async.function(…)` / `Async.procedure(…)`, scoped with `Workflow.newCancellationScope` |
+| JDBC, HTTP, gRPC, Kafka, file I/O | an **activity** |
+| `Logger.getLogger(…)` | `Workflow.getLogger(…)` — suppresses duplicate lines on replay |
+| iteration over `HashMap`/`HashSet` | `LinkedHashMap`/`TreeMap`, or sort explicitly |
+
+`@Inject` does not work here either (§2) — the workflow's only collaborators are its activity stubs. A workflow that needs configuration receives it as a **workflow argument**, never read from `ConfigProvider` at replay time.
+
+**Versioning is the production footgun.** Editing a workflow implementation while executions of the old code are still running causes a non-deterministic replay and a stuck workflow. Any change to the *sequence* of activity calls requires `Workflow.getVersion("addWallet", DEFAULT_VERSION, 1)` branching, or a new task queue (`…v2`) drained in parallel. Changing an activity's *body* is always safe; changing the workflow's call order never is.
+
+## 5. The saga: `io.temporal.workflow.Saga` with explicit compensations
+
+```java
+public class PartyOnboardingWorkflowImpl implements PartyOnboardingWorkflow {
+
+    private static final Logger log = Workflow.getLogger(PartyOnboardingWorkflowImpl.class);
+
+    private final PartyOnboardingActivities activities = Workflow.newActivityStub(
+        PartyOnboardingActivities.class,
+        ActivityOptions.newBuilder()
+            .setStartToCloseTimeout(Duration.ofSeconds(30))
+            .setScheduleToCloseTimeout(Duration.ofMinutes(10))      // the outer bound — never omit
+            .setRetryOptions(RetryOptions.newBuilder()
+                .setInitialInterval(Duration.ofSeconds(1))
+                .setBackoffCoefficient(2.0)
+                .setMaximumAttempts(5)
+                .setDoNotRetry("BusinessException")                 // matches the FAILURE TYPE — see §9
+                .build())
+            .build());
+
+    @Override
+    public PartyOnboardingResultDto onboard(PartyOnboardingRequestDto request) {
+        Saga saga = new Saga(new Saga.Options.Builder()
+            .setParallelCompensation(false)          // compensate in reverse order, one at a time
+            .build());
+        try {
+            String partyId = activities.createParty(request);
+            saga.addCompensation(activities::deleteParty, partyId);
+
+            String walletId = activities.openWallet(partyId, request.currency());
+            saga.addCompensation(activities::closeWallet, walletId);
+
+            activities.sendWelcomeNotification(partyId);
+            return new PartyOnboardingResultDto(partyId, walletId);
+
+        } catch (TemporalFailure e) {                 // NOT just ActivityFailure — see below
+            log.warn("Onboarding failed, compensating: {}", e.getMessage());
+            saga.compensate();
+            throw e;                                  // the workflow still fails — do not swallow
+        }
+    }
+}
+```
+
+Rules:
+- **Catch `TemporalFailure`, not `ActivityFailure`.** `ActivityFailure` misses `ChildWorkflowFailure`, `CanceledFailure` and every other `TemporalFailure` subtype — and a miss means the compensation chain silently never runs, which is the exact failure the saga exists to prevent.
+- **Decide `Saga.Options.setContinueWithError` deliberately.** It defaults to `false`, so the *first* failing compensation aborts the rest of the chain and leaves the earlier steps uncompensated. Set it to `true` when the compensations are independent and you would rather attempt all of them; leave it `false` only when a failed compensation genuinely makes the remaining ones unsafe.
+- **Register the compensation *after* the forward activity returns**, using its result. Registering before means compensating something that never happened.
+- Compensations run in **reverse registration order** (LIFO). Keep `setParallelCompensation(false)` unless the steps are provably independent — parallel compensation of dependent resources reintroduces the ordering bug the saga exists to avoid.
+- **`saga.compensate()` then rethrow.** A saga that compensates and returns normally reports success for a business process that did not happen.
+- A compensation is itself an activity, so it is retried like any other — and it must be **idempotent**: `deleteParty` on an already-deleted party succeeds quietly rather than failing the compensation chain.
+- No compensation is possible for some steps (an email that went out). Order the workflow so irreversible steps come **last**, after everything reversible has succeeded.
+
+## 6. Activities: the only side-effecting layer
+
+An activity implementation is thin: extract the arguments, perform **exactly one** side effect, return a plain value. **No business logic, no orchestration, no `@Transactional` of its own** — the transaction always lives one level down. What it delegates *to* is the one thing the topology (§3) changes:
+
+```java
+// A. Worker-only project (default): the side effect is a remote call
+@ApplicationScoped
+public class PartyOnboardingActivitiesImpl implements PartyOnboardingActivities {
+
+    @Inject PartyRegistrar partyRegistrar;      // common/client — gRPC, awaits internally (§7)
+    @Inject WalletOpener walletOpener;
+
+    @Override
+    public String createParty(PartyOnboardingRequestDto request) {
+        return partyRegistrar.register(request.tenantId(), request.givenName(), request.familyName());
+    }
+}
+```
+
+```java
+// B. Embedded worker: the side effect is a Handler in this same app
+@Inject CreatePartyIndividualHandler createPartyHandler;
+
+@Override
+public String createParty(PartyOnboardingRequestDto request) {
+    return createPartyHandler.process(toSliceRequest(request)).getPartyId();
+}
+```
+
+Either way the activity is a transport adapter in the sense the hexagonal-core skill defines, and the `@Transactional` boundary is the remote service's `Handler` (A) or the local one (B) — never here. The single exception is a worker-only app that owns a table of its own (§3): with no `Handler` beneath it, that activity plays the `Handler` role and carries the transaction itself.
+
+- **Activities are at-least-once.** Temporal retries on worker crash, timeout and failure, so every activity must be idempotent. Where the underlying operation is not naturally idempotent, dedupe on a business key or on `Activity.getExecutionContext().getInfo().getWorkflowId()`.
+- Every activity needs a `setScheduleToCloseTimeout` (or a `setMaximumAttempts`). An activity with unlimited retries and no outer bound does not fail — it hangs forever, in production and in your tests.
+- Long-running activities heartbeat (`Activity.getExecutionContext().heartbeat(progress)`) so a dead worker is detected in seconds rather than at the start-to-close timeout.
+
+### Starting a workflow
+
+The `*Starter` bean below is the same in both topologies — what differs is **which deployable owns it**:
+
+- **Worker-only (A):** it lives in the *calling* service, which therefore carries `temporal-sdk` and a `common/temporal` package of its own (client only — it registers no worker). The worker project itself does not start workflows; it runs them.
+- **Embedded (B):** it lives in this app, and a slice `Handler` injects it.
+
+In the embedded case a `Handler` must start the workflow through this bean and **never** by injecting `WorkflowClient` into the slice — that would drag `io.temporal` past the §3 quarantine:
+
+```java
+// common/temporal
+@ApplicationScoped
+public class PartyOnboardingStarter {
+
+    @Inject WorkflowClient client;
+    @Inject TemporalConfig config;
+
+    public void start(String partyId, PartyOnboardingRequestDto request) {
+        PartyOnboardingWorkflow workflow = client.newWorkflowStub(
+            PartyOnboardingWorkflow.class,
+            WorkflowOptions.newBuilder()
+                .setTaskQueue(config.taskQueue())
+                .setWorkflowId("party-onboarding-" + partyId)          // deterministic = deduplicated
+                .setWorkflowIdReusePolicy(
+                    WorkflowIdReusePolicy.WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY)
+                .build());
+        WorkflowClient.start(workflow::onboard, request);               // async — never block the Handler
+    }
+}
+```
+
+**Starting a workflow inside a database transaction is a dual write.** If `process()` rolls back after the start call succeeded, the workflow orchestrates an entity that does not exist. This is the same hazard the outbox solves for Kafka (see quarkus-kafka-messaging skill), and it gets the same two answers:
+
+1. **Deterministic workflow id derived from the business entity** (above) — a retry of the whole operation cannot start a second workflow, so the failure mode is recoverable rather than duplicated. This is mandatory, not optional. Use `ALLOW_DUPLICATE_FAILED_ONLY`, **not** `REJECT_DUPLICATE`: the latter blocks reuse even after the run closed, so a legitimate re-run of that business id becomes permanently impossible. The starter must also catch `WorkflowExecutionAlreadyStarted` and treat it as success — that exception *is* the deduplication working, not an error to propagate.
+2. **Start after commit**, the way `OutboxDispatcher.dispatchAfterCommit(eventId)` already does it — or record an outbox row and let the relay start the workflow. Never call `WorkflowClient.start` in the middle of `execution()` and hope the transaction commits.
+
+## 7. Transport: the invocations are gRPC
+
+Orchestration is internal by nature — a saga exists because a process crosses services — so **gRPC is the predominant transport at both ends of a workflow**, per the house rule that internal synchronous calls are always gRPC and never internal REST (see quarkus-grpc-services and quarkus-hexagonal-core skills). North-bound REST triggers exist (a customer action that kicks off onboarding) but are the minority; the default assumption for a Temporal capability is gRPC in, gRPC out.
+
+**A. Worker-only project** — the calling service starts the workflow; the worker only runs it and calls back out over gRPC:
+
+```
+  calling service (-ms)                  worker project (-worker)            other services
+┌───────────────────────┐              ┌────────────────────────┐
+│ GrpcService → Handler │              │  PartyOnboardingWorkflowImpl │      (no I/O here)
+│        ↓              │              │            ↓           │
+│  <Capability>Starter ─┼── Temporal ──┼→ PartyOnboardingActivitiesImpl      │
+└───────────────────────┘  task queue  │            ↓           │
+                                       │  common/client bean ───┼─ gRPC ─→ party-ms, wallet-ms
+                                       └────────────────────────┘
+```
+
+**B. Embedded worker** — everything in one deployable, the activity reaching a local `Handler`:
+
+```
+<Proto>GrpcService  →  Handler.process()  →  <Capability>Starter  →  Temporal
+   (slice folder)       (slice folder)        (common/temporal)
+                                                    ↓
+                              PartyOnboardingWorkflowImpl  (no I/O — orchestration only)
+                                                    ↓
+                              PartyOnboardingActivitiesImpl  →  slice Handler
+```
+
+Nothing about the inbound chain is special-cased for Temporal: the `*GrpcService` delegates to a `Handler`, and the `Handler` injects the `*Starter`. **A `*GrpcService` never injects `WorkflowClient` directly** — that would put `io.temporal` inside a slice folder and break the §3 quarantine. The one exception is the trigger RPC of a worker-only project, which has no `Handler` to delegate to and calls the `*Starter` itself (§3).
+
+### Inbound: the gRPC call starts the workflow, it does not wait for it
+
+A gRPC client carries a deadline measured in seconds (`quarkus.grpc.clients.<name>.deadline=2s`); a saga runs for minutes, days or months. So the RPC that triggers a workflow **returns as soon as the workflow is started** — the workflow id is the response — and never blocks on completion:
+
+- Start asynchronously (`WorkflowClient.start(...)`, as in §6), return the workflow id to the caller.
+- The caller learns the outcome by polling a `@QueryMethod`, by consuming the domain event the workflow's final activity emits (outbox → Kafka, per the messaging skill), or by its own callback RPC.
+- Blocking the RPC on `workflow.onboard(request)` ties a durable execution to a 2-second deadline: the deadline fires, the caller retries, and the only thing the deterministic workflow id saved you from was a second workflow. The first one is still running, unobserved.
+
+### Outbound: activities call other services through `common/client`
+
+An activity that reaches another service uses a capability-named bean from `common/client` — the same bean a `Handler` would use, never a raw `@GrpcClient` stub and never an internal REST client:
+
+```java
+@ApplicationScoped
+public class PartyOnboardingActivitiesImpl implements PartyOnboardingActivities {
+
+    @Inject CredentialsValidator credentialsValidator;    // common/client — awaits internally
+
+    @Override
+    public boolean validateCredentials(String username, String password) {
+        return credentialsValidator.validate(username, password);   // plain types in, plain types out
+    }
+}
+```
+
+Because those beans `await()` internally and expose plain types, the `reactiveIsQuarantined` ArchUnit rule keeps passing unchanged — no Mutiny ever reaches `orchestration/`, exactly as none reaches a `Handler`.
+
+**Only activities may call out. A workflow never holds a client**, gRPC or otherwise (§4).
+
+### Two timeout layers, and the order between them is not optional
+
+```
+grpc deadline  <  activity startToCloseTimeout  <  activity scheduleToCloseTimeout
+      2s                      30s                            10m
+```
+
+Get this backwards and the activity times out while the gRPC call is still in flight: Temporal schedules a retry, and now two identical calls are hitting a downstream that is already struggling. The gRPC deadline must be the *inner* bound so the call is dead before Temporal reacts to it.
+
+**Do not stack retries.** Temporal's activity retry policy and the gRPC/mesh retry policy multiply: 5 activity attempts × 3 mesh retries = 15 calls, sent to the exact service that is failing. Temporal owns the retry — its attempts are durable, backed off, and visible in the workflow history, where a mesh retry is invisible. Keep the client/mesh layer at a single retry for connection-level `UNAVAILABLE` blips at most, and let the activity policy do the rest.
+
+### Mapping gRPC failures onto the retry policy
+
+A `StatusRuntimeException` from a downstream is classified at the activity boundary, the same way §9 classifies the house exceptions:
+
+| gRPC status from the downstream | Temporal treatment |
+|---|---|
+| `INVALID_ARGUMENT`, `FAILED_PRECONDITION`, `NOT_FOUND`, `ALREADY_EXISTS`, `PERMISSION_DENIED` | **non-retryable** — translate to the slice's `BusinessException` code, then to a non-retryable `ApplicationFailure` |
+| `UNAVAILABLE`, `DEADLINE_EXCEEDED`, `RESOURCE_EXHAUSTED`, `ABORTED` | retryable — this is what the activity retry policy is for |
+| `INTERNAL`, `UNKNOWN` | retryable, but bounded by `scheduleToCloseTimeout` |
+
+The downstream already maps its `BusinessException` codes onto gRPC statuses on the way out (see the grpc skill's error-mapping table), so this table is that one read in reverse — keep the two consistent when either changes.
+
+### The SDK's own transport
+
+The worker and the client talk to the Temporal service over gRPC as well, on shaded Netty. That is not trivia: it is why the native build needs the run-time initialization flag in §8, why a Temporal Cloud connection is mTLS with a client certificate handled as a secret (§2), and why `WorkflowServiceStubsOptions` carries its own RPC timeout and keepalive settings, separate from every timeout above.
+
+## 8. Payloads and native image
+
+**Payloads are Java records, always annotated `@RegisterForReflection`.** Records are immutable, which is what replay safety wants, and the SDK's default `DataConverter` serializes them with Jackson — which needs reflection metadata that GraalVM will not infer.
+
+```java
+@RegisterForReflection
+public record PartyOnboardingRequestDto(
+    String tenantId,
+    String givenName,
+    String familyName,
+    String currency) {}
+```
+
+This is a deliberate local deviation from the slice DTO convention (Lombok `@Data` classes, per hexagonal-core): a Temporal payload is serialized into an immutable event history, so a mutable DTO with setters is the wrong shape. The `*Dto` suffix and the `dto/` package still apply, so the existing `dtosStayInDtoPackage` ArchUnit rule keeps passing.
+
+**The native build needs the gRPC/Netty run-time initialization flag.** Temporal talks gRPC over shaded Netty, which fails at image-build time without it:
+
+```properties
+quarkus.native.additional-build-args=--initialize-at-run-time=io.grpc.netty.shaded.io.netty
+```
+
+- This property is a **comma-separated list**: if the app already sets it, append rather than overwrite — a silently replaced flag is a native failure two builds later.
+- The SDK builds workflow and activity stubs with JDK dynamic proxies, which is precisely the pattern hexagonal-core tells you to avoid. Here it is unavoidable, so it is a *verified* exception, not an assumed one: if the native build or the binary fails on a missing proxy, register the interface with Quarkus's `@RegisterForProxy`. (The old `-H:DynamicProxyConfigurationResources` flag is gone on GraalVM for JDK 21+ — proxies are handled through reachability metadata now; do not reach for it.) Either way, **a Temporal app is not "native-ready" until `@QuarkusIntegrationTest` has run green against the built binary** — the JVM-mode test proves nothing about this.
+
+## 9. Errors and retries
+
+Temporal's retry policy is the automatic remediation this codebase otherwise has to hand-write — but only if failures are classified correctly. The house exception taxonomy (see quarkus-error-handling-i18n and quarkus-sql-jdbc-agroal skills) maps cleanly:
+
+| Exception from the `Handler` | Temporal treatment | Why |
+|---|---|---|
+| `BusinessException` (validation, business rule) | **non-retryable** — `setDoNotRetry(...)` | The input will not become valid on attempt 4. Retrying burns the retry budget and delays compensation. |
+| `TransientPersistenceException`, `PersistenceTimeoutException` (deadlock, `40001`, `57014`) | retryable — the default | Exactly what the retry policy exists for. |
+| `StaleVersionException` (optimistic lock) | retryable, small `maximumAttempts` | A genuine concurrent-update race that usually clears. |
+| `PersistenceException` (infrastructure) | retryable, capped by `scheduleToCloseTimeout` | Recoverable, but must not retry forever. |
+
+Make the classification explicit at the activity boundary rather than relying on class-name matching alone:
+
+```java
+catch (BusinessException e) {
+    // The 2nd argument is the failure TYPE and must match setDoNotRetry("BusinessException") in §5 —
+    // passing e.code() there instead would leave the declarative rule matching nothing.
+    // The error code travels as a detail, so the caller still gets it.
+    throw ApplicationFailure.newNonRetryableFailure(e.getMessage(), "BusinessException", e.code());
+}
+```
+
+`newNonRetryableFailure` already marks the failure non-retryable on its own, so the `setDoNotRetry` entry in §5 is the declarative belt to this braces — but only while the two strings agree. Keep them in sync, or the retry policy silently stops matching.
+
+The failure the client ultimately sees is still a house error code: `WorkflowFailedException` surfacing at the REST edge is translated by `GlobalExceptionHandler` into the catalogued `<MOD>-<HTTP>-<seq>` for that capability, localized as usual. A raw Temporal stack trace never reaches an API consumer.
+
+## 10. Observability
+
+- Propagate trace context into workflows and activities with `OpenTracingClientInterceptor` / `OpenTracingWorkerInterceptor`, registered on `WorkflowClientOptions` and `WorkerFactoryOptions` in the bootstrap bean. They come from `io.temporal:temporal-opentracing` (declared in §1) and need `io.opentelemetry:opentelemetry-opentracing-shim` to bridge onto the OTel SDK this platform uses — there is no OTel-native interceptor module, which is why a tracing-only dependency shows up in an otherwise minimal pom. Without them a workflow is a hole in the trace: the REST span ends, and the activity spans belong to no one.
+- Feed SDK metrics into the mandatory Micrometer registry (see quarkus-observability-otel skill) via `MicrometerClientStatsReporter` on `WorkflowServiceStubsOptions.setMetricsScope(...)`. Workflow task latency and activity failure rates are the client-side signals that a worker fleet is unhealthy. **Task-queue backlog is not among them** — it is server-side state, read from `DescribeTaskQueue` or the Temporal server's own metrics, so wire the autoscaling signal there rather than expecting it in `/q/metrics`.
+- Log inside workflow code only through `Workflow.getLogger(...)`; a plain logger re-emits every line on every replay and makes the log unreadable exactly when you need it.
+- Workflow ids and task queues are bounded, business-meaningful values — good span attributes. The workflow *arguments* are not: they carry the same PII prohibition as everything else.
+
+## 11. Testing: `TestWorkflowEnvironment`, in memory
+
+Saga behaviour is tested with Temporal's in-memory environment — plain JUnit 5 + Mockito, **no `@QuarkusTest`**, consistent with how `Handler`s are tested (see hexagonal-core testing table). The environment skips time, so a `Workflow.sleep(Duration.ofDays(30))` resolves instantly.
+
+```java
+class PartyOnboardingWorkflowTest {
+
+    private static final String TASK_QUEUE = "test-queue";
+
+    private TestWorkflowEnvironment testEnv;
+    private Worker worker;
+    private PartyOnboardingActivities activities;
+
+    @BeforeEach
+    void setUp() {
+        testEnv = TestWorkflowEnvironment.newInstance();
+        worker = testEnv.newWorker(TASK_QUEUE);
+        worker.registerWorkflowImplementationTypes(PartyOnboardingWorkflowImpl.class);
+        // withoutAnnotations() is REQUIRED: Mockito copies @ActivityInterface/@ActivityMethod
+        // onto the mock class and the worker rejects the registration without it.
+        activities = mock(PartyOnboardingActivities.class, withSettings().withoutAnnotations());
+        worker.registerActivitiesImplementations(activities);
+    }
+
+    @AfterEach
+    void tearDown() {
+        testEnv.close();
+    }
+
+    @Test
+    void shouldCompensateCreatedPartyWhenWalletFails() {
+        when(activities.createParty(any())).thenReturn("party-1");
+        when(activities.openWallet(any(), any())).thenThrow(new IllegalStateException("wallet down"));
+        testEnv.start();
+
+        PartyOnboardingWorkflow workflow = testEnv.getWorkflowClient().newWorkflowStub(
+            PartyOnboardingWorkflow.class,
+            WorkflowOptions.newBuilder().setTaskQueue(TASK_QUEUE).build());
+
+        assertThatThrownBy(() -> workflow.onboard(request()))
+            .isInstanceOf(WorkflowException.class);
+
+        verify(activities).deleteParty("party-1");          // the compensation ran
+        verify(activities, never()).closeWallet(any());     // the wallet was never created
+    }
+}
+```
+
+Mandatory scenarios per workflow — the compensation paths are the point of the whole exercise:
+
+| # | Scenario | Assert |
+|---|---|---|
+| 1 | Happy path | result DTO correct; activities invoked in order; **no** compensation invoked |
+| 2 | Failure at step *n* | compensations for steps `1..n-1` ran, in reverse order; none for `n..end`; the workflow still fails |
+| 3 | Non-retryable business failure | the activity ran **once** (`verify(activities, times(1))`) — proves `setDoNotRetry` is wired |
+| 4 | Compensation is idempotent | a compensation invoked twice leaves the same end state |
+| 5 | Signal / timer paths, where present | time-skipping drives the timer; assert the state the signal produced |
+
+- Mockito stubs the **activity interface**, so a workflow test never touches a database or a slice `Handler`. Slice behaviour is already covered by that slice's own `HandlerTest`.
+- Give mocked failing activities a bounded retry policy (or a non-retryable failure), or the test exercises the full retry schedule before failing.
+- Add a `WorkflowReplayer` test against a committed history JSON for any workflow already running in production — it fails the build on a change that would break in-flight executions (§4), which is the one bug integration tests cannot find.
+
+## Checklist for a new workflow
+
+1. The operation genuinely crosses a slice, service or time boundary — a single `Handler` + one transaction cannot do it.
+2. Topology chosen and written in the app README: **worker-only** (default — deployable named `{module}-{capability}-worker`, no REST, no slices, no datasource, activities call remote services) or **embedded** (stays `-ms`). In a worker-only project, none of the REST/slice/SQL standards were scaffolded and the ArchUnit suite ships the documented subset.
+3. `temporal-sdk` (1.27.0+) compile scope, `temporal-testing` test scope, explicit version, no Quarkiverse extension.
+4. Exactly one `TemporalBootstrap` in `common/temporal`: `@Produces WorkflowClient`, `@Observes StartupEvent` → register (workflows **by class**, activities **by instance**) → `factory.start()`; `@Observes ShutdownEvent` → `shutdown()` + `awaitTermination`.
+5. Endpoint, namespace and certificates come from `${VAR}` / `.env` / vault — never literals (security skill §1).
+6. Workflow lives in `orchestration/<capability>/`; in an embedded app, no `io.temporal` import inside any slice; ArchUnit quarantine + `*Impl` carve-out in place.
+7. `*WorkflowImpl` is deterministic: no clock, no random, no threads, no I/O, no `@Inject`, no unordered-collection iteration.
+8. Saga compensations registered **after** each forward step, LIFO, idempotent; irreversible steps ordered last; `compensate()` then rethrow.
+9. Every activity: idempotent, `scheduleToCloseTimeout` set, `BusinessException` non-retryable, delegating to a `Handler` with no logic of its own.
+10. Workflow started with a deterministic workflow id, after commit — never mid-transaction.
+11. Transport is gRPC in and out: the trigger reaches the `*Starter` through a `Handler` (embedded) or directly from the worker's own `*GrpcService` (worker-only), it **returns the workflow id without waiting**, and every outbound call goes through a `common/client` bean.
+12. Timeouts ordered `grpc deadline < startToCloseTimeout < scheduleToCloseTimeout`, and retries are not stacked — Temporal owns the retry, the mesh keeps at most one.
+13. Payload records annotated `@RegisterForReflection`; `--initialize-at-run-time=io.grpc.netty.shaded.io.netty` appended (not overwriting) `quarkus.native.additional-build-args`; `@QuarkusIntegrationTest` green against the native binary.
+14. `TestWorkflowEnvironment` tests cover happy path **and** every compensation path; tracing interceptors and Micrometer metrics scope registered.
+15. `orchestration/<capability>/README.md` documents the steps, their compensations, the timeouts and the task queue.