68: Await CONFIRMED on-chain outcomes for Jupiter Swap and Perps operations

openspec/specs/jupiter-swap-service/spec.md

@@ -78,15 +78,45 @@ After successful signing, the service SHALL reject a blank signed transaction an
 - **THEN** the service fails without submitting an execution request
 
 ### Requirement: Confirmed execution result validation
-The service SHALL return success only when the execution response has status `Success`, explicitly has result code `0`, contains a non-blank transaction signature, and contains positive valid actual total input and output raw amounts. It SHALL convert each actual amount using the independently resolved precision of its mint. Non-success HTTP responses, malformed responses, expired or rejected swaps, failed or contradictory status/code combinations, missing result codes, blank signatures, and invalid result amounts SHALL be reported as failures.
+The service SHALL first accept a Jupiter execution response only when it has status `Success`, explicitly has result code `0`, contains a non-blank transaction signature, and contains positive valid actual total input and output raw amounts. It SHALL convert each actual amount using the independently resolved precision of its mint. After this provider-response validation, the service SHALL independently await the returned signature on Solana at `CONFIRMED` using its configured confirmation timeout and SHALL return the already validated swap result only for a `SUCCEEDED` outcome. Non-success HTTP responses, malformed responses, expired or rejected swaps, failed or contradictory status/code combinations, missing result codes, blank signatures, and invalid result amounts SHALL remain provider failures and SHALL not be represented as successful swaps.
 
-#### Scenario: Successful execution response
-- **WHEN** Jupiter reports status `Success`, code `0`, a signature, and valid actual total input and output amounts
-- **THEN** the service returns those actual amounts in human-readable units and the reported transaction signature
+#### Scenario: Provider response and on-chain confirmation succeed
+- **WHEN** Jupiter reports status `Success`, code `0`, a signature, and valid actual total input and output amounts, and that signature independently reaches `CONFIRMED` with a `SUCCEEDED` outcome
+- **THEN** the service returns the signature and those actual amounts in human-readable units
 
 #### Scenario: Jupiter rejects or fails execution
 - **WHEN** Jupiter returns a failed status, a missing or non-zero result code, a contradictory status/code combination, expiration, rejection, non-success HTTP status, malformed body, blank signature, or invalid actual amount
-- **THEN** the service reports an I/O failure and does not represent the swap as successful
+- **THEN** the service reports an I/O failure without treating provider validation as an on-chain confirmation
+
+#### Scenario: Provider succeeds but transaction fails on-chain
+- **WHEN** a fully validated Jupiter execution response contains a signature whose independent `CONFIRMED` outcome is `FAILED`
+- **THEN** the service throws a structured checked outcome exception preserving the signature, requested commitment, slot, and complete compact Solana failure details
+
+#### Scenario: Provider succeeds but confirmation times out
+- **WHEN** a fully validated Jupiter execution response contains a signature whose independent `CONFIRMED` outcome is `TIMED_OUT`
+- **THEN** the service throws a structured checked outcome exception preserving the signature, requested commitment, and unknown outcome warning and does not automatically resubmit an equivalent transaction
+
+### Requirement: Swap confirmation timeout policy
+The reference service SHALL accept a constructor-injected, non-null, strictly positive confirmation timeout and SHALL preserve its existing constructor with a two-minute default. The configured duration SHALL be passed unchanged to independent confirmation after submission and SHALL begin governing only when awaiting the known signature starts.
+
+#### Scenario: Valid custom timeout
+- **WHEN** a reference service is constructed with a positive duration and later obtains a validated execution signature
+- **THEN** it awaits that signature at `CONFIRMED` with exactly the supplied duration
+
+#### Scenario: Invalid custom timeout
+- **WHEN** a reference service is constructed with a null, zero, or negative duration
+- **THEN** construction fails before any operation can be submitted
+
+### Requirement: Post-submission communication and interruption policy
+If independent confirmation fails with an I/O error after the signature is known, the service SHALL throw an `IOException` whose message identifies the swap operation, includes the signature, and states that the on-chain outcome is unknown, with the original error retained as its cause. Interruption SHALL propagate directly as `InterruptedException` without another RPC or Jupiter request. Neither condition SHALL trigger rebuilding, re-signing, retrying, or resubmitting a transaction.
+
+#### Scenario: Confirmation communication fails
+- **WHEN** independent confirmation throws an I/O error for a known submitted signature
+- **THEN** the service reports the signature and unknown on-chain outcome while preserving the original error and performs no retry or resubmission
+
+#### Scenario: Confirmation is interrupted
+- **WHEN** independent confirmation throws `InterruptedException`
+- **THEN** that interruption propagates directly and the service performs no subsequent request
 
 ### Requirement: API and implementation separation
 The stable service interface and result value SHALL reside in the Jupiter swap API package, while HTTP DTOs, endpoint handling, throttling, and the reference implementation SHALL remain in the reference-implementation package.