diff --git a/TOOLS/ARCHITECTURE.md b/TOOLS/ARCHITECTURE.md index a4a59c8..124bfe9 100644 --- a/TOOLS/ARCHITECTURE.md +++ b/TOOLS/ARCHITECTURE.md @@ -125,9 +125,14 @@ Each operation has a kind: Gateway may temporarily reject valid JWT tokens. - Implemented: `isRetryable` (`core/http.go`) includes 401 alongside {429, 502, 503, 504}; retry applies to GET requests only. -- Network errors and HTTP retryable statuses are retried for **GET only**. POST is not - retried (a blind retry of the creating `POST /instanceOperations` could duplicate an - operation — see open question on idempotency). +- Network errors and HTTP retryable statuses are retried for **GET only** (decided + 2026-09-30). POST is NEVER retried: `POST /instanceOperations` is not idempotent, and a + blind retry would duplicate the operation. The API has no `Idempotency-Key` support. +- Draft operation on failure (decided 2026-09-30): if an error occurs after + `POST /instanceOperations` but before `.../run`, the operation remains created but was + never executed (the instance is unaffected). No cancellation API is known — neither the + provider code nor the captured HAR contain `DELETE /instanceOperations/{uid}`. +- Transient 401 is retried for GET (see `isRetryable`). ### Generated Code Resilience @@ -227,14 +232,21 @@ From the unified YAML, generate: ## Lifecycle Vocabulary (single contract) -⚠️ The destroy-behaviour vocabulary is currently INCONSISTENT across resource kinds: +**Target contract (decided 2026-09-30):** two runtime flags — `keep_on_destroy` and +`suspend_on_destroy` — express destroy behaviour for ALL resource kinds. The compile-time +`delete_strategy` (YAML) is a generator input that MAPS onto them: -1. generated instance resources: runtime flags `suspend_on_destroy` / `keep_on_destroy`; -2. generated modifiers: compile-time `delete_strategy` (no runtime flag); -3. hand-written modifiers: runtime `keep_on_destroy` only. +| `delete_strategy` | Runtime meaning | +|---|---| +| `noop_warn` | `keep_on_destroy = true` (platform effect left untouched) | +| `inverse` | normal destroy (inverse modify is performed) | +| `error` | destroy refused with a validation error | -All three express the same intent ("what happens to the platform effect on destroy"). -Canonical direction: one unified vocabulary/contract for all resource kinds. +Current state (2026-09-30) — to be migrated: + +1. generated instance resources: already `suspend_on_destroy` / `keep_on_destroy`; +2. generated modifiers: `delete_strategy` only (no runtime flag yet); +3. hand-written modifiers: already `keep_on_destroy`. ## Non-Negotiable Rules