# 02. Tubulus Stabilization & The "Iron Logic" of Polling

**Date:** 2026-01-27
**Operator:** GitHub Copilot (Gemini 3 Pro)
**Task:** Fix Tubulus Creation and Polling

## The Problem
The `nubes_tubulus_instance` resource was unstable:
1.  **Timeouts**: Operations would finish, but the provider kept waiting until the hard timeout.
2.  **Bad Requests**: Valid inputs (empty maps) were rejected by the API.
3.  **Terraform Errors**: "Provider returned invalid result object" (Unknown values) after Apply.

## The Investigation (HAR Analysis)
We analyzed 14 HAR files covering various scenarios (Success, Failure, Fast, Slow).
Key finding: The API has a strict contract regarding `dtFinish`.
- `dtFinish` appears exactly when the operation ends.
- Waiting for `status="COMPLETED"` or similar text fields is unreliable.
- `isSuccessful` is only valid after `dtFinish` is present.

## The Solution
1.  **Refactored Polling (`waitForOperationAndInstanceStatus`)**:
    - Implemented strict check: If `dtFinish != nil`, stop waiting.
    - If `isSuccessful` is true -> Success. Else -> Error.
    - Removed arbitrary sleeps and secondary status checks.

2.  **Fixed Parameter Submission (`submitOperationParams`)**:
    - Restored logic to send `"{}"` for empty map/json types.
    - Added fallback mapping using `SvcOperationCfsParam` key.

3.  **Fixed Instance Reading (`readInstance`)**:
    - Added `?fields=...explainedStatus` to GET request to ensure status is returned.
    - Updated `InstanceResponse` struct to match API wrapper `{"instance": {...}}`.

4.  **Fixed Terraform State (`Create`)**:
    - Explicitly set all `Unknown` computed fields to `Null` at the end of resource creation to satisfy Terraform's safety checks.

## Outcome
Test 014 (Lifecycle Create) passed successfully in 33 seconds.

## Directives for Future
- **DO NOT TOUCH** `tubulus_resource.go` polling logic. It is based on hard evidence.
- Always check `dtFinish` for Nubes operations.