# Terraform Provider Development Strategy & AI Integration

## 1. Vision: "The Helpful Kitchen Assistant"
The provider should not just be a silent executor of commands. It should act as an intelligent assistant for users of all skill levels (the "Cook" persona). It must provide context, warnings, and advice *before* any potentially destructive or wasteful actions are taken.

## 2. Advanced Pre-Apply Logic
To prevent "bad applies" and incomplete infrastructure states, the provider will implement:

### A. Context-Aware Validation (Scanning the Cloud)
- **Data Sources as Sensors:** Use Data Sources not just for referencing existing resources, but as "sensors" to understand the current cloud state during `terraform plan`.
- **Pre-emptive Warnings:** Compare the proposed `plan` against current cloud limits, existing resource names, and regional availability.
- **Example:** Trigger a warning if a user is creating a 6th bucket while 5 existing ones are empty.

### B. Cascading & Logical Validation (Deep Validation)
- **Attribute Inter-dependency:** Check compatibility between linked resources (e.g., App vs DB versions, S3 permissions vs CDN requirements).
- **Early Termination:** If Resource A in a chain is logically "broken" or suboptimal, the provider should error out or warn on the entire chain before `apply` begins.

## 3. Human-Centric Output & AI Insights
- **Standardized Info:** `terraform plan` should output human-readable summaries of what's already in the cloud, not just what's being changed.
- **AI-Driven Advice:** 
    - The provider outputs a structured JSON state.
    - An AI Agent (Sub-chef) analyzes this JSON.
    - Result: "Hey, I noticed you're creating a DB in Region A but your VMs are in Region B. This will cause latency. Want to fix it?"

## 4. Implementation via Taffy API Specifics
- **Lifecycle Utilization:** Leverage the 3-step Taffy lifecycle (`Operation -> Parameters -> Run`).
- **Validation Step:** Use the `/validate-cfs` API endpoint during the Terraform `Plan` or `Create` phase (before the final `Run`) to ensure the cloud accepts the parameters without actually committing the change.

## 5. Reliability & Uncertainty Tracking
- All documentation and internal agent logic should use **Confidence Scores** (e.g., `[CONFIDENCE: 85%]`).
- Explicitly mark `[UNCERTAINTY]` tags for deprecated API features or areas where documentation contradicts observed behavior (from HAR/Traffic analysis).

---
*This document serves as the architectural north star for the project.*

## 6. Подресурсы (subresource) и поведение Terraform

### Зачем нужен ForceNew
Для подресурсов вроде `create_user`, `delete_user`, `create_database` часто **нет** операции `modify` в API. Это значит, что при изменении ключевых полей (например, `username` или `dbName`) мы не можем обновить объект на месте — только удалить и создать заново.

**ForceNew** — это стандартный механизм Terraform: изменение таких полей приводит к **замене** ресурса (Delete + Create). Это предотвращает ложные обновления, когда Terraform считает, что всё изменилось, а в API реально ничего не выполнено.

### Правило для генерации подресурсов
- Если у подресурса **нет** операции `modify`, то все его параметры считаются **ForceNew**.
- Если `modify` есть, то **ForceNew** получают параметры, которые участвуют в идентификации/удалении (ключи, по которым ресурс можно уникально определить).

### Итоговое поведение
- Изменение ключевых параметров подресурса => ресурс заменяется.
- Это соответствует возможностям API и сохраняет корректность состояния Terraform.

## 7. Каноничная lifecycle-логика для сервисов с suspend/resume

Этот раздел обязателен для всех агентов, генераторов и разработчиков.
Если в других документах встречаются старые правила (`resume_if_exists`, `delete_mode`), приоритет всегда у этого раздела.

Область действия:
- Только `instance`-ресурсы, у которых API поддерживает `suspend`/`resume`.
- Для сервисов без `suspend` действует обычная логика create/modify/delete.

Флаги:
- `adopt_existing_on_create` (optional, default: `false`) — разрешает усыновление уже `running` ресурса при create/apply.
- `suspend_on_destroy` (optional, default: `true`) — при destroy/удалении из манифеста выполнять `suspend` вместо удаления из state.

Правила по умолчанию:
- Никакого неявного adopt/import: без `adopt_existing_on_create=true` найденный `running` ресурс считается конфликтом.
- На destroy выполняется `suspend` по умолчанию (`suspend_on_destroy=true`).
- Режим state-only допускается только при явном `suspend_on_destroy=false`.

## 8. Обязательные правила apply / plan / destroy / modify

### Apply/Create (instance с suspend/resume)
- Всегда проверить облако по `resource_name` перед create.
- Если ресурс не найден в облаке или найден только в статусе `deleted` — всегда `create`.
- Если ресурс в статусе `suspend`:
    - при `adopt_existing_on_create=true` и совпадении основных параметров — `resume` + `adopt`, и явное сообщение в plan/apply;
    - при `adopt_existing_on_create=false` — hard error (явно требовать включить флаг для resume/adopt);
    - при несовпадении — hard error с перечислением несовпавших ключей.
- Если ресурс в статусе `running`:
    - при `adopt_existing_on_create=true` — adopt (import-поведение) с явным сообщением в plan;
    - при `adopt_existing_on_create=false` — hard error "resource already exists".
- Если ресурс в статусе `not created` — hard error "проверьте ресурс в личном кабинете" (без auto-adopt/create).
- Если ресурс в статусе `creating`/`pending`/`failed` — hard error.

### Формат диагностик (обязательно)
- Диагностики должны быть многострочными и читаемыми.
- В тексте обязательно указывать:
    - итоговое решение (`adopt`/`resume`/`error`),
    - какой флаг повлиял (`adopt_existing_on_create`/`suspend_on_destroy`),
    - детализированные поля (`resource_name`, `service_id`, `instance_uid`, `status`, `status_raw`, `operation_pending`, `operation_in_progress`) отдельными строками.
- Для конфликта `resource already exists` при `adopt_existing_on_create=false` диагностика обязана явно предлагать оба пути:
    - изменить `resource_name`, если нужен новый ресурс;
    - включить `adopt_existing_on_create=true` и повторить `apply` для импорта/усыновления существующего ресурса.

### Destroy / удаление из манифеста (instance с suspend/resume)
- Если `suspend_on_destroy=true` — выполнить `suspend`.
- Если `suspend_on_destroy=false` — удалить только из Terraform state, без delete/suspend вызовов в API (осознанный override).

### Modify
- При diff по immutable/create-only параметрам — hard error (replace запрещён).
- При diff только по mutable параметрам — выполнить `modify`.

### Replace
- Для сервисов с `suspend` запрещён любой implicit replace (`delete+create`).
- Попытка replace должна завершаться ошибкой на этапе plan.

## 9. Контрольный список для реализации

### Plan messages (обязательно)
- Явно указывать обнаруженный cloud status: `deleted`/`suspend`/`running`/`not created`/`creating`.
- Явно указывать, какой флаг повлиял на решение: `adopt_existing_on_create` или `suspend_on_destroy`.
- Для веток `resume` и `adopt` показывать причину выбора действия.

### Safety guards
- Для `suspend` + mismatch не допускать auto-resume.
- Для `running` без `adopt_existing_on_create=true` не допускать auto-adopt.
- После `resume`/`adopt` выполнять read-back и обновлять state только по фактическому ответу API.

### Терминология
- `resume_if_exists` и `delete_mode` считаются legacy-терминами и не используются в новой логике.