# Tubulus (Bolvanka) & Polling Logic Discovery

## Overview
This document describes the critical discovery made regarding the Nubes Tubulus (Bolvanka) service and, more importantly, the strict polling logic required to interact with the Nubes API reliably.

## The "Bolvanka" Service
Tubulus is a test service ("Bolvanka") that mimics long-running operations. It is used to test the provider's lifecycle management capabilities, including:
- Creating instances with delays.
- Handling failures at different stages (Start, InProgress).
- Soft Delete (Resume) logic.

## Critical Polling Logic (The "Iron Logic")

After analyzing 14+ HAR files (HTTP Archives) from real API interactions, the following **INVARIANT** behavior was established for Instance Operations (`instanceOperations`):

### 1. The `dtFinish` Rule
*   **dtFinish is NULL** while the operation is running (PENDING, IN_PROGRESS).
*   **dtFinish is NOT NULL** (contains a timestamp) **IMMEDIATELY** when the operation finishes.
*   **IMPLICATION**: `dtFinish` is the **ONLY** reliable source of truth for completion. Do not rely on `status`, `isInProgress`, or `isPending`.

### 2. The Success/Failure Rule
Once `dtFinish` is detected (not null), the success is determined solely by `isSuccessful`:
*   **isSuccessful == true**: Operation succeeded. Proceed to read instance.
*   **isSuccessful == false**: Operation failed.
*   **isSuccessful == null**: Operation failed (or indeterminate state treated as failure).

### 3. The Instance Status Rule
*   Do NOT check instance status while the operation is running. It will be "not created" or "suspended".
*   Only after Operation Success (dtFinish != nil && isSuccessful == true) should you expect the Instance status to be `running`.

## Parameter Submission Logic
To successfully execute an operation (`run`), parameters must be submitted correctly:
1.  **Empty Maps/JSONs**: Must be sent as `"{}"`. Sending `""` causes `400 Bad Request`.
2.  **Empty Lists**: Must be sent as `"[]"`.
3.  **Mapping keys**: The API returns parameters with `code`, `name`, and `svcOperationCfsParam`. Terraform resource attributes must be mapped to one of these (fallback order: Code -> Name -> SvcOperationCfsParam).

## Terraform "Unknown" Values
The Terraform Provider Framework requires that all attributes marked as `Computed` have a known value after `Apply`.
*   The Nubes API `readInstance` does NOT return fields like `fail_at_start`, `duration_ms`, etc.
*   **SOLUTION**: In the `Create` method, after reading the instance status, all optional computed fields that are still `Unknown` must be explicitly set to `Null`.

## Reference Code
See `internal/provider/tubulus_resource.go` for the implementation.
**DO NOT CHANGE THE POLLING OR PARAMETER LOGIC WITHOUT REVIEWING THIS DOCUMENT.**