Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,31 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+aws_infra/ministack_logo.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/architecture_diagram.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/compare_dataset.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/compare_rl_env.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/curriculum_progression.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/dataset_composition.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/env_init_screenshot.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/grpo_final_per_step.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/grpo_optuna_trial_curves.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/grpo_optuna_trials_comparison.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/grpo_reward_curve.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/ministack_logo.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/optuna_parallel.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/optuna_slice.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/parallel_rollout_diagram.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/reward_components.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/sft_loss_curve.png filter=lfs diff=lfs merge=lfs -text
+docs/figures/tier_pyramid.png filter=lfs diff=lfs merge=lfs -text
+images/compare_dataset.png filter=lfs diff=lfs merge=lfs -text
+images/compare_rl_env.png filter=lfs diff=lfs merge=lfs -text
+scripts/Screenshot[[:space:]]2026-04-20[[:space:]]at[[:space:]]6.50.47 PM.png filter=lfs diff=lfs merge=lfs -text
+server/static/figures/compare_dataset.png filter=lfs diff=lfs merge=lfs -text
+server/static/figures/compare_rl_env.png filter=lfs diff=lfs merge=lfs -text
+server/static/figures/grpo_final_per_step.png filter=lfs diff=lfs merge=lfs -text
+server/static/figures/grpo_optuna_trials_comparison.png filter=lfs diff=lfs merge=lfs -text
+server/static/figures/grpo_reward_curve.png filter=lfs diff=lfs merge=lfs -text
+server/static/figures/ministack_logo.png filter=lfs diff=lfs merge=lfs -text
+server/static/figures/sft_loss_curve.png filter=lfs diff=lfs merge=lfs -text

Blog.MD

@@ -0,0 +1,564 @@
+---
+title: "From Cloud Chaos to Capable Agents: Training an LLM SRE on 120+ AWS Tasks"
+thumbnail: docs/figures/blog_hero.png
+authors:
+  - user: Sizzing
+    name: Uday Kiran Padhy
+tags:
+  - reinforcement-learning
+  - openenv
+  - grpo
+  - agents
+  - rlve
+  - aws
+  - sft
+  - lora
+  - trl
+date: "2026-04-26"
+---
+
+![From Cloud Chaos to Capable Agents](docs/figures/blog_hero.png)
+
+# From Cloud Chaos to Capable Agents
+
+### Training an LLM SRE on 120+ AWS Tasks with SFT → GRPO
+
+> **TL;DR.** Cloud agents fail in production not because they don't know the commands — but because **state drifts, services hiccup, and reward signals get gamed.** We built an OpenEnv-compatible RL environment that simulates all three: 120+ AWS tasks across 5 difficulty tiers under chaos and drift, an **8-layer anti-reward-hacking stack**, and a SFT → GRPO pipeline with **8-way parallel multi-turn rollouts on a single GPU**. After training, format compliance hit **100%**, exact-match jumped **39% → 89%**, and intermediate-tier success climbed **81% → 87%** — all with a 3B-parameter base model on a free Colab runtime.
+
+| | |
+|---|---|
+| **Live demo**  | [sizzing-aws-rl-env.hf.space/web](https://sizzing-aws-rl-env.hf.space/web) |
+| **API docs**   | [sizzing-aws-rl-env.hf.space/docs](https://sizzing-aws-rl-env.hf.space/docs) (Swagger) · [/redoc](https://sizzing-aws-rl-env.hf.space/redoc) |
+| **HF Space**   | [huggingface.co/spaces/Sizzing/aws_rl_env](https://huggingface.co/spaces/Sizzing/aws_rl_env) |
+| **SFT adapter**| [Sizzing/aws-rl-sft-qwen25coder3b-adapter](https://huggingface.co/Sizzing/aws-rl-sft-qwen25coder3b-adapter) |
+| **GRPO adapter**| [Sizzing/aws-rl-grpo-qwen25coder3b-adapter](https://huggingface.co/Sizzing/aws-rl-grpo-qwen25coder3b-adapter) |
+| **Dataset**    | [Sizzing/aws-rl-sft](https://huggingface.co/datasets/Sizzing/aws-rl-sft) |
+| **GitHub**     | [github.com/udaykiranpadhy/aws-rl-env](https://github.com/udaykiranpadhy/aws-rl-env) |
+
+---
+
+## 1. The problem: why cloud-ops RL is hard
+
+Modern AI agents are increasingly asked to operate cloud infrastructure — provision resources, fix misconfigurations, respond to drift, lock down a leaky bucket at 2 a.m. To train such agents you need three things at once: a **realistic environment**, **reliable reward signals**, and **enough scale to make RL feasible**. The market currently forces a hard tradeoff:
+
+- **Real AWS** — production-fidelity, but **hundreds of dollars per training run**, impossible to reset cleanly, dangerous if the agent decides to delete prod.
+- **Toy emulators / vanilla LocalStack** — free and resettable, but they **don't behave like production AWS**: error codes drift, response shapes diverge, and the agent learns shortcuts that crumble on real cloud.
+
+There's a third trap that bites every RL practitioner who's tried this before: **reward hacking**. An agent that optimizes a naïve reward will discover that printing `"bucket created"` to stdout is way easier than actually creating a bucket, and its training curve will look great while its real success rate stays at zero.
+
+This project closes the gap. We built:
+
+1. **An OpenEnv-compatible RL environment** that speaks **real AWS CLI semantics**. The agent sends `aws s3 mb …`, `aws iam create-role …`, exactly the commands a human SRE would type.
+2. **A vendored, customized [MiniStack](https://github.com/srivenkat/MiniStack) simulator** that responds with production-equivalent JSON, runs locally for **zero cost**, supports 34 AWS services, and exposes a single-call state-introspection endpoint we added so the grader has cheap ground-truth access.
+3. **A 120+ task curriculum** across 5 tiers (warmup → expert) plus an adversarial drift track, with adaptive selection, mastery tracking, spaced repetition, chaos injection, and randomized drift mutations — every feature designed to keep the reward signal honest.
+4. **A complete SFT → GRPO training pipeline.** A 1,500-row synthetic dataset spanning 5 trajectory shapes, an 11-model base benchmark, LoRA fine-tuning, and TRL GRPO with multi-turn rollouts and Optuna hyperparameter search.
+5. **An 8-way parallel-rollout architecture.** Server-side MiniStack pool, client-side `GrpoPool`, in-process `MultiTurnEnvPool` — three coordinated layers that let G=8 concurrent rollouts run on one GPU **without state contamination**.
+
+This isn't another gym classic. It's grounded in real-world utility: **everything an SRE actually does on call.**
+
+---
+
+## 2. System architecture
+
+![System architecture](docs/figures/architecture_diagram.png)
+
+The whole environment ships as **one Docker container** that bundles a FastAPI server, a pool of MiniStack simulator instances, and the AWS CLI v2 binary. Nothing reaches the public internet at runtime.
+
+```
+┌────────────────────────────── Docker container ──────────────────────────────┐
+│                                                                              │
+│   FastAPI server  (port 8000)                                                │
+│   ├── OpenEnv router       /reset  /step  /state  /schema  /ws  /health      │
+│   ├── Web playground       /web   (Jinja2 + 40 AWS service icons)            │
+│   ├── env_factory          per-WS-session AwsRlEnvironment instance          │
+│   │                        (acquires a MiniStack port from MiniStackPool)    │
+│   └── Services                                                               │
+│       Curriculum · TaskGrader · ResourceVerifier · ChaosEngine · DriftEngine │
+│       HintProvider · EpisodeTracker · EnvironmentDesigner · …Strategy        │
+│                                                                              │
+│   MiniStack instances    :4566  :4567  :4568  …  :4566+POOL_SIZE-1           │
+│   (vendored at aws_infra/, started by the Dockerfile entrypoint)             │
+└──────────────────────────────────────────────────────────────────────────────┘
+                ▲                                  ▲
+                │ HTTP / WebSocket                 │ AWS CLI subprocess
+                │                                  │ (AWS_ENDPOINT_URL=http://localhost:4566+i)
+                │                                  │
+        ┌───────┴───────────┐              ┌───────┴───────────┐
+        │   RL Agent        │              │  AWS CLI commands │
+        │   (the agent)     │              │  (client.py)      │
+        └───────────────────┘              └───────────────────┘
+```
+
+### Episode lifecycle
+
+```mermaid
+flowchart LR
+    A([reset]) --> B[Curriculum<br/>picks task]
+    B --> C[Run<br/>setup_commands]
+    C --> D{drift<br/>task?}
+    D -->|yes| E[DriftEngine<br/>applies 2–3 mutations]
+    D -->|no| F[Initial<br/>observation]
+    E --> F
+    F --> G([step])
+    G --> H{starts<br/>with 'aws'?}
+    H -->|no| I[reject<br/>success=False]
+    H -->|yes| J[EnvironmentStrategy<br/>runs AWS CLI]
+    J --> K[EpisodeTracker<br/>records command]
+    K --> L[TaskGrader<br/>computes reward]
+    L --> M[ChaosEngine<br/>maybe mutates state]
+    M --> N{terminate?}
+    N -->|achieved or step ≥ MAX| O([done])
+    N -->|continue| G
+    I --> G
+```
+
+Three primitives — `reset`, `step`, `state` — exposed over HTTP and WebSocket. The OpenEnv contract gives any compatible trainer (TRL, TorchForge, SkyRL, Unsloth) a drop-in interface.
+
+Full mechanics in [server/README.md](server/README.md).
+
+---
+
+## 3. The curriculum: 124 tasks, 5 tiers, one priority formula
+
+![Curriculum tier pyramid](docs/figures/tier_pyramid.png)
+
+We didn't hand-author a fixed schedule. The `Curriculum` service runs a **single weighted-priority formula** that handles exploration, weakness-targeting, and forgetting prevention all at once:
+
+```
+score = novelty_bonus          # +100 if never attempted
+      + weakness_weight        # +50 × (1 − task_success_rate)
+      + spaced_rep_bonus       # +30 if a graduated task is "due" for re-test
+      − recency_penalty        # −20 if attempted in the last 2 episodes
+```
+
+Read that formula and you immediately know the schedule: never-seen tasks dominate at first; once attempted, weak ones rise; once mastered, they go on a re-test schedule with intervals `[3, 6, 12, 24, 48]` episodes; you never see the same task two episodes in a row. **Explainable. Auditable. Boring in the best sense.**
+
+### Mastery and tier promotion
+
+Every task carries a sliding 10-episode success window with `0.85` exponential decay. When that window's success rate crosses `0.7`, the task **graduates** — it stops appearing in the standard rotation but resurfaces on the spaced-rep schedule above. If a graduated task fails on re-test, it un-graduates and rejoins the pool. There are **two ways** to get promoted to the next tier:
+
+- **Standard path** — meet the tier's `min_episodes` AND `advance_rate` (0.6 – 0.7 depending on tier).
+- **Fast-track** — three consecutive episodes at ≥ 0.9 success. If you're crushing it, you skip ahead.
+
+![Curriculum progression](docs/figures/curriculum_progression.png)
+
+### What's in each tier
+
+| Tier | Tasks | Chaos | Grading strategy | What the agent must do |
+|------|------:|------:|------------------|------------------------|
+| Warmup | 25 | 10% | `command_match` | Emit the right service + operation. |
+| Beginner | 25 | 10% | `resource_creation` | Actually create a resource that ends up in MiniStack state. |
+| Intermediate | 25 | 20% | `multi_step` | Complete an ordered sequence (e.g., bucket → policy → versioning). |
+| Advanced | 25 | 30% | `multi_step + services` | Same, but **all** required services must be touched. |
+| Expert | 24 | 30% | `state_checks` | Pass arbitrary AWS CLI assertions on the final state. |
+| **Drift** | 9 | — | `state_checks` (auto-repair) | Detect and fix 2–3 random pre-applied mutations. |
+
+The full task pool is YAML-defined in [server/services/tasks/](server/services/tasks/) — judges can read or modify it without touching code.
+
+---
+
+## 4. Reward shaping and the 8-layer anti-reward-hacking stack
+
+> **This is the most novel part of the project.** Most environments trust the reward signal. This one assumes the agent will try to game it — and stops it eight different ways.
+
+### How reward is built up
+
+```mermaid
+flowchart TD
+    Start([step result]) --> Q1{task<br/>achieved?}
+    Q1 -->|yes| R1[reward = 1.0]
+    R1 --> CB{survived<br/>chaos?}
+    CB -->|yes| R2[× 1.05<br/>chaos bonus]
+    CB -->|no| R3[reward stays 1.0]
+    R2 --> HD[× 0.85^n<br/>hint decay]
+    R3 --> HD
+    Q1 -->|no| S1[reward = partial × 0.8]
+    S1 --> S2{progress<br/>increased?}
+    S2 -->|yes| S3[+ 0.1<br/>progress delta]
+    S2 -->|no| S4[no delta]
+    S3 --> S5{command<br/>failed?}
+    S4 --> S5
+    S5 -->|yes| S6[× 0.5<br/>error penalty]
+    S5 -->|no| S7[no penalty]
+    S6 --> S8[− 0.1 × rollback_count<br/>+ 0.02 × idempotent_retries]
+    S7 --> S8
+    S8 --> S9[clamp to 0.0–0.99<br/>1.0 reserved for completion]
+    S9 --> HD
+    HD --> End([final reward])
+```
+
+![Reward components](docs/figures/reward_components.png)
+
+The reward is **dense by design**: every step provides meaningful signal, not just terminal success. Rollbacks (create-then-delete cycles) are explicitly penalized. Graceful retries on "already exists" errors get a small bonus. **Operational discipline is baked into the reward**, not just task completion.
+
+### Five grading strategies, dispatched by tier
+
+A single grader can't fairly score "did you say `aws s3 mb`?" and "did the bucket end up with versioning enabled, encrypted, blocking public access, AND not deleted by accident?" so the `TaskGrader` polymorphs:
+
+| Tier | Strategy | Example assertion |
+|------|----------|-------------------|
+| Warmup | `command_match` | `command_contains: "s3 mb"` |
+| Beginner | `resource_creation` | `resource_exists: {service: s3, name: my-bucket}` |
+| Intermediate | `multi_step` | Ordered list of step criteria |
+| Advanced | `multi_step + services` | Same + `services: [s3, iam]` must all be touched |
+| Expert | `state_checks` | Arbitrary AWS CLI assertions on infra state |
+
+### The 8 defense layers
+
+```mermaid
+flowchart LR
+    Agent[Agent action] --> L1["①  Allow-list<br/>must start with 'aws '"]
+    L1 --> L2["②  Per-episode dedup<br/>op,resource credits once"]
+    L2 --> L3["③  Grader invisibility<br/>state-checks never seen by agent"]
+    L3 --> L4["④  No read-credit<br/>describe/list earn zero"]
+    L4 --> L5["⑤  Monotonic progress<br/>can't decrement to re-credit"]
+    L5 --> L6["⑥  Exact resource-name match<br/>my-bucket-2 ≠ my-bucket"]
+    L6 --> L7["⑦  Ground-truth via MiniStack<br/>not agent stdout"]
+    L7 --> L8["⑧  Final-state assertions<br/>jq-paths on live state"]
+    L8 --> Reward([Reward])
+```
+
+| # | Layer | Hack it defeats |
+|---|-------|------------------|
+| 1 | **Command allow-list** (`aws ` prefix only) | Shell escapes, fake stdout |
+| 2 | **Dedup of `(operation, resource)` per episode** | Spamming `s3 mb …` 50× to inflate a "completed steps" counter |
+| 3 | **Grader invisibility** | Reverse-engineering reward by reading state-check queries |
+| 4 | **No verification reward** | Running `aws s3 ls` to "prove" the bucket exists |
+| 5 | **Monotonic `partial_progress`** | Bouncing progress down then back up to re-earn credit |
+| 6 | **Exact resource-name validation** | Creating `my-test-bucket-2` instead of `my-test-bucket` |
+| 7 | **Ground-truth via `/_ministack/state`** | Forging stdout that looks successful when the resource doesn't exist |
+| 8 | **Final-state AWS CLI assertions** | Passing the steps but leaving prod broken |
+
+These layers **compose**. To hack the reward, the agent would have to defeat all eight independently — each one alone is a hard problem.
+
+### Chaos engine and drift engine
+
+The reward stack is hardened, but the env itself is also adversarial:
+
+- **Chaos** (`server/services/chaos.py`) — silent mid-episode mutations on services the task is touching. Probabilities scale by tier: 10% / 20% / 30%. Survive a chaotic episode and the reward is multiplied by **×1.05**.
+- **Drift** (`server/services/drift.py`) — for the 9 drift tasks, 2–3 random mutations from a per-task pool are applied **before** the agent sees the env. The agent must detect and repair them. Mutations are **randomized per episode** so the agent can't memorize a script.
+- **Hints** — three progressive levels available via `aws help --task-hint`. Each hint multiplies the final reward by `0.85` (so 3 hints → 0.61× decay). The agent decides whether the cost is worth it.
+
+Full mechanics, including all 5 grading strategies and the chaos/drift logic, are in [server/README.md §8 – §13](server/README.md).
+
+---
+
+## 5. Parallel rollout architecture: 3 coordinated pool layers
+
+GRPO needs `G=8` rollouts **on the same task** per training step — that's how it computes group-relative advantages without a critic. Run them sequentially and you pay 8 × 6 turns × 50 ms = **2,400 ms** of wall-clock per step, before the GPU has done anything. Run them in parallel and a state bug between two rollouts will silently destroy your gradient.
+
+So we built three coordinated pool layers that **parallelize transparently while guaranteeing state isolation**.
+
+```mermaid
+flowchart TD
+    T[Trainer step<br/>needs G=8 rollouts] --> M[MultiTurnEnvPool<br/>sync API · owns asyncio loop]
+    M --> G[GrpoPool<br/>async · asyncio.gather]
+    G --> WS1[WS session 1]
+    G --> WS2[WS session 2]
+    G --> WS3[WS session ...]
+    G --> WS8[WS session 8]
+    WS1 --> S[FastAPI server<br/>OpenEnv max_concurrent_envs=8]
+    WS2 --> S
+    WS3 --> S
+    WS8 --> S
+    S --> P[MiniStackPool<br/>free-list · threading.Lock]
+    P --> M1[:4566]
+    P --> M2[:4567]
+    P --> M3[:4568]
+    P --> M8[:4573]
+    style P fill:#fff7fa,stroke:#ff4f8b
+    style M fill:#fff7fa,stroke:#ff4f8b
+    style G fill:#fff7fa,stroke:#ff4f8b
+```
+
+![Parallel rollout architecture](docs/figures/parallel_rollout_diagram.png)
+
+### The three layers
+
+- **Server-side `MiniStackPool`** ([server/app.py](server/app.py)) — free-list of ports `[BASE, BASE + POOL_SIZE)`, lock-guarded `acquire()` / `release()`. Each WebSocket session gets a unique MiniStack process that persists for the session's lifetime. **8 isolated MiniStack instances on ports 4566–4573 mean zero cross-rollout state bleed.**
+- **Client-side async `GrpoPool`** ([scripts/grpo_pool.py](scripts/grpo_pool.py)) — pure-asyncio, uses `asyncio.gather` over N WebSocket sessions. Used by training and demo notebooks.
+- **In-process sync `MultiTurnEnvPool`** ([train/train_grpo_lora.ipynb](train/train_grpo_lora.ipynb)) — wraps `GrpoPool` behind a sync API by owning a background asyncio loop. The TRL trainer keeps its sync API; concurrency happens inside.
+
+### The all-or-nothing connect protocol
+
+Here's the surprising-detail callout, the kind a judge appreciates:
+
+> **If 7 of 8 WebSocket connects succeed and the 8th fails, all 8 must be rolled back and closed.**
+
+Why? Because the 7 successful connects already acquired MiniStack ports from the server-side pool. If we kept them open and just retried the 8th, those 7 ports would leak — they stay acquired until the server's idle timeout fires (minutes), and the next training step finds the pool exhausted.
+
+This single invariant is the difference between *"training resumes cleanly after every flake"* and *"every flake corrupts the pool; rebuild the container at 3 a.m."*
+
+![8 simultaneous WebSocket sessions](docs/figures/env_init_screenshot.png)
+
+### Wall-clock impact
+
+- **Sequential**: 8 rollouts × 6 turns × ~50 ms env time = **2,400 ms / GRPO step**.
+- **Parallel (8-way)**: max(8 envs) ≈ **300 ms / GRPO step**.
+- **Effective speedup**: ~8× on the env side. The GPU forward-pass still serializes behind a `threading.Lock`, but env time is no longer the bottleneck.
+
+Full details, including all the corner cases of the all-or-nothing protocol, are in [scripts/README.md](scripts/README.md).
+
+---
+
+## 6. MiniStack: vendored, customized, reproducible
+
+The simulator powering the env is **vendored as a git subtree** at [aws_infra/](aws_infra/), not pulled as a black-box dependency. Why fork a perfectly good upstream?
+
+1. **One-call grading**. We added a custom `/_ministack/state` endpoint (commit `a648c3a`) that returns the entire infrastructure inventory in **one HTTP call** instead of iterating 20+ list APIs per grading pass. This single endpoint is what makes layer 7 of the anti-hacking stack cheap enough to run every step.
+2. **Reproducible Docker builds with no runtime network**. Pinning a specific MiniStack revision means the image is bit-identical across rebuilds. The Docker image bundles the simulator; it doesn't pull at startup.
+3. **Freedom to extend service coverage** when a task needs a service the upstream doesn't yet support.
+
+The custom commits are kept as **small, isolated patches** so periodic upstream syncs (e.g., `af2e945`, `579597b`) replay cleanly with `git subtree pull`. To inspect:
+
+```bash
+git show a648c3a               # the state-endpoint diff
+git log --oneline -- aws_infra/  # only the aws_infra subtree history
+```
+
+This is a small thing, but it's one of those engineering-maturity signals that says **"this repo is built to be maintained, not just demoed."** The full subtree workflow is in [server/README.md §5](server/README.md#5-ministack-vendored-fork--customizations).
+
+---
+
+## 7. The training pipeline: SFT → GRPO
+
+```mermaid
+flowchart LR
+    TT[tests_tasks/<br/>134 canonical solutions] --> AST[AST extract<br/>build_sft_dataset.py]
+    AST --> DS[1,500 row<br/>SFT dataset<br/>5 trajectory types]
+    DS -.->|published| HF1[(HF Dataset<br/>aws-rl-sft)]
+    DS --> SFT[Stage 1: SFT LoRA<br/>Qwen2.5-Coder-3B<br/>Optuna 6 trials]
+    SFT --> SA[SFT adapter]
+    SA -.->|published| HF2[(HF Hub<br/>aws-rl-sft-adapter)]
+    SA --> GRPO[Stage 2: GRPO<br/>TRL · G=8 rollouts<br/>Optuna 4 trials]
+    ENV[(AWS RL Env<br/>FastAPI + MiniStack pool)] --> GRPO
+    GRPO --> GA[GRPO adapter]
+    GA -.->|published| HF3[(HF Hub<br/>aws-rl-grpo-adapter)]
+    style ENV fill:#fff7fa,stroke:#ff4f8b
+    style HF1 fill:#fffbeb,stroke:#f59e0b
+    style HF2 fill:#fffbeb,stroke:#f59e0b
+    style HF3 fill:#fffbeb,stroke:#f59e0b
+```
+
+Two stages, both reproducible on a free Colab GPU runtime. Full detail in [train/README.md](train/README.md).
+
+### 7.1 Dataset — 1,500 deterministic synthetic rows
+
+![SFT dataset composition](docs/figures/dataset_composition.png)
+
+The dataset is **synthetic but deterministic** — and that's not an oxymoron. We don't run pytest to generate examples; we use Python's `ast` module to extract canonical commands directly from `tests_tasks/test_<tier>_tasks.py`. **No simulator spin-up. Zero flake risk. Bit-for-bit reproducible** with one script.
+
+Five trajectory types teach realistic multi-turn behavior:
+
+- **Success (55%)** — the canonical command for the task.
+- **Multi-step continuation (20%)** — given the partial conversation, predict the next command. Simulated AWS responses are interpolated with resource names, so the model learns *"what you do depends on what's already been done"*, not *"always run the first command"*.
+- **Failure recovery (15%)** — on a malformed AWS error, fix the command.
+- **Verification (5%)** — pick the right `aws describe-*` to confirm state.
+- **Hint usage (5%)** — given a hint, follow it.
+
+Tier weighting is **50/30/15/5/0** (warmup / beginner / intermediate / advanced / expert). **Expert is intentionally excluded from SFT** — expert tasks have randomized state checks, so there's no single canonical script. Teaching SFT a fixed solution would be wrong; GRPO's reward signal is the right tool for randomized end-states.
+
+Published as [Sizzing/aws-rl-sft](https://huggingface.co/datasets/Sizzing/aws-rl-sft).
+
+### 7.2 Base model selection — 11 candidates, 1 winner
+
+![Top-4 candidate models on the held-out benchmark](docs/figures/model_eval_chart.png)
+
+We didn't pick a base model on vibes. **11 chat models × 27 held-out prompts**, four quality metrics plus latency. Full report in [data/sft/MODEL_EVALUATION.md](data/sft/MODEL_EVALUATION.md).
+
+| Model | exact% | op% | latency | Verdict |
+|-------|------:|----:|--------:|---------|
+| **Qwen2.5-Coder-3B-Instruct** ✅ | **41%** | **63%** | **3.1 s** | Best balance of accuracy and speed |
+| Qwen3-4B | 33% | 59% | 10.4 s | Perfect format, but 3× slower |
+| Qwen2.5-Coder-1.5B | 22% | 41% | 2.5 s | Fast, but 19-pp accuracy gap |
+| SmolLM2-1.7B | 7% | 19% | 2.0 s | Too small for AWS knowledge |
+| DeepSeek-R1-Distill-Qwen-1.5B | 0% | 4% | 6.8 s | Wrong domain — reasoning ≠ AWS |
+
+**Winner: [unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit](https://huggingface.co/unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit)** — 41% exact-match, 63% operation-match, 3.1 s latency. Small enough for 8-way parallel GRPO on a 24 GB GPU; accurate enough that SFT has a strong starting point.
+
+### 7.3 Stage 1 — SFT (LoRA)
+
+LoRA, attention-only, ~10–40M trainable parameters. We let Optuna sweep 6 trials over `[lora_r, lora_alpha_mul, lora_dropout, learning_rate, warmup_ratio]`:
+
+| Hyperparameter | Search space | Best value |
+|---------------|--------------|-----------:|
+| `lora_r` | {8, 16, 32} | **16** |
+| `lora_alpha_mul` | [0.5, 2.0] | **1.0** (α = 16) |
+| `lora_dropout` | [0.005, 0.031] | **0.0058** |
+| `learning_rate` | [5e-5, 5e-4] | **4.03e-4** |
+| `warmup_ratio` | [0.05, 0.15] | **0.10** |
+
+![SFT loss curve](docs/figures/sft_loss_curve.png)
+
+![Optuna parameter importance](docs/figures/optuna_param_importance.png)
+![Optuna optimization history](docs/figures/optuna_history.png)
+
+Best trial reached **val loss 0.052 after 188 steps** (~30 min on a Colab A10). Adapter published: [Sizzing/aws-rl-sft-qwen25coder3b-adapter](https://huggingface.co/Sizzing/aws-rl-sft-qwen25coder3b-adapter).
+
+### 7.4 Stage 2 — GRPO (TRL)
+
+GRPO is a critic-free RL algorithm that computes advantages from a **group of G rollouts** on the same prompt. TRL's `GRPOTrainer` is the implementation; we wrap it with our `MultiTurnEnvPool` so each "rollout" is a multi-turn AWS CLI episode, not a single completion.
+
+```python
+GRPOConfig(
+    model_name_or_path="Sizzing/aws-rl-sft-qwen25coder3b-adapter",
+    num_generations=8,           # G=8 rollouts per step
+    beta=0.0021,                 # KL coefficient (tight — Optuna picked it)
+    learning_rate=1.6e-5,
+    temperature=0.99,
+    top_p=0.95,
+    max_turns=6,                 # multi-turn episode length
+    loss_type="dapo",
+    reward_func=env_reward,      # AwsRlEnv → final reward
+)
+```
+
+Optuna swept 4 trials over `[learning_rate, beta, temperature]` — a tighter 3-parameter space because we already had a strong SFT baseline.
+
+![GRPO Optuna trials comparison](docs/figures/grpo_optuna_trials_comparison.png)
+![GRPO Optuna parameter importances](docs/figures/grpo_optuna_importances.png)
+![GRPO Optuna optimization history](docs/figures/grpo_optuna_history.png)
+
+Final run: **35 GRPO steps, ~1.5 hours on Colab A10**.
+
+![GRPO per-step training signals](docs/figures/grpo_final_per_step.png)
+![GRPO env reward over training](docs/figures/grpo_reward_curve.png)
+![GRPO per-tier reward curve](docs/figures/grpo_per_tier_curve.png)
+
+Adapter published: [Sizzing/aws-rl-grpo-qwen25coder3b-adapter](https://huggingface.co/Sizzing/aws-rl-grpo-qwen25coder3b-adapter).
+
+---
+
+## 8. Results
+
+### 8.1 Base vs SFT — single-step held-out eval
+
+After running the SFT pipeline end-to-end, the eval delta on the same held-out prompts is striking:
+
+| Metric          |   Base | Post-SFT | Δ            |
+|-----------------|-------:|---------:|:------------:|
+| `format_pct`    |  33.3% | **100.0%** | **+66.7 pp** |
+| `exact_pct`     |  38.9% | **88.9%**  | **+50.0 pp** |
+| `service_pct`   |  77.8% | **88.9%**  | +11.1 pp     |
+| `operation_pct` |  61.1% | **88.9%**  | +27.8 pp     |
+| `avg_len`       |   85.8 |    74.7    | −11 chars (tighter) |
+
+![Base vs SFT eval-metrics comparison](docs/figures/base_vs_sft_success.png)
+![Single-step eval, base vs SFT](docs/figures/single_step_eval.png)
+![Dataset comparison: base vs SFT](docs/figures/compare_dataset.png)
+
+Every target from [data/sft/MODEL_EVALUATION.md §11](data/sft/MODEL_EVALUATION.md#11-target-metrics-for-sft) is met or exceeded. **Format compliance is now perfect**; the model never wraps commands in fences or quotes after SFT. **Exact-match jumped from 39% to 89%** — the agent now emits the canonical command for ~9 of every 10 prompts.
+
+### 8.2 SFT vs GRPO — multi-step live env eval (100+ episodes)
+
+This is the harder benchmark. We let the SFT and GRPO adapters loose on the live RL environment for 100+ episodes each:
+
+| Metric                         | SFT     | SFT + GRPO | Δ            |
+|-------------------------------:|:-------:|:----------:|:------------:|
+| Overall success rate           | 86.8%   | 86.2%      | −0.5 pp      |
+| Overall mean reward            | 0.883   | 0.877      | −0.006       |
+| Beginner success               | 96.2%   | **100.0%** | **+3.8 pp**  |
+| **Intermediate success**       | 81.0%   | **87.0%**  | **+6.0 pp**  |
+| Warmup success                 | 96.0%   | 90.2%      | −5.8 pp      |
+| Expert success                 | 22.2%   | 22.2%      | flat         |
+| Drift repair rate              | 22.2%   | 22.2%      | flat         |
+| Destructive-action fail rate   | 15.1%   | 14.7%      | −0.4 pp      |
+| Steps to solve                 | 1.45    | 1.55       | +0.10        |
+
+![SFT vs GRPO metrics grid](docs/figures/sft_vs_grpo_metrics_grid.png)
+![SFT vs GRPO by tier](docs/figures/sft_vs_grpo_by_tier.png)
+![SFT vs GRPO scalar comparison](docs/figures/sft_vs_grpo_scalar.png)
+![RL env comparison: base vs SFT (per-episode rewards)](docs/figures/compare_rl_env.png)
+
+> **Honest reading.** GRPO **preserves the SFT gains** and **modestly improves the middle tiers** (beginner +3.8 pp, intermediate +6.0 pp). It does **not crack the expert-tier bottleneck** — 22% on SRE / drift / security-posture tasks, flat from SFT. With longer GRPO runs and an expert-weighted curriculum, this is the next gain to chase. We're calling this out directly because credibility matters more than a clean win-bar.
+
+### 8.3 Qualitative rollouts
+
+One sample episode per tier, post-GRPO:
+
+![Qualitative rollouts on representative tasks](docs/figures/qualitative_rollouts.png)
+
+The full notebook with side-by-side base / SFT / GRPO transcripts is at [compare/compare_base_vs_sft.ipynb](compare/compare_base_vs_sft.ipynb).
+
+---
+
+## 9. Reproducibility
+
+Everything in this blog runs from three Colab notebooks. **No private dependencies, no purchased compute, no leaked state.**
+
+| Notebook | What it does | Open |
+|---|---|---|
+| [train/train_sft_lora.ipynb](train/train_sft_lora.ipynb) | Stage 1 — SFT LoRA fine-tune | [Colab](https://colab.research.google.com/drive/1dm9sDaLxHX6s9zEG_SC0FQcKWKkc3TfL?usp=sharing) |
+| [train/train_grpo_lora.ipynb](train/train_grpo_lora.ipynb) | Stage 2 — GRPO multi-turn rollouts | [Colab](https://colab.research.google.com/drive/1NwiOM0h_JpXXGRxfY_xZtDiaigvIaKjx?usp=sharing) |
+| [compare/compare_base_vs_sft.ipynb](compare/compare_base_vs_sft.ipynb) | Side-by-side base vs SFT (dataset + RL env) | [Colab](https://colab.research.google.com/drive/17406aiad8h4nAphV42vVNZ-a5SzZMIre?usp=sharing) |
+
+**Local dev** is one command:
+
+```bash
+make docker-run             # FastAPI + MiniStack on :8000
+
+# 8-way parallel rollouts for training:
+AWS_RL_ENV_POOL_SIZE=8 make run
+```
+
+**The test suite** is also the canonical-solution source. 10 unit tests + 134 tier-integration tests, where each integration test is an AST-extractable solution for the SFT dataset:
+
+```bash
+pytest tests/ tests_tasks/ -v
+```
+
+| Path | What it covers |
+|------|----------------|
+| [tests/test_task_grader.py](tests/test_task_grader.py) | All 5 grading strategies + every penalty/bonus |
+| [tests/test_resource_verifier.py](tests/test_resource_verifier.py) | Per-service ground-truth verification (20+ services) |
+| [tests/test_pool.py](tests/test_pool.py) · [test_grpo_pool.py](tests/test_grpo_pool.py) | All-or-nothing connect protocol |
+| [tests/test_drift_engine.py](tests/test_drift_engine.py) | Random drift selection + mutation application |
+| [tests_tasks/test_*_tasks.py](tests_tasks/) | 134 tasks exercised end-to-end against MiniStack |
+
+All artifacts are on the Hub (dataset, SFT adapter, GRPO adapter, Space). A judge can fork this repo and re-run the entire pipeline in a few hours.
+
+---
+
+## 10. What's next
+
+The expert-tier bottleneck (22% success on state-check / drift / security-posture tasks) is the single biggest target:
+
+- **Longer GRPO runs** — 35 steps is short by RL standards. We'd expect compounded improvements from 200–500 steps with the same config.
+- **Expert-weighted curriculum** — currently the priority formula doesn't preferentially upweight expert tasks; with a small bias term we'd see more expert exposure per step.
+- **DPO on expert trajectories** — preference pairs (good vs bad expert solves) might shape multi-step expert behavior more efficiently than scalar reward.
+- **Real-AWS strategy backend** — `BACKEND_TYPE=aws` is wired and ready. Cost-budgeted eval runs against a sandboxed real account would close the sim-to-real gap once and for all.
+
+PRs welcome at [github.com/udaykiranpadhy/aws-rl-env](https://github.com/udaykiranpadhy/aws-rl-env). The env is OpenEnv-compliant, so any TRL / TorchForge / SkyRL / Unsloth user can plug in tomorrow.
+
+---
+
+## 11. Acknowledgments
+
+Thank you to:
+
+- **MiniStack** — vendored at [aws_infra/](aws_infra/), upstream license preserved. Custom modifications are commits `a648c3a`, `a00e981`; periodic upstream syncs `af2e945`, `579597b`.
+- **OpenEnv** — environment protocol and Python client framework that this entire project plugs into.
+- **TRL** (Hugging Face) — `GRPOTrainer` implementation and the rest of the post-training stack.
+- **Unsloth** — 4-bit quantized model loaders and fused training kernels that fit a 3B model + 8 rollouts on 24 GB.
+- **Optuna** — TPE sampler that found the SFT and GRPO hyperparameters without us having to.
+- **Google Colab** — free GPU runtime for the full training pipeline.
+- **AWS service icons** in [server/static/img/aws/](server/static/img/aws/) — used in the web playground.
+
+---
+
+### Sub-README index — for the deeper dives
+
+| Path | What it covers |
+|------|----------------|
+| [server/README.md](server/README.md) | Environment internals — curriculum, reward shaping, anti-hacking, chaos, drift, MiniStack-fork detail |
+| [train/README.md](train/README.md) | SFT + GRPO pipeline — LoRA config, Optuna search, multi-turn rollouts |
+| [scripts/README.md](scripts/README.md) | Parallel-rollout architecture — 3 pool layers, all-or-nothing connect, concurrency safety |
+| [data/README.md](data/README.md) | Dataset generation — 5 trajectory types, AST extraction, base-model selection summary |
+| [data/sft/MODEL_EVALUATION.md](data/sft/MODEL_EVALUATION.md) | Full 11-model benchmark report — methodology, per-model verdicts |
+| [compare/README.md](compare/README.md) | Base vs SFT comparison harness |
+| [aws_infra/README.md](aws_infra/README.md) | Vendored MiniStack upstream documentation |
+
+---
+
+### Small Explanation Video
+- [Recorded Video](https://share.zight.com/NQu0pLvQ)

Dockerfile

@@ -0,0 +1,119 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=aws_rl_env
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+    curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    mv /root/.local/bin/uv /usr/local/bin/uv && \
+    mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+    uv sync --frozen --extra dev --no-install-project --no-editable; \
+    else \
+    uv sync --extra dev --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+    uv sync --frozen --extra dev --no-editable; \
+    else \
+    uv sync --extra dev --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the uv-managed Python interpreter from builder
+COPY --from=builder /root/.local/share/uv/python /root/.local/share/uv/python
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Install AWS CLI
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends awscli && \
+    rm -rf /var/lib/apt/lists/*
+
+# Configure AWS CLI to point to MiniStack (vendored at aws_infra/) and use dummy credentials
+RUN mkdir -p /root/.aws && \
+    printf '[default]\nregion = us-east-1\noutput = json\n' > /root/.aws/config && \
+    printf '[default]\naws_access_key_id = test\naws_secret_access_key = test\n' > /root/.aws/credentials
+ENV AWS_ENDPOINT_URL=http://localhost:4566
+
+# Enable the web interface for OpenEnv (if applicable)
+ENV ENABLE_WEB_INTERFACE=true
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+ENV AWS_RL_ENV_POOL_SIZE=8
+ENV AWS_RL_ENV_MINISTACK_BASE_PORT=4566
+# Dedicated port for the web playground's lazily-spawned MiniStack.
+# Kept outside the pool's range so a WebSocket session can never claim it.
+ENV AWS_RL_ENV_WEB_MINISTACK_PORT=4565
+
+# DEV_MODE=1 enables live reload via --reload flag
+ENV DEV_MODE=0
+
+ENV API_BASE_URL=https://router.huggingface.co/v1
+ENV MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
+
+# Entrypoint: start N MiniStack instances (AWS_RL_ENV_POOL_SIZE, default 1),
+# then run the FastAPI server. Each MiniStack listens on a distinct port
+# starting at AWS_RL_ENV_MINISTACK_BASE_PORT (default 4566).
+# The web playground's MiniStack on AWS_RL_ENV_WEB_MINISTACK_PORT is NOT
+# started here — the FastAPI server spawns it lazily on the first /web/*
+# request so training-only deployments pay zero cost.
+# cloudflared tunnel --url localhost:8000
+CMD ["sh", "-c", "\
+  POOL_SIZE=\"${AWS_RL_ENV_POOL_SIZE:-1}\"; \
+  BASE_PORT=\"${AWS_RL_ENV_MINISTACK_BASE_PORT:-4566}\"; \
+  i=0; while [ \"$i\" -lt \"$POOL_SIZE\" ]; do \
+    GATEWAY_PORT=$((BASE_PORT + i)) ministack -d; \
+    i=$((i + 1)); \
+  done; \
+  sleep 3; \
+  uvicorn server.app:app --host 0.0.0.0 --port 8000 $([ \"$DEV_MODE\" = '1' ] && echo '--reload --reload-dir /app/env') \
+"]

Makefile

@@ -0,0 +1,187 @@
+# Load .env if present so Make sees every KEY=value in it, both as $(VAR)
+# inside the Makefile and as an environment variable exported to recipes.
+# Precedence (highest → lowest):
+#   1. CLI:           make run POOL_SIZE=16
+#   2. Shell env:     POOL_SIZE=16 make run
+#   3. .env file:     AWS_RL_ENV_POOL_SIZE=16 in ./.env
+#   4. Makefile default (via ?=)
+# Create one by copying the template:  cp .env.example .env
+ifneq (,$(wildcard ./.env))
+    include .env
+    export
+endif
+
+# Project settings
+PROJECT_NAME := openenv-aws_rl_env
+PYTHON := python3
+UV := uv
+DOCKER_IMAGE := aws-rl-env
+DOCKER_TAG := latest
+SERVER_HOST := 0.0.0.0
+SERVER_PORT := 8000
+
+# Parallel MiniStack pool (used by `make run`).
+#   POOL_SIZE=1           → single MiniStack on MINISTACK_BASE_PORT (legacy behavior)
+#   POOL_SIZE>1           → N MiniStacks on MINISTACK_BASE_PORT..BASE_PORT+N-1,
+#                           server exposes N concurrent WebSocket sessions
+# Override from CLI: `make run POOL_SIZE=8` or `POOL_SIZE=8 make run`.
+POOL_SIZE ?= $(or $(AWS_RL_ENV_POOL_SIZE),1)
+MINISTACK_BASE_PORT ?= $(or $(AWS_RL_ENV_MINISTACK_BASE_PORT),4566)
+
+.DEFAULT_GOAL := help
+
+# ──────────────────────────────────────────────
+# Setup & Dependencies
+# ──────────────────────────────────────────────
+
+.PHONY: install
+install: ## Install project dependencies
+	$(UV) sync --frozen
+
+.PHONY: install-dev
+install-dev: ## Install project with dev dependencies
+	$(UV) sync --frozen --extra dev
+
+
+.PHONY: install-all
+install-all: ## Install project with all dependencies (dev + training)
+	$(UV) sync --frozen --all-extras
+
+.PHONY: lock
+lock: ## Update the lockfile
+	$(UV) lock
+
+# ──────────────────────────────────────────────
+# Development
+# ──────────────────────────────────────────────
+
+.PHONY: run
+run: ## Run MiniStack pool + FastAPI server. Env: POOL_SIZE (default 1), MINISTACK_BASE_PORT (default 4566)
+	@echo "==> Starting $(POOL_SIZE) MiniStack(s) on ports $(MINISTACK_BASE_PORT)..$$(($(MINISTACK_BASE_PORT) + $(POOL_SIZE) - 1))"
+	@for i in $$(seq 0 $$(($(POOL_SIZE) - 1))); do \
+		port=$$(($(MINISTACK_BASE_PORT) + $$i)); \
+		echo "    MiniStack :$$port"; \
+		GATEWAY_PORT=$$port ministack -d; \
+	done
+	@sleep 2
+	@echo "==> FastAPI server on $(SERVER_HOST):$(SERVER_PORT) (POOL_SIZE=$(POOL_SIZE))"
+	AWS_RL_ENV_POOL_SIZE=$(POOL_SIZE) \
+	AWS_RL_ENV_MINISTACK_BASE_PORT=$(MINISTACK_BASE_PORT) \
+	$(UV) run uvicorn server.app:app --host $(SERVER_HOST) --port $(SERVER_PORT) --reload
+
+.PHONY: run-stop
+run-stop: ## Stop every MiniStack started by `make run` (uses current POOL_SIZE + MINISTACK_BASE_PORT)
+	@for i in $$(seq 0 $$(($(POOL_SIZE) - 1))); do \
+		port=$$(($(MINISTACK_BASE_PORT) + $$i)); \
+		echo "    stopping MiniStack :$$port"; \
+		GATEWAY_PORT=$$port ministack --stop || true; \
+	done
+
+# ──────────────────────────────────────────────
+# Code Quality
+# ──────────────────────────────────────────────
+
+.PHONY: format
+format: ## Format code with ruff
+	$(UV) run ruff format .
+
+.PHONY: lint
+lint: ## Lint code with ruff
+	$(UV) run ruff check .
+
+.PHONY: lint-fix
+lint-fix: ## Lint and auto-fix code with ruff
+	$(UV) run ruff check --fix .
+
+.PHONY: typecheck
+typecheck: ## Run type checking with mypy
+	$(UV) run mypy
+
+.PHONY: check
+check: lint typecheck
+
+# ──────────────────────────────────────────────
+# Docker
+# ──────────────────────────────────────────────
+
+.PHONY: docker-build
+docker-build: ## Build Docker image
+	docker build -t $(DOCKER_IMAGE):$(DOCKER_TAG) .
+
+.PHONY: docker-run
+docker-run: ## Run Docker container
+	docker run --rm --name $(DOCKER_IMAGE) -p $(SERVER_PORT):8000 $(DOCKER_IMAGE):$(DOCKER_TAG)
+
+.PHONY: docker-run-dev
+docker-run-dev: ## Run Docker container in dev mode with live reload
+	docker run --rm --name $(DOCKER_IMAGE) -p $(SERVER_PORT):8000 -v $(PWD):/app/env -v /app/env/.venv -e DEV_MODE=1 $(DOCKER_IMAGE):$(DOCKER_TAG)
+
+.PHONY: docker-run-detach
+docker-run-detach: ## Run Docker container in background
+	docker run -d --rm --name $(DOCKER_IMAGE) -p $(SERVER_PORT):8000 -v $(PWD):/app/env -v /app/env/.venv -e DEV_MODE=1 $(DOCKER_IMAGE):$(DOCKER_TAG)
+
+.PHONY: docker-stop
+docker-stop: ## Stop the running Docker container
+	docker stop $(DOCKER_IMAGE)
+
+.PHONY: docker-logs
+docker-logs: ## Tail logs from the running Docker container
+	docker logs -f $(DOCKER_IMAGE)
+
+.PHONY: docker-shell
+docker-shell: ## Open a shell in the running Docker container
+	docker exec -it $(DOCKER_IMAGE) /bin/bash
+
+.PHONY: docker-clean
+docker-clean: ## Stop and remove all running containers for this image
+	@docker ps -q --filter ancestor=$(DOCKER_IMAGE):$(DOCKER_TAG) | xargs -r docker rm -f
+
+.PHONY: docker-test
+docker-test: ## Run tests inside the running Docker container
+	docker exec $(DOCKER_IMAGE) python -m pytest env/tests -v
+
+.PHONY: docker-health
+docker-health: ## Check health of the running container
+	@curl -sf http://localhost:$(SERVER_PORT)/health && echo " OK" || echo " FAIL"
+
+# ──────────────────────────────────────────────
+# OpenEnv
+# ──────────────────────────────────────────────
+
+.PHONY: openenv-validate
+openenv-validate: ## Validate the OpenEnv configuration
+	openenv validate
+
+.PHONY: openenv-build
+openenv-build: ## Build the environment using OpenEnv CLI
+	openenv build
+
+.PHONY: openenv-push
+openenv-push: ## Push the environment to Hugging Face Spaces
+	openenv push
+
+# ──────────────────────────────────────────────
+# Cleanup
+# ──────────────────────────────────────────────
+
+.PHONY: clean
+clean: ## Remove build artifacts and caches
+	rm -rf build/ dist/ *.egg-info .eggs/
+	rm -rf aws_infra/*.egg-info aws_infra/build/ aws_infra/dist/
+	rm -rf .pytest_cache/ .mypy_cache/ .ruff_cache/
+	rm -rf htmlcov/ .coverage coverage.xml
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name '*.pyc' -delete 2>/dev/null || true
+
+.PHONY: clean-all
+clean-all: clean ## Remove all artifacts including venv
+	rm -rf .venv/
+
+# ──────────────────────────────────────────────
+# Help
+# ──────────────────────────────────────────────
+
+.PHONY: help
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

README.md

@@ -1,10 +1,718 @@
 ---
-title: Aws Rl Env
-emoji: 🦀
-colorFrom: green
-colorTo: red
+title: AWS RL Environment Server
+emoji: 🥇
+colorFrom: pink
+colorTo: pink
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# AWS Cloud Operations — RL Environment & Training Pipeline
+
+> Cloud agents fail in production not because they don’t know the commands — but because state drifts, services hiccup, and reward signals get gamed. We built an environment that simulates all three: 120+ AWS tasks under chaos and drift, an 8-layer anti-reward-hacking stack, and an adversarial curriculum that targets the agent’s own weak spots. After SFT → GRPO on a single GPU with 8 parallel rollouts, format compliance hit 100%, exact-match jumped 39% → 89%, and intermediate-tier success climbed 81% → 87%.
+
+| | |
+|---|---|
+| **Live demo** | [sizzing-aws-rl-env.hf.space/web](https://sizzing-aws-rl-env.hf.space/web) — try the playground in a browser |
+| **API docs**  | [sizzing-aws-rl-env.hf.space/docs](https://sizzing-aws-rl-env.hf.space/docs) (Swagger), [/redoc](https://sizzing-aws-rl-env.hf.space/redoc) |
+| **HF Space**  | [huggingface.co/spaces/Sizzing/aws_rl_env](https://huggingface.co/spaces/Sizzing/aws_rl_env) |
+| **SFT adapter**| [Sizzing/aws-rl-sft-qwen25coder3b-adapter](https://huggingface.co/Sizzing/aws-rl-sft-qwen25coder3b-adapter) |
+| **Dataset**   | [Sizzing/aws-rl-sft](https://huggingface.co/datasets/Sizzing/aws-rl-sft) |
+
+---
+
+## Table of contents
+
+1. [What this is & why it matters](#1-what-this-is--why-it-matters)
+2. [Highlights — full feature inventory](#2-highlights--full-feature-inventory)
+3. [Architecture](#3-architecture)
+4. [Live demo & Quick Start](#4-live-demo--quick-start)
+5. [Run on Colab](#5-run-on-colab)
+6. [Action / Observation spec](#6-action--observation-spec)
+7. [Curriculum & Reward (overview)](#7-curriculum--reward-overview)
+8. [Training pipeline (SFT → GRPO)](#8-training-pipeline-sft--grpo)
+9. [Parallel rollout architecture](#9-parallel-rollout-architecture)
+10. [MiniStack: vendored & customized](#10-ministack-vendored--customized)
+11. [Results & Benchmarks](#11-results--benchmarks)
+12. [Repository map](#12-repository-map)
+13. [Configuration & Running](#13-configuration--running)
+14. [Testing](#14-testing)
+15. [Tech stack](#15-tech-stack)
+16. [Links](#16-links)
+17. [Acknowledgments](#17-acknowledgments)
+
+---
+
+## 1. What this is & why it matters
+
+Modern AI agents are increasingly asked to operate cloud infrastructure — provisioning resources, fixing misconfigurations, responding to drift. Training such agents needs (a) a realistic environment, (b) reliable reward signals, and (c) enough scale to make RL feasible. Existing options force a hard tradeoff: real AWS costs hundreds of dollars per training run and is impossible to reset; toy emulators don't behave like production AWS.
+
+**This project closes that gap.** We built:
+
+1. **An OpenEnv-compatible RL environment** that speaks real AWS CLI semantics. The agent sends `aws s3 mb …`, `aws iam create-role …`, and so on — the exact same commands a human SRE would type.
+2. **A vendored, customized MiniStack simulator** that responds with production-equivalent JSON, runs locally for zero cost, supports 34 AWS services, and exposes a single-call state-introspection endpoint we added so the grader has cheap ground-truth access.
+3. **A 120+ task curriculum** across 5 tiers (warmup → expert) with adaptive selection, mastery tracking, spaced repetition, chaos injection, and drift-detection scenarios — every feature designed to keep the reward signal honest and prevent the agent from gaming it.
+4. **A complete SFT → GRPO training pipeline.** A 1,500-row synthetic dataset spanning 5 trajectory shapes, an 11-model base benchmark, LoRA fine-tuning, and TRL GRPO with multi-turn rollouts and Optuna hyperparameter search.
+5. **An 8-way parallel-rollout architecture.** Server-side MiniStack pool, client-side `GrpoPool`, in-process `MultiTurnEnvPool` — three coordinated layers that let G=8 concurrent rollouts run on one GPU without state contamination.
+
+Everything is reproducible: the dataset is generated by a deterministic script, the model selection is documented end-to-end, training entry points run on Colab, and the env runs locally in a single Docker container with no external network requirement.
+
+---
+
+## 2. Highlights — full feature inventory
+
+This is the complete surface area of the project. Each entry links to deeper documentation in the corresponding sub-README.
+
+### Environment & Curriculum
+- **[120+ tasks across 5 tiers](server/services/tasks/)** — warmup (25), beginner (25), intermediate (25), advanced (25), expert (24), drift (9). YAML-defined task spec per tier.
+- **[Curriculum learning with priority scoring](server/README.md#7-curriculum-manager)** — `score = novelty + weakness − recency + spaced_rep_bonus` drives task selection.
+- **[Mastery tracking](server/README.md#7-curriculum-manager)** — sliding 10-episode window, 0.7 threshold, 0.85 exponential decay, supports un-graduation.
+- **[Spaced repetition](server/README.md#7-curriculum-manager)** — graduated tasks resurface at intervals `[3, 6, 12, 24, 48]` to prevent forgetting.
+- **[Tier promotion](server/README.md#7-curriculum-manager)** — standard (min episodes + success rate) + fast-track (3 consecutive ≥90% episodes).
+- **[Strategy pattern: simulator vs real AWS](server/README.md#4-strategy-pattern-simulator-vs-real-aws)** — `BACKEND_TYPE=simulator` (default) or `aws`, no code fork.
+
+### Reward shaping
+- **[Five grading strategies](server/README.md#8-reward-shaping--taskgrader)** — command-match (warmup), resource-creation (beginner), multi-step (intermediate), multi-step+services (advanced), state-checks (expert).
+- **[Dense partial-progress signal](server/README.md#8-reward-shaping--taskgrader)** — clamped to `[0.0, 0.99]`, `1.0` reserved for verified completion.
+- **[Rollback penalty](server/README.md#8-reward-shaping--taskgrader)** — `−0.1` per `(create-X, …, delete-X)` pair.
+- **[Idempotency bonus](server/README.md#8-reward-shaping--taskgrader)** — `+0.02` for graceful "already exists" retry.
+- **[Hint decay](server/README.md#13-hint-provider)** — three-level progressive hints with `0.85^n` reward multiplier.
+- **[Chaos survival bonus](server/README.md#11-chaos-engine)** — `×1.05` if the agent completes a chaotic task.
+
+### Resilience & adversarial features
+- **[Chaos injection](server/README.md#11-chaos-engine)** — silent mid-episode mutations, tier-scaled probabilities (10/20/30%) on services the task is touching.
+- **[Drift detection](server/README.md#12-drift-engine)** — 6 expert tasks, 2–3 random mutations from a per-task pool, randomized per episode (no memorization).
+- **[Security-posture audit tasks](server/README.md#17-security-posture-audit-examples)** — S3 public bucket lockdown, IAM least-privilege, Lambda secret rotation.
+- **[8-layer anti-reward-hacking](server/README.md#9-anti-reward-hacking--8-defense-layers)** — ground-truth verification, dedup, grader invisibility, command allow-list, no-credit-for-reads, monotonic progress, exact resource-name validation, final state checks.
+
+### Training pipeline
+- **[Synthetic SFT dataset (1,500 rows)](data/README.md)** — 5 trajectory types: success / multi-step continuation / failure recovery / verification / hint usage.
+- **[Rigorous base-model selection](data/sft/MODEL_EVALUATION.md)** — 11 models × 27 prompts, [Qwen2.5-Coder-3B-Instruct](https://huggingface.co/unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit) wins.
+- **[LoRA SFT](train/README.md#1-sft-stage--supervised-lora)** — `r ∈ {8,16,32}`, `lora_alpha = r × multiplier`, attention-only adaptation.
+- **[GRPO RL via TRL](train/README.md#2-grpo-stage--reinforcement-learning)** — group-relative advantages, KL to SFT reference, `dapo` loss, no critic.
+- **[Multi-turn rollouts](train/README.md#4-multi-turn-rollouts--parallel-envs)** — up to `MAX_TURNS=6`, observation fed back as next-turn user message.
+- **[Optuna hyperparameter search](train/README.md#3-optuna-hyperparameter-search)** — TPE sampler over 8-dim space, frozen held-out validation set.
+- **[HuggingFace integration](data/README.md#7-huggingface-publishing)** — adapter + dataset published to Hub, OpenEnv Space deployment.
+
+### Parallel rollout architecture
+- **[Server-side MiniStack pool](server/README.md#6-server-side-ministack-pool-parallel-rollouts)** — `MiniStackPool` ([server/app.py](server/app.py)), free-list of ports, lock-guarded acquire/release.
+- **[Client-side GrpoPool](scripts/README.md#2-three-coordinated-pool-layers)** — async-native, all-or-nothing connect, asyncio.gather for concurrent rollouts.
+- **[In-process MultiTurnEnvPool](train/README.md#4-multi-turn-rollouts--parallel-envs)** — sync API, owns a background asyncio loop, used by the trainer.
+- **[8 isolated rollouts on one server](scripts/README.md#7-running-the-multi-connection-demo)** — proof in [scripts/TestMultipleConnects.ipynb](scripts/TestMultipleConnects.ipynb).
+
+### Vendored simulator
+- **[MiniStack as git subtree](server/README.md#5-ministack-vendored-fork--customizations)** — vendored at [aws_infra/](aws_infra/) (commit `2c38c0b`). 34 AWS services. MIT.
+- **[Custom `/_ministack/state` endpoint](server/README.md#5-ministack-vendored-fork--customizations)** — added in commit `a648c3a`; returns full infra inventory in one call.
+- **[Upstream sync workflow](server/README.md#5-ministack-vendored-fork--customizations)** — periodic `git subtree pull`; isolated patches keep conflicts minimal.
+
+### Operations & deployment
+- **[OpenEnv-compliant](https://github.com/openai/openenv)** — `/reset`, `/step`, `/state`, `/schema`, `/ws` HTTP+WebSocket endpoints.
+- **[Web playground UI](server/README.md#19-web-playground)** — `/web` route, 40 AWS service icons, Jinja2 + JS frontend.
+- **[Docker-first deployment](Dockerfile)** — multi-stage build, container ships server + N MiniStack instances + AWS CLI.
+- **[Comprehensive test suite](#14-testing)** — 10 unit tests + 6 tier-integration suites covering 134 tasks.
+
+---
+
+## 3. Architecture
+
+> ![System architecture](docs/figures/architecture_diagram.png)
+
+```
+┌────────────────────────────────── Docker container ──────────────────────────────────┐
+│                                                                                      │
+│   FastAPI server  (port 8000)                                                        │
+│   ├── OpenEnv router       /reset  /step  /state  /schema  /ws  /health              │
+│   ├── Web playground       /web  (Jinja2 + 40 AWS icon SVGs)                         │
+│   ├── env_factory          per-WS-session AwsRlEnvironment instance                  │
+│   │                        (acquires a MiniStack port from MiniStackPool)            │
+│   └── Services                                                                       │
+│       Curriculum · TaskGrader · ResourceVerifier · ChaosEngine · DriftEngine         │
+│       HintProvider · EpisodeTracker · EnvironmentDesigner · EnvironmentStrategy      │
+│                                                                                      │
+│                                                                                      │
+│   MiniStack instances    :4566  :4567  :4568  …  :4566+POOL_SIZE-1                   │
+│   (vendored at aws_infra/, started by the Dockerfile entrypoint)                     │
+│                                                                                      │
+└──────────────────────────────────────────────────────────────────────────────────────┘
+                ▲                                  ▲
+                │ HTTP/WS                          │ AWS CLI subprocess
+                │                                  │ (AWS_ENDPOINT_URL=http://localhost:4566+i)
+                │                                  │
+        ┌───────┴───────────┐              ┌───────┴───────────┐
+        │   RL Agent        │              │  AWS CLI commands │
+        │   the agent emits │              │  (client.py)      │
+        └───────────────────┘              └───────────────────┘
+```
+
+### Episode lifecycle
+
+1. **`reset()`** — wipes simulator state, picks next task from the curriculum, runs `setup_commands`, applies drift if applicable, returns initial observation.
+2. **`step(action)`** — validates the command (must start with `aws `), intercepts hint requests, executes via the strategy, records in tracker, grades with shaped reward, optionally injects chaos, returns observation.
+3. **Hint** — agent sends `aws help --task-hint`; intercepted before reaching MiniStack; returns next-level hint, increments `hints_used` (which decays final reward by `0.85^n`).
+4. **Termination** — `task_achieved=True` or `step_count >= MAX_STEPS` (default 15).
+
+Full mechanics in [At server/README.md file](server/README.md).
+
+---
+
+## 4. Live demo & Quick Start
+
+### Try it in a browser
+
+The hosted playground lets you click around any task without writing code:
+
+> **[Hugging Face Spaces Playground](https://sizzing-aws-rl-env.hf.space/web#playground)**
+
+### Python client
+
+```python
+from aws_rl_env import AwsRlAction, AwsRlEnv
+
+with AwsRlEnv.from_docker_image("aws-rl-env:latest") as env:
+    result = env.reset()
+    print(f"Task: {result.observation.task.description}")
+
+    result = env.step(AwsRlAction(command="aws s3 mb s3://my-bucket"))
+    print(f"Reward: {result.reward}, Done: {result.done}")
+```
+
+Or against a running server:
+
+```python
+env = AwsRlEnv(base_url="http://localhost:8000")
+result = env.reset()
+result = env.step(AwsRlAction(command="aws s3 ls"))
+```
+
+### WebSocket API
+
+```python
+import websockets, json
+
+async with websockets.connect("wss://sizzing-aws-rl-env.hf.space/ws") as ws:
+    await ws.send(json.dumps({"type": "reset"}))
+    obs = json.loads(await ws.recv())
+
+    await ws.send(json.dumps({"type": "step", "data": {"command": "aws s3 ls"}}))
+    obs = json.loads(await ws.recv())
+```
+
+### Local Docker
+
+```bash
+make docker-build           # build the image
+make docker-run             # foreground; serves on :8000
+make docker-run-detach      # background
+make docker-health          # liveness probe
+```
+
+For training (8-way parallel rollouts):
+
+```bash
+AWS_RL_ENV_POOL_SIZE=8 make run
+```
+
+---
+
+## 5. Run on Colab
+
+The full pipeline is reproducible on a Colab GPU runtime. Drop your token into Colab Secrets, set `ENV_BASE_URL` to your HF Space (or local with ngrok), and run.
+
+| Notebook                                                                            | What it does                                          | Open in Colab                                |
+|-------------------------------------------------------------------------------------|-------------------------------------------------------|----------------------------------------------|
+| [train/train_sft_lora.ipynb](train/train_sft_lora.ipynb)                            | Stage 1 — SFT LoRA fine-tuning of Qwen2.5-Coder-3B    | https://colab.research.google.com/drive/1dm9sDaLxHX6s9zEG_SC0FQcKWKkc3TfL?usp=sharing|
+| [train/train_grpo_lora.ipynb](train/train_grpo_lora.ipynb)                          | Stage 2 — GRPO RL training with multi-turn rollouts   | https://colab.research.google.com/drive/1NwiOM0h_JpXXGRxfY_xZtDiaigvIaKjx?usp=sharing |
+| [compare/compare_base_vs_sft.ipynb](compare/compare_base_vs_sft.ipynb)              | Side-by-side: base model vs SFT adapter (dataset + RL env) | https://colab.research.google.com/drive/17406aiad8h4nAphV42vVNZ-a5SzZMIre?usp=sharing |
+
+Replace each `<!-- TODO -->` with the Colab badge URL once published.
+
+---
+
+## 6. Action / Observation spec
+
+The full Pydantic data models — kept inline so any reader can wire up an agent without leaving this page. Source: [models.py](models.py).
+
+### Action
+
+```python
+class AwsRlAction(Action):
+    command: str   # AWS CLI command, e.g. "aws s3 ls"
+```
+
+The environment validates that `command` starts with `aws `; anything else is rejected with `success=False`.
+
+### Observation
+
+```python
+class AwsRlObservation(Observation):
+    episode_id: EpisodeID
+    step_count: StepCount
+    command_success: bool          # exit code == 0
+    command_output: str            # stdout from the AWS CLI invocation
+    error: str                     # stderr (empty if success)
+    task: TaskInfo | None          # masked task definition (no success criteria)
+    task_achieved: bool
+    partial_progress: float        # current task progress in [0.0, 1.0]
+    hints_used: int                # cumulative hint count this episode
+    hint_text: str                 # most recent hint text (if any)
+```
+
+### State
+
+```python
+class AwsRlState(State):
+    current_task: Task | None      # full task assigned for the episode
+    tracker: TrackerState          # episode tracker snapshot
+    infra_state: dict              # AWS infrastructure state keyed by service name
+    chaos_occurred: bool           # whether chaos was injected this episode
+    current_tier: str              # agent's current difficulty tier
+
+class TrackerState:
+    step_count: int                # steps taken this episode
+    hints_used: int                # hints requested this episode
+    progress: float                # current partial progress [0.0, 1.0]
+    commands_executed: list[str]   # commands executed this episode
+    credited_operations: list[str] # (operation, resource) pairs that earned credit
+```
+
+### Task definitions
+
+```python
+class Task:
+    task_id: TaskID
+    difficulty: TaskDifficulty       # warmup | beginner | intermediate | advanced | expert
+    description: str                 # human-readable goal
+    success_criteria: SuccessCriteria
+    setup_commands: list[SetupCommand]      # pre-provision for SRE tasks
+    desired_state_spec: str | None          # natural-language desired end state (drift tasks)
+    possible_drifts: list[SetupCommand]     # pool of mutations for DriftEngine
+
+class TaskInfo:
+    """Agent-visible subset of Task — masks success_criteria, setup_commands, and possible_drifts."""
+    task_id: TaskID
+    difficulty: TaskDifficulty
+    description: str
+    desired_state_spec: str | None
+
+class SuccessCriteria:
+    command_contains: str | None                   # warmup/beginner
+    operation: str | None                          # warmup/beginner
+    resource_exists: ResourceExistsCheck | None    # beginner
+    steps: list[StepCriteria]                      # intermediate/advanced/expert
+    services: list[AwsService]                     # advanced/expert
+    state_checks: list[StateCheck]                 # expert (ground truth)
+```
+
+### Curriculum config
+
+```python
+class TierConfig:
+    min_episodes: int          # minimum episodes before promotion
+    advance_rate: float        # tier success rate threshold (0.6 - 1.0)
+    mastery_window: int        # sliding window size (default: 10)
+    mastery_threshold: float   # per-task graduation threshold (default: 0.7)
+    fast_track_rate: float    # early promotion threshold (default: 0.9)
+    chaos_probability: float   # probability of chaos injection per step
+
+class SpacedRepState:
+    interval: int                  # episodes until next re-test (3 → 48)
+    last_graduated_episode: int    # when last graduated
+```
+
+---
+
+## 7. Curriculum & Reward (overview)
+
+The curriculum and reward stack is the heart of the project. This section is the elevator pitch; **the full mechanics — priority scoring math, anti-reward-hacking layers, chaos engine, drift engine — live in [server/README.md](server/README.md)**.
+
+### Priority scoring (one-formula task selection)
+
+```
+score = novelty_bonus          # +100 if never attempted
+      + weakness_weight        # +50 × (1 − task_success_rate)
+      + spaced_rep_bonus       # +30 if a graduated task is "due" for re-test
+      − recency_penalty        # −20 if attempted in the last 2 episodes
+```
+
+Exploration, weakness-targeting, anti-forgetting, and variety — all balanced by one weighted sum.
+
+### Reward shaping
+
+```
+if task_achieved:
+    reward = 1.0
+    if survived_chaos:    reward *= 1.05      # chaos survival bonus
+else:
+    reward = partial_progress * 0.8           # ≤ 0.8 from steps alone
+    if progress_increased: reward += 0.1      # dense progress signal
+    if command_failed:     reward *= 0.5      # error penalty
+    reward -= 0.1 * rollback_count            # waste penalty
+    reward += 0.02 * idempotent_retries       # graceful retry bonus
+    reward = clamp(reward, 0.0, 0.99)         # 1.0 reserved for completion
+
+reward *= 0.85 ** hints_used                  # hint decay applied last
+```
+
+The agent's loss surface is intentionally narrow: only doing the task earns full reward, and every reward-hacking shortcut we identified during design has a defense layer (full list in [Server's Readme file  section §9](server/README.md#9-anti-reward-hacking--8-defense-layers)).
+
+> ![Curriculum progression: 5 tiers, priority scoring formula, mastery + spaced rep + fast-track](docs/figures/curriculum_progression.png)
+
+---
+
+## 8. Training pipeline (SFT → GRPO)
+
+The training pipeline runs in two stages, both reproducible on Colab. Full detail in **[train/README.md](train/README.md)**.
+
+```
+                      ┌────────── data/sft/ ──────────┐
+                      │  1,500 train · 150 val rows   │
+                      │  5 trajectory types           │
+                      └───────────────┬───────────────┘
+                                      ▼
+   STAGE 1 — Supervised Fine-Tuning   train/train_sft_lora.ipynb
+   Qwen2.5-Coder-3B-Instruct + LoRA r=8/16/32 (Optuna) → SFT adapter
+                                      │
+                                      │ Sizzing/aws-rl-sft-qwen25coder3b-adapter
+                                      ▼
+   STAGE 2 — GRPO RL                  train/train_grpo_lora.ipynb
+   G=8 parallel rollouts · multi-turn · reward = env return
+   Optuna over (lr, β, G, T, top_p, lora_r, max_turns)
+```
+
+### Numbers worth knowing
+
+| | |
+|---|---|
+| **Base model** | `unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit` — picked via [Through model evaluation](data/sft/MODEL_EVALUATION.md) |
+| **SFT LoRA** | `r ∈ {8,16,32}`, `lora_alpha = r × multiplier`, target = attention only, dropout `[0.005, 0.031]` |
+| **GRPO config** | `G=8`, `β=0.04`, `lr=5e-6`, `T=0.9`, `top_p=0.95`, `max_turns=6`, loss=`dapo` |
+| **Optuna search** | TPE sampler, 6 trials × 30 GRPO steps, frozen 10-task held-out val set |
+| **Final training** | 200 GRPO steps with best config |
+
+### Training graphs
+
+> Embed once notebook is executed:
+> ![SFT loss curve](docs/figures/sft_loss_curve.png)
+> ![GRPO mean reward over training](docs/figures/grpo_reward_curve.png)
+> ![Per-rollout reward by curriculum tier](docs/figures/grpo_per_tier_curve.png)
+> ![Optuna parameter importance](docs/figures/optuna_param_importance.png)
+
+---
+
+## 9. Parallel rollout architecture
+
+GRPO needs `G` rollouts on the same task per training step. We run all G in parallel with **state isolation guaranteed**. Three coordinated pool layers make it work:
+
+```
+                        Trainer (G=8 generations needed per step)
+                                        │
+                   ┌────────────────────┼────────────────────┐
+                   ▼                    ▼                    ▼
+            MultiTurnEnvPool        GrpoPool            (in-process)
+            (train_grpo.py)         (scripts/grpo_pool.py)
+            sync API                async API
+                   │                    │
+                   └─────── 8 WebSocket connections ────────┘
+                                        │
+                                        ▼
+                            FastAPI server  :8000
+                            + OpenEnv max_concurrent_envs=8
+                                        │
+                                        ▼
+                            MiniStackPool (free-list, lock-guarded)
+                            acquire(port) on connect, release on disconnect
+                                        │
+                                        ▼
+                    8 isolated MiniStack instances :4566..:4573
+```
+
+Wall-clock impact: an 8-rollout × 6-turn episode runs in ~300 ms of env time vs ~2.4 s sequential. Full mechanics, including the **all-or-nothing connect protocol** that prevents pool-slot leakage on flake, are in **[Scripts README file](scripts/README.md)**.
+
+> ![Parallel rollout: 3 coordinated pool layers](docs/figures/parallel_rollout_diagram.png)
+
+---
+
+## 10. MiniStack: vendored & customized
+
+The simulator powering the env is **vendored** as a git subtree at [aws_infra/](aws_infra/), not pulled as a black-box dependency. We forked it because we needed:
+
+1. A custom `/_ministack/state` JSON endpoint so the grader can read the entire infra inventory in **one HTTP call** instead of iterating 20+ list APIs per grading pass. Added in commit `a648c3a "feat: Add support for service state retrieval and action listing across multiple AWS services"`.
+2. A reproducible build with no runtime network requirement — the Docker image bundles a specific MiniStack revision.
+3. The freedom to extend service coverage on demand.
+
+Custom commits live as small, isolated patches so periodic upstream syncs (`af2e945`, `579597b`) replay cleanly. To inspect:
+
+```bash
+git show a648c3a               # the state-endpoint diff
+git log --oneline -- aws_infra/  # only the aws_infra subtree history
+```
+
+Full subtree workflow + commit-by-commit detail in [server/README.md §5](server/README.md#5-ministack-vendored-fork--customizations). Upstream MiniStack docs (81 KB) are preserved at [aws_infra/README.md](aws_infra/README.md).
+
+---
+
+## 11. Results & Benchmarks
+
+### Base-model selection
+
+We evaluated 11 chat models on 27 held-out prompts. **Qwen2.5-Coder-3B-Instruct** wins on every metric that matters: 41% exact match (highest), 63% operation match (highest), 3.1 s/call (3× faster than the 4B runner-up). Full report:
+
+> **[data/sft/MODEL_EVALUATION.md](data/sft/MODEL_EVALUATION.md)** — 270-line writeup, per-model verdicts, methodology
+
+> ![Top 4 candidate models on the held-out benchmark](docs/figures/model_eval_chart.png)
+
+### Base vs SFT — actual results
+
+After running the SFT pipeline end-to-end, the eval delta on the same held-out prompts is striking:
+
+| Metric          | Base   | Post-SFT | Delta       |
+|-----------------|:------:|:--------:|:-----------:|
+| `format_pct`    | 33.3%  | **100.0%** | **+66.7 pp** |
+| `exact_pct`     | 38.9%  | **88.9%**  | **+50.0 pp** |
+| `service_pct`   | 77.8%  | **88.9%**  | +11.1 pp    |
+| `operation_pct` | 61.1%  | **88.9%**  | +27.8 pp    |
+| `avg_len`       | 85.8   | 74.7     | −11 chars (tighter) |
+
+> ![Base vs SFT eval-metrics comparison](docs/figures/base_vs_sft_success.png)
+
+Every target from [data/sft/MODEL_EVALUATION.md §11](data/sft/MODEL_EVALUATION.md) is met or exceeded. Format compliance is now perfect; the model never wraps commands in fences or quotes after SFT. Exact-match jumped from 39% to 89% — the agent now emits the canonical command for ~9 of every 10 prompts.
+
+The richer two-mode benchmark (dataset eval + live RL env eval) is in [compare/compare_base_vs_sft.ipynb](compare/compare_base_vs_sft.ipynb); methodology in [compare/README.md](compare/README.md).
+
+> ![Dataset comparison: base vs SFT (per-row scores)](docs/figures/compare_dataset.png)
+> ![RL env comparison: base vs SFT (per-episode rewards)](docs/figures/compare_rl_env.png)
+
+### SFT training curves
+
+> ![SFT loss curve over training](docs/figures/sft_loss_curve.png)
+
+### Optuna SFT search
+
+The best SFT trial (out of 6) used `lora_r=16, lora_alpha=16, dropout=0.0058, lr=4.03e-4, warmup=0.1` — see [train/README.md §3](train/README.md#3-optuna-hyperparameter-search) for the full Optuna study table.
+
+> ![Optuna parameter importances](docs/figures/optuna_param_importance.png)
+> ![Optuna optimization history](docs/figures/optuna_history.png)
+
+### GRPO results (live multi-step env eval)
+
+After 35 GRPO steps on top of the SFT adapter (best Optuna config: `lr=1.6e-5, β=0.0021, T=0.99`), we re-evaluated end-to-end on 100+ episodes:
+
+| Metric                        | Base + SFT | Base + SFT + GRPO | Δ            |
+|-------------------------------|:---------:|:-----------------:|:------------:|
+| Overall success rate          | 86.8%     | 86.2%             | −0.5 pp      |
+| Overall mean reward           | 0.883     | 0.877             | −0.006       |
+| Beginner success              | 96.2%     | **100.0%**        | **+3.8 pp**  |
+| Intermediate success          | 81.0%     | **87.0%**         | **+6.0 pp**  |
+| Warmup success                | 96.0%     | 90.2%             | −5.8 pp      |
+| Expert success                | 22.2%     | 22.2%             | flat         |
+| Drift repair rate             | 22.2%     | 22.2%             | flat         |
+| Destructive-action fail rate  | 15.1%     | 14.7%             | −0.4 pp      |
+| Steps to solve                | 1.45      | 1.55              | +0.10        |
+
+> ![SFT vs GRPO metrics grid](docs/figures/sft_vs_grpo_metrics_grid.png)
+> ![SFT vs GRPO by tier](docs/figures/sft_vs_grpo_by_tier.png)
+
+**Honest reading:** the 35-step GRPO run preserves the SFT gains and modestly improves the middle tiers (beginner +3.8 pp, intermediate +6.0 pp) — but does not crack the **expert-tier bottleneck** (22% success on SRE / drift / security-posture tasks). With longer GRPO runs and more curriculum exposure to expert tasks, this is the next gain to chase.
+
+### GRPO training curves
+
+Per-step training signals from the final 35-step GRPO run:
+
+> ![GRPO final per-step training signals](docs/figures/grpo_final_per_step.png)
+> ![GRPO env reward over training](docs/figures/grpo_reward_curve.png)
+
+Optuna search across 4 trials picked the final config:
+
+> ![GRPO Optuna trial comparison](docs/figures/grpo_optuna_trials_comparison.png)
+> ![GRPO Optuna parameter importances](docs/figures/grpo_optuna_importances.png)
+> ![GRPO Optuna optimization history](docs/figures/grpo_optuna_history.png)
+
+### Qualitative rollouts (post-GRPO)
+
+One sample episode per tier:
+
+> ![Qualitative rollouts on representative tasks](docs/figures/qualitative_rollouts.png)
+
+---
+
+## 12. Repository map
+
+| Path                           | Purpose                                                            | Sub-README                              |
+|--------------------------------|--------------------------------------------------------------------|-----------------------------------------|
+| [server/](server/)             | OpenEnv FastAPI server, env logic, services, web playground       | [server/README.md](server/README.md)    |
+| [train/](train/)               | SFT and GRPO training notebooks                                   | [train/README.md](train/README.md)      |
+| [data/](data/)                 | SFT dataset, base-model selection, eval harness                   | [data/README.md](data/README.md) · [MODEL_EVALUATION.md](data/sft/MODEL_EVALUATION.md) |
+| [compare/](compare/)           | Base vs SFT side-by-side benchmark                                | [compare/README.md](compare/README.md)  |
+| [scripts/](scripts/)           | Parallel-rollout architecture + multi-connection demo             | [scripts/README.md](scripts/README.md)  |
+| [aws_infra/](aws_infra/)       | Vendored MiniStack simulator (git subtree)                        | [aws_infra/README.md](aws_infra/README.md) |
+| [tests/](tests/), [tests_tasks/](tests_tasks/) | Unit + tier-integration test suites                       | (see [§14](#14-testing))                |
+| [models.py](models.py)         | Pydantic data models for action/observation/task                  | (inline §6)                             |
+| [client.py](client.py)         | OpenEnv HTTP/WebSocket client wrapper                             | —                                       |
+| [inference.py](inference.py)   | Single-model agent loop (matches RL eval mode of `compare/`)      | —                                       |
+| [train_grpo.py](train_grpo.py) | GRPO trainer (1,283 LOC) — `MultiTurnEnvPool`, Optuna, plotting   | (see [train/README.md](train/README.md)) |
+| [aws_rl_env_colab.ipynb](aws_rl_env_colab.ipynb) | Colab driver for the full training pipeline             | —                                       |
+| [docs/figures/](docs/figures/) | All README graphs and screenshots                                  | —                                       |
+
+---
+
+## 13. Configuration & Running
+
+### Docker (recommended)
+
+```bash
+make docker-build          # build the image
+make docker-run            # foreground on :8000
+make docker-run-detach     # background
+make docker-health         # liveness probe
+```
+
+
+### OpenEnv deployment
+
+```bash
+make openenv-validate      # validate config
+make openenv-build         # build environment
+make openenv-push          # push to HuggingFace Spaces
+```
+
+### Environment variables
+
+| Variable                            | Default                  | Description                                                       |
+|-------------------------------------|--------------------------|-------------------------------------------------------------------|
+| `AWS_INFRA_URL`                     | `http://localhost:4566`  | MiniStack endpoint (used when `POOL_SIZE=1`)                      |
+| `AWS_RL_ENV_POOL_SIZE`              | `1`                      | **Server-side MiniStack pool size; set to 8 for GRPO training**   |
+| `AWS_RL_ENV_MINISTACK_BASE_PORT`    | `4566`                   | First MiniStack port; pool covers `[BASE, BASE + POOL_SIZE)`      |
+| `BACKEND_TYPE`                      | `simulator`              | `simulator` (MiniStack) or `aws` (real AWS, no pool)              |
+| `AWS_ACCESS_KEY_ID`                 | `test`                   | AWS credentials (any value works for the simulator)               |
+| `AWS_SECRET_ACCESS_KEY`             | `test`                   | AWS credentials (any value works for the simulator)               |
+| `AWS_DEFAULT_REGION`                | `us-east-1`              | AWS region                                                         |
+| `MAX_STEPS`                         | `15`                     | Max steps per episode                                              |
+| `API_BASE_URL`                      | —                        | LLM API endpoint for [inference.py](inference.py)                 |
+| `MODEL_NAME`                        | —                        | LLM model name for [inference.py](inference.py)                   |
+| `HF_TOKEN`                          | —                        | HuggingFace token (dataset/adapter access, push)                  |
+| `TEMPERATURE`                       | `0.7`                    | LLM sampling temperature                                          |
+
+### Curriculum stats API
+
+```python
+curriculum.get_stats()
+# {
+#   "episode_count": 42,
+#   "tier": "intermediate",
+#   "tier_episodes": 12,
+#   "tier_success_rate": 0.75,
+#   "graduated_tasks": [0, 2, 4],
+#   "weak_spots": [11, 12],
+#   "skill_profile": {0: 0.95, 1: 0.8, ...},
+#   "spaced_rep_due": [0, 2],
+#   "avg_reward_last_10": 0.65
+# }
+```
+
+---
+
+## 14. Testing
+
+The test suite covers both isolated unit logic and end-to-end task execution against MiniStack.
+
+### Unit tests — [tests/](tests/)
+
+```bash
+pytest tests/ -v
+```
+
+| File                                                                                         | Covers                                                          |
+|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
+| [test_aws_rl_env_environment.py](tests/test_aws_rl_env_environment.py)                       | Environment lifecycle, reset/step semantics, reward integration |
+| [test_task_grader.py](tests/test_task_grader.py)                                             | All 5 grading strategies, partial progress, penalties, bonuses  |
+| [test_resource_verifier.py](tests/test_resource_verifier.py)                                 | Per-service ground-truth verification (20+ services)            |
+| [test_episode_tracker.py](tests/test_episode_tracker.py)                                     | Command parsing, dedup, monotonic progress, rollback detection  |
+| [test_episode_context.py](tests/test_episode_context.py)                                     | Per-episode context lifecycle                                   |
+| [test_drift_engine.py](tests/test_drift_engine.py)                                           | Random drift selection, mutation application                    |
+| [test_hint_provider.py](tests/test_hint_provider.py)                                         | Three-level progressive hints, decay computation                |
+| [test_environment_designer.py](tests/test_environment_designer.py)                           | Setup-command provisioning                                      |
+| [test_pool.py](tests/test_pool.py)                                                           | Server-side `MiniStackPool` acquire/release, exhaustion         |
+| [test_grpo_pool.py](tests/test_grpo_pool.py)                                                 | Client-side `GrpoPool` connect/close, all-or-nothing rollback   |
+
+### Tier integration tests — [tests_tasks/](tests_tasks/)
+
+```bash
+pytest tests_tasks/ -v
+```
+
+134 tasks exercised end-to-end:
+
+| File                                                                                                | Tasks |
+|-----------------------------------------------------------------------------------------------------|------:|
+| [test_warmup_tasks.py](tests_tasks/test_warmup_tasks.py)                                            |   25  |
+| [test_beginner_tasks.py](tests_tasks/test_beginner_tasks.py)                                        |   25  |
+| [test_intermediate_tasks.py](tests_tasks/test_intermediate_tasks.py)                                |   25  |
+| [test_advanced_tasks.py](tests_tasks/test_advanced_tasks.py)                                        |   25  |
+| [test_expert_tasks.py](tests_tasks/test_expert_tasks.py)                                            |   24  |
+| [test_drift_tasks.py](tests_tasks/test_drift_tasks.py)                                              |    9  |
+| **Total**                                                                                           | **133** |
+
+These tests double as the source of truth for canonical solutions used by the SFT dataset generator (extracted via AST — see [data/README.md §1](data/README.md#1-sft-dataset-generation)).
+
+---
+
+## 15. Tech stack
+
+- **Python 3.12**, [`uv`](https://github.com/astral-sh/uv) for dependency management, multi-stage Docker
+- **FastAPI**, **OpenEnv** (HTTP + WebSocket env protocol), **uvicorn**
+- **TRL ≥ 0.21** (`GRPOTrainer`, `GRPOConfig`)
+- **PEFT** (LoRA), **Unsloth** (4-bit quantized base, fused training kernels)
+- **Transformers ≥ 4.45**, **datasets ≥ 2.20**, **HuggingFace Hub ≥ 0.24**
+- **Optuna ≥ 3.6** (TPE sampler, SQLite study storage)
+- **asyncio** + **websockets** + **httpx** (parallel rollout orchestration)
+- **MiniStack** (vendored at [aws_infra/](aws_infra/), 34 AWS services)
+- **AWS CLI v2** (subprocess invocation against MiniStack endpoint)
+- **matplotlib**, **plotly** (training curves, Optuna visualizations)
+- **pytest** (16 test files, ~250 KB of test code)
+
+---
+
+## 16. Links
+
+- **Live demo**: [sizzing-aws-rl-env.hf.space/web](https://sizzing-aws-rl-env.hf.space/web)
+- **HF Space**: [huggingface.co/spaces/Sizzing/aws_rl_env](https://huggingface.co/spaces/Sizzing/aws_rl_env)
+- **API docs**: [/docs](https://sizzing-aws-rl-env.hf.space/docs) · [/redoc](https://sizzing-aws-rl-env.hf.space/redoc)
+- **SFT adapter**: [Sizzing/aws-rl-sft-qwen25coder3b-adapter](https://huggingface.co/Sizzing/aws-rl-sft-qwen25coder3b-adapter)
+- **GRPO adapter**: [Sizzing/aws-rl-grpo-qwen25coder3b-adapter](https://huggingface.co/Sizzing/aws-rl-grpo-qwen25coder3b-adapter)
+- **Dataset**: [Sizzing/aws-rl-sft](https://huggingface.co/datasets/Sizzing/aws-rl-sft)
+- **GitHub**: [github.com/udaykiranpadhy/aws-rl-env](https://github.com/udaykiranpadhy/aws-rl-env)
+
+---
+
+## 17. Acknowledgments
+
+- **MiniStack** — vendored at [aws_infra/](aws_infra/). Upstream license preserved. Custom modifications attributable to commits `a648c3a`, `a00e981`; periodic upstream syncs `af2e945`, `579597b`.
+- **OpenEnv** — environment protocol and Python client framework.
+- **TRL** (HuggingFace) — `GRPOTrainer` implementation.
+- **Unsloth** — 4-bit quantized model loaders + fused training kernels.
+- **Google Colab** for providing their infrastructure to train models.
+- **AWS service icons** in [server/static/img/aws/](server/static/img/aws/) — used in the web playground.
+
+---
+
+## Sub-README index
+
+For deep technical detail on any subsystem:
+
+- [server/README.md](server/README.md) — environment internals (curriculum, reward shaping, anti-hacking, chaos, drift, MiniStack-fork detail)
+- [train/README.md](train/README.md) — SFT + GRPO training pipeline (LoRA config, Optuna search, multi-turn rollouts)
+- [scripts/README.md](scripts/README.md) — parallel-rollout architecture (3 pool layers, all-or-nothing connect, concurrency safety)
+- [data/README.md](data/README.md) — dataset generation (5 trajectory types, AST extraction) + base-model selection summary
+- [data/sft/MODEL_EVALUATION.md](data/sft/MODEL_EVALUATION.md) — full 11-model benchmark report
+- [compare/README.md](compare/README.md) — base vs SFT comparison harness
+- [aws_infra/README.md](aws_infra/README.md) — vendored MiniStack upstream documentation (81 KB)
+
+
+## Small Video Explanation
+
+- [Recorded Video explaining core functionality](https://share.zight.com/NQu0pLvQ)

__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Aws Rl Env Environment."""
+
+try:
+    from .client import AwsRlEnv
+    from .models import AwsRlAction, AwsRlObservation
+except ImportError:
+    # When imported directly (e.g. by pytest from rootdir) rather than as
+    # part of the aws_rl_env package, relative imports are unavailable.
+    pass
+
+__all__ = [
+    "AwsRlAction",
+    "AwsRlObservation",
+    "AwsRlEnv",
+]

aws_infra/CONTRIBUTING.md

@@ -0,0 +1,196 @@
+# Contributing to MiniStack
+
+Thanks for wanting to contribute. The codebase is intentionally simple — each AWS service is a single self-contained Python file inside `ministack/services/`. Adding a new service or fixing a bug should take minutes, not hours.
+
+## Project Structure
+
+```
+ministack/
+├── ministack/
+│   ├── app.py              # ASGI entry point, service routing, reset endpoint
+│   ├── core/
+│   │   ├── responses.py    # json_response, error_response_json, new_uuid
+│   │   ├── router.py       # detect_service(), SERVICE_PATTERNS
+│   │   ├── lambda_runtime.py
+│   │   └── persistence.py
+│   └── services/
+│       ├── s3.py, sqs.py, sns.py, dynamodb.py, ...
+│       └── cognito.py      # example of a two-client service file
+├── tests/
+│   ├── conftest.py         # pytest fixtures (boto3 clients)
+│   └── test_services.py    # all integration tests
+├── Dockerfile
+├── pyproject.toml
+└── CHANGELOG.md
+```
+
+## Adding a New Service
+
+Every service follows the same 4-step pattern:
+
+### 1. Create `ministack/services/myservice.py`
+
+```python
+"""
+MyService Emulator.
+JSON-based API via X-Amz-Target.
+Supports: OperationOne, OperationTwo, ...
+"""
+
+import json
+import logging
+from ministack.core.responses import json_response, error_response_json, new_uuid
+
+logger = logging.getLogger("myservice")
+
+ACCOUNT_ID = "000000000000"
+REGION = "us-east-1"
+
+_state: dict = {}  # in-memory storage
+
+
+async def handle_request(method, path, headers, body, query_params):
+    target = headers.get("x-amz-target", "")
+    action = target.split(".")[-1] if "." in target else ""
+
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError:
+        return error_response_json("SerializationException", "Invalid JSON", 400)
+
+    handlers = {
+        "OperationOne": _operation_one,
+        "OperationTwo": _operation_two,
+    }
+
+    handler = handlers.get(action)
+    if not handler:
+        return error_response_json("InvalidAction", f"Unknown action: {action}", 400)
+    return handler(data)
+
+
+def _operation_one(data):
+    return json_response({"result": "ok"})
+
+
+def _operation_two(data):
+    return json_response({})
+
+
+def reset():
+    _state.clear()
+```
+
+**Protocol guide:**
+
+- JSON services (DynamoDB, SecretsManager, Glue, Athena, Cognito, etc.) — use `json_response` / `error_response_json`, route via `X-Amz-Target`
+- XML/Query services (S3, SQS, SNS, IAM, STS, RDS, ElastiCache, EC2) — build XML responses, route via `Action` query param; use `_xml(status, root_tag, inner)` pattern; verify field names against botocore shapes via `Loader().load_service_model()`
+- REST services (Lambda, ECS, Route53) — route via URL path
+
+### 2. Register in `ministack/app.py`
+
+```python
+from ministack.services import myservice
+
+SERVICE_REGISTRY = {
+    # ... existing ...
+    "myservice": {"module": "myservice"},
+}
+```
+
+If the service needs aliases, add them in the registry entry.
+
+### 3. Add detection to `ministack/core/router.py`
+
+```python
+SERVICE_PATTERNS = {
+    # ... existing ...
+    "myservice": {
+        "target_prefixes": ["AWSMyService"],   # for X-Amz-Target routing
+        "host_patterns": [r"myservice\."],      # for host-based routing
+    },
+}
+```
+
+Add any credential scope or `Action`-based routing as needed.
+
+### 4. Add a fixture to `tests/conftest.py`
+
+```python
+@pytest.fixture(scope="session")
+def mysvc():
+    return make_client("myservice")
+```
+
+### 5. Add tests to `tests/test_services.py`
+
+```python
+def test_myservice_operation_one(mysvc):
+    resp = mysvc.operation_one(Param="value")
+    assert resp["result"] == "ok"
+```
+
+---
+
+## Running Tests Locally
+
+```bash
+# Start the stack
+docker compose up -d
+
+# Install test dependencies
+pip install boto3 pytest pytest-xdist duckdb docker cbor2 
+
+# Parallel-safe phase: run tests that are safe to run concurrently
+pytest tests/ -v -n 4 --dist=loadfile -m "not serial"
+
+# Serial/global-state phase: run tests that mutate runtime state or require isolation
+pytest tests/ -v -m serial
+
+# Run a specific service
+pytest tests/ -v -k "cognito"
+```
+
+---
+
+## Code Conventions
+
+- **One file per service** — keep everything for a service in `ministack/services/myservice.py`
+- **Imports** — always `from ministack.core.responses import ...`, never `from core.responses import ...`
+- **In-memory state** — use module-level dicts (`_things: dict = {}`)
+- **reset()** — every service must expose a `reset()` that clears all module-level state; it's called by `/_ministack/reset`
+- **No external AWS deps** — no `boto3`, `botocore`, or `aws-sdk` in service code
+- **Minimal dependencies** — `duckdb` and `docker` are optional; guard with `try/except ImportError`
+- **Error responses** — match real AWS error codes and HTTP status codes as closely as possible
+- **Logging** — `logger = logging.getLogger("servicename")`; DEBUG for request details, INFO for significant events
+
+---
+
+## Pull Request Checklist
+
+- [ ] New service file in `ministack/services/`
+- [ ] Registered in `ministack/app.py` SERVICE_REGISTRY
+- [ ] Detection patterns added to `ministack/core/router.py`
+- [ ] Fixture added to `tests/conftest.py`
+- [ ] Tests added and passing (`pytest tests/ -v`)
+- [ ] Linting passes (`ruff check ministack/`)
+- [ ] Service added to the table in `README.md`
+- [ ] Entry added to `CHANGELOG.md`
+
+---
+
+## What We're Looking For
+
+High-value contributions right now:
+
+- **CloudFront** — distribution CRUD, invalidations, origin configuration
+- **CodeBuild / CodePipeline** — CI/CD pipeline stubs
+- **AppSync** — GraphQL API CRUD
+- **SQS FIFO** — message group / deduplication support
+- **More Cognito flows** — hosted UI, federated identity providers, custom auth triggers
+
+---
+
+## Questions?
+
+Open a GitHub Discussion or file an issue with the `question` label.

aws_infra/Dockerfile

@@ -0,0 +1,70 @@
+FROM python:3.12-alpine AS builder
+
+RUN pip install --no-cache-dir --no-compile \
+        hypercorn==0.18.0 \
+        "cbor2>=5.4.0" \
+        "defusedxml>=0.7" \
+        "docker>=7.0.0" \
+        "pyyaml>=6.0" \
+        "cryptography>=41.0" \
+        "pymysql>=1.1" \
+        "boto3>=1.34" \
+        "awscli"
+
+# Strip awscli help examples (~25 MB) and Python cache files (~15 MB).
+RUN rm -rf /usr/local/lib/python3.12/site-packages/awscli/examples \
+    && find /usr/local/lib/python3.12/site-packages -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null \
+    && rm -rf /usr/local/lib/python3.12/site-packages/pip*.dist-info \
+    && rm -rf /usr/local/lib/python3.12/site-packages/pip*
+
+FROM python:3.12-alpine
+
+LABEL maintainer="MiniStack" \
+      description="Local AWS Service Emulator — drop-in LocalStack replacement"
+
+# Upgrade base packages to pick up latest security patches.
+RUN apk upgrade --no-cache && apk add --no-cache nodejs bash && rm -f /usr/bin/wget /bin/wget \
+    && rm -rf /usr/local/lib/python3.12/site-packages/pip* \
+              /usr/local/bin/pip*
+
+WORKDIR /opt/ministack
+
+# Copy cleaned Python packages and CLI entrypoints from builder.
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin/aws /usr/local/bin/aws
+COPY --from=builder /usr/local/bin/aws_completer /usr/local/bin/aws_completer
+COPY --from=builder /usr/local/bin/hypercorn /usr/local/bin/hypercorn
+
+COPY bin/awslocal /usr/local/bin/awslocal
+RUN chmod +x /usr/local/bin/awslocal
+
+COPY ministack/ ministack/
+
+RUN addgroup -S ministack && adduser -S ministack -G ministack
+RUN mkdir -p /tmp/ministack-data/s3 && chown -R ministack:ministack /tmp/ministack-data
+RUN mkdir -p /docker-entrypoint-initaws.d/ready.d \
+             /etc/localstack/init/boot.d \
+             /etc/localstack/init/ready.d && \
+    chown -R ministack:ministack /docker-entrypoint-initaws.d /etc/localstack
+VOLUME /docker-entrypoint-initaws.d
+VOLUME /etc/localstack/init
+
+ENV GATEWAY_PORT=4566 \
+    LOG_LEVEL=INFO \
+    S3_PERSIST=0 \
+    S3_DATA_DIR=/tmp/ministack-data/s3 \
+    REDIS_HOST=redis \
+    REDIS_PORT=6379 \
+    RDS_BASE_PORT=15432 \
+    RDS_PERSIST=0 \
+    ELASTICACHE_BASE_PORT=16379 \
+    LAMBDA_EXECUTOR=local \
+    PYTHONUNBUFFERED=1
+
+EXPOSE 4566
+
+# Pure Python healthcheck — no curl dependency
+HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:4566/_ministack/health')" || exit 1
+
+ENTRYPOINT ["python", "-m", "hypercorn", "ministack.app:app", "--bind", "0.0.0.0:4566", "--keep-alive", "75"]

aws_infra/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiniStack Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aws_infra/Makefile

@@ -0,0 +1,127 @@
+.PHONY: build run stop test logs health clean
+
+IMAGE_NAME := ministack
+CONTAINER_NAME := ministack
+PORT := 4566
+
+# Override any shell AWS credentials so make test is self-contained
+export AWS_ACCESS_KEY_ID := test
+export AWS_SECRET_ACCESS_KEY := test
+export AWS_DEFAULT_REGION := us-east-1
+unexport AWS_PROFILE
+
+build:
+	docker build -t $(IMAGE_NAME) .
+
+run: build
+	docker run -d --name $(CONTAINER_NAME) -p $(PORT):4566 \
+		-e LOG_LEVEL=INFO \
+		-v /var/run/docker.sock:/var/run/docker.sock \
+		$(IMAGE_NAME)
+	@echo "MiniStack running on http://localhost:$(PORT)"
+	@echo "Health: http://localhost:$(PORT)/_ministack/health"
+
+run-compose:
+	docker compose up -d --build
+	@echo "MiniStack running on http://localhost:$(PORT)"
+
+stop:
+	docker stop $(CONTAINER_NAME) 2>/dev/null || true
+	docker rm $(CONTAINER_NAME) 2>/dev/null || true
+
+stop-compose:
+	docker compose down
+
+logs:
+	docker logs -f $(CONTAINER_NAME)
+
+health:
+	@curl -s http://localhost:$(PORT)/_ministack/health | python3 -m json.tool
+
+test: stop run
+	@echo "Waiting for ministack to be ready..."
+	@READY=0; \
+	for i in $$(seq 1 30); do \
+		if curl -sf http://localhost:$(PORT)/_ministack/health > /dev/null 2>&1; then \
+			echo "Ready after $$i second(s)."; READY=1; break; \
+		fi; \
+		sleep 1; \
+	done; \
+	if [ "$$READY" = "0" ]; then echo "ERROR: ministack did not start within 30s" >&2; exit 1; fi
+	@echo "=== S3 ==="
+	aws --endpoint-url=http://localhost:$(PORT) s3 mb s3://test-bucket
+	echo "hello" | aws --endpoint-url=http://localhost:$(PORT) s3 cp - s3://test-bucket/hello.txt
+	aws --endpoint-url=http://localhost:$(PORT) s3 ls s3://test-bucket
+	aws --endpoint-url=http://localhost:$(PORT) s3 cp s3://test-bucket/hello.txt -
+	@echo ""
+	@echo "=== SQS ==="
+	aws --endpoint-url=http://localhost:$(PORT) sqs create-queue --queue-name test-queue
+	aws --endpoint-url=http://localhost:$(PORT) sqs send-message --queue-url http://localhost:$(PORT)/000000000000/test-queue --message-body "hello sqs"
+	aws --endpoint-url=http://localhost:$(PORT) sqs receive-message --queue-url http://localhost:$(PORT)/000000000000/test-queue
+	@echo ""
+	@echo "=== DynamoDB ==="
+	aws --endpoint-url=http://localhost:$(PORT) dynamodb create-table \
+		--table-name TestTable \
+		--attribute-definitions AttributeName=pk,AttributeType=S \
+		--key-schema AttributeName=pk,KeyType=HASH \
+		--billing-mode PAY_PER_REQUEST
+	aws --endpoint-url=http://localhost:$(PORT) dynamodb put-item \
+		--table-name TestTable \
+		--item '{"pk":{"S":"key1"},"data":{"S":"value1"}}'
+	aws --endpoint-url=http://localhost:$(PORT) dynamodb get-item \
+		--table-name TestTable \
+		--key '{"pk":{"S":"key1"}}'
+	@echo ""
+	@echo "=== SNS ==="
+	aws --endpoint-url=http://localhost:$(PORT) sns create-topic --name test-topic
+	aws --endpoint-url=http://localhost:$(PORT) sns list-topics
+	@echo ""
+	@echo "=== STS ==="
+	aws --endpoint-url=http://localhost:$(PORT) sts get-caller-identity
+	@echo ""
+	@echo "=== SecretsManager ==="
+	aws --endpoint-url=http://localhost:$(PORT) secretsmanager create-secret --name test-secret --secret-string '{"user":"admin","pass":"s3cr3t"}'
+	aws --endpoint-url=http://localhost:$(PORT) secretsmanager get-secret-value --secret-id test-secret
+	@echo ""
+	@echo "=== Lambda ==="
+	aws --endpoint-url=http://localhost:$(PORT) lambda list-functions
+	@echo ""
+	@echo "=== ALB/ELBv2 ==="
+	@python3 -c "\
+import zipfile; \
+z = zipfile.ZipFile('/tmp/ms-alb-test.zip', 'w'); \
+z.writestr('index.py', 'import json\ndef handler(event, context):\n    return {\"statusCode\": 200, \"headers\": {\"Content-Type\": \"application/json\"}, \"body\": json.dumps({\"ok\": True, \"path\": event[\"path\"]})}\n'); \
+z.close(); \
+print('Lambda zip created')"
+	aws --endpoint-url=http://localhost:$(PORT) lambda create-function \
+		--function-name alb-test-fn --runtime python3.12 \
+		--handler index.handler \
+		--role arn:aws:iam::000000000000:role/role \
+		--zip-file fileb:///tmp/ms-alb-test.zip
+	@LB_ARN=$$(aws --endpoint-url=http://localhost:$(PORT) elbv2 create-load-balancer \
+		--name test-alb --query 'LoadBalancers[0].LoadBalancerArn' --output text) && \
+	TG_ARN=$$(aws --endpoint-url=http://localhost:$(PORT) elbv2 create-target-group \
+		--name test-tg --target-type lambda --protocol HTTP --port 80 \
+		--vpc-id vpc-00000001 --query 'TargetGroups[0].TargetGroupArn' --output text) && \
+	FN_ARN=$$(aws --endpoint-url=http://localhost:$(PORT) lambda get-function \
+		--function-name alb-test-fn --query 'Configuration.FunctionArn' --output text) && \
+	aws --endpoint-url=http://localhost:$(PORT) elbv2 register-targets \
+		--target-group-arn $$TG_ARN --targets Id=$$FN_ARN && \
+	aws --endpoint-url=http://localhost:$(PORT) elbv2 create-listener \
+		--load-balancer-arn $$LB_ARN --protocol HTTP --port 80 \
+		--default-actions Type=forward,TargetGroupArn=$$TG_ARN && \
+	RESULT=$$(curl -sf http://localhost:$(PORT)/_alb/test-alb/ping) && \
+	echo "ALB response: $$RESULT" && \
+	echo "$$RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); assert d['ok'] and d['path']=='/ping', f'Unexpected response: {d}'" && \
+	echo "ALB -> Lambda routing: OK"
+	@echo ""
+	@echo "=== All tests passed ==="
+
+clean: stop
+	docker rmi $(IMAGE_NAME) 2>/dev/null || true
+
+purge: stop-compose
+	docker rm -f $$(docker ps -aq --filter "label=ministack") 2>/dev/null || true
+	docker volume prune -f
+	rm -rf ./data/s3/*
+	@echo "Orphaned ministack containers, dangling volumes, and S3 data cleared"

aws_infra/README.md

@@ -0,0 +1,1163 @@
+<p align="center">
+  <img src="ministack_logo.png" alt="MiniStack — Free Open-Source AWS Emulator" width="400"/>
+</p>
+
+<h1 align="center">MiniStack</h1>
+<p align="center"><strong>Free, open-source local AWS emulator. Free forever.</strong></p>
+<p align="center">40+ AWS services on a single port · Terraform compatible · Real databases · MIT licensed</p>
+
+<p align="center">
+  <a href="https://github.com/ministackorg/ministack/releases"><img src="https://img.shields.io/github/v/release/ministackorg/ministack" alt="GitHub release"></a>
+  <a href="https://github.com/ministackorg/ministack/actions"><img src="https://img.shields.io/github/actions/workflow/status/ministackorg/ministack/ci.yml?branch=master" alt="Build"></a>
+  <a href="https://hub.docker.com/r/ministackorg/ministack"><img src="https://img.shields.io/docker/pulls/ministackorg/ministack" alt="Docker Pulls"></a>
+  <a href="https://hub.docker.com/r/ministackorg/ministack"><img src="https://img.shields.io/docker/image-size/ministackorg/ministack/latest" alt="Docker Image Size"></a>
+  <a href="https://github.com/ministackorg/ministack/blob/master/LICENSE"><img src="https://img.shields.io/github/license/ministackorg/ministack" alt="License"></a>
+  <img src="https://img.shields.io/badge/python-3.12-blue" alt="Python">
+  <a href="https://github.com/ministackorg/ministack/stargazers"><img src="https://img.shields.io/github/stars/ministackorg/ministack" alt="GitHub stars"></a>
+</p>
+
+<p align="center">
+  <a href="https://ministack.org">Website</a> · <a href="https://hub.docker.com/r/ministackorg/ministack">Docker Hub</a> · <a href="https://www.linkedin.com/company/ministackorg/">LinkedIn</a> · <a href="https://www.producthunt.com/products/ministack">Product Hunt</a>
+</p>
+
+---
+
+## Why MiniStack?
+
+LocalStack recently moved its core services behind a paid plan. If you relied on LocalStack Community for local development and CI/CD pipelines, MiniStack is your free alternative.
+
+- **40+ AWS services** emulated on a single port (4566)
+- **Drop-in compatible** — works with `boto3`, AWS CLI, Terraform, CDK, Pulumi, any SDK
+- **Real infrastructure** — RDS spins up actual Postgres/MySQL containers, ElastiCache spins up real Redis, Athena runs real SQL via DuckDB, ECS runs real Docker containers
+- **Tiny footprint** — ~270MB image, ~21MB RAM at idle vs LocalStack's ~1GB image and ~500MB RAM
+- **Fast startup** — under 2 seconds, HTTP/2 (h2c) supported
+- **MIT licensed** — use it, fork it, contribute to it
+
+---
+
+## Quick Start
+
+```bash
+# Option 1: PyPI (simplest)
+pip install ministack
+ministack
+# Runs on http://localhost:4566 — use GATEWAY_PORT=XXXX to change
+
+# Option 2: Docker Hub
+docker run -p 4566:4566 ministackorg/ministack
+
+# Option 2b: Docker Hub with real infrastructure (RDS, ECS, Lambda containers)
+docker run -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock ministackorg/ministack
+
+# Option 3: Clone and build
+git clone https://github.com/ministackorg/ministack
+cd ministack
+docker compose up -d
+
+# Verify (any option)
+curl http://localhost:4566/_ministack/health
+```
+
+That's it. No account, no API key, no sign-up.
+
+---
+
+## Internal API
+
+MiniStack exposes internal endpoints for test automation:
+
+```bash
+# Health check — returns service status
+curl http://localhost:4566/_ministack/health
+
+# Reset all state — wipe every service back to empty (useful between test runs)
+curl -X POST http://localhost:4566/_ministack/reset
+
+# Reset and re-run init scripts (boot.d + ready.d)
+curl -X POST http://localhost:4566/_ministack/reset?init=1
+
+# Runtime config — change service-level settings without restart
+curl -X POST http://localhost:4566/_ministack/config \
+  -H "Content-Type: application/json" \
+  -d '{"lambda_svc.LAMBDA_EXECUTOR": "docker"}'
+```
+
+The reset endpoint is especially useful in CI pipelines and test suites — call it in `setUp`/`beforeEach` to get a clean environment for every test without restarting the container. Add `?init=1` to re-run your init scripts after the reset, restoring any resources they create (VPCs, queues, seed data, etc.).
+
+The config endpoint supports these keys:
+
+| Key | Description |
+|-----|-------------|
+| `lambda_svc.LAMBDA_EXECUTOR` | Lambda execution mode (`local` or `docker`) |
+| `athena.ATHENA_ENGINE` | Athena query engine (`duckdb` or `mock`) |
+| `athena.ATHENA_DATA_DIR` | Directory for Athena DuckDB data files |
+| `stepfunctions._sfn_mock_config` | SFN mock config (AWS SFN Local compatible) |
+| `stepfunctions._SFN_WAIT_SCALE` | Scale factor for Wait state durations and retry sleeps (`0` = skip all waits) |
+
+To set region or account ID, use environment variables at startup:
+
+```bash
+docker run -p 4566:4566 \
+  -e MINISTACK_REGION=eu-west-1 \
+  -e MINISTACK_ACCOUNT_ID=123456789012 \
+  ministackorg/ministack
+```
+
+Or use the multi-tenancy feature — a 12-digit access key automatically becomes the account ID (see [Multi-Tenancy](#multi-tenancy) below).
+
+Also compatible with LocalStack's health endpoint:
+
+```bash
+curl http://localhost:4566/_localstack/health
+curl http://localhost:4566/health
+```
+
+---
+
+## Multi-Tenancy
+
+MiniStack supports lightweight multi-tenancy without any configuration. If the `AWS_ACCESS_KEY_ID` is a **12-digit number**, it is used as the **Account ID** for all ARN generation. Non-numeric keys (like `test`) fall back to the `MINISTACK_ACCOUNT_ID` env var or `000000000000`.
+
+```bash
+# Team A — gets account 111111111111
+export AWS_ACCESS_KEY_ID=111111111111
+export AWS_SECRET_ACCESS_KEY=anything
+aws --endpoint-url=http://localhost:4566 sts get-caller-identity
+# → { "Account": "111111111111", ... }
+
+# Team B — gets account 222222222222
+export AWS_ACCESS_KEY_ID=222222222222
+export AWS_SECRET_ACCESS_KEY=anything
+aws --endpoint-url=http://localhost:4566 sts get-caller-identity
+# → { "Account": "222222222222", ... }
+```
+
+All ARNs and resource state (SQS queues, Lambda functions, IAM roles, S3 buckets, DynamoDB tables, etc.) are fully isolated per account. Resources with the same name in different accounts never collide. This allows multiple developers or CI pipelines to share a single MiniStack endpoint with complete tenant isolation — no extra setup needed.
+
+| Access Key | Account ID Used |
+|---|---|
+| `111111111111` | `111111111111` |
+| `048408301323` | `048408301323` |
+| `test` | `000000000000` (default) |
+| `AKIAIOSFODNN7EXAMPLE` | `000000000000` (default) |
+
+**Terraform** — set `access_key` in your provider block:
+```hcl
+provider "aws" {
+  access_key = "048408301323"
+  secret_key = "test"
+  region     = "us-east-1"
+  endpoints { ... }
+}
+```
+
+**boto3** — pass `aws_access_key_id`:
+```python
+boto3.client("s3",
+    endpoint_url="http://localhost:4566",
+    aws_access_key_id="048408301323",
+    aws_secret_access_key="test",
+)
+```
+
+---
+
+## Using with AWS CLI
+
+```bash
+# Option A — environment variables (no profile needed)
+export AWS_ACCESS_KEY_ID=test
+export AWS_SECRET_ACCESS_KEY=test
+export AWS_DEFAULT_REGION=us-east-1
+
+aws --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket
+aws --endpoint-url=http://localhost:4566 sqs create-queue --queue-name my-queue
+aws --endpoint-url=http://localhost:4566 dynamodb list-tables
+aws --endpoint-url=http://localhost:4566 sts get-caller-identity
+
+# Option B — named profile (must pass --profile on every command)
+aws configure --profile local
+# AWS Access Key ID: test
+# AWS Secret Access Key: test
+# Default region: us-east-1
+# Default output format: json
+
+aws --profile local --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket
+aws --profile local --endpoint-url=http://localhost:4566 s3 cp ./file.txt s3://my-bucket/
+aws --profile local --endpoint-url=http://localhost:4566 sqs create-queue --queue-name my-queue
+aws --profile local --endpoint-url=http://localhost:4566 dynamodb list-tables
+aws --profile local --endpoint-url=http://localhost:4566 sts get-caller-identity
+```
+
+### awslocal wrapper
+
+```bash
+chmod +x bin/awslocal
+./bin/awslocal s3 ls
+./bin/awslocal dynamodb list-tables
+```
+
+---
+
+## Using with boto3
+
+```python
+import boto3
+
+# All clients use the same endpoint
+def client(service):
+    return boto3.client(
+        service,
+        endpoint_url="http://localhost:4566",
+        aws_access_key_id="test",
+        aws_secret_access_key="test",
+        region_name="us-east-1",
+    )
+
+# S3
+s3 = client("s3")
+s3.create_bucket(Bucket="my-bucket")
+s3.put_object(Bucket="my-bucket", Key="hello.txt", Body=b"Hello, MiniStack!")
+obj = s3.get_object(Bucket="my-bucket", Key="hello.txt")
+print(obj["Body"].read())  # b'Hello, MiniStack!'
+
+# SQS
+sqs = client("sqs")
+q = sqs.create_queue(QueueName="my-queue")
+sqs.send_message(QueueUrl=q["QueueUrl"], MessageBody="hello")
+msgs = sqs.receive_message(QueueUrl=q["QueueUrl"])
+print(msgs["Messages"][0]["Body"])  # hello
+
+# DynamoDB
+ddb = client("dynamodb")
+ddb.create_table(
+    TableName="Users",
+    KeySchema=[{"AttributeName": "userId", "KeyType": "HASH"}],
+    AttributeDefinitions=[{"AttributeName": "userId", "AttributeType": "S"}],
+    BillingMode="PAY_PER_REQUEST",
+)
+ddb.put_item(TableName="Users", Item={"userId": {"S": "u1"}, "name": {"S": "Alice"}})
+
+# SSM Parameter Store
+ssm = client("ssm")
+ssm.put_parameter(Name="/app/db/host", Value="localhost", Type="String")
+param = ssm.get_parameter(Name="/app/db/host")
+print(param["Parameter"]["Value"])  # localhost
+
+# Secrets Manager
+sm = client("secretsmanager")
+sm.create_secret(Name="db-password", SecretString='{"password":"s3cr3t"}')
+
+# Kinesis
+kin = client("kinesis")
+kin.create_stream(StreamName="events", ShardCount=1)
+kin.put_record(StreamName="events", Data=b'{"event":"click"}', PartitionKey="user1")
+
+# EventBridge
+eb = client("events")
+eb.put_events(Entries=[{
+    "Source": "myapp",
+    "DetailType": "UserSignup",
+    "Detail": '{"userId": "123"}',
+    "EventBusName": "default",
+}])
+
+# Step Functions
+sfn = client("stepfunctions")
+sfn.create_state_machine(
+    name="my-workflow",
+    definition='{"StartAt":"Hello","States":{"Hello":{"Type":"Pass","End":true}}}',
+    roleArn="arn:aws:iam::000000000000:role/role",
+)
+
+# Step Functions — TestState API (test a single state in isolation)
+# Note: inject_host_prefix=False prevents boto3 from prepending "sync-" to the hostname
+from botocore.config import Config as BotoConfig
+sfn_test = client("stepfunctions", config=BotoConfig(inject_host_prefix=False))
+
+result = sfn_test.test_state(
+    definition='{"Type":"Pass","Result":{"greeting":"hello"},"End":true}',
+    input='{"name":"world"}',
+)
+print(result["status"])  # SUCCEEDED
+print(result["output"])  # {"greeting": "hello"}
+
+# TestState with mock — test error handling without calling real services
+result = sfn_test.test_state(
+    definition=json.dumps({
+        "Type": "Task",
+        "Resource": "arn:aws:lambda:us-east-1:000000000000:function:my-fn",
+        "Catch": [{"ErrorEquals": ["States.ALL"], "Next": "Fallback"}],
+        "End": True
+    }),
+    input='{}',
+    inspectionLevel="DEBUG",
+    mock={"errorOutput": {"error": "ServiceError", "cause": "Timeout"}},
+)
+print(result["status"])  # CAUGHT_ERROR
+print(result["nextState"])  # Fallback
+
+# EC2
+ec2 = client("ec2")
+reservation = ec2.run_instances(
+    ImageId="ami-00000001",
+    MinCount=1,
+    MaxCount=1,
+    InstanceType="t3.micro",
+)
+instance_id = reservation["Instances"][0]["InstanceId"]
+print(instance_id)  # i-xxxxxxxxxxxxxxxxx
+
+# Security Groups
+sg = ec2.create_security_group(GroupName="my-sg", Description="My SG")
+ec2.authorize_security_group_ingress(
+    GroupId=sg["GroupId"],
+    IpPermissions=[{"IpProtocol": "tcp", "FromPort": 80, "ToPort": 80,
+                    "IpRanges": [{"CidrIp": "0.0.0.0/0"}]}],
+)
+
+# VPC / Subnet
+vpc = ec2.create_vpc(CidrBlock="10.0.0.0/16")
+subnet = ec2.create_subnet(
+    VpcId=vpc["Vpc"]["VpcId"],
+    CidrBlock="10.0.1.0/24",
+    AvailabilityZone="us-east-1a",
+)
+```
+
+---
+
+## Supported Services
+
+### Core Services
+
+| Service | Operations | Notes |
+|---------|-----------|-------|
+| **S3** | CreateBucket, DeleteBucket, ListBuckets, HeadBucket, PutObject, GetObject, DeleteObject, HeadObject, CopyObject, ListObjects v1/v2, DeleteObjects, GetBucketVersioning, PutBucketVersioning, GetBucketEncryption, PutBucketEncryption, DeleteBucketEncryption, GetBucketLifecycleConfiguration, PutBucketLifecycleConfiguration, DeleteBucketLifecycle, GetBucketCors, PutBucketCors, DeleteBucketCors, GetBucketAcl, PutBucketAcl, GetBucketTagging, PutBucketTagging, DeleteBucketTagging, GetBucketPolicy, PutBucketPolicy, DeleteBucketPolicy, GetBucketNotificationConfiguration, PutBucketNotificationConfiguration, GetBucketLogging, PutBucketLogging, ListObjectVersions, CreateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload, PutObjectLockConfiguration, GetObjectLockConfiguration, PutObjectRetention, GetObjectRetention, PutObjectLegalHold, GetObjectLegalHold, PutBucketReplication, GetBucketReplication, DeleteBucketReplication | Optional disk persistence via `S3_PERSIST=1`; Object Lock with retention & legal hold enforcement on delete |
+| **SQS** | CreateQueue, DeleteQueue, ListQueues, GetQueueUrl, GetQueueAttributes, SetQueueAttributes, PurgeQueue, SendMessage, ReceiveMessage, DeleteMessage, ChangeMessageVisibility, ChangeMessageVisibilityBatch, SendMessageBatch, DeleteMessageBatch, TagQueue, UntagQueue, ListQueueTags | Both Query API and JSON protocol; FIFO queues with deduplication; DLQ support |
+| **SNS** | CreateTopic, DeleteTopic, ListTopics, GetTopicAttributes, SetTopicAttributes, Subscribe, Unsubscribe, ListSubscriptions, ListSubscriptionsByTopic, GetSubscriptionAttributes, SetSubscriptionAttributes, ConfirmSubscription, Publish, PublishBatch, TagResource, UntagResource, ListTagsForResource, CreatePlatformApplication, CreatePlatformEndpoint | SNS→SQS fanout delivery; SNS→Lambda fanout (synchronous invocation); FIFO topics with 5-minute deduplication, sequence numbers, content-based deduplication, and subscription validation |
+| **DynamoDB** | CreateTable, UpdateTable, DeleteTable, DescribeTable, ListTables, PutItem, GetItem, DeleteItem, UpdateItem, Query, Scan, BatchWriteItem, BatchGetItem, TransactWriteItems, TransactGetItems, DescribeTimeToLive, UpdateTimeToLive, DescribeContinuousBackups, UpdateContinuousBackups, DescribeEndpoints, TagResource, UntagResource, ListTagsOfResource | TTL enforced via thread-safe background reaper (60s cadence); DynamoDB Streams — `StreamSpecification` emits INSERT/MODIFY/REMOVE records on all write operations, respects `StreamViewType` |
+| **Lambda** | CreateFunction, DeleteFunction, GetFunction, GetFunctionConfiguration, ListFunctions, Invoke, UpdateFunctionCode, UpdateFunctionConfiguration, AddPermission, RemovePermission, GetPolicy, ListVersionsByFunction, PublishVersion, CreateAlias, GetAlias, UpdateAlias, DeleteAlias, ListAliases, TagResource, UntagResource, ListTags, CreateEventSourceMapping, DeleteEventSourceMapping, GetEventSourceMapping, ListEventSourceMappings, UpdateEventSourceMapping, CreateFunctionUrlConfig, GetFunctionUrlConfig, UpdateFunctionUrlConfig, DeleteFunctionUrlConfig, ListFunctionUrlConfigs, PutFunctionConcurrency, GetFunctionConcurrency, DeleteFunctionConcurrency, PutFunctionEventInvokeConfig, GetFunctionEventInvokeConfig, DeleteFunctionEventInvokeConfig, PublishLayerVersion, GetLayerVersion, GetLayerVersionByArn, ListLayerVersions, DeleteLayerVersion, ListLayers, AddLayerVersionPermission, RemoveLayerVersionPermission, GetLayerVersionPolicy | Python and Node.js runtimes execute with warm worker pool; `provided.al2023`/`provided.al2` runtimes execute via Docker RIE (Go, Rust, C++ support); `Publish=True` creates immutable numbered versions; Code via `ZipFile`, `S3Bucket`/`S3Key`, or `ImageUri` (Docker image); `PackageType: Image` pulls and invokes user-provided Docker images via Lambda RIE; SQS, Kinesis, and DynamoDB Streams event source mappings; Function URL CRUD; Lambda Layers CRUD; Aliases; Concurrency; EventInvokeConfig |
+| **IAM** | CreateUser, GetUser, ListUsers, DeleteUser, CreateRole, GetRole, ListRoles, DeleteRole, CreatePolicy, GetPolicy, DeletePolicy, AttachRolePolicy, DetachRolePolicy, PutRolePolicy, GetRolePolicy, DeleteRolePolicy, ListRolePolicies, ListAttachedRolePolicies, CreateAccessKey, ListAccessKeys, DeleteAccessKey, CreateInstanceProfile, GetInstanceProfile, DeleteInstanceProfile, AddRoleToInstanceProfile, RemoveRoleFromInstanceProfile, ListInstanceProfiles, CreateGroup, GetGroup, AddUserToGroup, RemoveUserFromGroup, CreateServiceLinkedRole, DeleteServiceLinkedRole, GetServiceLinkedRoleDeletionStatus, CreateOpenIDConnectProvider, TagRole, UntagRole, TagUser, UntagUser, TagPolicy, UntagPolicy | |
+| **STS** | GetCallerIdentity, AssumeRole, GetSessionToken, AssumeRoleWithWebIdentity | |
+| **SecretsManager** | CreateSecret, GetSecretValue, ListSecrets, DeleteSecret, UpdateSecret, DescribeSecret, PutSecretValue, UpdateSecretVersionStage, RestoreSecret, RotateSecret, GetRandomPassword, ListSecretVersionIds, ReplicateSecretToRegions, TagResource, UntagResource, PutResourcePolicy, GetResourcePolicy, DeleteResourcePolicy, ValidateResourcePolicy | |
+| **CloudWatch Logs** | CreateLogGroup, DeleteLogGroup, DescribeLogGroups, CreateLogStream, DeleteLogStream, DescribeLogStreams, PutLogEvents, GetLogEvents, FilterLogEvents, PutRetentionPolicy, DeleteRetentionPolicy, PutSubscriptionFilter, DeleteSubscriptionFilter, DescribeSubscriptionFilters, PutMetricFilter, DeleteMetricFilter, DescribeMetricFilters, TagLogGroup, UntagLogGroup, ListTagsLogGroup, TagResource, UntagResource, ListTagsForResource, StartQuery, GetQueryResults, StopQuery, PutDestination, DeleteDestination, DescribeDestinations, PutDestinationPolicy | `FilterLogEvents` supports `*`/`?` globs, multi-term AND, `-term` exclusion |
+
+### Extended Services
+
+| Service | Operations | Notes |
+|---------|-----------|-------|
+| **SSM Parameter Store** | PutParameter, GetParameter, GetParameters, GetParametersByPath, DeleteParameter, DeleteParameters, DescribeParameters, GetParameterHistory, LabelParameterVersion, AddTagsToResource, RemoveTagsFromResource, ListTagsForResource | Supports String, SecureString, StringList |
+| **EventBridge** | CreateEventBus, UpdateEventBus, DeleteEventBus, ListEventBuses, DescribeEventBus, PutRule, DeleteRule, ListRules, DescribeRule, EnableRule, DisableRule, PutTargets, RemoveTargets, ListTargetsByRule, ListRuleNamesByTarget, PutEvents, TestEventPattern, TagResource, UntagResource, ListTagsForResource, CreateArchive, DeleteArchive, DescribeArchive, UpdateArchive, ListArchives, PutPermission, RemovePermission, CreateConnection, DescribeConnection, DeleteConnection, UpdateConnection, DeauthorizeConnection, ListConnections, CreateApiDestination, DescribeApiDestination, DeleteApiDestination, UpdateApiDestination, ListApiDestinations, StartReplay, DescribeReplay, ListReplays, CancelReplay, CreateEndpoint, DeleteEndpoint, DescribeEndpoint, ListEndpoints, UpdateEndpoint, ActivateEventSource, DeactivateEventSource, DescribeEventSource, CreatePartnerEventSource, DeletePartnerEventSource, DescribePartnerEventSource, ListPartnerEventSources, ListPartnerEventSourceAccounts, ListEventSources, PutPartnerEvents | Lambda target dispatch on PutEvents; S3 EventBridge notifications; replays and SaaS/partner APIs are control-plane stubs |
+| **Kinesis** | CreateStream, DeleteStream, DescribeStream, DescribeStreamSummary, ListStreams, ListShards, PutRecord, PutRecords, GetShardIterator, GetRecords, IncreaseStreamRetentionPeriod, DecreaseStreamRetentionPeriod, MergeShards, SplitShard, UpdateShardCount, StartStreamEncryption, StopStreamEncryption, EnableEnhancedMonitoring, DisableEnhancedMonitoring, RegisterStreamConsumer, DeregisterStreamConsumer, ListStreamConsumers, DescribeStreamConsumer, AddTagsToStream, RemoveTagsFromStream, ListTagsForStream | Partition key → shard routing; AWS limits enforced (1 MB/record, 500 records/batch, 5 MB payload, 256-char partition key) |
+| **CloudWatch Metrics** | PutMetricData, GetMetricStatistics, GetMetricData, ListMetrics, PutMetricAlarm, PutCompositeAlarm, DescribeAlarms, DescribeAlarmsForMetric, DescribeAlarmHistory, DeleteAlarms, SetAlarmState, EnableAlarmActions, DisableAlarmActions, TagResource, UntagResource, ListTagsForResource, PutDashboard, GetDashboard, DeleteDashboards, ListDashboards | CBOR and JSON protocol |
+| **SES** | SendEmail, SendRawEmail, SendTemplatedEmail, SendBulkTemplatedEmail, VerifyEmailIdentity, VerifyEmailAddress, VerifyDomainIdentity, VerifyDomainDkim, ListIdentities, ListVerifiedEmailAddresses, GetIdentityVerificationAttributes, GetIdentityDkimAttributes, DeleteIdentity, GetSendQuota, GetSendStatistics, SetIdentityNotificationTopic, SetIdentityFeedbackForwardingEnabled, CreateConfigurationSet, DeleteConfigurationSet, DescribeConfigurationSet, ListConfigurationSets, CreateTemplate, GetTemplate, UpdateTemplate, DeleteTemplate, ListTemplates | Emails stored in-memory, not sent |
+| **SES v2** | SendEmail, CreateEmailIdentity, GetEmailIdentity, DeleteEmailIdentity, ListEmailIdentities, CreateConfigurationSet, GetConfigurationSet, DeleteConfigurationSet, ListConfigurationSets, GetAccount, PutAccountSuppressionAttributes, ListSuppressedDestinations | REST API (`/v2/email/`); identities auto-verified; emails stored in-memory, not sent |
+| **ACM** | RequestCertificate, DescribeCertificate, ListCertificates, DeleteCertificate, GetCertificate, ImportCertificate, AddTagsToCertificate, RemoveTagsFromCertificate, ListTagsForCertificate, UpdateCertificateOptions, RenewCertificate, ResendValidationEmail | Certificates auto-issued; DNS validation records generated; supports SANs |
+| **WAF v2** | CreateWebACL, GetWebACL, UpdateWebACL, DeleteWebACL, ListWebACLs, AssociateWebACL, DisassociateWebACL, GetWebACLForResource, ListResourcesForWebACL, CreateIPSet, GetIPSet, UpdateIPSet, DeleteIPSet, ListIPSets, CreateRuleGroup, GetRuleGroup, UpdateRuleGroup, DeleteRuleGroup, ListRuleGroups, TagResource, UntagResource, ListTagsForResource, CheckCapacity, DescribeManagedRuleGroup | LockToken enforced on Update/Delete; resource associations tracked |
+| **Step Functions** | CreateStateMachine, DeleteStateMachine, DescribeStateMachine, UpdateStateMachine, ListStateMachines, StartExecution, StartSyncExecution, StopExecution, DescribeExecution, DescribeStateMachineForExecution, ListExecutions, GetExecutionHistory, SendTaskSuccess, SendTaskFailure, SendTaskHeartbeat, CreateActivity, DeleteActivity, DescribeActivity, ListActivities, GetActivityTask, TestState, TagResource, UntagResource, ListTagsForResource | Full ASL interpreter; Retry/Catch; waitForTaskToken; Activities (worker pattern); Pass/Task/Choice/Wait/Succeed/Fail/Map/Parallel; TestState API with mock and inspectionLevel support; SFN_MOCK_CONFIG for AWS SFN Local compatible mock testing; intrinsic functions (States.StringToJson, States.JsonToString, States.JsonMerge, States.Format); nested startExecution.sync |
+| **API Gateway v2** | CreateApi, GetApi, GetApis, UpdateApi, DeleteApi, CreateRoute, GetRoute, GetRoutes, UpdateRoute, DeleteRoute, CreateIntegration, GetIntegration, GetIntegrations, UpdateIntegration, DeleteIntegration, CreateRouteResponse, GetRouteResponse, GetRouteResponses, UpdateRouteResponse, DeleteRouteResponse, CreateIntegrationResponse, GetIntegrationResponse, GetIntegrationResponses, UpdateIntegrationResponse, DeleteIntegrationResponse, CreateStage, GetStage, GetStages, UpdateStage, DeleteStage, CreateDeployment, GetDeployment, GetDeployments, DeleteDeployment, CreateAuthorizer, GetAuthorizer, GetAuthorizers, UpdateAuthorizer, DeleteAuthorizer, TagResource, UntagResource, GetTags, PostToConnection, GetConnection, DeleteConnection | **HTTP API** and **WebSocket API** (`protocolType=WEBSOCKET`); Lambda proxy (`AWS_PROXY`), HTTP proxy (`HTTP_PROXY`), and MOCK integrations; HTTP data plane via `{apiId}.execute-api.localhost` Host header or path-based `/_aws/execute-api/{apiId}/{stage}/{path}` (no DNS/Host override needed — works from browsers on macOS and strict clients); `$default` stage served from the URL root (no stage segment in the path); per-API `corsConfiguration` applied to preflights + dispatched responses; qualified-alias integration URIs (`arn:...:function:<name>:<alias>`) resolve to the alias's target version; WebSocket data plane on the same two URL forms, with `$connect` / `$disconnect` / `$default` / custom-action routing, `$request.body.*` RouteSelectionExpression, `@connections` management API (PostToConnection / GetConnection / DeleteConnection), per-connection outbox for server-side push; `{param}` / `{proxy+}` matching; JWT/Lambda authorizer CRUD; pin `apiId` across runs with the `ms-custom-id` tag |
+| **API Gateway v1** | CreateRestApi, GetRestApi, GetRestApis, UpdateRestApi, DeleteRestApi, CreateResource, GetResource, GetResources, UpdateResource, DeleteResource, PutMethod, GetMethod, DeleteMethod, UpdateMethod, PutMethodResponse, GetMethodResponse, DeleteMethodResponse, PutIntegration, GetIntegration, DeleteIntegration, UpdateIntegration, PutIntegrationResponse, GetIntegrationResponse, DeleteIntegrationResponse, CreateDeployment, GetDeployment, GetDeployments, UpdateDeployment, DeleteDeployment, CreateStage, GetStage, GetStages, UpdateStage, DeleteStage, CreateAuthorizer, GetAuthorizer, GetAuthorizers, UpdateAuthorizer, DeleteAuthorizer, CreateModel, GetModel, GetModels, DeleteModel, CreateApiKey, GetApiKey, GetApiKeys, UpdateApiKey, DeleteApiKey, CreateUsagePlan, GetUsagePlan, GetUsagePlans, UpdateUsagePlan, DeleteUsagePlan, CreateUsagePlanKey, GetUsagePlanKeys, DeleteUsagePlanKey, CreateDomainName, GetDomainName, GetDomainNames, DeleteDomainName, CreateBasePathMapping, GetBasePathMapping, GetBasePathMappings, DeleteBasePathMapping, TagResource, UntagResource, GetTags | REST API (v1) protocol; Lambda proxy format 1.0 (AWS_PROXY), HTTP proxy (HTTP_PROXY), MOCK integration; data plane via `{apiId}.execute-api.localhost` Host header, path-based `/_aws/execute-api/{apiId}/{stage}/{path}`, or legacy `/restapis/{apiId}/{stage}/_user_request_/{path}`; qualified-alias integration URIs (`arn:...:function:<name>:<alias>`) resolve to the alias's target version; resource tree with `{param}` and `{proxy+}` path matching; JSON Patch for all PATCH operations; state persistence; pin `id` across runs with the `ms-custom-id` tag |
+| **ELBv2 / ALB** | CreateLoadBalancer, DescribeLoadBalancers, DeleteLoadBalancer, DescribeLoadBalancerAttributes, ModifyLoadBalancerAttributes, CreateTargetGroup, DescribeTargetGroups, ModifyTargetGroup, DeleteTargetGroup, DescribeTargetGroupAttributes, ModifyTargetGroupAttributes, CreateListener, DescribeListeners, ModifyListener, DeleteListener, CreateRule, DescribeRules, ModifyRule, DeleteRule, SetRulePriorities, RegisterTargets, DeregisterTargets, DescribeTargetHealth, AddTags, RemoveTags, DescribeTags | Control plane + data plane; ALB→Lambda live traffic routing; `path-pattern`, `host-header`, `http-method`, `query-string`, `http-header` rule conditions; `forward`, `redirect`, `fixed-response` actions; data plane via `{lb-name}.alb.localhost` Host header or `/_alb/{lb-name}/` path prefix |
+| **KMS** | CreateKey, ListKeys, DescribeKey, GetPublicKey, Sign, Verify, Encrypt, Decrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext, CreateAlias, DeleteAlias, ListAliases, UpdateAlias, EnableKeyRotation, DisableKeyRotation, GetKeyRotationStatus, GetKeyPolicy, PutKeyPolicy, ListKeyPolicies, EnableKey, DisableKey, ScheduleKeyDeletion, CancelKeyDeletion, TagResource, UntagResource, ListResourceTags | 27 actions; RSA (2048/4096), ECC (SECG_P256K1, NIST P-256/384/521), and symmetric keys; PKCS1v15, PSS, and ECDSA signing; envelope encryption; alias resolution; key rotation; key policies; tags; enable/disable/schedule deletion; full Terraform `aws_kms_key` compatible; `cryptography` package included in Docker image |
+| **CloudFront** | CreateDistribution, GetDistribution, GetDistributionConfig, ListDistributions, UpdateDistribution, DeleteDistribution, CreateInvalidation, ListInvalidations, GetInvalidation, CreateOriginAccessControl, GetOriginAccessControl, GetOriginAccessControlConfig, ListOriginAccessControls, UpdateOriginAccessControl, DeleteOriginAccessControl, TagResource, UntagResource, ListTagsForResource | REST/XML API; ETag-based optimistic concurrency; Origin Access Control (OAC) with SigV4 signing for S3, MediaStore, Lambda, MediaPackageV2 origins; field validation and name uniqueness enforcement |
+
+### CloudFormation
+
+| Feature | Details |
+|---------|---------|
+| **Stack Operations** | CreateStack, UpdateStack, DeleteStack, DescribeStacks, ListStacks, DescribeStackEvents, DescribeStackResource, DescribeStackResources, GetTemplate, ValidateTemplate, GetTemplateSummary |
+| **Change Sets** | CreateChangeSet, DescribeChangeSet, ExecuteChangeSet, DeleteChangeSet, ListChangeSets |
+| **Exports** | ListExports — cross-stack references via `Fn::ImportValue` |
+| **Template Formats** | JSON and YAML (including `!Ref`, `!Sub`, `!GetAtt` shorthand tags) |
+| **Intrinsic Functions** | Ref, Fn::GetAtt, Fn::Join, Fn::Sub (both forms), Fn::Select, Fn::Split, Fn::If, Fn::Equals, Fn::And, Fn::Or, Fn::Not, Fn::Base64, Fn::FindInMap, Fn::ImportValue, Fn::GetAZs, Fn::Cidr |
+| **Pseudo-Parameters** | AWS::StackName, AWS::StackId, AWS::Region, AWS::AccountId, AWS::URLSuffix, AWS::Partition, AWS::NoValue |
+| **Parameters** | Default values, AllowedValues validation, NoEcho masking, String/Number/CommaDelimitedList types |
+| **Conditions** | Fn::Equals, Fn::And, Fn::Or, Fn::Not — conditional resource creation |
+| **Rollback** | Configurable via `DisableRollback` — on failure, previously created resources are cleaned up in reverse dependency order |
+| **Async Status** | Stacks deploy asynchronously (`CREATE_IN_PROGRESS` → `CREATE_COMPLETE`) — poll with DescribeStacks |
+
+**Supported Resource Types:**
+
+| Resource Type | Ref Returns | GetAtt |
+|---------------|-------------|--------|
+| `AWS::S3::Bucket` | Bucket name | Arn, DomainName, RegionalDomainName, WebsiteURL |
+| `AWS::SQS::Queue` | Queue URL | Arn, QueueName, QueueUrl |
+| `AWS::SNS::Topic` | Topic ARN | TopicArn, TopicName |
+| `AWS::SNS::Subscription` | Subscription ARN | — |
+| `AWS::DynamoDB::Table` | Table name | Arn, StreamArn |
+| `AWS::Lambda::Function` | Function name | Arn |
+| `AWS::IAM::Role` | Role name | Arn, RoleId |
+| `AWS::IAM::Policy` | Policy ARN | — |
+| `AWS::IAM::InstanceProfile` | Profile name | Arn |
+| `AWS::SSM::Parameter` | Parameter name | Type, Value |
+| `AWS::Logs::LogGroup` | Log group name | Arn |
+| `AWS::Events::EventBus` | EventBus name | Arn, Name |
+| `AWS::Events::Rule` | Rule name | Arn |
+| `AWS::Kinesis::Stream` | Stream name | Arn, StreamId |
+| `AWS::Lambda::Permission` | Statement ID | — |
+| `AWS::Lambda::Version` | Version ARN | Version |
+| `AWS::Lambda::Alias` | Alias ARN | — |
+| `AWS::Lambda::EventSourceMapping` | UUID | — |
+| `AWS::S3::BucketPolicy` | Bucket name | — |
+| `AWS::SQS::QueuePolicy` | Policy ID | — |
+| `AWS::SNS::TopicPolicy` | Policy ID | — |
+| `AWS::ApiGateway::RestApi` | API ID | RootResourceId |
+| `AWS::ApiGateway::Resource` | Resource ID | — |
+| `AWS::ApiGateway::Method` | Method ID | — |
+| `AWS::ApiGateway::Deployment` | Deployment ID | — |
+| `AWS::ApiGateway::Stage` | Stage name | — |
+| `AWS::AppSync::GraphQLApi` | API ID | Arn, GraphQLUrl, ApiId |
+| `AWS::AppSync::DataSource` | DataSource name | DataSourceArn |
+| `AWS::AppSync::Resolver` | Resolver ARN | ResolverArn |
+| `AWS::AppSync::GraphQLSchema` | Schema ID | — |
+| `AWS::AppSync::ApiKey` | API key ID | ApiKey, Arn |
+| `AWS::SecretsManager::Secret` | Secret ARN | — |
+| `AWS::Cognito::UserPool` | Pool ID | Arn, ProviderName |
+| `AWS::Cognito::UserPoolClient` | Client ID | — |
+| `AWS::Cognito::IdentityPool` | Pool ID | — |
+| `AWS::Cognito::UserPoolDomain` | Domain | — |
+| `AWS::ECR::Repository` | Repo name | Arn, RepositoryUri |
+| `AWS::IAM::ManagedPolicy` | Policy ARN | — |
+| `AWS::KMS::Key` | Key ID | Arn, KeyId |
+| `AWS::KMS::Alias` | Alias name | — |
+| `AWS::EC2::VPC` | VPC ID | VpcId, DefaultSecurityGroup, DefaultNetworkAcl |
+| `AWS::EC2::Subnet` | Subnet ID | SubnetId, AvailabilityZone |
+| `AWS::EC2::SecurityGroup` | SG ID | GroupId, VpcId |
+| `AWS::EC2::InternetGateway` | IGW ID | InternetGatewayId |
+| `AWS::EC2::VPCGatewayAttachment` | Attachment ID | — |
+| `AWS::EC2::RouteTable` | RTB ID | RouteTableId |
+| `AWS::EC2::Route` | Route ID | — |
+| `AWS::EC2::SubnetRouteTableAssociation` | Association ID | — |
+| `AWS::EC2::LaunchTemplate` | LT ID | LaunchTemplateId, LaunchTemplateName, DefaultVersionNumber, LatestVersionNumber |
+| `AWS::ECS::Cluster` | Cluster name | Arn, ClusterName |
+| `AWS::ECS::TaskDefinition` | Task def ARN | TaskDefinitionArn |
+| `AWS::ECS::Service` | Service ARN | ServiceArn, Name |
+| `AWS::ElasticLoadBalancingV2::LoadBalancer` | LB ARN | Arn, DNSName, LoadBalancerFullName, CanonicalHostedZoneID, SecurityGroups |
+| `AWS::ElasticLoadBalancingV2::Listener` | Listener ARN | ListenerArn, Arn |
+| `AWS::Lambda::LayerVersion` | Layer version ARN | LayerVersionArn, Arn |
+| `AWS::StepFunctions::StateMachine` | State machine ARN | Arn, Name |
+| `AWS::Route53::HostedZone` | Zone ID | Id, NameServers |
+| `AWS::Route53::RecordSet` | Record FQDN (trailing dot) | Name |
+| `AWS::ApiGatewayV2::Api` | API ID | ApiId, ApiEndpoint |
+| `AWS::ApiGatewayV2::Stage` | Stage ID | StageName |
+| `AWS::SES::EmailIdentity` | Identity | EmailIdentity |
+| `AWS::WAFv2::WebACL` | WebACL ID | Arn, Id |
+| `AWS::CloudFront::Distribution` | Distribution ID | Arn, DomainName, Id |
+| `AWS::CloudWatch::Alarm` | Alarm name | Arn |
+| `AWS::RDS::DBCluster` | Cluster ID | Arn, Endpoint.Address, Endpoint.Port, ReadEndpoint.Address |
+| `AWS::AutoScaling::AutoScalingGroup` | ASG name | Arn |
+| `AWS::AutoScaling::LaunchConfiguration` | LC name | Arn |
+| `AWS::AutoScaling::ScalingPolicy` | Policy ARN | Arn, PolicyName |
+| `AWS::AutoScaling::LifecycleHook` | Hook name | LifecycleHookName |
+| `AWS::AutoScaling::ScheduledAction` | Action ARN | Arn, ScheduledActionName |
+| `AWS::Scheduler::Schedule` | Schedule name | Arn |
+| `AWS::Scheduler::ScheduleGroup` | Group name | Arn |
+| `AWS::CloudFormation::WaitCondition` | Condition ID | — |
+| `AWS::CloudFormation::WaitConditionHandle` | Handle URL | — |
+
+Unsupported resource types fail with `CREATE_FAILED` (or `ROLLBACK_COMPLETE` if rollback is enabled), so templates with unsupported types won't silently succeed.
+
+### Infrastructure Services
+
+| Service | Operations | Notes |
+|---------|-----------|-------|
+| **ECS** | CreateCluster, DeleteCluster, DescribeClusters, ListClusters, UpdateCluster, UpdateClusterSettings, PutClusterCapacityProviders, RegisterTaskDefinition, DeregisterTaskDefinition, DescribeTaskDefinition, ListTaskDefinitions, ListTaskDefinitionFamilies, DeleteTaskDefinitions, CreateService, DeleteService, DescribeServices, UpdateService, ListServices, ListServicesByNamespace, RunTask, StopTask, DescribeTasks, ListTasks, ExecuteCommand, UpdateTaskProtection, GetTaskProtection, CreateCapacityProvider, UpdateCapacityProvider, DeleteCapacityProvider, DescribeCapacityProviders, TagResource, UntagResource, ListTagsForResource, ListAccountSettings, PutAccountSetting, PutAccountSettingDefault, DeleteAccountSetting, PutAttributes, DeleteAttributes, ListAttributes, DescribeServiceDeployments, ListServiceDeployments, DescribeServiceRevisions, SubmitTaskStateChange, SubmitContainerStateChange, SubmitAttachmentStateChanges, DiscoverPollEndpoint | 47 actions; `RunTask` starts real Docker containers via Docker socket; full Terraform ECS coverage |
+| **RDS** | CreateDBInstance, DeleteDBInstance, DescribeDBInstances, ModifyDBInstance, StartDBInstance, StopDBInstance, RebootDBInstance, CreateDBInstanceReadReplica, RestoreDBInstanceFromDBSnapshot, CreateDBCluster, DeleteDBCluster, DescribeDBClusters, ModifyDBCluster, StartDBCluster, StopDBCluster, CreateDBSnapshot, DeleteDBSnapshot, DescribeDBSnapshots, CreateDBClusterSnapshot, DescribeDBClusterSnapshots, DeleteDBClusterSnapshot, CreateDBSubnetGroup, DeleteDBSubnetGroup, DescribeDBSubnetGroups, ModifyDBSubnetGroup, CreateDBParameterGroup, DeleteDBParameterGroup, DescribeDBParameterGroups, DescribeDBParameters, ModifyDBParameterGroup, CreateDBClusterParameterGroup, DescribeDBClusterParameterGroups, DeleteDBClusterParameterGroup, DescribeDBClusterParameters, ModifyDBClusterParameterGroup, CreateOptionGroup, DeleteOptionGroup, DescribeOptionGroups, DescribeOptionGroupOptions, ListTagsForResource, AddTagsToResource, RemoveTagsFromResource, DescribeDBEngineVersions, DescribeOrderableDBInstanceOptions, CreateGlobalCluster, DescribeGlobalClusters, DeleteGlobalCluster, RemoveFromGlobalCluster, ModifyGlobalCluster | `CreateDBInstance` spins up real Postgres/MySQL Docker container, returns actual `host:port` endpoint |
+| **ElastiCache** | CreateCacheCluster, DeleteCacheCluster, DescribeCacheClusters, ModifyCacheCluster, RebootCacheCluster, CreateReplicationGroup, DeleteReplicationGroup, DescribeReplicationGroups, ModifyReplicationGroup, IncreaseReplicaCount, DecreaseReplicaCount, CreateCacheSubnetGroup, DescribeCacheSubnetGroups, ModifyCacheSubnetGroup, DeleteCacheSubnetGroup, CreateCacheParameterGroup, DescribeCacheParameterGroups, ModifyCacheParameterGroup, ResetCacheParameterGroup, DeleteCacheParameterGroup, DescribeCacheParameters, DescribeCacheEngineVersions, CreateUser, DescribeUsers, DeleteUser, ModifyUser, CreateUserGroup, DescribeUserGroups, DeleteUserGroup, ModifyUserGroup, ListTagsForResource, AddTagsToResource, RemoveTagsFromResource, CreateSnapshot, DeleteSnapshot, DescribeSnapshots, DescribeEvents | `CreateCacheCluster` spins up real Redis/Memcached Docker container |
+| **Glue** | CreateDatabase, DeleteDatabase, GetDatabase, GetDatabases, UpdateDatabase, CreateTable, DeleteTable, GetTable, GetTables, UpdateTable, BatchDeleteTable, CreatePartition, DeletePartition, GetPartition, GetPartitions, BatchCreatePartition, BatchGetPartition, CreatePartitionIndex, GetPartitionIndexes, CreateConnection, DeleteConnection, GetConnection, GetConnections, CreateCrawler, DeleteCrawler, GetCrawler, GetCrawlers, UpdateCrawler, StartCrawler, StopCrawler, GetCrawlerMetrics, CreateJob, DeleteJob, GetJob, GetJobs, UpdateJob, StartJobRun, GetJobRun, GetJobRuns, BatchStopJobRun, CreateTrigger, GetTrigger, DeleteTrigger, UpdateTrigger, StartTrigger, StopTrigger, ListTriggers, BatchGetTriggers, GetTriggers, CreateWorkflow, GetWorkflow, DeleteWorkflow, UpdateWorkflow, StartWorkflowRun, CreateSecurityConfiguration, DeleteSecurityConfiguration, GetSecurityConfiguration, GetSecurityConfigurations, CreateClassifier, GetClassifier, GetClassifiers, DeleteClassifier, TagResource, UntagResource, GetTags | Python shell jobs actually execute via subprocess |
+| **Athena** | StartQueryExecution, GetQueryExecution, GetQueryResults, StopQueryExecution, ListQueryExecutions, BatchGetQueryExecution, CreateWorkGroup, DeleteWorkGroup, GetWorkGroup, ListWorkGroups, UpdateWorkGroup, CreateNamedQuery, DeleteNamedQuery, GetNamedQuery, ListNamedQueries, BatchGetNamedQuery, CreateDataCatalog, GetDataCatalog, ListDataCatalogs, DeleteDataCatalog, UpdateDataCatalog, CreatePreparedStatement, GetPreparedStatement, DeletePreparedStatement, ListPreparedStatements, GetTableMetadata, ListTableMetadata, TagResource, UntagResource, ListTagsForResource | Real SQL via **DuckDB** when installed (`pip install duckdb`), otherwise returns mock results; result pagination; column type metadata |
+| **Firehose** | CreateDeliveryStream, DeleteDeliveryStream, DescribeDeliveryStream, ListDeliveryStreams, PutRecord, PutRecordBatch, UpdateDestination, TagDeliveryStream, UntagDeliveryStream, ListTagsForDeliveryStream, StartDeliveryStreamEncryption, StopDeliveryStreamEncryption | S3 destinations write records to the local S3 emulator; all other destination types buffer in-memory; concurrency-safe `UpdateDestination` via `VersionId` |
+| **Route53** | CreateHostedZone, GetHostedZone, DeleteHostedZone, ListHostedZones, ListHostedZonesByName, UpdateHostedZoneComment, ChangeResourceRecordSets (CREATE/UPSERT/DELETE), ListResourceRecordSets, GetChange, CreateHealthCheck, GetHealthCheck, DeleteHealthCheck, ListHealthChecks, UpdateHealthCheck, ChangeTagsForResource, ListTagsForResource | REST/XML protocol; SOA + NS records auto-created; CallerReference idempotency; alias records, weighted/failover/latency routing; marker-based pagination |
+| **EC2** | RunInstances, DescribeInstances, DescribeInstanceAttribute, DescribeInstanceTypes, DescribeVpcAttribute, TerminateInstances, StopInstances, StartInstances, RebootInstances, DescribeImages, CreateSecurityGroup, DeleteSecurityGroup, DescribeSecurityGroups, AuthorizeSecurityGroupIngress, RevokeSecurityGroupIngress, AuthorizeSecurityGroupEgress, RevokeSecurityGroupEgress, DescribeSecurityGroupRules, CreateKeyPair, DeleteKeyPair, DescribeKeyPairs, ImportKeyPair, CreateVpc, DeleteVpc, DescribeVpcs, ModifyVpcAttribute, CreateSubnet, DeleteSubnet, DescribeSubnets, ModifySubnetAttribute, CreateInternetGateway, DeleteInternetGateway, DescribeInternetGateways, AttachInternetGateway, DetachInternetGateway, CreateRouteTable, DeleteRouteTable, DescribeRouteTables, AssociateRouteTable, DisassociateRouteTable, ReplaceRouteTableAssociation, CreateRoute, ReplaceRoute, DeleteRoute, CreateNetworkInterface, DeleteNetworkInterface, DescribeNetworkInterfaces, AttachNetworkInterface, DetachNetworkInterface, CreateVpcEndpoint, DeleteVpcEndpoints, DescribeVpcEndpoints, ModifyVpcEndpoint, DescribePrefixLists, DescribeAvailabilityZones, AllocateAddress, ReleaseAddress, AssociateAddress, DisassociateAddress, DescribeAddresses, DescribeAddressesAttribute, CreateTags, DeleteTags, DescribeTags, CreateNatGateway, DescribeNatGateways, DeleteNatGateway, CreateNetworkAcl, DescribeNetworkAcls, DeleteNetworkAcl, CreateNetworkAclEntry, DeleteNetworkAclEntry, ReplaceNetworkAclEntry, ReplaceNetworkAclAssociation, CreateFlowLogs, DescribeFlowLogs, DeleteFlowLogs, CreateVpcPeeringConnection, AcceptVpcPeeringConnection, DescribeVpcPeeringConnections, DeleteVpcPeeringConnection, CreateDhcpOptions, AssociateDhcpOptions, DescribeDhcpOptions, DeleteDhcpOptions, CreateEgressOnlyInternetGateway, DescribeEgressOnlyInternetGateways, DeleteEgressOnlyInternetGateway, CreateManagedPrefixList, DescribeManagedPrefixLists, GetManagedPrefixListEntries, ModifyManagedPrefixList, DeleteManagedPrefixList, CreateVpnGateway, DescribeVpnGateways, AttachVpnGateway, DetachVpnGateway, DeleteVpnGateway, EnableVgwRoutePropagation, DisableVgwRoutePropagation, CreateCustomerGateway, DescribeCustomerGateways, DeleteCustomerGateway, DescribeInstanceCreditSpecifications, DescribeInstanceMaintenanceOptions, DescribeInstanceAutoRecoveryAttribute, ModifyInstanceMaintenanceOptions, DescribeInstanceTopology, DescribeSpotInstanceRequests, DescribeCapacityReservations, DescribeInstanceStatus, DescribeVpcClassicLink, DescribeVpcClassicLinkDnsSupport, CreateLaunchTemplate, CreateLaunchTemplateVersion, DescribeLaunchTemplates, DescribeLaunchTemplateVersions, ModifyLaunchTemplate, DeleteLaunchTemplate | 136 actions; in-memory state only — no real VMs; CreateVpc provisions per-VPC default route table, network ACL, and security group; full Terraform VPC module v6.6.0 compatible; VPN/Customer gateways, managed prefix lists, VPC endpoints with modify support; launch templates with versioning ($Latest/$Default) |
+| **EBS** | CreateVolume, DeleteVolume, DescribeVolumes, DescribeVolumeStatus, AttachVolume, DetachVolume, ModifyVolume, DescribeVolumesModifications, EnableVolumeIO, ModifyVolumeAttribute, DescribeVolumeAttribute, CreateSnapshot, DeleteSnapshot, DescribeSnapshots, CopySnapshot, ModifySnapshotAttribute, DescribeSnapshotAttribute | Part of EC2 Query/XML service; attach/detach updates volume state; snapshots stored as completed immediately; Pro-only on LocalStack — free here |
+| **EFS** | CreateFileSystem, DescribeFileSystems, DeleteFileSystem, UpdateFileSystem, CreateMountTarget, DescribeMountTargets, DeleteMountTarget, DescribeMountTargetSecurityGroups, ModifyMountTargetSecurityGroups, CreateAccessPoint, DescribeAccessPoints, DeleteAccessPoint, TagResource, UntagResource, ListTagsForResource, PutLifecycleConfiguration, DescribeLifecycleConfiguration, PutBackupPolicy, DescribeBackupPolicy, DescribeAccountPreferences, PutAccountPreferences | REST/JSON `/2015-02-01/*`; CreationToken idempotency; FileSystem deletion blocked when mount targets exist; Pro-only on LocalStack — free here |
+| **EMR** | RunJobFlow, DescribeCluster, ListClusters, TerminateJobFlows, ModifyCluster, SetTerminationProtection, SetVisibleToAllUsers, AddJobFlowSteps, DescribeStep, ListSteps, CancelSteps, AddInstanceFleet, ListInstanceFleets, ModifyInstanceFleet, AddInstanceGroups, ListInstanceGroups, ModifyInstanceGroups, ListBootstrapActions, AddTags, RemoveTags, GetBlockPublicAccessConfiguration, PutBlockPublicAccessConfiguration | Control plane only — no real Spark/Hadoop; clusters start in WAITING (KeepAlive=true) or TERMINATED (KeepAlive=false); steps stored as COMPLETED immediately; all three instance modes (simple, InstanceGroups, InstanceFleets); TerminationProtected enforced; Pro-only on LocalStack — free here |
+| **Cognito** | **User Pools**: CreateUserPool, DeleteUserPool, DescribeUserPool, ListUserPools, UpdateUserPool, CreateUserPoolClient, DeleteUserPoolClient, DescribeUserPoolClient, ListUserPoolClients, UpdateUserPoolClient, AdminCreateUser, AdminDeleteUser, AdminGetUser, ListUsers, AdminSetUserPassword, AdminUpdateUserAttributes, AdminConfirmSignUp, AdminDisableUser, AdminEnableUser, AdminResetUserPassword, AdminUserGlobalSignOut, AdminAddUserToGroup, AdminRemoveUserFromGroup, AdminListGroupsForUser, AdminListUserAuthEvents, AdminInitiateAuth, AdminRespondToAuthChallenge, InitiateAuth, RespondToAuthChallenge, GlobalSignOut, RevokeToken, SignUp, ConfirmSignUp, ForgotPassword, ConfirmForgotPassword, ChangePassword, GetUser, UpdateUserAttributes, DeleteUser, CreateGroup, DeleteGroup, GetGroup, ListGroups, ListUsersInGroup, CreateUserPoolDomain, DeleteUserPoolDomain, DescribeUserPoolDomain, GetUserPoolMfaConfig, SetUserPoolMfaConfig, AssociateSoftwareToken, VerifySoftwareToken, AdminSetUserMFAPreference, SetUserMFAPreference, TagResource, UntagResource, ListTagsForResource; **Identity Pools**: CreateIdentityPool, DeleteIdentityPool, DescribeIdentityPool, ListIdentityPools, UpdateIdentityPool, GetId, GetCredentialsForIdentity, GetOpenIdToken, SetIdentityPoolRoles, GetIdentityPoolRoles, ListIdentities, DescribeIdentity, MergeDeveloperIdentities, UnlinkDeveloperIdentity, UnlinkIdentity, TagResource, UntagResource, ListTagsForResource; **OAuth2**: /oauth2/token (client_credentials) | Stub JWT tokens (structurally valid base64url JWTs); SRP auth returns PASSWORD_VERIFIER challenge; confirmation codes hardcoded (signup: 123456, forgot-password: 654321); TOTP SOFTWARE_TOKEN_MFA challenge flow; MFA config and per-user enrollment stored in-memory |
+| **ECR** | CreateRepository, DescribeRepositories, DeleteRepository, ListImages, DescribeImages, PutImage, BatchGetImage, BatchDeleteImage, GetAuthorizationToken, GetRepositoryPolicy, SetRepositoryPolicy, DeleteRepositoryPolicy, PutLifecyclePolicy, GetLifecyclePolicy, DeleteLifecyclePolicy, ListTagsForResource, TagResource, UntagResource, PutImageTagMutability, PutImageScanningConfiguration, DescribeRegistry, GetDownloadUrlForLayer, BatchCheckLayerAvailability, InitiateLayerUpload, UploadLayerPart, CompleteLayerUpload | In-memory image registry; Docker V2 manifest support; authorization token generation; lifecycle policies; tag mutability; Pro-only on LocalStack — free here |
+| **AppSync** | CreateGraphQLApi, GetGraphQLApi, ListGraphQLApis, UpdateGraphQLApi, DeleteGraphQLApi, CreateApiKey, DeleteApiKey, ListApiKeys, CreateDataSource, GetDataSource, ListDataSources, DeleteDataSource, CreateResolver, GetResolver, ListResolvers, DeleteResolver, CreateType, ListTypes, GetType, TagResource, UntagResource, ListTagsForResource | Control plane + data plane; GraphQL queries/mutations execute against DynamoDB resolvers (create/get/list/update/delete); Lambda resolvers supported; designed for Amplify/CDK CRUD patterns — not a full GraphQL spec engine |
+| **Cloud Map** | CreateHttpNamespace, CreatePrivateDnsNamespace, CreatePublicDnsNamespace, GetNamespace, ListNamespaces, DeleteNamespace, UpdateHttpNamespace, UpdatePrivateDnsNamespace, UpdatePublicDnsNamespace, CreateService, GetService, ListServices, DeleteService, UpdateService, RegisterInstance, DeregisterInstance, DiscoverInstances, DiscoverInstancesRevision, ListInstances, GetInstancesHealthStatus, UpdateInstanceCustomHealthStatus, GetServiceAttributes, UpdateServiceAttributes, DeleteServiceAttributes, GetOperation, ListOperations, TagResource, UntagResource, ListTagsForResource | DNS namespaces create Route53 hosted zones; operation tracking; Terraform `aws_service_discovery_*` compatible |
+| **RDS Data API** | ExecuteStatement, BatchExecuteStatement, BeginTransaction, CommitTransaction, RollbackTransaction | Routes SQL to real Docker-backed RDS database containers; supports MySQL (pymysql) and PostgreSQL (psycopg2); REST paths (`/Execute`, `/BeginTransaction`, etc.) |
+| **S3 Files** | CreateFileSystem, GetFileSystem, ListFileSystems, DeleteFileSystem, CreateMountTarget, GetMountTarget, ListMountTargets, UpdateMountTarget, DeleteMountTarget, CreateAccessPoint, GetAccessPoint, ListAccessPoints, DeleteAccessPoint, GetFileSystemPolicy, PutFileSystemPolicy, DeleteFileSystemPolicy, GetSynchronizationConfiguration, PutSynchronizationConfiguration, TagResource, UntagResource, ListTagsForResource | 21 operations; control plane for the new S3 Files service (launched April 2026); file systems, mount targets, access points, policies |
+| **AutoScaling** | CreateAutoScalingGroup, DescribeAutoScalingGroups, UpdateAutoScalingGroup, DeleteAutoScalingGroup, DescribeAutoScalingInstances, CreateLaunchConfiguration, DescribeLaunchConfigurations, DeleteLaunchConfiguration, PutScalingPolicy, DescribePolicies, DeletePolicy, PutLifecycleHook, DescribeLifecycleHooks, DeleteLifecycleHook, CompleteLifecycleAction, RecordLifecycleActionHeartbeat, PutScheduledUpdateGroupAction, DescribeScheduledActions, DeleteScheduledAction, CreateOrUpdateTags, DescribeTags, DeleteTags | 23 actions; in-memory state — no real instance scaling; full ASG lifecycle (launch configs, scaling policies, lifecycle hooks, scheduled actions, tags); CDK/Terraform compatible |
+| **CodeBuild** | CreateProject, BatchGetProjects, ListProjects, UpdateProject, DeleteProject, StartBuild, BatchGetBuilds, StopBuild, ListBuilds, ListBuildsForProject, BatchDeleteBuilds | 11 actions; builds complete immediately with SUCCEEDED status; project and build metadata stored in-memory |
+| **AppConfig** | CreateApplication, GetApplication, ListApplications, UpdateApplication, DeleteApplication, CreateEnvironment, GetEnvironment, ListEnvironments, UpdateEnvironment, DeleteEnvironment, CreateConfigurationProfile, GetConfigurationProfile, ListConfigurationProfiles, UpdateConfigurationProfile, DeleteConfigurationProfile, CreateHostedConfigurationVersion, GetHostedConfigurationVersion, ListHostedConfigurationVersions, DeleteHostedConfigurationVersion, CreateDeploymentStrategy, GetDeploymentStrategy, ListDeploymentStrategies, UpdateDeploymentStrategy, DeleteDeploymentStrategy, StartDeployment, GetDeployment, ListDeployments, StopDeployment, TagResource, UntagResource, ListTagsForResource, StartConfigurationSession, GetLatestConfiguration | 33 operations; control plane + data plane; hosted configuration versions; deployments complete immediately; session-based configuration retrieval with token rotation |
+| **Transfer Family** | CreateServer, DescribeServer, DeleteServer, ListServers, CreateUser, DescribeUser, DeleteUser, ListUsers, ImportSshPublicKey, DeleteSshPublicKey | 10 operations; SFTP server and user management; SSH key rotation; LOGICAL home directory mappings to S3; in-memory state |
+| **EventBridge Scheduler** | CreateSchedule, GetSchedule, UpdateSchedule, DeleteSchedule, ListSchedules, CreateScheduleGroup, GetScheduleGroup, DeleteScheduleGroup, ListScheduleGroups, TagResource, UntagResource, ListTagsForResource | 12 actions; schedule groups with cascading deletes; `rate()`, `cron()`, `at()` expressions; group/prefix/state filters on list; default group auto-created; CFN `AWS::Scheduler::Schedule` and `AWS::Scheduler::ScheduleGroup` supported |
+| **EKS** | CreateCluster, DescribeCluster, ListClusters, DeleteCluster, CreateNodegroup, DescribeNodegroup, ListNodegroups, DeleteNodegroup, TagResource, UntagResource, ListTagsForResource | 11 operations; `CreateCluster` spawns a real **k3s** container (75 MB) with a full Kubernetes API server; `kubectl`, Helm, and any K8s tooling work out of the box; cascading delete removes nodegroups and k3s container; CFN `AWS::EKS::Cluster` and `AWS::EKS::Nodegroup` supported |
+
+---
+
+## Real Database Endpoints (RDS)
+
+When you create an RDS instance, MiniStack starts a real database container and returns the actual connection endpoint:
+
+```python
+import boto3
+import psycopg2  # pip install psycopg2-binary
+
+rds = boto3.client("rds", endpoint_url="http://localhost:4566",
+                   aws_access_key_id="test", aws_secret_access_key="test", region_name="us-east-1")
+
+resp = rds.create_db_instance(
+    DBInstanceIdentifier="mydb",
+    DBInstanceClass="db.t3.micro",
+    Engine="postgres",
+    MasterUsername="admin",
+    MasterUserPassword="password",
+    DBName="appdb",
+    AllocatedStorage=20,
+)
+
+endpoint = resp["DBInstance"]["Endpoint"]
+# Connect directly — it's a real Postgres instance
+conn = psycopg2.connect(
+    host=endpoint["Address"],   # localhost
+    port=endpoint["Port"],      # 15432 (auto-assigned)
+    user="admin",
+    password="password",
+    dbname="appdb",
+)
+```
+
+Supported engines: `postgres`, `mysql`, `mariadb`, `aurora-postgresql`, `aurora-mysql`
+
+---
+
+## Real Redis Endpoints (ElastiCache)
+
+```python
+import boto3
+import redis  # pip install redis
+
+ec = boto3.client("elasticache", endpoint_url="http://localhost:4566",
+                  aws_access_key_id="test", aws_secret_access_key="test", region_name="us-east-1")
+
+resp = ec.create_cache_cluster(
+    CacheClusterId="my-redis",
+    Engine="redis",
+    CacheNodeType="cache.t3.micro",
+    NumCacheNodes=1,
+)
+
+node = resp["CacheCluster"]["CacheNodes"][0]["Endpoint"]
+r = redis.Redis(host=node["Address"], port=node["Port"])
+r.set("key", "value")
+print(r.get("key"))  # b'value'
+```
+
+A Redis sidecar is also always available at `localhost:6379` when using Docker Compose.
+
+---
+
+## Athena with Real SQL
+
+Athena queries run via DuckDB and can query files in your local S3 data directory:
+
+```python
+import boto3, time
+
+athena = boto3.client("athena", endpoint_url="http://localhost:4566",
+                      aws_access_key_id="test", aws_secret_access_key="test", region_name="us-east-1")
+
+# Query runs real SQL via DuckDB
+resp = athena.start_query_execution(
+    QueryString="SELECT 42 AS answer, 'hello' AS greeting",
+    ResultConfiguration={"OutputLocation": "s3://athena-results/"},
+)
+query_id = resp["QueryExecutionId"]
+
+# Poll for result
+while True:
+    status = athena.get_query_execution(QueryExecutionId=query_id)
+    if status["QueryExecution"]["Status"]["State"] == "SUCCEEDED":
+        break
+    time.sleep(0.1)
+
+results = athena.get_query_results(QueryExecutionId=query_id)
+for row in results["ResultSet"]["Rows"][1:]:  # skip header
+    print([col["VarCharValue"] for col in row["Data"]])
+# ['42', 'hello']
+```
+
+---
+
+## ECS with Real Containers
+
+```python
+import boto3
+
+ecs = boto3.client("ecs", endpoint_url="http://localhost:4566",
+                   aws_access_key_id="test", aws_secret_access_key="test", region_name="us-east-1")
+
+ecs.create_cluster(clusterName="dev")
+
+ecs.register_task_definition(
+    family="web",
+    containerDefinitions=[{
+        "name": "nginx",
+        "image": "nginx:alpine",
+        "cpu": 128,
+        "memory": 256,
+        "portMappings": [{"containerPort": 80, "hostPort": 8080}],
+    }],
+)
+
+# This actually runs an nginx container via Docker
+resp = ecs.run_task(cluster="dev", taskDefinition="web", count=1)
+task_arn = resp["tasks"][0]["taskArn"]
+
+# Stop it (removes the container)
+ecs.stop_task(cluster="dev", task=task_arn)
+```
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GATEWAY_PORT` | `4566` | Port to listen on. Also accepts `EDGE_PORT` (LocalStack compatibility alias) |
+| `MINISTACK_HOST` | `localhost` | Hostname used in response URLs (SQS queues, SNS subscriptions, API Gateway endpoints, Lambda layers) |
+| `MINISTACK_ACCOUNT_ID` | `000000000000` | Default AWS account ID. Overridden per-request when `AWS_ACCESS_KEY_ID` is a 12-digit number (see [Multi-Tenancy](#multi-tenancy)) |
+| `MINISTACK_REGION` | `us-east-1` | AWS region reported in ARNs and service responses across all services |
+| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `S3_PERSIST` | `0` | Set `1` to persist S3 objects to disk |
+| `S3_DATA_DIR` | `/tmp/ministack-data/s3` | S3 persistence directory |
+| `REDIS_HOST` | `redis` | Redis host for ElastiCache fallback |
+| `REDIS_PORT` | `6379` | Redis port for ElastiCache fallback |
+| `RDS_BASE_PORT` | `15432` | Starting host port for RDS containers |
+| `RDS_TMPFS_SIZE` | `256m` | Tmpfs size for RDS database containers (when `RDS_PERSIST=0`). Set to `2g` or higher for large databases |
+| `RDS_PERSIST` | `0` | Set `1` to use Docker named volumes for RDS containers instead of tmpfs. Storage grows dynamically with no fixed cap |
+| `ELASTICACHE_BASE_PORT` | `16379` | Starting host port for ElastiCache containers |
+| `PERSIST_STATE` | `0` | Set `1` to persist service state across restarts |
+| `STATE_DIR` | `/tmp/ministack-state` | Directory for persisted state files |
+| `LAMBDA_EXECUTOR` | `local` | Lambda execution mode: `local` (subprocess) or `docker` (container). `provided` runtimes and `PackageType: Image` always use Docker |
+| `LAMBDA_STRICT` | `0` | Set `1` for AWS-fidelity mode: every Lambda invocation runs in a Docker container via the AWS RIE image; in-process fallbacks are disabled. Missing Docker surfaces as `Runtime.DockerUnavailable` instead of degrading to a subprocess. Opt-in because the default install doesn't require Docker |
+| `LAMBDA_DOCKER_NETWORK` | _(unset)_ | Docker network for Lambda containers. Set to your Docker Compose network name so Lambda can reach MiniStack |
+| `LAMBDA_WARM_TTL_SECONDS` | `300` | How long an idle warm Lambda container stays in the pool before the reaper evicts it |
+| `LAMBDA_ACCOUNT_CONCURRENCY` | `0` | Account-level concurrent-invocation cap (0 = unbounded). Match real AWS by setting to `1000`. Used to simulate `ConcurrentInvocationLimitExceeded` throttles |
+| `SFN_MOCK_CONFIG` | _(unset)_ | Path to JSON file for Step Functions mock testing; compatible with AWS SFN Local format. Also accepts `LOCALSTACK_SFN_MOCK_CONFIG` |
+| `ATHENA_ENGINE` | `auto` | SQL engine for Athena: `auto`, `duckdb`, `mock` |
+| `SMTP_HOST` | _(unset)_ | SMTP server for SES email relay (e.g. `mailhog:1025`). When set, SES SendEmail/SendRawEmail actually deliver mail. When unset, emails are stored in-memory only |
+
+### Startup Scripts
+
+MiniStack supports two types of init scripts, with LocalStack-compatible paths:
+
+| Phase | MiniStack path | LocalStack-compatible path |
+|-------|----------------|---------------------------|
+| Pre-start | `/docker-entrypoint-initaws.d/*.{sh,py}` | `/etc/localstack/init/boot.d/*.{sh,py}` |
+| Post-ready | `/docker-entrypoint-initaws.d/ready.d/*.{sh,py}` | `/etc/localstack/init/ready.d/*.{sh,py}` |
+
+Scripts from both paths are merged, deduplicated by filename, and run in alphabetical order.
+If the same filename exists in both paths, the MiniStack-native path takes priority.
+
+Init scripts automatically receive `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, and `AWS_ENDPOINT_URL` — no manual configuration needed. The `aws` CLI is bundled in the image.
+
+```bash
+# ready.d/01-create-resources.sh
+aws s3 mb s3://my-bucket
+aws sqs create-queue --queue-name my-queue
+```
+
+```python
+# ready.d/02-seed-data.py
+import boto3, os
+s3 = boto3.client("s3", endpoint_url=os.environ["AWS_ENDPOINT_URL"])
+s3.put_object(Bucket="my-bucket", Key="config.json", Body=b'{"env": "local"}')
+```
+
+**Docker Compose** — mount scripts at either path:
+```yaml
+volumes:
+  - ./init-scripts:/docker-entrypoint-initaws.d           # ministack-native
+  # OR
+  - ./init-scripts:/etc/localstack/init                    # localstack-compatible
+```
+
+### Athena SQL Engines
+
+Set `ATHENA_ENGINE` to control Athena's SQL execution engine. In `auto` mode, DuckDB is used if installed, otherwise queries return mock results.
+
+| Capability | `duckdb` | `mock` |
+|---|---|---|
+| Simple SELECT / expressions | Yes | Partial (regex) |
+| Arithmetic, aggregations, JOINs, CTEs | Yes | No |
+| Window functions, subqueries | Yes | No |
+| Parquet / CSV / JSON file queries | Yes | No |
+| UNNEST, ARRAY, MAP functions | Yes | No |
+| APPROX\_DISTINCT, REGEXP\_EXTRACT | Yes | No |
+
+Install DuckDB for full Athena SQL compatibility: `pip install ministack[full]`.
+
+### State Persistence
+
+When `PERSIST_STATE=1`, MiniStack saves service state to `STATE_DIR` on shutdown and reloads it on startup. Writes are atomic (write-to-tmp then rename) to prevent corruption on crash.
+
+Services currently supporting persistence: **All services** — API Gateway v1/v2, ALB, ACM, AppConfig, AppSync, Athena, Cloud Map, CloudFront, CloudWatch, CloudWatch Logs, CodeBuild, Cognito, DynamoDB, EC2, ECR, ECS, EFS, EKS, ElastiCache, EMR, EventBridge, EventBridge Scheduler, Firehose, Glue, IAM/STS, Kinesis, KMS, Lambda, RDS, Route 53, S3, Secrets Manager, SES, SES v2, SNS, SQS, SSM, Step Functions, Transfer Family, WAF v2 
+
+```bash
+docker run -p 4566:4566 \
+  -e PERSIST_STATE=1 \
+  -e STATE_DIR=/data/ministack-state \
+  -v /tmp/ministack-data:/data \
+  ministackorg/ministack
+```
+
+### Lambdas in docker
+
+To run lambda in docker, the LAMBDA_EXECUTOR needs to be set to "docker". All lambdas will be run in an
+AWS supplied docker image, following docker images are supported:
+   *  "python3.8": "public.ecr.aws/lambda/python:3.8"
+   *  "python3.9": "public.ecr.aws/lambda/python:3.9"
+   *  "python3.10": "public.ecr.aws/lambda/python:3.10"
+   *  "python3.11": "public.ecr.aws/lambda/python:3.11"
+   *  "python3.12": "public.ecr.aws/lambda/python:3.12"
+   *  "python3.13": "public.ecr.aws/lambda/python:3.13"
+   *  "python3.14": "public.ecr.aws/lambda/python:3.14"
+   *  "nodejs14.x": "public.ecr.aws/lambda/nodejs:14"
+   *  "nodejs16.x": "public.ecr.aws/lambda/nodejs:16"
+   *  "nodejs18.x": "public.ecr.aws/lambda/nodejs:18"
+   *  "nodejs20.x": "public.ecr.aws/lambda/nodejs:20"
+   *  "nodejs22.x": "public.ecr.aws/lambda/nodejs:22"
+   *  "nodejs24.x": "public.ecr.aws/lambda/nodejs:24"
+   *  "provided.al2023": "public.ecr.aws/lambda/provided:al2023"
+   *  "provided.al2": "public.ecr.aws/lambda/provided:al2"
+   *  "provided": "public.ecr.aws/lambda/provided:latest"
+
+Docker containers for lambda are name lambda-<random-hex-16>.
+
+Docker containers are always kept "warm", and reused when possible. This means that containers
+created for lambdas need to be killed manually.
+
+Additionally a volume is needed to mount the code (and extra layers). This must be set with
+the LAMBDA_REMOTE_DOCKER_VOLUME_MOUNT environment variable. This must be a named volume (managed by docker).
+
+If a ministack is not running on the default network, LAMBDA_DOCKER_NETWORK needs to be set, which will attach
+the lambda to this network, making it posssible to access ministack (AWS) resources from the lambda.
+
+Example docker compose file:
+```
+services:
+  ministack:
+    image: ministackorg/ministack:latest
+    container_name: infra_ministack
+    entrypoint: ["python", "-m", "hypercorn", "ministack.app:app", "--bind", "0.0.0.0:4566", "--keep-alive", "75"]
+    networks:
+      infra-network:
+    healthcheck:
+      test: "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:4566/_ministack/health')\" || exit 1"
+      interval: 10s
+      timeout: 2s
+      start_period: 5s
+      retries: 3
+    ports:
+      - "4566:4566"
+    environment:
+      DOCKER_SOCK: ${DOCKER_SOCK:-/var/run/docker.sock}
+      LAMBDA_EXECUTOR: docker
+      LAMBDA_DOCKER_NETWORK: ${COMPOSE_PROJECT_NAME}_infra-network
+      LAMBDA_REMOTE_DOCKER_VOLUME_MOUNT: "{COMPOSE_PROJECT_NAME}_lambda-docker-volume"
+      AWS_DEFAULT_REGION: ${AWS_REGION:-eu-central-1}
+      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY:-my_secret}
+      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID:-my_key}
+      AWS_ENDPOINT_URL: http://localstack:4566
+    volumes:
+      - "/var/run/docker.sock:/var/run/docker.sock"
+      - "lambda-docker-volume:/var/task"
+
+volumes:
+  lambda-docker-volume:
+
+networks:
+  infra-network:
+```
+
+Option privileged set to "true" is needed if /var/run/docker.sock is root owned.
+
+### EKS with Real Kubernetes (k3s)
+
+MiniStack's EKS spawns a real [k3s](https://k3s.io) cluster (75 MB image) when you create a cluster. `kubectl`, Helm, and any Kubernetes tooling work out of the box.
+
+```bash
+# Create an EKS cluster — k3s starts automatically
+aws --endpoint-url=http://localhost:4566 eks create-cluster \
+  --name my-cluster --role-arn arn:aws:iam::000000000000:role/eks \
+  --resources-vpc-config subnetIds=subnet-1
+
+# Get the k3s kubeconfig (container name follows ministack-eks-{name} pattern)
+docker exec ministack-eks-my-cluster cat /etc/rancher/k3s/k3s.yaml \
+  | sed "s/127.0.0.1:6443/localhost:$(docker port ministack-eks-my-cluster 6443/tcp | cut -d: -f2)/" \
+  > /tmp/ministack-kubeconfig.yaml
+
+# Use kubectl against real Kubernetes
+export KUBECONFIG=/tmp/ministack-kubeconfig.yaml
+kubectl get nodes          # Real k3s node, Ready status
+kubectl create deployment nginx --image=nginx:alpine
+kubectl get pods           # Real pod running
+
+# Helm works too
+helm repo add bitnami https://charts.bitnami.com/bitnami
+helm install my-redis bitnami/redis --set auth.enabled=false
+
+# Clean up — k3s container is removed automatically
+aws --endpoint-url=http://localhost:4566 eks delete-cluster --name my-cluster
+```
+
+> **Note:** EKS requires Docker socket access (`-v /var/run/docker.sock:/var/run/docker.sock`) to spawn k3s containers. The k3s image is pulled on first `CreateCluster` call.
+
+### Lambda Warm Starts
+
+MiniStack keeps Python and Node.js Lambda functions warm between invocations. After the first call (cold start), the handler module stays loaded in a persistent subprocess. Subsequent calls skip the import/require step, matching real AWS warm-start behaviour and making test suites significantly faster.
+
+### Lambda Node.js Runtimes
+
+MiniStack supports Node.js Lambda runtimes (`nodejs14.x`, `nodejs16.x`, `nodejs18.x`, `nodejs20.x`, `nodejs22.x`). Functions execute via a local `node` subprocess (or Docker when `LAMBDA_EXECUTOR=docker`) — no mocking, real JS execution.
+
+```python
+import boto3, json, zipfile, io
+
+lam = boto3.client("lambda", endpoint_url="http://localhost:4566", region_name="us-east-1",
+                   aws_access_key_id="test", aws_secret_access_key="test")
+
+code = "exports.handler = async (event) => ({ statusCode: 200, body: JSON.stringify(event) });"
+buf = io.BytesIO()
+with zipfile.ZipFile(buf, "w") as zf:
+    zf.writestr("index.js", code)
+
+lam.create_function(
+    FunctionName="my-node-fn",
+    Runtime="nodejs20.x",
+    Role="arn:aws:iam::000000000000:role/r",
+    Handler="index.handler",
+    Code={"ZipFile": buf.getvalue()},
+)
+
+resp = lam.invoke(FunctionName="my-node-fn", Payload=json.dumps({"hello": "world"}))
+print(json.loads(resp["Payload"].read()))  # {'statusCode': 200, 'body': '{"hello": "world"}'}
+```
+
+Layers that ship npm packages work too — MiniStack resolves the `nodejs/node_modules` subdirectory inside each layer zip and prepends it to the module search path.
+
+MiniStack also sets the standard Lambda runtime environment before the handler module is loaded, including `LAMBDA_TASK_ROOT`, `AWS_LAMBDA_FUNCTION_NAME`, `AWS_LAMBDA_FUNCTION_MEMORY_SIZE`, and `_LAMBDA_FUNCTION_ARN`. That keeps import-time Lambda detection and conditional handler setup aligned with AWS warm runtime behaviour.
+
+---
+
+## Architecture
+
+```
+                    ┌──────────────────────────────────────────┐
+ AWS CLI / boto3    │         ASGI Gateway  :4566              │
+ Terraform / CDK ──►│  ┌────────────────────────────────────┐  │
+ Any AWS SDK        │  │          Request Router            │  │
+                    │  │  1. X-Amz-Target header            │  │
+                    │  │  2. Authorization credential scope │  │
+                    │  │  3. Action query param             │  │
+                    │  │  4. URL path pattern               │  │
+                    │  │  5. Host header                    │  │
+                    │  │  6. Default → S3                   │  │
+                    │  └────────────────┬───────────────────┘  │
+                    │                 │                        │
+                    │  ┌────────────────────────────────────┐  │
+                    │  │   Service Handlers (lazy-loaded)   │  │
+                    │  │                                    │  │
+                    │  │  S3      SQS     SNS    DynamoDB   │  │
+                    │  │  Lambda  IAM     STS    Secrets    │  │
+                    │  │  SSM     Events  Kinesis    CW     │  │
+                    │  │  CW Logs  SES    SESv2     ACM     │  │
+                    │  │  Step Functions   API GW  v1/v2    │  │
+                    │  │  ECS    RDS   ElastiCache  Glue    │  │
+                    │  │  Athena   Firehose    Route53      │  │
+                    │  │  Cognito  EC2    EMR   EBS  EFS    │  │
+                    │  │  ALB/ELBv2   WAF v2   KMS  ECR     │  │
+                    │  │  CloudFormation    CloudFront      │  │
+                    │  │  AppSync  Cloud Map   CodeBuild    │  │
+                    │  │  AutoScaling  AppConfig     EKS    │  │
+                    │  │  RDS Data  S3 Files  Scheduler     │  │
+                    │  │  Transfer Family                   │  │
+                    │  └────────────────────────────────────┘  │
+                    │                                          │
+                    │  In-Memory Storage + Optional Docker     │
+                    └──────────────────────────────────────────┘
+                                        │
+                         ┌──────────────┼──────────────┐
+                         ▼              ▼              ▼
+                    Redis:6379    Postgres:15432+  MySQL:15433+
+                    (ElastiCache)    (RDS)           (RDS)
+```
+
+---
+
+## Running Tests
+
+```bash
+# Install test dependencies
+pip install boto3 pytest duckdb docker cbor2
+
+# Start MiniStack
+docker compose up -d
+
+# Run the full test suite (1,300+ tests across all services)
+pytest tests/ -v
+```
+
+Expected output:
+
+```
+collected 955 items
+
+tests/test_services.py::test_s3_create_bucket PASSED
+...
+tests/test_services.py::test_app_asgi_callable PASSED
+
+955 passed in ~100s
+```
+
+---
+
+## Terraform / CDK / Pulumi
+
+### Terraform
+
+Works with both Terraform AWS Provider v5 and v6.
+
+```hcl
+provider "aws" {
+  region                      = "us-east-1"
+  access_key                  = "test"
+  secret_key                  = "test"
+  s3_use_path_style           = true
+  skip_credentials_validation = true
+  skip_metadata_api_check     = true
+  skip_requesting_account_id  = true
+
+  endpoints {
+    acm             = "http://localhost:4566"
+    apigateway      = "http://localhost:4566"
+    appsync         = "http://localhost:4566"
+    athena          = "http://localhost:4566"
+    cloudformation  = "http://localhost:4566"
+    cloudfront      = "http://localhost:4566"
+    cloudwatch      = "http://localhost:4566"
+    codebuild       = "http://localhost:4566"
+    cognitoidentity = "http://localhost:4566"
+    cognitoidp      = "http://localhost:4566"
+    dynamodb        = "http://localhost:4566"
+    ec2             = "http://localhost:4566"
+    ecr             = "http://localhost:4566"
+    ecs             = "http://localhost:4566"
+    efs             = "http://localhost:4566"
+    elasticache     = "http://localhost:4566"
+    elbv2           = "http://localhost:4566"
+    emr             = "http://localhost:4566"
+    events          = "http://localhost:4566"
+    firehose        = "http://localhost:4566"
+    glue            = "http://localhost:4566"
+    iam             = "http://localhost:4566"
+    kinesis         = "http://localhost:4566"
+    kms             = "http://localhost:4566"
+    lambda          = "http://localhost:4566"
+    logs            = "http://localhost:4566"
+    rds             = "http://localhost:4566"
+    route53         = "http://localhost:4566"
+    s3              = "http://localhost:4566"
+    s3control       = "http://localhost:4566"
+    secretsmanager  = "http://localhost:4566"
+    ses             = "http://localhost:4566"
+    sesv2           = "http://localhost:4566"
+    sns             = "http://localhost:4566"
+    sqs             = "http://localhost:4566"
+    ssm             = "http://localhost:4566"
+    stepfunctions   = "http://localhost:4566"
+    sts             = "http://localhost:4566"
+    wafv2           = "http://localhost:4566"
+  }
+}
+```
+
+**Terraform VPC module** — fully supported (v6.6.0):
+
+```hcl
+module "vpc" {
+  source  = "terraform-aws-modules/vpc/aws"
+  version = "6.6.0"
+
+  name = "my-vpc"
+  cidr = "10.0.0.0/16"
+
+  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
+  private_subnets = ["10.0.0.0/20", "10.0.16.0/20", "10.0.32.0/20"]
+  public_subnets  = ["10.0.64.0/20", "10.0.80.0/20", "10.0.96.0/20"]
+
+  enable_nat_gateway = true
+  single_nat_gateway = true
+}
+```
+
+Creates VPC with per-VPC default network ACL, security group, and main route table. All 23 resources (subnets, IGW, NAT, route tables, associations, routes, default resources) supported.
+
+#### Predictable API Gateway IDs (`ms-custom-id`)
+
+Pin the generated `apiId` / REST API id to a caller-supplied value so URLs stay stable across `terraform apply` runs. Works on `aws_apigatewayv2_api` (HTTP + WebSocket) and `aws_apigateway_rest_api`.
+
+```hcl
+resource "aws_apigatewayv2_api" "example" {
+  name          = "example"
+  protocol_type = "HTTP"
+  tags = {
+    ms-custom-id = "example"
+  }
+}
+# → invoke URL stays "example.execute-api.localhost:4566" every apply
+```
+
+Duplicates in the same account fail with `ConflictException`. The LocalStack `ls-custom-id` tag is not recognised — use `ms-custom-id` only (callers hitting the old name get a clear `BadRequestException`).
+
+### AWS CDK
+
+Set `AWS_ENDPOINT_URL` to route all CDK requests to MiniStack:
+
+```bash
+export AWS_ENDPOINT_URL=http://localhost:4566
+export AWS_ACCESS_KEY_ID=test
+export AWS_SECRET_ACCESS_KEY=test
+export AWS_DEFAULT_REGION=us-east-1
+
+cdk bootstrap aws://000000000000/us-east-1
+cdk deploy --require-approval never
+```
+
+> **Important:** Running `cdk deploy` without `AWS_ENDPOINT_URL` will send requests to **real AWS**, not MiniStack. If you see "The security token included in the request is invalid", your requests are hitting AWS — set the endpoint.
+
+To reset the bootstrap stack or delete all state:
+
+```bash
+# Delete a specific stack
+aws --endpoint-url=http://localhost:4566 cloudformation delete-stack --stack-name CDKToolkit
+
+# Or reset all MiniStack state
+curl -X POST http://localhost:4566/_ministack/reset
+```
+
+### Pulumi
+
+```yaml
+# Pulumi.dev.yaml
+config:
+  aws:endpoints:
+    - s3: http://localhost:4566
+      dynamodb: http://localhost:4566
+      # ... etc
+```
+
+### Amplify / CDK
+
+MiniStack supports Amplify Gen 2 and CDK deployments. The underlying services are fully emulated:
+
+- **Auth** — Cognito User Pools with JWKS/OIDC endpoints (`/.well-known/jwks.json`) for real JWT validation
+- **Data** — AppSync GraphQL queries/mutations execute against DynamoDB resolvers (create/get/list/update/delete)
+- **Storage** — S3
+- **Functions** — Lambda (Python + Node.js)
+
+```bash
+export AWS_ENDPOINT_URL=http://localhost:4566
+npx ampx sandbox
+```
+
+> **Note:** AppSync supports Amplify-style CRUD operations. Advanced GraphQL features (fragments, unions, subscriptions) are not supported.
+
+### Testcontainers (Java / Go / Python)
+
+See [`Testcontainers/java-testcontainers`](Testcontainers/java-testcontainers), [`Testcontainers/go-testcontainers`](Testcontainers/go-testcontainers), and [`Testcontainers/python-testcontainers`](Testcontainers/python-testcontainers) for ready-to-run integration tests using Testcontainers with the AWS SDK v2.
+
+---
+
+## Comparison
+
+| Feature | MiniStack | LocalStack Free | LocalStack Pro |
+|---------|-----------|-----------------|----------------|
+| S3, SQS, SNS, DynamoDB | ✅ | ✅ | ✅ |
+| Lambda (Python + Node.js execution) | ✅ | ✅ | ✅ |
+| IAM, STS, SecretsManager | ✅ | ✅ | ✅ |
+| CloudWatch Logs | ✅ | ✅ | ✅ |
+| SSM Parameter Store | ✅ | ✅ | ✅ |
+| EventBridge | ✅ | ✅ | ✅ |
+| Kinesis | ✅ | ✅ | ✅ |
+| SES | ✅ | ✅ | ✅ |
+| Step Functions | ✅ | ✅ | ✅ |
+| **RDS (real DB containers)** | ✅ | ❌ | ✅ |
+| **ElastiCache (real Redis)** | ✅ | ❌ | ✅ |
+| **ECS (real Docker containers)** | ✅ | ❌ | ✅ |
+| **Athena (real SQL via DuckDB)** | ✅ | ❌ | ✅ |
+| **Glue Data Catalog + Jobs** | ✅ | ❌ | ✅ |
+| **API Gateway v2 (HTTP API)** | ✅ | ✅ | ✅ |
+| **API Gateway v2 (WebSocket API)** | ✅ | ❌ | ✅ |
+| **API Gateway v1 (REST API)** | ✅ | ✅ | ✅ |
+| **Firehose** | ✅ | ✅ | ✅ |
+| **Route53** | ✅ | ✅ | ✅ |
+| **Cognito** | ✅ | ✅ | ✅ |
+| **EC2** | ✅ | ✅ | ✅ |
+| **EMR** | ✅ | Paid | ✅ |
+| **ELBv2 / ALB** | ✅ | ✅ | ✅ |
+| **EBS** | ✅ | Paid | ✅ |
+| **EFS** | ✅ | Paid | ✅ |
+| **ACM** | ✅ | ✅ | ✅ |
+| **SES v2** | ✅ | ✅ | ✅ |
+| **WAF v2** | ✅ | Paid | ✅ |
+| **CloudFormation** | **partial** | partial | ✅ Free |
+| **KMS** | ✅ | Paid | ✅ Free |
+| **ECR** | ✅ | ✅ | ✅ |
+| **CloudFront** | ✅ | Paid | ✅ |
+| **AppSync** | ✅ | NO | ✅ |
+| **Cloud Map** | ✅ | ❌ | ✅ |
+| **CodeBuild** | ✅ | ✅ | ✅ |
+| **Transfer Family** | ✅ | ❌ | ❌ |
+| **S3 Files** | ✅ | ❌ | ❌ |
+| Cost | **Free forever** | Was free, now paid | $35+/mo |
+| Docker image size | ~250MB | ~1GB | ~1GB |
+| Memory at idle | ~40MB | ~500MB | ~500MB |
+| Startup time | <1s | ~15-30s | ~15-30s |
+| License | MIT | BSL (restricted) | Proprietary |
+
+---
+
+## Community Integrations
+
+| Project | Description |
+|---------|-------------|
+| [**StackPort**](https://github.com/DaviReisVieira/stackport) | Visual dashboard to browse and inspect AWS resources in MiniStack. Available on [PyPI](https://pypi.org/project/stackport/) and [Docker Hub](https://hub.docker.com/r/davireis/stackport). |
+| [**McDoit.Aspire.Hosting.Ministack**](https://github.com/McDoit/aspire-hosting-ministack) | .NET Aspire hosting integration for MiniStack. |
+
+---
+
+## Contributing
+
+PRs welcome. The codebase is intentionally simple — each service is a single self-contained Python file in `ministack/services/`. Adding a new service means:
+
+1. Create `ministack/services/myservice.py` with an `async def handle_request(...)` function and a `reset()` function
+2. Add it to `SERVICE_REGISTRY` in `ministack/app.py` so the handler, aliases, and service filter are generated automatically
+3. Add detection patterns to `ministack/core/router.py`
+4. Add a fixture to `tests/conftest.py` and tests to `tests/test_services.py`
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for a full walkthrough.
+
+---
+
+## License
+
+MIT — free to use, modify, and distribute. No restrictions.
+
+```
+Copyright (c) 2026 MiniStack Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+```

aws_infra/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## ⚠️ Important: Local Development Only
+
+MiniStack is designed **exclusively for local development and CI/CD testing**.
+
+**Do not expose MiniStack to the internet or any untrusted network.**
+
+- It has no authentication — any request is accepted
+- Credentials (`aws_access_key_id`, `aws_secret_access_key`) are ignored
+- All data is stored in-memory and is not encrypted
+- The Docker socket mount (for ECS/RDS/ElastiCache) gives container-level access to your host
+
+## Reporting a Vulnerability
+
+If you find a security issue that could affect users running MiniStack in a way that exposes their host system or data, please open a GitHub issue tagged `security`.
+
+Since this is a local dev tool with no auth by design, most "vulnerabilities" are intentional trade-offs for simplicity. But if you find something that could cause unintended host compromise (e.g. path traversal in S3 persistence, command injection in Lambda execution), please report it.
+
+## Recommended Usage
+
+```yaml
+# docker-compose.yml — bind to localhost only, never 0.0.0.0 on a shared machine
+ports:
+  - "127.0.0.1:4566:4566"
+```
+
+Never run with `S3_PERSIST=1` pointing to sensitive directories.

aws_infra/Testcontainers/go-testcontainers/README.md

@@ -0,0 +1,25 @@
+# MiniStack — Go Testcontainers Example
+
+Integration tests for S3, SQS, and DynamoDB using [testcontainers-go](https://golang.testcontainers.org/) and the AWS SDK v2.
+
+## Prerequisites
+
+- Go 1.21+
+- Docker (running)
+
+## Run
+
+```bash
+go mod tidy
+go test ./... -v
+```
+
+Testcontainers will pull `ministackorg/ministack:latest`, start it, run the tests, and tear it down automatically.
+
+## What's tested
+
+| Service    | Operations |
+|------------|------------|
+| S3         | CreateBucket, PutObject, GetObject, ListBuckets |
+| SQS        | CreateQueue, SendMessage, ReceiveMessage |
+| DynamoDB   | CreateTable, PutItem, GetItem, DeleteItem |

aws_infra/Testcontainers/go-testcontainers/go.mod

@@ -0,0 +1,75 @@
+module github.com/ministackorg/ministack/examples/go-testcontainers
+
+go 1.24.0
+
+require (
+	github.com/aws/aws-sdk-go-v2 v1.41.5
+	github.com/aws/aws-sdk-go-v2/credentials v1.17.11
+	github.com/aws/aws-sdk-go-v2/service/dynamodb v1.31.1
+	github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3
+	github.com/aws/aws-sdk-go-v2/service/sqs v1.31.1
+	github.com/testcontainers/testcontainers-go v0.34.0
+)
+
+require (
+	dario.cat/mergo v1.0.0 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/endpoint-discovery v1.9.6 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21 // indirect
+	github.com/aws/smithy-go v1.24.2 // indirect
+	github.com/cenkalti/backoff/v4 v4.2.1 // indirect
+	github.com/containerd/containerd v1.7.29 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	github.com/cpuguy83/dockercfg v0.3.2 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/docker v27.1.1+incompatible // indirect
+	github.com/docker/go-connections v0.5.0 // indirect
+	github.com/docker/go-units v0.5.0 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/jmespath/go-jmespath v0.4.0 // indirect
+	github.com/klauspost/compress v1.17.4 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/patternmatcher v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.5.0 // indirect
+	github.com/moby/sys/user v0.3.0 // indirect
+	github.com/moby/sys/userns v0.1.0 // indirect
+	github.com/moby/term v0.5.0 // indirect
+	github.com/morikuni/aec v1.0.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.0 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
+	github.com/shirou/gopsutil/v3 v3.23.12 // indirect
+	github.com/shoenig/go-m1cpu v0.1.6 // indirect
+	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/stretchr/testify v1.9.0 // indirect
+	github.com/tklauser/go-sysconf v0.3.12 // indirect
+	github.com/tklauser/numcpus v0.6.1 // indirect
+	github.com/yusufpapurcu/wmi v1.2.3 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 // indirect
+	go.opentelemetry.io/otel v1.24.0 // indirect
+	go.opentelemetry.io/otel/metric v1.24.0 // indirect
+	go.opentelemetry.io/otel/trace v1.24.0 // indirect
+	golang.org/x/crypto v0.45.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

aws_infra/Testcontainers/go-testcontainers/go.sum

@@ -0,0 +1,232 @@
+dario.cat/mergo v1.0.0 h1:AGCNq9Evsj31mOgNPcLyXc+4PNABt905YmuqPYYpBWk=
+dario.cat/mergo v1.0.0/go.mod h1:uNxQE+84aUszobStD9th8a29P2fMDhsBdgRYvZOxGmk=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20230811130428-ced1acdcaa24 h1:bvDV9vkmnHYOMsOr4WLk+Vo07yKIzd94sVoIqshQ4bU=
+github.com/AdaLogics/go-fuzz-headers v0.0.0-20230811130428-ced1acdcaa24/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8=
+github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 h1:UQHMgLO+TxOElx5B5HZ4hJQsoJ/PvUvKRhJHDQXO8P8=
+github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
+github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV/yY=
+github.com/aws/aws-sdk-go-v2 v1.41.5/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 h1:eBMB84YGghSocM7PsjmmPffTa+1FBUeNvGvFou6V/4o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.11 h1:YuIB1dJNf1Re822rriUOTxopaHHvIq0l/pX3fwO+Tzs=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.11/go.mod h1:AQtFPsDH9bI2O+71anW6EKL+NcD7LG3dpKGMV4SShgo=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 h1:Rgg6wvjjtX8bNHcvi9OnXWwcE0a2vGpbwmtICOsvcf4=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21/go.mod h1:A/kJFst/nm//cyqonihbdpQZwiUhhzpqTsdbhDdRF9c=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 h1:PEgGVtPoB6NTpPrBgqSE5hE/o47Ij9qk/SEZFbUOe9A=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21/go.mod h1:p+hz+PRAYlY3zcpJhPwXlLC4C+kqn70WIHwnzAfs6ps=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22 h1:rWyie/PxDRIdhNf4DzRk0lvjVOqFJuNnO8WwaIRVxzQ=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.22/go.mod h1:zd/JsJ4P7oGfUhXn1VyLqaRZwPmZwg44Jf2dS84Dm3Y=
+github.com/aws/aws-sdk-go-v2/service/dynamodb v1.31.1 h1:dZXY07Dm59TxAjJcUfNMJHLDI/gLMxTRZefn2jFAVsw=
+github.com/aws/aws-sdk-go-v2/service/dynamodb v1.31.1/go.mod h1:lVLqEtX+ezgtfalyJs7Peb0uv9dEpAQP5yuq2O26R44=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13 h1:JRaIgADQS/U6uXDqlPiefP32yXTda7Kqfx+LgspooZM=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.13/go.mod h1:CEuVn5WqOMilYl+tbccq8+N2ieCy0gVn3OtRb0vBNNM=
+github.com/aws/aws-sdk-go-v2/service/internal/endpoint-discovery v1.9.6 h1:6tayEze2Y+hiL3kdnEUxSPsP+pJsUfwLSFspFl1ru9Q=
+github.com/aws/aws-sdk-go-v2/service/internal/endpoint-discovery v1.9.6/go.mod h1:qVNb/9IOVsLCZh0x2lnagrBwQ9fxajUpXS7OZfIsKn0=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 h1:c31//R3xgIJMSC8S6hEVq+38DcvUlgFY0FM6mSI5oto=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21/go.mod h1:r6+pf23ouCB718FUxaqzZdbpYFyDtehyZcmP5KL9FkA=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21 h1:ZlvrNcHSFFWURB8avufQq9gFsheUgjVD9536obIknfM=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.21/go.mod h1:cv3TNhVrssKR0O/xxLJVRfd2oazSnZnkUeTf6ctUwfQ=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3 h1:HwxWTbTrIHm5qY+CAEur0s/figc3qwvLWsNkF4RPToo=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.97.3/go.mod h1:uoA43SdFwacedBfSgfFSjjCvYe8aYBS7EnU5GZ/YKMM=
+github.com/aws/aws-sdk-go-v2/service/sqs v1.31.1 h1:124rVNP6NbCfBZwiX1kfjMQrnsJtnpKeB0GalkuqSXo=
+github.com/aws/aws-sdk-go-v2/service/sqs v1.31.1/go.mod h1:YijRvM1SAmuiIQ9pjfwahIEE3HMHUkx9P5oplL/Jnj4=
+github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
+github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/cenkalti/backoff/v4 v4.2.1 h1:y4OZtCnogmCPw98Zjyt5a6+QwPLGkiQsYW5oUqylYbM=
+github.com/cenkalti/backoff/v4 v4.2.1/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/containerd/containerd v1.7.29 h1:90fWABQsaN9mJhGkoVnuzEY+o1XDPbg9BTC9QTAHnuE=
+github.com/containerd/containerd v1.7.29/go.mod h1:azUkWcOvHrWvaiUjSQH0fjzuHIwSPg1WL5PshGP4Szs=
+github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
+github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
+github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
+github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
+github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
+github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY=
+github.com/creack/pty v1.1.18/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
+github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/docker v27.1.1+incompatible h1:hO/M4MtV36kzKldqnA37IWhebRA+LnqqcqDja6kVaKY=
+github.com/docker/docker v27.1.1+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/go-connections v0.5.0 h1:USnMq7hx7gwdVZq1L49hLXaFtUdTADjXGp+uj1Br63c=
+github.com/docker/go-connections v0.5.0/go.mod h1:ov60Kzw0kKElRwhNs9UlUHAE/F9Fe6GLaXnqyDdmEXc=
+github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
+github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.2 h1:6pFjapn8bFcIbiKo3XT4j/BhANplGihG6tvd+8rYgrY=
+github.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
+github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.16.0 h1:YBftPWNWd4WwGqtY2yeZL2ef8rHAxPBD8KFhJpmcqms=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.16.0/go.mod h1:YN5jB8ie0yfIUg6VvR9Kz84aCaG7AsGZnLjhHbUqwPg=
+github.com/jmespath/go-jmespath v0.4.0 h1:BEgLn5cpjn8UN1mAw4NjwDrS35OdebyEtFe+9YPoQUg=
+github.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo=
+github.com/jmespath/go-jmespath/internal/testify v1.5.1 h1:shLQSRRSCCPj3f2gpwzGwWFoC7ycTf1rcQZHOlsJ6N8=
+github.com/jmespath/go-jmespath/internal/testify v1.5.1/go.mod h1:L3OGu8Wl2/fWfCI6z80xFu9LTZmf1ZRjMHUOPmWr69U=
+github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
+github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+github.com/klauspost/compress v1.17.4 h1:Ej5ixsIri7BrIjBkRZLTo6ghwrEtHFk7ijlczPW4fZ4=
+github.com/klauspost/compress v1.17.4/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM=
+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
+github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
+github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
+github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
+github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
+github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
+github.com/moby/sys/sequential v0.5.0 h1:OPvI35Lzn9K04PBbCLW0g4LcFAJgHsvXsRyewg5lXtc=
+github.com/moby/sys/sequential v0.5.0/go.mod h1:tH2cOOs5V9MlPiXcQzRC+eEyab644PWKGRYaaV5ZZlo=
+github.com/moby/sys/user v0.3.0 h1:9ni5DlcW5an3SvRSx4MouotOygvzaXbaSrc/wGDFWPo=
+github.com/moby/sys/user v0.3.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
+github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
+github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
+github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
+github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
+github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
+github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.0 h1:8SG7/vwALn54lVB/0yZ/MMwhFrPYtpEHQb2IpWsCzug=
+github.com/opencontainers/image-spec v1.1.0/go.mod h1:W4s4sFTMaBeK1BQLXbG4AdM2szdn85PY75RI83NrTrM=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF4JjgDlrVEn3C11VoGHZN7m8qihwgMEtzYw=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
+github.com/rogpeppe/go-internal v1.8.1 h1:geMPLpDpQOgVyCg5z5GoRwLHepNdb71NXb67XFkP+Eg=
+github.com/rogpeppe/go-internal v1.8.1/go.mod h1:JeRgkft04UBgHMgCIwADu4Pn6Mtm5d4nPKWu0nJ5d+o=
+github.com/shirou/gopsutil/v3 v3.23.12 h1:z90NtUkp3bMtmICZKpC4+WaknU1eXtp5vtbQ11DgpE4=
+github.com/shirou/gopsutil/v3 v3.23.12/go.mod h1:1FrWgea594Jp7qmjHUUPlJDTPgcsb9mGnXDxavtikzM=
+github.com/shoenig/go-m1cpu v0.1.6 h1:nxdKQNcEB6vzgA2E2bvzKIYRuNj7XNJ4S/aRSwKzFtM=
+github.com/shoenig/go-m1cpu v0.1.6/go.mod h1:1JJMcUBvfNwpq05QDQVAnx3gUHr9IYF7GNg9SUEw2VQ=
+github.com/shoenig/test v0.6.4 h1:kVTaSd7WLz5WZ2IaoM0RSzRsUD+m8wRR+5qvntpn4LU=
+github.com/shoenig/test v0.6.4/go.mod h1:byHiCGXqrVaflBLAMq/srcZIHynQPQgeyvkvXnjqq0k=
+github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
+github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/testcontainers/testcontainers-go v0.34.0 h1:5fbgF0vIN5u+nD3IWabQwRybuB4GY8G2HHgCkbMzMHo=
+github.com/testcontainers/testcontainers-go v0.34.0/go.mod h1:6P/kMkQe8yqPHfPWNulFGdFHTD8HB2vLq/231xY2iPQ=
+github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFAEVmqU=
+github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
+github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk=
+github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
+github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yusufpapurcu/wmi v1.2.3 h1:E1ctvB7uKFMOJw3fdOW32DwGE9I7t++CRUEMKvFoFiw=
+github.com/yusufpapurcu/wmi v1.2.3/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0 h1:jq9TW8u3so/bN+JPT166wjOI6/vQPF6Xe7nMNIltagk=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.49.0/go.mod h1:p8pYQP+m5XfbZm9fxtSKAbM6oIllS7s2AfxrChvc7iw=
+go.opentelemetry.io/otel v1.24.0 h1:0LAOdjNmQeSTzGBzduGe/rU4tZhMwL5rWgtp9Ku5Jfo=
+go.opentelemetry.io/otel v1.24.0/go.mod h1:W7b9Ozg4nkF5tWI5zsXkaKKDjdVjpD4oAt9Qi/MArHo=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.19.0 h1:Mne5On7VWdx7omSrSSZvM4Kw7cS7NQkOOmLcgscI51U=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.19.0/go.mod h1:IPtUMKL4O3tH5y+iXVyAXqpAwMuzC1IrxVS81rummfE=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0 h1:IeMeyr1aBvBiPVYihXIaeIZba6b8E1bYp7lbdxK8CQg=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.19.0/go.mod h1:oVdCUtjq9MK9BlS7TtucsQwUcXcymNiEDjgDD2jMtZU=
+go.opentelemetry.io/otel/metric v1.24.0 h1:6EhoGWWK28x1fbpA4tYTOWBkPefTDQnb8WSGXlc88kI=
+go.opentelemetry.io/otel/metric v1.24.0/go.mod h1:VYhLe1rFfxuTXLgj4CBiyz+9WYBA8pNGJgDcSFRKBco=
+go.opentelemetry.io/otel/sdk v1.21.0 h1:FTt8qirL1EysG6sTQRZ5TokkU8d0ugCj8htOgThZXQ8=
+go.opentelemetry.io/otel/sdk v1.21.0/go.mod h1:Nna6Yv7PWTdgJHVRD9hIYywQBRx7pbox6nwBnZIxl/E=
+go.opentelemetry.io/otel/trace v1.24.0 h1:CsKnnL4dUAr/0llH9FKuc698G04IrpWV0MQA/Y1YELI=
+go.opentelemetry.io/otel/trace v1.24.0/go.mod h1:HPc3Xr/cOApsBI154IU0OI0HJexz+aw5uPdbs3UCjNU=
+go.opentelemetry.io/proto/otlp v1.0.0 h1:T0TX0tmXU8a3CbNXzEKGeU5mIVOdf0oykP+u2lIVU/I=
+go.opentelemetry.io/proto/otlp v1.0.0/go.mod h1:Sy6pihPLfYHkr3NkUbEhGHFhINUSI/v80hjKIs5JXpM=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=
+golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
+golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
+golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=
+golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
+golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/term v0.37.0 h1:8EGAD0qCmHYZg6J17DvsMy9/wJ7/D/4pV/wfnld5lTU=
+golang.org/x/term v0.37.0/go.mod h1:5pB4lxRNYYVZuTLmy8oR2BH8dflOR+IbTYFD8fi3254=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
+golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
+golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
+golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/genproto v0.0.0-20231211222908-989df2bf70f3 h1:1hfbdAfFbkmpg41000wDVqr7jUpK/Yo+LPnIxxGzmkg=
+google.golang.org/genproto/googleapis/api v0.0.0-20231120223509-83a465c0220f h1:2yNACc1O40tTnrsbk9Cv6oxiW8pxI/pXj0wRtdlYmgY=
+google.golang.org/genproto/googleapis/api v0.0.0-20231120223509-83a465c0220f/go.mod h1:Uy9bTZJqmfrw2rIBxgGLnamc78euZULUBrLZ9XTITKI=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20240401170217-c3f982113cda h1:LI5DOvAxUPMv/50agcLLoo+AdWc1irS9Rzz4vPuD1V4=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20240401170217-c3f982113cda/go.mod h1:WtryC6hu0hhx87FDGxWCDptyssuo68sk10vYjF+T9fY=
+google.golang.org/grpc v1.64.1 h1:LKtvyfbX3UGVPFcGqJ9ItpVWW6oN/2XqTxfAnwRRXiA=
+google.golang.org/grpc v1.64.1/go.mod h1:hiQF4LFZelK2WKaP6W0L92zGHtiQdZxk8CrSdvyjeP0=
+google.golang.org/protobuf v1.35.2 h1:8Ar7bF+apOIoThw1EdZl0p1oWvMqTHmpA2fRTyZO8io=
+google.golang.org/protobuf v1.35.2/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gotest.tools/v3 v3.5.1 h1:EENdUnS3pdur5nybKYIh2Vfgc8IUNBjxDPSjtiJcOzU=
+gotest.tools/v3 v3.5.1/go.mod h1:isy3WKz7GK6uNw/sbHzfKBLvlvXwUyV06n6brMxxopU=

aws_infra/Testcontainers/go-testcontainers/ministack_test.go

@@ -0,0 +1,297 @@
+package ministacktest
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/credentials"
+	"github.com/aws/aws-sdk-go-v2/service/dynamodb"
+	"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
+	"github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/aws/aws-sdk-go-v2/service/sqs"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/wait"
+)
+
+// newMiniStackContainer starts a MiniStack container and returns the endpoint URL.
+func newMiniStackContainer(ctx context.Context, t *testing.T) (string, func()) {
+	t.Helper()
+
+	req := testcontainers.ContainerRequest{
+		Image:        "ministackorg/ministack:latest",
+		ExposedPorts: []string{"4566/tcp"},
+		Env: map[string]string{
+			"GATEWAY_PORT": "4566",
+			"LOG_LEVEL":    "INFO",
+		},
+		WaitingFor: wait.ForHTTP("/_ministack/health").
+			WithPort("4566/tcp").
+			WithStartupTimeout(60 * time.Second),
+	}
+
+	container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
+		ContainerRequest: req,
+		Started:          true,
+	})
+	if err != nil {
+		t.Fatalf("failed to start MiniStack container: %v", err)
+	}
+
+	host, err := container.Host(ctx)
+	if err != nil {
+		t.Fatalf("failed to get container host: %v", err)
+	}
+	port, err := container.MappedPort(ctx, "4566")
+	if err != nil {
+		t.Fatalf("failed to get mapped port: %v", err)
+	}
+
+	endpoint := fmt.Sprintf("http://%s:%s", host, port.Port())
+
+	cleanup := func() {
+		if err := container.Terminate(ctx); err != nil {
+			t.Logf("failed to terminate container: %v", err)
+		}
+	}
+
+	return endpoint, cleanup
+}
+
+func awsCfg(endpoint string) aws.Config {
+	return aws.Config{
+		Region: "us-east-1",
+		Credentials: credentials.NewStaticCredentialsProvider("test", "test", ""),
+		EndpointResolverWithOptions: aws.EndpointResolverWithOptionsFunc(
+			func(service, region string, options ...interface{}) (aws.Endpoint, error) {
+				return aws.Endpoint{URL: endpoint}, nil
+			},
+		),
+	}
+}
+
+// ── S3 ──────────────────────────────────────────────────────────────────────
+
+func TestS3_PutAndGetObject(t *testing.T) {
+	ctx := context.Background()
+	endpoint, cleanup := newMiniStackContainer(ctx, t)
+	defer cleanup()
+
+	cfg := awsCfg(endpoint)
+	client := s3.NewFromConfig(cfg, func(o *s3.Options) {
+		o.UsePathStyle = true
+	})
+
+	bucket := "go-test-bucket"
+	_, err := client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String(bucket)})
+	if err != nil {
+		t.Fatalf("CreateBucket: %v", err)
+	}
+
+	_, err = client.PutObject(ctx, &s3.PutObjectInput{
+		Bucket: aws.String(bucket),
+		Key:    aws.String("hello.txt"),
+		Body:   strings.NewReader("Hello from Go!"),
+	})
+	if err != nil {
+		t.Fatalf("PutObject: %v", err)
+	}
+
+	out, err := client.GetObject(ctx, &s3.GetObjectInput{
+		Bucket: aws.String(bucket),
+		Key:    aws.String("hello.txt"),
+	})
+	if err != nil {
+		t.Fatalf("GetObject: %v", err)
+	}
+	defer out.Body.Close()
+
+	buf := new(strings.Builder)
+	if _, err := fmt.Fscan(out.Body, buf); err != nil && buf.Len() == 0 {
+		t.Fatalf("read body: %v", err)
+	}
+	if !strings.Contains(buf.String(), "Hello") {
+		t.Errorf("unexpected body: %q", buf.String())
+	}
+}
+
+func TestS3_ListBuckets(t *testing.T) {
+	ctx := context.Background()
+	endpoint, cleanup := newMiniStackContainer(ctx, t)
+	defer cleanup()
+
+	cfg := awsCfg(endpoint)
+	client := s3.NewFromConfig(cfg, func(o *s3.Options) { o.UsePathStyle = true })
+
+	_, err := client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String("list-bucket")})
+	if err != nil {
+		t.Fatalf("CreateBucket: %v", err)
+	}
+
+	out, err := client.ListBuckets(ctx, &s3.ListBucketsInput{})
+	if err != nil {
+		t.Fatalf("ListBuckets: %v", err)
+	}
+
+	found := false
+	for _, b := range out.Buckets {
+		if aws.ToString(b.Name) == "list-bucket" {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("expected list-bucket in ListBuckets response")
+	}
+}
+
+// ── SQS ──────────────────────────────────────────────────────────────────────
+
+func TestSQS_SendAndReceive(t *testing.T) {
+	ctx := context.Background()
+	endpoint, cleanup := newMiniStackContainer(ctx, t)
+	defer cleanup()
+
+	cfg := awsCfg(endpoint)
+	client := sqs.NewFromConfig(cfg)
+
+	q, err := client.CreateQueue(ctx, &sqs.CreateQueueInput{QueueName: aws.String("go-test-queue")})
+	if err != nil {
+		t.Fatalf("CreateQueue: %v", err)
+	}
+
+	_, err = client.SendMessage(ctx, &sqs.SendMessageInput{
+		QueueUrl:    q.QueueUrl,
+		MessageBody: aws.String("hello from go"),
+	})
+	if err != nil {
+		t.Fatalf("SendMessage: %v", err)
+	}
+
+	recv, err := client.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{
+		QueueUrl:            q.QueueUrl,
+		MaxNumberOfMessages: 1,
+		WaitTimeSeconds:     2,
+	})
+	if err != nil {
+		t.Fatalf("ReceiveMessage: %v", err)
+	}
+	if len(recv.Messages) != 1 {
+		t.Fatalf("expected 1 message, got %d", len(recv.Messages))
+	}
+	if aws.ToString(recv.Messages[0].Body) != "hello from go" {
+		t.Errorf("unexpected body: %q", aws.ToString(recv.Messages[0].Body))
+	}
+}
+
+// ── DynamoDB ──────────────────────────────────────────────────────────────────
+
+func TestDynamoDB_PutAndGet(t *testing.T) {
+	ctx := context.Background()
+	endpoint, cleanup := newMiniStackContainer(ctx, t)
+	defer cleanup()
+
+	cfg := awsCfg(endpoint)
+	client := dynamodb.NewFromConfig(cfg)
+
+	_, err := client.CreateTable(ctx, &dynamodb.CreateTableInput{
+		TableName: aws.String("go-test-table"),
+		KeySchema: []types.KeySchemaElement{
+			{AttributeName: aws.String("pk"), KeyType: types.KeyTypeHash},
+		},
+		AttributeDefinitions: []types.AttributeDefinition{
+			{AttributeName: aws.String("pk"), AttributeType: types.ScalarAttributeTypeS},
+		},
+		BillingMode: types.BillingModePayPerRequest,
+	})
+	if err != nil {
+		t.Fatalf("CreateTable: %v", err)
+	}
+
+	_, err = client.PutItem(ctx, &dynamodb.PutItemInput{
+		TableName: aws.String("go-test-table"),
+		Item: map[string]types.AttributeValue{
+			"pk":    &types.AttributeValueMemberS{Value: "key1"},
+			"value": &types.AttributeValueMemberS{Value: "hello dynamodb from go"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("PutItem: %v", err)
+	}
+
+	out, err := client.GetItem(ctx, &dynamodb.GetItemInput{
+		TableName: aws.String("go-test-table"),
+		Key: map[string]types.AttributeValue{
+			"pk": &types.AttributeValueMemberS{Value: "key1"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("GetItem: %v", err)
+	}
+
+	val, ok := out.Item["value"].(*types.AttributeValueMemberS)
+	if !ok {
+		t.Fatal("expected string attribute 'value'")
+	}
+	if val.Value != "hello dynamodb from go" {
+		t.Errorf("unexpected value: %q", val.Value)
+	}
+}
+
+func TestDynamoDB_DeleteItem(t *testing.T) {
+	ctx := context.Background()
+	endpoint, cleanup := newMiniStackContainer(ctx, t)
+	defer cleanup()
+
+	cfg := awsCfg(endpoint)
+	client := dynamodb.NewFromConfig(cfg)
+
+	_, err := client.CreateTable(ctx, &dynamodb.CreateTableInput{
+		TableName: aws.String("go-delete-table"),
+		KeySchema: []types.KeySchemaElement{
+			{AttributeName: aws.String("pk"), KeyType: types.KeyTypeHash},
+		},
+		AttributeDefinitions: []types.AttributeDefinition{
+			{AttributeName: aws.String("pk"), AttributeType: types.ScalarAttributeTypeS},
+		},
+		BillingMode: types.BillingModePayPerRequest,
+	})
+	if err != nil {
+		t.Fatalf("CreateTable: %v", err)
+	}
+
+	_, err = client.PutItem(ctx, &dynamodb.PutItemInput{
+		TableName: aws.String("go-delete-table"),
+		Item: map[string]types.AttributeValue{
+			"pk": &types.AttributeValueMemberS{Value: "del1"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("PutItem: %v", err)
+	}
+
+	_, err = client.DeleteItem(ctx, &dynamodb.DeleteItemInput{
+		TableName: aws.String("go-delete-table"),
+		Key: map[string]types.AttributeValue{
+			"pk": &types.AttributeValueMemberS{Value: "del1"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("DeleteItem: %v", err)
+	}
+
+	out, err := client.GetItem(ctx, &dynamodb.GetItemInput{
+		TableName: aws.String("go-delete-table"),
+		Key: map[string]types.AttributeValue{
+			"pk": &types.AttributeValueMemberS{Value: "del1"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("GetItem: %v", err)
+	}
+	if len(out.Item) != 0 {
+		t.Error("expected item to be deleted")
+	}
+}

aws_infra/Testcontainers/java-testcontainers/README.md

@@ -0,0 +1,25 @@
+# MiniStack — Java Testcontainers Example
+
+Integration tests for S3, SQS, and DynamoDB using [Testcontainers](https://testcontainers.com/) and the AWS SDK v2.
+
+## Prerequisites
+
+- Java 17+
+- Maven 3.8+
+- Docker (running)
+
+## Run
+
+```bash
+mvn test
+```
+
+Testcontainers will pull `ministackorg/ministack:latest`, start it, run the tests, and tear it down automatically.
+
+## What's tested
+
+| Service    | Operations |
+|------------|------------|
+| S3         | CreateBucket, PutObject, GetObject, ListBuckets, DeleteObject |
+| SQS        | CreateQueue, SendMessage, ReceiveMessage, DeleteMessage, GetQueueAttributes |
+| DynamoDB   | CreateTable, PutItem, GetItem, UpdateItem, DeleteItem |

aws_infra/Testcontainers/java-testcontainers/pom.xml

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>io.ministack</groupId>
+    <artifactId>ministack-testcontainers-example</artifactId>
+    <version>1.0.0</version>
+    <packaging>jar</packaging>
+
+    <properties>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <testcontainers.version>1.19.8</testcontainers.version>
+        <aws.sdk.version>2.25.40</aws.sdk.version>
+        <junit.version>5.10.2</junit.version>
+    </properties>
+
+    <dependencies>
+        <!-- JUnit 5 -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>${junit.version}</version>
+            <scope>test</scope>
+        </dependency>
+
+        <!-- Testcontainers -->
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>testcontainers</artifactId>
+            <version>${testcontainers.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>${testcontainers.version}</version>
+            <scope>test</scope>
+        </dependency>
+
+        <!-- AWS SDK v2 -->
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>s3</artifactId>
+            <version>${aws.sdk.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>sqs</artifactId>
+            <version>${aws.sdk.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>dynamodb</artifactId>
+            <version>${aws.sdk.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>url-connection-client</artifactId>
+            <version>${aws.sdk.version}</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.2.5</version>
+            </plugin>
+        </plugins>
+    </build>
+</project>

aws_infra/Testcontainers/java-testcontainers/src/test/java/io/ministack/MiniStackTest.java

@@ -0,0 +1,211 @@
+package io.ministack;
+
+import org.junit.jupiter.api.*;
+import org.testcontainers.containers.GenericContainer;
+import org.testcontainers.containers.wait.strategy.HttpWaitStrategy;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+import org.testcontainers.utility.DockerImageName;
+
+import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
+import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
+import software.amazon.awssdk.regions.Region;
+import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
+import software.amazon.awssdk.services.dynamodb.model.*;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.*;
+import software.amazon.awssdk.services.sqs.SqsClient;
+import software.amazon.awssdk.services.sqs.model.*;
+
+import java.net.URI;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@Testcontainers
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
+class MiniStackTest {
+
+    @Container
+    static final GenericContainer<?> ministack = new GenericContainer<>(
+            DockerImageName.parse("ministackorg/ministack:latest"))
+            .withExposedPorts(4566)
+            .withEnv("GATEWAY_PORT", "4566")
+            .withEnv("LOG_LEVEL", "INFO")
+            .waitingFor(new HttpWaitStrategy()
+                    .forPath("/_ministack/health")
+                    .forPort(4566)
+                    .withStartupTimeout(Duration.ofSeconds(60)));
+
+    private static URI endpoint;
+    private static StaticCredentialsProvider credentials;
+
+    @BeforeAll
+    static void setup() {
+        endpoint = URI.create("http://" + ministack.getHost() + ":" + ministack.getMappedPort(4566));
+        credentials = StaticCredentialsProvider.create(
+                AwsBasicCredentials.create("test", "test"));
+    }
+
+    private S3Client s3() {
+        return S3Client.builder()
+                .endpointOverride(endpoint)
+                .credentialsProvider(credentials)
+                .region(Region.US_EAST_1)
+                .httpClient(UrlConnectionHttpClient.create())
+                .forcePathStyle(true)
+                .build();
+    }
+
+    private SqsClient sqs() {
+        return SqsClient.builder()
+                .endpointOverride(endpoint)
+                .credentialsProvider(credentials)
+                .region(Region.US_EAST_1)
+                .httpClient(UrlConnectionHttpClient.create())
+                .build();
+    }
+
+    private DynamoDbClient ddb() {
+        return DynamoDbClient.builder()
+                .endpointOverride(endpoint)
+                .credentialsProvider(credentials)
+                .region(Region.US_EAST_1)
+                .httpClient(UrlConnectionHttpClient.create())
+                .build();
+    }
+
+    // ── S3 ──────────────────────────────────────────────────────────────────
+
+    @Test
+    @Order(1)
+    void s3_createBucketPutAndGetObject() {
+        try (S3Client client = s3()) {
+            client.createBucket(b -> b.bucket("test-bucket"));
+
+            client.putObject(
+                    PutObjectRequest.builder().bucket("test-bucket").key("hello.txt").build(),
+                    RequestBody.fromString("Hello MiniStack!"));
+
+            String body = client.getObjectAsBytes(
+                    GetObjectRequest.builder().bucket("test-bucket").key("hello.txt").build()
+            ).asUtf8String();
+
+            assertEquals("Hello MiniStack!", body);
+        }
+    }
+
+    @Test
+    @Order(2)
+    void s3_listBuckets() {
+        try (S3Client client = s3()) {
+            List<Bucket> buckets = client.listBuckets().buckets();
+            assertTrue(buckets.stream().anyMatch(b -> b.name().equals("test-bucket")));
+        }
+    }
+
+    @Test
+    @Order(3)
+    void s3_deleteObject() {
+        try (S3Client client = s3()) {
+            client.deleteObject(b -> b.bucket("test-bucket").key("hello.txt"));
+            assertThrows(NoSuchKeyException.class, () ->
+                    client.getObjectAsBytes(b -> b.bucket("test-bucket").key("hello.txt")));
+        }
+    }
+
+    // ── SQS ─────────────────────────────────────────────────────────────────
+
+    @Test
+    @Order(10)
+    void sqs_sendAndReceiveMessage() {
+        try (SqsClient client = sqs()) {
+            String queueUrl = client.createQueue(b -> b.queueName("test-queue")).queueUrl();
+
+            client.sendMessage(b -> b.queueUrl(queueUrl).messageBody("hello from java"));
+
+            ReceiveMessageResponse resp = client.receiveMessage(b -> b
+                    .queueUrl(queueUrl)
+                    .maxNumberOfMessages(1)
+                    .waitTimeSeconds(2));
+
+            assertEquals(1, resp.messages().size());
+            assertEquals("hello from java", resp.messages().get(0).body());
+
+            client.deleteMessage(b -> b
+                    .queueUrl(queueUrl)
+                    .receiptHandle(resp.messages().get(0).receiptHandle()));
+        }
+    }
+
+    @Test
+    @Order(11)
+    void sqs_queueAttributes() {
+        try (SqsClient client = sqs()) {
+            String queueUrl = client.createQueue(b -> b.queueName("test-queue")).queueUrl();
+            GetQueueAttributesResponse attrs = client.getQueueAttributes(b -> b
+                    .queueUrl(queueUrl)
+                    .attributeNames(QueueAttributeName.ALL));
+            assertNotNull(attrs.attributes().get(QueueAttributeName.QUEUE_ARN));
+        }
+    }
+
+    // ── DynamoDB ─────────────────────────────────────────────────────────────
+
+    @Test
+    @Order(20)
+    void dynamodb_createTablePutAndGetItem() {
+        try (DynamoDbClient client = ddb()) {
+            client.createTable(b -> b
+                    .tableName("test-table")
+                    .keySchema(KeySchemaElement.builder().attributeName("pk").keyType(KeyType.HASH).build())
+                    .attributeDefinitions(AttributeDefinition.builder()
+                            .attributeName("pk").attributeType(ScalarAttributeType.S).build())
+                    .billingMode(BillingMode.PAY_PER_REQUEST));
+
+            client.putItem(b -> b
+                    .tableName("test-table")
+                    .item(Map.of(
+                            "pk", AttributeValue.fromS("key1"),
+                            "value", AttributeValue.fromS("hello dynamodb"))));
+
+            GetItemResponse resp = client.getItem(b -> b
+                    .tableName("test-table")
+                    .key(Map.of("pk", AttributeValue.fromS("key1"))));
+
+            assertTrue(resp.hasItem());
+            assertEquals("hello dynamodb", resp.item().get("value").s());
+        }
+    }
+
+    @Test
+    @Order(21)
+    void dynamodb_updateAndDeleteItem() {
+        try (DynamoDbClient client = ddb()) {
+            client.updateItem(b -> b
+                    .tableName("test-table")
+                    .key(Map.of("pk", AttributeValue.fromS("key1")))
+                    .updateExpression("SET #v = :v")
+                    .expressionAttributeNames(Map.of("#v", "value"))
+                    .expressionAttributeValues(Map.of(":v", AttributeValue.fromS("updated"))));
+
+            GetItemResponse resp = client.getItem(b -> b
+                    .tableName("test-table")
+                    .key(Map.of("pk", AttributeValue.fromS("key1"))));
+            assertEquals("updated", resp.item().get("value").s());
+
+            client.deleteItem(b -> b
+                    .tableName("test-table")
+                    .key(Map.of("pk", AttributeValue.fromS("key1"))));
+
+            GetItemResponse after = client.getItem(b -> b
+                    .tableName("test-table")
+                    .key(Map.of("pk", AttributeValue.fromS("key1"))));
+            assertFalse(after.hasItem());
+        }
+    }
+}

aws_infra/Testcontainers/python-testcontainers/README.md

@@ -0,0 +1,23 @@
+# MiniStack Python Testcontainers Example
+
+Integration tests for MiniStack using [Testcontainers](https://testcontainers-python.readthedocs.io/) and boto3.
+
+## Prerequisites
+
+- Python 3.10+
+- Docker
+- pip
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+## Run tests
+
+```bash
+pytest test_ministack.py -v
+```
+
+The tests automatically start a MiniStack container, wait for it to become healthy, and run S3, SQS, and DynamoDB integration tests against it.

aws_infra/Testcontainers/python-testcontainers/requirements.txt

@@ -0,0 +1,3 @@
+testcontainers
+boto3
+pytest

aws_infra/Testcontainers/python-testcontainers/test_ministack.py

@@ -0,0 +1,110 @@
+import time
+
+import boto3
+import pytest
+import requests
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.waiting_utils import wait_for_logs
+
+
+@pytest.fixture(scope="module")
+def ministack():
+    """Start a MiniStack container and wait for it to be healthy."""
+    container = DockerContainer("ministackorg/ministack:latest").with_exposed_ports(4566)
+    container.start()
+
+    host = container.get_container_host_ip()
+    port = container.get_exposed_port(4566)
+    endpoint = f"http://{host}:{port}"
+
+    # Wait for health endpoint to be ready
+    deadline = time.time() + 30
+    while time.time() < deadline:
+        try:
+            resp = requests.get(f"{endpoint}/_ministack/health", timeout=2)
+            if resp.status_code == 200:
+                break
+        except Exception:
+            pass
+        time.sleep(0.5)
+    else:
+        raise RuntimeError("MiniStack container did not become healthy within 30s")
+
+    yield endpoint
+
+    container.stop()
+
+
+def _client(service: str, endpoint: str):
+    """Create a boto3 client pointing at the MiniStack container."""
+    return boto3.client(
+        service,
+        endpoint_url=endpoint,
+        region_name="us-east-1",
+        aws_access_key_id="test",
+        aws_secret_access_key="test",
+    )
+
+
+# ---------------------------------------------------------------------------
+# S3
+# ---------------------------------------------------------------------------
+
+class TestS3:
+    def test_create_bucket_put_get_object(self, ministack):
+        s3 = _client("s3", ministack)
+
+        bucket = "test-bucket"
+        s3.create_bucket(Bucket=bucket)
+
+        s3.put_object(Bucket=bucket, Key="hello.txt", Body=b"hello world")
+
+        resp = s3.get_object(Bucket=bucket, Key="hello.txt")
+        body = resp["Body"].read()
+        assert body == b"hello world"
+
+
+# ---------------------------------------------------------------------------
+# SQS
+# ---------------------------------------------------------------------------
+
+class TestSQS:
+    def test_create_queue_send_receive(self, ministack):
+        sqs = _client("sqs", ministack)
+
+        queue = sqs.create_queue(QueueName="test-queue")
+        queue_url = queue["QueueUrl"]
+
+        sqs.send_message(QueueUrl=queue_url, MessageBody="ping")
+
+        messages = sqs.receive_message(QueueUrl=queue_url, MaxNumberOfMessages=1)
+        assert len(messages["Messages"]) == 1
+        assert messages["Messages"][0]["Body"] == "ping"
+
+
+# ---------------------------------------------------------------------------
+# DynamoDB
+# ---------------------------------------------------------------------------
+
+class TestDynamoDB:
+    def test_create_table_put_get_item(self, ministack):
+        ddb = _client("dynamodb", ministack)
+
+        table_name = "test-table"
+        ddb.create_table(
+            TableName=table_name,
+            KeySchema=[{"AttributeName": "pk", "KeyType": "HASH"}],
+            AttributeDefinitions=[{"AttributeName": "pk", "AttributeType": "S"}],
+            BillingMode="PAY_PER_REQUEST",
+        )
+
+        ddb.put_item(
+            TableName=table_name,
+            Item={"pk": {"S": "key1"}, "data": {"S": "value1"}},
+        )
+
+        resp = ddb.get_item(
+            TableName=table_name,
+            Key={"pk": {"S": "key1"}},
+        )
+        assert resp["Item"]["data"]["S"] == "value1"

aws_infra/bin/awslocal

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# awslocal — Wrapper around AWS CLI that points to local MiniStack endpoint.
+# Usage: ./awslocal s3 ls
+#        ./awslocal sqs create-queue --queue-name my-queue
+#        ./awslocal dynamodb list-tables
+
+ENDPOINT_URL="${MINISTACK_ENDPOINT:-http://localhost:4566}"
+AWS_ACCESS_KEY_ID="${AWS_ACCESS_KEY_ID:-test}"
+AWS_SECRET_ACCESS_KEY="${AWS_SECRET_ACCESS_KEY:-test}"
+AWS_DEFAULT_REGION="${AWS_DEFAULT_REGION:-us-east-1}"
+
+export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_DEFAULT_REGION
+
+exec aws --endpoint-url="$ENDPOINT_URL" "$@"

aws_infra/docker-compose.yml

@@ -0,0 +1,58 @@
+services:
+  ministack:
+    build: .
+    image: ministackorg/ministack:latest
+    container_name: ministack
+    ports:
+      - "4566:4566"
+    environment:
+      - GATEWAY_PORT=4566
+      - LOG_LEVEL=INFO
+      - S3_PERSIST=0
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+      - RDS_BASE_PORT=15432
+      - ELASTICACHE_BASE_PORT=16379
+    volumes:
+      - ./data/s3:/tmp/ministack-data/s3
+      - /var/run/docker.sock:/var/run/docker.sock
+    depends_on:
+      redis:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:4566/_ministack/health')"]
+      interval: 10s
+      timeout: 3s
+      retries: 3
+      start_period: 5s
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    container_name: ministack-redis
+    ports:
+      - "127.0.0.1:6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+
+  # Optional: Postgres for RDS (always-on, no Docker-in-Docker needed)
+  # Uncomment to have a persistent Postgres available at localhost:5432
+  # postgres:
+  #   image: postgres:15-alpine
+  #   container_name: ministack-postgres
+  #   ports:
+  #     - "5432:5432"
+  #   environment:
+  #     POSTGRES_USER: admin
+  #     POSTGRES_PASSWORD: password
+  #     POSTGRES_DB: mydb
+  #   healthcheck:
+  #     test: ["CMD-SHELL", "pg_isready -U admin"]
+  #     interval: 5s
+  #     timeout: 3s
+  #     retries: 5
+  #   restart: unless-stopped

aws_infra/ministack/__main__.py

@@ -0,0 +1,3 @@
+from ministack.app import main
+
+main()

aws_infra/ministack/app.py

@@ -0,0 +1,1414 @@
+"""
+MiniStack — Local AWS Service Emulator.
+Single-port ASGI application on port 4566 (configurable via GATEWAY_PORT).
+Routes requests to service handlers based on AWS headers, paths, and query parameters.
+Compatible with AWS CLI, boto3, and any AWS SDK via --endpoint-url.
+"""
+
+import argparse
+import asyncio
+import base64
+import json
+import logging
+import math
+import os
+import re
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import uuid
+from urllib.parse import parse_qs, unquote
+
+_MINISTACK_HOST = os.environ.get("MINISTACK_HOST", "localhost")
+_MINISTACK_PORT = os.environ.get("GATEWAY_PORT", "4566")
+
+try:
+    from importlib.metadata import version as _pkg_version
+    _VERSION = _pkg_version("ministack")
+except Exception:
+    _VERSION = "dev"
+
+# Matches host headers like "{apiId}.execute-api.<host>" or "{apiId}.execute-api.<host>:4566"
+_EXECUTE_API_RE = re.compile(
+    r"^([a-f0-9]{8})\.execute-api\." + re.escape(_MINISTACK_HOST) + r"(?::\d+)?$"
+)
+# Matches virtual-hosted S3:
+#   "{bucket}.<host>" or "{bucket}.<host>:4566"          (boto3/SDK default)
+#   "{bucket}.s3.<host>" or "{bucket}.s3.<host>:4566"    (Terraform AWS provider v4+)
+# Does NOT match execute-api, alb, or other sub-service hostnames.
+_S3_VHOST_RE = re.compile(
+    r"^([^.]+)(?:\.s3)?\." + re.escape(_MINISTACK_HOST) + r"(?::\d+)?$"
+)
+_S3_VHOST_EXCLUDE_RE = re.compile(r"\.(execute-api|alb|emr|efs|elasticache|s3-control)\.")
+_HEALTH_PATHS = ("/_ministack/health", "/_localstack/health", "/health")
+_BODY_METHODS = ("POST", "PUT", "PATCH")
+_COGNITO_USERINFO_PATHS = ("/oauth2/userInfo", "/oauth2/userinfo")
+_RDS_DATA_PATHS = ("/Execute", "/BeginTransaction", "/CommitTransaction", "/RollbackTransaction", "/BatchExecute")
+_S3_CONTROL_PREFIX = "/v20180820/"
+_SES_V2_PREFIX = "/v2/email"
+_ALB_PATH_PREFIX = "/_alb/"
+_NON_S3_VHOST_NAMES = frozenset({
+    "s3", "s3-control", "sqs", "sns", "dynamodb", "lambda", "iam", "sts",
+    "secretsmanager", "logs", "ssm", "events", "kinesis", "monitoring", "ses",
+    "states", "ecs", "rds", "rds-data", "elasticache", "glue", "athena",
+    "apigateway", "cloudformation", "autoscaling", "codebuild", "transfer",
+})
+
+from ministack.core.hypercorn_compat import install as _install_hypercorn_compat
+from ministack.core.persistence import PERSIST_STATE, load_state, save_all
+from ministack.core.responses import set_request_account_id, set_request_region
+from ministack.core.router import detect_service, extract_access_key_id, extract_region
+
+# Must run before hypercorn emits its first Expect: 100-continue reply.
+# See ministack/core/hypercorn_compat.py for the rationale (issue #389).
+_install_hypercorn_compat()
+
+# ---------------------------------------------------------------------------
+# Lazy service loader — modules are imported on first request, not at startup.
+# This saves ~20 MB of idle RAM and speeds up boot.
+# ---------------------------------------------------------------------------
+_loaded_modules: dict = {}
+
+# Execution state of ready.d scripts — surfaced via /_ministack/health and /_ministack/ready.
+# status: "pending" (not started) | "running" | "completed" (all scripts finished, errors included)
+_ready_scripts_state: dict = {
+    "status": "pending",
+    "total": 0,
+    "completed": 0,
+    "failed": 0,
+}
+
+
+class _ErrorModule:
+    """Stub returned when a service module fails to import."""
+    def __init__(self, name: str, error: str):
+        self._name = name
+        self._error = error
+
+    async def handle_request(self, method, path, headers, body, query_params):
+        return 500, {"Content-Type": "application/json"}, \
+            json.dumps({"__type": "ServiceUnavailable",
+                        "message": f"Service module '{self._name}' failed to load: {self._error}"}).encode()
+
+    def get_state(self):
+        return {}
+
+    def restore_state(self, data):
+        pass
+
+    def load_persisted_state(self, data):
+        pass
+
+    def reset(self):
+        pass
+
+
+def _get_module(name: str):
+    """Import and cache a service module by short name (e.g. 's3', 'lambda_svc')."""
+    mod = _loaded_modules.get(name)
+    if mod is None:
+        try:
+            mod = __import__(f"ministack.services.{name}", fromlist=["handle_request"])
+        except (ModuleNotFoundError, ImportError) as e:
+            logger.warning("Service module failed to load: %s - %s", name, e)
+            mod = _ErrorModule(name, str(e))
+        _loaded_modules[name] = mod
+    return mod
+
+
+def _lazy_handler(module_name: str):
+    """Return a callable that lazily imports module_name and delegates to handle_request."""
+    async def _handler(method, path, headers, body, query_params):
+        mod = _get_module(module_name)
+        return await mod.handle_request(method, path, headers, body, query_params)
+    return _handler
+
+LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO").upper()
+logging.basicConfig(
+    level=getattr(logging, LOG_LEVEL, logging.INFO),
+    format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger("ministack")
+
+# Single source of truth for routable services, their backing modules, and aliases.
+SERVICE_REGISTRY = {
+    "acm": {"module": "acm"},
+    "apigateway": {"module": "apigateway", "aliases": ("execute-api", "apigatewayv2")},
+    "appconfig": {"module": "appconfig"},
+    "appconfigdata": {"module": "appconfig"},
+    "appsync": {"module": "appsync"},
+    "athena": {"module": "athena"},
+    "autoscaling": {"module": "autoscaling"},
+    "cloudformation": {"module": "cloudformation"},
+    "cloudfront": {"module": "cloudfront"},
+    "codebuild": {"module": "codebuild"},
+    "cognito-identity": {"module": "cognito"},
+    "cognito-idp": {"module": "cognito"},
+    "dynamodb": {"module": "dynamodb"},
+    "ec2": {"module": "ec2"},
+    "ecr": {"module": "ecr"},
+    "ecs": {"module": "ecs"},
+    "eks": {"module": "eks"},
+    "elasticache": {"module": "elasticache"},
+    "elasticfilesystem": {"module": "efs"},
+    "elasticloadbalancing": {"module": "alb", "aliases": ("elbv2", "elb")},
+    "elasticmapreduce": {"module": "emr"},
+    "events": {"module": "eventbridge", "aliases": ("eventbridge",)},
+    "firehose": {"module": "firehose", "aliases": ("kinesis-firehose",)},
+    "glue": {"module": "glue"},
+    "iam": {"module": "iam"},
+    "kinesis": {"module": "kinesis"},
+    "kms": {"module": "kms"},
+    "lambda": {"module": "lambda_svc"},
+    "logs": {"module": "cloudwatch_logs", "aliases": ("cloudwatch-logs",)},
+    "monitoring": {"module": "cloudwatch", "aliases": ("cloudwatch",)},
+    "rds-data": {"module": "rds_data"},
+    "rds": {"module": "rds"},
+    "route53": {"module": "route53"},
+    "s3": {"module": "s3"},
+    "s3files": {"module": "s3files"},
+    "scheduler": {"module": "scheduler"},
+    "secretsmanager": {"module": "secretsmanager"},
+    "servicediscovery": {"module": "servicediscovery"},
+    "ses": {"module": "ses"},
+    "sns": {"module": "sns"},
+    "sqs": {"module": "sqs"},
+    "ssm": {"module": "ssm"},
+    "states": {"module": "stepfunctions", "aliases": ("step-functions", "stepfunctions")},
+    "sts": {"module": "sts"},
+    "tagging": {"module": "tagging"},
+    "transfer": {"module": "transfer"},
+    "wafv2": {"module": "waf"},
+}
+
+SERVICE_HANDLERS = {
+    service_name: _lazy_handler(service_config["module"])
+    for service_name, service_config in SERVICE_REGISTRY.items()
+}
+
+SERVICE_NAME_ALIASES = {
+    alias: service_name
+    for service_name, service_config in SERVICE_REGISTRY.items()
+    for alias in service_config.get("aliases", ())
+}
+
+
+def _resolve_port():
+    """Resolve gateway port: GATEWAY_PORT > EDGE_PORT > 4566."""
+    return os.environ.get("GATEWAY_PORT") or os.environ.get("EDGE_PORT") or "4566"
+
+
+if os.environ.get("LOCALSTACK_PERSISTENCE") == "1" and os.environ.get("S3_PERSIST") != "1":
+    os.environ["S3_PERSIST"] = "1"
+    logger.info("LOCALSTACK_PERSISTENCE=1 detected — enabling S3_PERSIST")
+
+_services_env = os.environ.get("SERVICES", "").strip()
+if _services_env:
+    _requested = {s.strip() for s in _services_env.split(",") if s.strip()}
+    _resolved = set()
+    for _name in _requested:
+        _key = SERVICE_NAME_ALIASES.get(_name, _name)
+        if _key in SERVICE_HANDLERS:
+            _resolved.add(_key)
+        else:
+            logger.warning("SERVICES: unknown service '%s' (resolved as '%s') — skipping", _name, _key)
+    SERVICE_HANDLERS = {k: v for k, v in SERVICE_HANDLERS.items() if k in _resolved}
+    logger.info("SERVICES filter active — enabled: %s", sorted(SERVICE_HANDLERS.keys()))
+
+BANNER = r"""
+  __  __ _       _ ____  _             _
+ |  \/  (_)_ __ (_) ___|| |_ __ _  ___| | __
+ | |\/| | | '_ \| \___ \| __/ _` |/ __| |/ /
+ | |  | | | | | | |___) | || (_| | (__|   <
+ |_|  |_|_|_| |_|_|____/ \__\__,_|\___|_|\_\
+
+ Local AWS Service Emulator — Port {port}
+ Services: S3, SQS, SNS, DynamoDB, Lambda, IAM, STS, SecretsManager, CloudWatch Logs,
+          SSM, EventBridge, Kinesis, CloudWatch, SES, SES v2, ACM, WAF v2, Step Functions,
+          ECS, RDS, ElastiCache, Glue, Athena, API Gateway, Firehose, Route53,
+          Cognito, EC2, EMR, EBS, EFS, ALB/ELBv2, CloudFormation, KMS, ECR, CloudFront,
+          AppSync, Cloud Map, S3 Files, RDS Data API, CodeBuild, AppConfig, Transfer, EKS
+"""
+
+
+_reset_lock: "asyncio.Lock | None" = None
+
+
+def _get_reset_lock() -> asyncio.Lock:
+    global _reset_lock
+    if _reset_lock is None:
+        _reset_lock = asyncio.Lock()
+    return _reset_lock
+
+
+# ---------------------------------------------------------------------------
+# Request I/O helpers
+# ---------------------------------------------------------------------------
+
+def _decode_aws_chunked_body(body: bytes, headers: dict) -> bytes:
+    """Decode AWS chunked request bodies and normalize content-encoding headers."""
+    sha256_header = headers.get("x-amz-content-sha256", "")
+    content_encoding = headers.get("content-encoding", "")
+    if not (
+        sha256_header.startswith("STREAMING-")
+        or "aws-chunked" in content_encoding
+        or headers.get("x-amz-decoded-content-length")
+    ):
+        return body
+
+    decoded = b""
+    remaining = body
+    while remaining:
+        crlf = remaining.find(b"\r\n")
+        if crlf == -1:
+            break
+        chunk_header = remaining[:crlf].decode("ascii", errors="replace")
+        size_hex = chunk_header.split(";")[0].strip()
+        try:
+            chunk_size = int(size_hex, 16)
+        except ValueError:
+            break
+        if chunk_size == 0:
+            break
+        data_start = crlf + 2
+        decoded += remaining[data_start:data_start + chunk_size]
+        remaining = remaining[data_start + chunk_size + 2:]  # skip trailing \r\n
+
+    if decoded or not body:
+        body = decoded
+    if "aws-chunked" in content_encoding:
+        encodings = [p.strip() for p in content_encoding.split(",") if p.strip() != "aws-chunked"]
+        if encodings:
+            headers["content-encoding"] = ", ".join(encodings)
+        else:
+            headers.pop("content-encoding", None)
+    return body
+
+
+async def _read_request_body(receive, method: str, headers: dict) -> bytes:
+    """Read and decode the request body only for methods or headers that can carry one."""
+    body = b""
+    if headers.get("content-length") or headers.get("transfer-encoding") or method in _BODY_METHODS:
+        while True:
+            message = await receive()
+            body += message.get("body", b"")
+            if not message.get("more_body", False):
+                break
+    return _decode_aws_chunked_body(body, headers)
+
+
+async def _send_response(send, status, headers, body):
+    """Send ASGI HTTP response."""
+    def _encode_header_value(v: str) -> bytes:
+        try:
+            return v.encode("latin-1")
+        except UnicodeEncodeError:
+            return v.encode("utf-8")
+
+    body_bytes = body if isinstance(body, bytes) else body.encode("utf-8")
+    if "content-length" not in {k.lower() for k in headers}:
+        headers["Content-Length"] = str(len(body_bytes))
+    header_list = [(k.encode("latin-1"), _encode_header_value(str(v))) for k, v in headers.items()]
+    await send({
+        "type": "http.response.start",
+        "status": status,
+        "headers": header_list,
+    })
+    await send({
+        "type": "http.response.body",
+        "body": body_bytes,
+        "more_body": False,
+    })
+
+
+async def _send_if_handled(send, response) -> bool:
+    """Send a response tuple and report whether the request was handled."""
+    if response is None:
+        return False
+    await _send_response(send, *response)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Tier 1 — Pre-body handlers (no request body needed)
+# ---------------------------------------------------------------------------
+
+def _handle_options_request(method: str, request_id: str):
+    """Return the standard CORS preflight response when applicable."""
+    if method != "OPTIONS":
+        return None
+    return 200, {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH",
+        "Access-Control-Allow-Headers": "*",
+        "Access-Control-Expose-Headers": "*",
+        "Access-Control-Max-Age": "86400",
+        "Content-Length": "0",
+        "x-amzn-requestid": request_id,
+    }, b""
+
+
+def _handle_health_request(path: str, request_id: str):
+    """Return health responses for MiniStack and LocalStack-compatible endpoints."""
+    if path not in _HEALTH_PATHS:
+        return None
+    return 200, {
+        "Content-Type": "application/json",
+        "x-amzn-requestid": request_id,
+    }, json.dumps({
+        "services": {s: "available" for s in SERVICE_HANDLERS},
+        "edition": "light",
+        "version": _VERSION,
+        "ready_scripts": dict(_ready_scripts_state),
+    }).encode()
+
+
+def _handle_ready_request(path: str, request_id: str):
+    """Return readiness state once ready.d scripts have completed."""
+    if path != "/_ministack/ready":
+        return None
+    ready = _ready_scripts_state["status"] == "completed"
+    status = 200 if ready else 503
+    return status, {
+        "Content-Type": "application/json",
+        "x-amzn-requestid": request_id,
+    }, json.dumps(dict(_ready_scripts_state)).encode()
+
+
+def _handle_lambda_download_request(path: str, method: str):
+    """Serve MiniStack's Lambda layer and function-code download endpoints."""
+    if path.startswith("/_ministack/lambda-layers/") and method == "GET":
+        path_parts = path.split("/")
+        if len(path_parts) >= 6 and path_parts[5] == "content" and path_parts[4].isdigit():
+            return _get_module("lambda_svc").serve_layer_content(path_parts[3], int(path_parts[4]))
+
+    if path.startswith("/_ministack/lambda-code/") and method == "GET":
+        path_parts = path.split("/")
+        if len(path_parts) >= 4:
+            return _get_module("lambda_svc").serve_function_code(path_parts[3])
+    return None
+
+
+async def _handle_cognito_get_request(method: str, path: str, headers: dict, query_params: dict):
+    """Handle Cognito GET endpoints that do not require request body parsing."""
+    if "/.well-known/" in path and method == "GET":
+        if path.endswith("/.well-known/jwks.json"):
+            pool_id = path.rsplit("/.well-known/jwks.json", 1)[0].lstrip("/")
+            if pool_id:
+                return _get_module("cognito").well_known_jwks(pool_id)
+        elif path.endswith("/.well-known/openid-configuration"):
+            pool_id = path.rsplit("/.well-known/openid-configuration", 1)[0].lstrip("/")
+            if pool_id:
+                region = extract_region(headers) or "us-east-1"
+                return _get_module("cognito").well_known_openid_configuration(pool_id, region)
+
+    if path == "/oauth2/authorize" and method == "GET":
+        return _get_module("cognito").handle_oauth2_authorize(method, path, headers, query_params)
+    if path in _COGNITO_USERINFO_PATHS and method == "GET":
+        return _get_module("cognito").handle_oauth2_userinfo(method, path, headers, b"", query_params)
+    if path == "/logout" and method == "GET":
+        return _get_module("cognito").handle_logout(method, path, headers, query_params)
+    return None
+
+
+async def _handle_admin_reset(path: str, method: str, query_params: dict):
+    """Handle reset requests before request body parsing."""
+    if path != "/_ministack/reset" or method != "POST":
+        return None
+
+    async with _get_reset_lock():
+        await asyncio.to_thread(_reset_all_state)
+
+    run_init = query_params.get("init", [""])[0] == "1"
+    if run_init:
+        _run_init_scripts()
+        _ready_scripts_state.update({"status": "pending", "total": 0, "completed": 0, "failed": 0})
+        asyncio.create_task(_run_ready_scripts())
+    return 200, {"Content-Type": "application/json"}, json.dumps({"reset": "ok"}).encode()
+
+
+def _handle_admin_introspection(path: str, method: str):
+    """Handle /_ministack/{state,handlers,handlers/<svc>} introspection endpoints."""
+    if method != "GET":
+        return None
+    if path == "/_ministack/state":
+        return 200, {"Content-Type": "application/json"}, json.dumps(_get_all_state()).encode()
+    if path == "/_ministack/handlers":
+        return 200, {"Content-Type": "application/json"}, json.dumps(_get_all_handlers()).encode()
+    if path.startswith("/_ministack/handlers/"):
+        service_name = path[len("/_ministack/handlers/"):].strip("/")
+        info = _get_service_info(service_name)
+        if info is None:
+            return 404, {"Content-Type": "application/json"}, json.dumps({"error": f"Unknown service: {service_name}"}).encode()
+        return 200, {"Content-Type": "application/json"}, json.dumps(info).encode()
+    return None
+
+
+async def _handle_pre_body_request(method: str, path: str, headers: dict, query_params: dict, request_id: str):
+    """Handle fast-path routes that do not require request body parsing."""
+    # OPTIONS on an execute-api host / path MUST flow through apigateway.handle_execute
+    # so the API's own corsConfiguration is applied (#406). Skip the generic wildcard
+    # preflight in that case.
+    host = headers.get("host", "")
+    is_execute_api = _parse_execute_api_url(host, path) is not None
+    for response in (
+        None if is_execute_api else _handle_options_request(method, request_id),
+        _handle_health_request(path, request_id),
+        _handle_ready_request(path, request_id),
+        _handle_lambda_download_request(path, method),
+        _handle_admin_introspection(path, method),
+    ):
+        if response is not None:
+            return response
+
+    response = await _handle_cognito_get_request(method, path, headers, query_params)
+    if response is not None:
+        return response
+    return await _handle_admin_reset(path, method, query_params)
+
+
+# ---------------------------------------------------------------------------
+# Tier 2 — Post-body shortcuts (body required, before generic routing)
+# ---------------------------------------------------------------------------
+
+async def _handle_cognito_body_request(method: str, path: str, headers: dict, body: bytes, query_params: dict):
+    """Handle Cognito routes that require the parsed request body."""
+    if path in ("/oauth2/login", "/login") and method == "POST":
+        return _get_module("cognito").handle_login_submit(method, path, headers, body, query_params)
+    if path == "/oauth2/token" and method == "POST":
+        return _get_module("cognito").handle_oauth2_token(method, path, headers, body, query_params)
+    if path in _COGNITO_USERINFO_PATHS and method == "POST":
+        return _get_module("cognito").handle_oauth2_userinfo(method, path, headers, body, query_params)
+    return None
+
+
+async def _handle_admin_config_request(path: str, method: str, body: bytes):
+    """Apply whitelisted runtime config changes through the admin endpoint."""
+    if path != "/_ministack/config" or method != "POST":
+        return None
+
+    allowed_config_keys = {
+        "athena.ATHENA_ENGINE", "athena.ATHENA_DATA_DIR",
+        "stepfunctions._sfn_mock_config",
+        "stepfunctions._SFN_WAIT_SCALE",
+        "lambda_svc.LAMBDA_EXECUTOR",
+    }
+    try:
+        config = json.loads(body) if body else {}
+    except json.JSONDecodeError:
+        config = {}
+
+    applied = {}
+    for key, value in config.items():
+        if key not in allowed_config_keys:
+            logger.warning("/_ministack/config: rejected key %s (not in whitelist)", key)
+            continue
+        if "." not in key:
+            continue
+
+        mod_name, var_name = key.rsplit(".", 1)
+        try:
+            mod = __import__(f"ministack.services.{mod_name}", fromlist=[var_name])
+            if key == "stepfunctions._SFN_WAIT_SCALE":
+                try:
+                    float_value = float(value)
+                except (ValueError, TypeError):
+                    logger.warning("/_ministack/config: invalid SFN_WAIT_SCALE=%r", value)
+                    continue
+                if not math.isfinite(float_value) or float_value < 0:
+                    logger.warning("/_ministack/config: invalid SFN_WAIT_SCALE=%r", value)
+                    continue
+                value = float_value
+            setattr(mod, var_name, value)
+            applied[key] = value
+        except (ImportError, AttributeError) as e:
+            logger.warning("/_ministack/config: failed to set %s: %s", key, e)
+    return 200, {"Content-Type": "application/json"}, json.dumps({"applied": applied}).encode()
+
+
+async def _handle_post_body_shortcuts(method: str, path: str, headers: dict, body: bytes, query_params: dict):
+    """Handle body-dependent routes before the generic service router."""
+    response = await _handle_cognito_body_request(method, path, headers, body, query_params)
+    if response is not None:
+        return response
+    return await _handle_admin_config_request(path, method, body)
+
+
+# ---------------------------------------------------------------------------
+# Tier 3 — Special data-plane handlers (host/path-based routing)
+# ---------------------------------------------------------------------------
+
+async def _handle_s3_control_request(path: str, method: str, body: bytes, query_params: dict, request_id: str):
+    """Handle S3 Control operations addressed via the /v20180820 path prefix."""
+    if not path.startswith(_S3_CONTROL_PREFIX):
+        return None
+
+    if path.startswith("/v20180820/tags/"):
+        raw_arn = path[len("/v20180820/tags/"):]
+        arn = unquote(raw_arn)
+        bucket_name = arn.split(":::")[-1].split("/")[0] if ":::" in arn else arn.split("/")[0]
+
+        if method == "GET":
+            tags = _get_module("s3")._bucket_tags.get(bucket_name, {})
+            tag_members = "".join(
+                f"<member><Key>{k}</Key><Value>{v}</Value></member>"
+                for k, v in tags.items()
+            )
+            xml_body = (
+                '<?xml version="1.0" encoding="UTF-8"?>'
+                '<ListTagsForResourceResult xmlns="https://awss3control.amazonaws.com/doc/2018-08-20/">'
+                f"<Tags>{tag_members}</Tags>"
+                "</ListTagsForResourceResult>"
+            ).encode()
+            return 200, {
+                "Content-Type": "application/xml",
+                "x-amzn-requestid": request_id,
+            }, xml_body
+
+        if method == "PUT":
+            try:
+                payload = json.loads(body) if body else {}
+                new_tags = {t["Key"]: t["Value"] for t in payload.get("Tags", [])}
+                existing = _get_module("s3")._bucket_tags.get(bucket_name, {})
+                existing.update(new_tags)
+                _get_module("s3")._bucket_tags[bucket_name] = existing
+            except Exception as e:
+                logger.warning("S3 Control TagResource parse error: %s", e)
+            return 204, {"x-amzn-requestid": request_id}, b""
+
+        if method == "DELETE":
+            keys_to_remove = query_params.get("tagKeys", [])
+            if isinstance(keys_to_remove, str):
+                keys_to_remove = [keys_to_remove]
+            tags = _get_module("s3")._bucket_tags.get(bucket_name, {})
+            for key in keys_to_remove:
+                tags.pop(key, None)
+            _get_module("s3")._bucket_tags[bucket_name] = tags
+            return 204, {"x-amzn-requestid": request_id}, b""
+
+        return 200, {
+            "Content-Type": "application/json",
+            "x-amzn-requestid": request_id,
+        }, b"{}"
+
+    return 200, {
+        "Content-Type": "application/json",
+        "x-amzn-requestid": request_id,
+    }, b"{}"
+
+
+async def _handle_rds_data_request(method: str, path: str, headers: dict, body: bytes, query_params: dict):
+    """Handle RDS Data API operations before generic routing."""
+    if path not in _RDS_DATA_PATHS:
+        return None
+    return await _get_module("rds_data").handle_request(method, path, headers, body, query_params)
+
+
+async def _handle_ses_v2_request(method: str, path: str, headers: dict, body: bytes, query_params: dict):
+    """Handle SES v2 REST API operations before generic routing."""
+    if not path.startswith(_SES_V2_PREFIX):
+        return None
+    return await _get_module("ses_v2").handle_request(method, path, headers, body, query_params)
+
+
+def _parse_execute_api_url(host: str, path: str) -> tuple[str, str, str] | None:
+    """Resolve an execute-api request into (api_id, stage, execute_path).
+
+    Supports three addressing modes, in priority order:
+      1. Host-based (AWS-native):   {apiId}.execute-api.<host>[:port]/{stage}/{path}
+      2. LocalStack-compat (new):   <host>[:port]/_aws/execute-api/{apiId}/{stage}/{path}
+      3. LocalStack-compat (v1):    <host>[:port]/restapis/{apiId}/{stage}/_user_request_/{path}
+
+    The path-based forms exist because (a) browsers on macOS don't resolve
+    `*.localhost` and (b) many HTTP clients can't override the `Host` header
+    (issue #401). Returns ``None`` if none of the three patterns match."""
+    m = _EXECUTE_API_RE.match(host)
+    if m:
+        api_id = m.group(1)
+        parts = path.lstrip("/").split("/", 1)
+        stage = parts[0] if parts and parts[0] else "$default"
+        execute_path = "/" + parts[1] if len(parts) > 1 else "/"
+        return api_id, stage, execute_path
+
+    # LocalStack-compat: /_aws/execute-api/{apiId}/{stage}/{path...}
+    if path.startswith("/_aws/execute-api/"):
+        rest = path[len("/_aws/execute-api/"):]
+        parts = rest.split("/", 2)
+        if len(parts) >= 2 and parts[0]:
+            api_id = parts[0]
+            stage = parts[1] if parts[1] else "$default"
+            execute_path = "/" + parts[2] if len(parts) > 2 else "/"
+            return api_id, stage, execute_path
+
+    # LocalStack v1 legacy: /restapis/{apiId}/{stage}/_user_request_/{path...}
+    if path.startswith("/restapis/"):
+        rest = path[len("/restapis/"):]
+        parts = rest.split("/", 3)
+        if len(parts) >= 3 and parts[2] == "_user_request_":
+            api_id = parts[0]
+            stage = parts[1] if parts[1] else "$default"
+            execute_path = "/" + parts[3] if len(parts) > 3 else "/"
+            return api_id, stage, execute_path
+
+    return None
+
+
+def _resolve_stage_and_path(api_id: str, tentative_stage: str, execute_path: str) -> tuple[str, str]:
+    """Pick (stage, execute_path) based on the API's configured stages.
+
+    AWS v2 HTTP / WebSocket APIs configured with the ``$default`` stage serve
+    from the root of the execute-api URL — no stage segment in the path. v1
+    REST APIs always carry the stage as the first path segment. We can't tell
+    from the URL alone which pattern applies, so we check the API's configured
+    stages and route accordingly (issue #404).
+
+    Rules:
+      - If the tentative first segment IS a configured stage name, strip it.
+      - Else if the API has a ``$default`` stage, use that and treat the
+        whole original path (including ``tentative_stage``) as ``execute_path``.
+      - Else fall through (``handle_execute`` will return "Stage not found").
+    """
+    apigw_v1 = _get_module("apigateway_v1")
+    if api_id in apigw_v1._rest_apis:
+        stages_map = apigw_v1._stages_v1.get(api_id, {})
+    else:
+        stages_map = _get_module("apigateway")._stages.get(api_id, {})
+
+    if tentative_stage in stages_map:
+        return tentative_stage, execute_path
+    if "$default" in stages_map:
+        if execute_path == "/":
+            resolved_path = "/" + tentative_stage if tentative_stage else "/"
+        else:
+            resolved_path = "/" + tentative_stage + execute_path
+        return "$default", resolved_path
+    # No match — let handle_execute report the stage miss verbatim.
+    return tentative_stage, execute_path
+
+
+async def _handle_execute_api_request(host: str, path: str, method: str, headers: dict, body: bytes, query_params: dict):
+    """Handle API Gateway execute-api data plane requests (Host-based + path-based)."""
+    parsed = _parse_execute_api_url(host, path)
+    if parsed is None:
+        return None
+    api_id, tentative_stage, execute_path = parsed
+    try:
+        # WebSocket @connections management API — /{stage}/@connections/{id}.
+        # The @connections prefix is authoritative; skip $default resolution.
+        if execute_path.startswith("/@connections/"):
+            connection_id = execute_path[len("/@connections/"):].split("/", 1)[0]
+            return await _get_module("apigateway").handle_connections_api(
+                method, api_id, tentative_stage, connection_id, body, headers
+            )
+        stage, execute_path = _resolve_stage_and_path(api_id, tentative_stage, execute_path)
+        if api_id in _get_module("apigateway_v1")._rest_apis:
+            return await _get_module("apigateway_v1").handle_execute(
+                api_id, stage, method, execute_path, headers, body, query_params
+            )
+        return await _get_module("apigateway").handle_execute(
+            api_id, stage, execute_path, method, headers, body, query_params
+        )
+    except Exception as e:
+        logger.exception("Error in execute-api dispatch: %s", e)
+        return 500, {"Content-Type": "application/json"}, json.dumps({"message": str(e)}).encode()
+
+
+def _is_potential_alb_request(host: str, path: str) -> bool:
+    """Cheap ALB gate so ordinary requests avoid loading the ALB module."""
+    hostname = host.split(":")[0].lower()
+    return path.startswith(_ALB_PATH_PREFIX) or hostname.endswith(".elb.amazonaws.com") or hostname.endswith(".alb.localhost")
+
+
+async def _handle_alb_request(host: str, path: str, method: str, headers: dict, body: bytes, query_params: dict):
+    """Handle ALB data-plane requests for host-based and /_alb-prefixed addressing."""
+    if not _is_potential_alb_request(host, path):
+        return None
+
+    alb_module = _get_module("alb")
+    load_balancer = alb_module.find_lb_for_host(host)
+    dispatch_path = path
+
+    if load_balancer is None and path.startswith(_ALB_PATH_PREFIX):
+        path_parts = path[len(_ALB_PATH_PREFIX):].split("/", 1)
+        load_balancer = alb_module._find_lb_by_name(path_parts[0])
+        if load_balancer:
+            dispatch_path = "/" + path_parts[1] if len(path_parts) > 1 else "/"
+
+    if load_balancer is None:
+        return None
+
+    alb_port = 80
+    if ":" in host:
+        try:
+            alb_port = int(host.rsplit(":", 1)[-1])
+        except ValueError:
+            pass
+
+    try:
+        return await alb_module.dispatch_request(
+            load_balancer, method, dispatch_path, headers, body, query_params, alb_port
+        )
+    except Exception as e:
+        logger.exception("Error in ALB data-plane dispatch: %s", e)
+        return 500, {"Content-Type": "application/json"}, json.dumps({"message": str(e)}).encode()
+
+
+async def _handle_s3_vhost_request(host: str, path: str, method: str, headers: dict, body: bytes, query_params: dict):
+    """Handle virtual-hosted S3 requests before generic routing."""
+    s3_vhost = _S3_VHOST_RE.match(host)
+    if not s3_vhost or _S3_VHOST_EXCLUDE_RE.search(host):
+        return None
+
+    bucket = s3_vhost.group(1)
+    if bucket in _NON_S3_VHOST_NAMES:
+        return None
+
+    vhost_path = "/" + bucket + path if path != "/" else "/" + bucket + "/"
+    try:
+        return await _get_module("s3").handle_request(method, vhost_path, headers, body, query_params)
+    except Exception as e:
+        logger.exception("Error handling virtual-hosted S3 request: %s", e)
+        from xml.sax.saxutils import escape as _xml_esc
+
+        return 500, {"Content-Type": "application/xml"}, (
+            f"<Error><Code>InternalError</Code><Message>{_xml_esc(str(e))}</Message></Error>".encode()
+        )
+
+
+def _with_data_plane_headers(response, request_id: str, include_s3_id: bool = False, wildcard_cors: bool = True):
+    """Attach common data-plane request-id headers to a response tuple.
+
+    ``wildcard_cors`` controls whether a wildcard ``Access-Control-Allow-Origin: *``
+    is added. API Gateway owns its own CORS (per-API ``corsConfiguration``,
+    issue #406) so the caller passes ``wildcard_cors=False`` there to avoid
+    clobbering the per-config value. Respects any ``Access-Control-Allow-Origin``
+    already set by the upstream handler."""
+    if response is None:
+        return None
+    status, headers, body = response
+    if wildcard_cors and "Access-Control-Allow-Origin" not in headers:
+        headers["Access-Control-Allow-Origin"] = "*"
+    headers["x-amzn-requestid"] = request_id
+    headers["x-amz-request-id"] = request_id
+    if include_s3_id:
+        headers["x-amz-id-2"] = base64.b64encode(os.urandom(48)).decode()
+    return status, headers, body
+
+
+async def _handle_special_data_plane_request(
+    method: str,
+    path: str,
+    headers: dict,
+    body: bytes,
+    query_params: dict,
+    request_id: str,
+):
+    """Handle special-case service entrypoints before the generic router."""
+    if response := await _handle_s3_control_request(path, method, body, query_params, request_id):
+        return response
+    if response := await _handle_rds_data_request(method, path, headers, body, query_params):
+        return response
+    if response := await _handle_ses_v2_request(method, path, headers, body, query_params):
+        return response
+
+    host = headers.get("host", "")
+    if response := await _handle_execute_api_request(host, path, method, headers, body, query_params):
+        return _with_data_plane_headers(response, request_id, wildcard_cors=False)
+    if response := await _handle_s3_vhost_request(host, path, method, headers, body, query_params):
+        return _with_data_plane_headers(response, request_id, include_s3_id=True)
+    if response := await _handle_alb_request(host, path, method, headers, body, query_params):
+        return _with_data_plane_headers(response, request_id)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Tier 4 — Generic service dispatch
+# ---------------------------------------------------------------------------
+
+def _routing_params(method: str, path: str, headers: dict, body: bytes, query_params: dict) -> dict:
+    """Augment routing params for unsigned form-encoded requests whose Action lives in the body."""
+    routing_params = query_params
+    if not query_params.get("Action") and headers.get("content-type", "").startswith("application/x-www-form-urlencoded"):
+        body_params = parse_qs(body.decode("utf-8", errors="replace"), keep_blank_values=True)
+        if body_params.get("Action"):
+            routing_params = {**query_params, "Action": body_params["Action"]}
+    return routing_params
+
+
+async def _dispatch_service_request(method: str, path: str, headers: dict, body: bytes, query_params: dict, request_id: str):
+    """Dispatch a request through the generic service router."""
+    routing_params = _routing_params(method, path, headers, body, query_params)
+    service = detect_service(method, path, headers, routing_params)
+    region = extract_region(headers)
+
+    logger.debug("%s %s -> service=%s region=%s", method, path, service, region)
+
+    handler = SERVICE_HANDLERS.get(service)
+    if not handler:
+        return 400, {"Content-Type": "application/json"}, json.dumps({"error": f"Unsupported service: {service}"}).encode()
+
+    try:
+        status, resp_headers, resp_body = await handler(method, path, headers, body, query_params)
+    except Exception as e:
+        logger.exception("Error handling %s request: %s", service, e)
+        return 500, {"Content-Type": "application/json"}, json.dumps({"__type": "InternalError", "message": str(e)}).encode()
+
+    resp_headers.update({
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH",
+        "Access-Control-Allow-Headers": "*",
+        "Access-Control-Expose-Headers": "*",
+        "x-amzn-requestid": request_id,
+        "x-amz-request-id": request_id,
+        "x-amz-id-2": base64.b64encode(os.urandom(48)).decode(),
+    })
+    return status, resp_headers, resp_body
+
+
+# ---------------------------------------------------------------------------
+# ASGI entry point
+# ---------------------------------------------------------------------------
+
+async def app(scope, receive, send):
+    """ASGI application entry point."""
+    if scope["type"] == "lifespan":
+        await _handle_lifespan(scope, receive, send)
+        return
+
+    if scope["type"] == "websocket":
+        # WebSocket APIs are reachable two ways:
+        #   ws://{apiId}.execute-api.{host}[:port]/{stage}[/...]           (Host-based)
+        #   ws://<host>[:port]/_aws/execute-api/{apiId}/{stage}[/...]      (LocalStack-compat path)
+        ws_headers = {}
+        for name, value in scope.get("headers", []):
+            try:
+                ws_headers[name.decode("latin-1").lower()] = value.decode("utf-8")
+            except UnicodeDecodeError:
+                ws_headers[name.decode("latin-1").lower()] = value.decode("latin-1")
+        ws_host = ws_headers.get("host", "")
+        ws_path = scope.get("path", "")
+        parsed = _parse_execute_api_url(ws_host, ws_path)
+        if not parsed:
+            msg = await receive()
+            if msg.get("type") == "websocket.connect":
+                await send({"type": "websocket.close", "code": 1008})
+            return
+        ws_api_id, _stage, _execute_path = parsed
+        try:
+            await _get_module("apigateway").handle_websocket(
+                scope, receive, send, ws_api_id, path_override=_execute_path,
+            )
+        except Exception:
+            logger.exception("Error in WebSocket dispatch")
+            try:
+                await send({"type": "websocket.close", "code": 1011})
+            except Exception:
+                pass
+        return
+
+    if scope["type"] != "http":
+        return
+
+    method = scope["method"]
+    path = scope["path"]
+    query_string = scope.get("query_string", b"").decode("utf-8")
+    query_params = parse_qs(query_string, keep_blank_values=True)
+
+    headers = {}
+    for name, value in scope.get("headers", []):
+        try:
+            headers[name.decode("latin-1").lower()] = value.decode("utf-8")
+        except UnicodeDecodeError:
+            headers[name.decode("latin-1").lower()] = value.decode("latin-1")
+
+    request_id = str(uuid.uuid4())
+
+    # If a /_ministack/reset is in flight, wait for it to finish before
+    # serving this request. The lock is uncontended in steady state
+    # (acquire/release is near-free); during a reset, new requests block
+    # until state-wipe completes so no test can observe a half-reset server.
+    if path != "/_ministack/reset":
+        async with _get_reset_lock():
+            pass
+
+    # Set per-request account ID from credentials (multi-tenancy support).
+    # If the access key is a 12-digit number, it becomes the account ID.
+    _access_key = extract_access_key_id(headers)
+    if _access_key:
+        set_request_account_id(_access_key)
+
+    # Set per-request region from SigV4 Credential scope so CFN's AWS::Region
+    # pseudo-param and ARN-building use the caller's region, not MINISTACK_REGION
+    # (issue #398). Falls back to MINISTACK_REGION env.
+    set_request_region(extract_region(headers))
+
+    if await _send_if_handled(send, await _handle_pre_body_request(method, path, headers, query_params, request_id)):
+        return
+
+    body = await _read_request_body(receive, method, headers)
+
+    if await _send_if_handled(send, await _handle_post_body_shortcuts(method, path, headers, body, query_params)):
+        return
+
+    if await _send_if_handled(send, await _handle_special_data_plane_request(
+        method, path, headers, body, query_params, request_id
+    )):
+        return
+
+    await _send_response(send, *await _dispatch_service_request(method, path, headers, body, query_params, request_id))
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle, init scripts, and server administration
+# ---------------------------------------------------------------------------
+
+async def _handle_lifespan(scope, receive, send):
+    """Handle ASGI lifespan events."""
+    while True:
+        message = await receive()
+        if message["type"] == "lifespan.startup":
+            port = _resolve_port()
+            logger.info(BANNER.format(port=port))
+            _run_init_scripts()
+            if PERSIST_STATE:
+                _load_persisted_state()
+            await send({"type": "lifespan.startup.complete"})
+            logger.info("Ready.")
+            for svc in SERVICE_HANDLERS:
+                logger.info("%s init completed.", svc.capitalize())
+            asyncio.create_task(_run_ready_scripts())
+        elif message["type"] == "lifespan.shutdown":
+            logger.info("MiniStack shutting down...")
+            if PERSIST_STATE:
+                # Only save state for modules that were actually loaded
+                _state_map = {
+                    "apigateway": "apigateway", "apigateway_v1": "apigateway_v1",
+                    "sqs": "sqs", "sns": "sns", "ssm": "ssm",
+                    "secretsmanager": "secretsmanager", "iam": "iam",
+                    "dynamodb": "dynamodb", "kms": "kms", "eventbridge": "eventbridge",
+                    "cloudwatch_logs": "cloudwatch_logs", "kinesis": "kinesis",
+                    "ec2": "ec2", "route53": "route53", "cognito": "cognito",
+                    "ecr": "ecr", "cloudwatch": "cloudwatch", "s3": "s3",
+                    "lambda": "lambda_svc", "rds": "rds", "ecs": "ecs",
+                    "elasticache": "elasticache", "appsync": "appsync",
+                    "stepfunctions": "stepfunctions", "alb": "alb",
+                    "glue": "glue", "efs": "efs", "waf": "waf",
+                    "athena": "athena", "emr": "emr", "cloudfront": "cloudfront",
+                    "codebuild": "codebuild", "acm": "acm", "firehose": "firehose",
+                    "ses": "ses", "ses_v2": "ses_v2",
+                    "servicediscovery": "servicediscovery", "s3files": "s3files",
+                    "appconfig": "appconfig", "transfer": "transfer",
+                    "scheduler": "scheduler", "autoscaling": "autoscaling",
+                    "eks": "eks",
+                }
+                save_dict = {}
+                for key, mod_name in _state_map.items():
+                    if mod_name in _loaded_modules:
+                        save_dict[key] = _loaded_modules[mod_name].get_state
+                save_all(save_dict)
+            _stop_docker_containers()
+            await send({"type": "lifespan.shutdown.complete"})
+            return
+
+
+def _stop_docker_containers():
+    """Stop all Docker containers managed by MiniStack (RDS, ECS, ElastiCache).
+    Uses container labels to find them — does not touch service state."""
+    try:
+        import docker
+        client = docker.from_env()
+    except Exception:
+        return
+    for label in ("ministack=rds", "ministack=ecs", "ministack=elasticache", "ministack=eks", "ministack=lambda"):
+        try:
+            for c in client.containers.list(filters={"label": label}):
+                try:
+                    c.stop(timeout=5)
+                    c.remove(v=True)
+                except Exception:
+                    pass
+        except Exception:
+            pass
+
+
+def _load_persisted_state():
+    """Load persisted state for services that support it."""
+    for svc_key in ("apigateway", "apigateway_v1", "servicediscovery"):
+        data = load_state(svc_key)
+        if data:
+            _get_module(svc_key).load_persisted_state(data)
+            logger.info("Loaded persisted state for %s", svc_key)
+
+
+async def _wait_for_port(port, timeout=30):
+    """Wait until the server is accepting TCP connections."""
+    import time
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            reader, writer = await asyncio.open_connection('127.0.0.1', port)
+            writer.close()
+            await writer.wait_closed()
+            return
+        except OSError:
+            await asyncio.sleep(0.1)
+    logger.warning('Server did not become ready within %ds — skipping ready.d scripts', timeout)
+
+
+async def _run_ready_scripts():
+    """Execute .sh/.py scripts from ready.d directories after the server is ready."""
+    scripts = _collect_scripts('/docker-entrypoint-initaws.d/ready.d', '/etc/localstack/init/ready.d')
+    if not scripts:
+        _ready_scripts_state.update({"status": "completed", "total": 0, "completed": 0, "failed": 0})
+        return
+    _ready_scripts_state.update({"status": "running", "total": len(scripts), "completed": 0, "failed": 0})
+    port = int(_resolve_port())
+    await _wait_for_port(port)
+    logger.info('Found %d ready script(s)', len(scripts))
+    # Provide sensible defaults so init scripts can use aws cli / boto3
+    # without requiring manual credential configuration.  Skip credential
+    # defaults when the user has mounted ~/.aws/credentials so the CLI
+    # respects their configured profile.
+    script_env = {**os.environ}
+    _creds_paths = [os.path.expanduser("~/.aws"), "/root/.aws"]
+    _custom_creds = os.environ.get("AWS_SHARED_CREDENTIALS_FILE")
+    _has_creds_file = (_custom_creds and os.path.isfile(_custom_creds)) or any(
+        os.path.isfile(os.path.join(d, "credentials")) for d in _creds_paths
+    )
+    if not _has_creds_file:
+        script_env.setdefault("AWS_ACCESS_KEY_ID", "test")
+        script_env.setdefault("AWS_SECRET_ACCESS_KEY", "test")
+    script_env.setdefault("AWS_DEFAULT_REGION", os.environ.get("MINISTACK_REGION", "us-east-1"))
+    script_env.setdefault("AWS_ENDPOINT_URL", f"http://{_MINISTACK_HOST}:{port}")
+    for script_path in scripts:
+        logger.info('Running ready script: %s', script_path)
+        script_failed = False
+        try:
+            cmd = [sys.executable, script_path] if script_path.endswith('.py') else ['sh', script_path]
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=script_env,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=300)
+            if stdout:
+                logger.info('  stdout: %s', stdout.decode('utf-8', errors='replace').rstrip())
+            if proc.returncode != 0:
+                script_failed = True
+                logger.error('Ready script %s failed (exit %d): %s', script_path, proc.returncode,
+                             stderr.decode('utf-8', errors='replace'))
+            else:
+                logger.info('Ready script %s completed successfully', script_path)
+        except asyncio.TimeoutError:
+            script_failed = True
+            logger.error('Ready script %s timed out after 300s', script_path)
+            proc.kill()
+        except Exception as e:
+            script_failed = True
+            logger.error('Failed to execute ready script %s: %s', script_path, e)
+        _ready_scripts_state["completed"] += 1
+        if script_failed:
+            _ready_scripts_state["failed"] += 1
+    _ready_scripts_state["status"] = "completed"
+
+
+def _collect_scripts(*dirs):
+    """Collect .sh/.py scripts from multiple directories, deduped by filename."""
+    seen = {}
+    for d in dirs:
+        if not os.path.isdir(d):
+            continue
+        for f in sorted(os.listdir(d)):
+            if f.endswith(('.sh', '.py')) and f not in seen:
+                seen[f] = os.path.join(d, f)
+    return [seen[f] for f in sorted(seen)]
+
+
+def _run_init_scripts():
+    """Execute .sh/.py scripts from init directories in alphabetical order."""
+    scripts = _collect_scripts('/docker-entrypoint-initaws.d', '/etc/localstack/init/boot.d')
+    if not scripts:
+        return
+    logger.info("Found %d init script(s)", len(scripts))
+    for script_path in scripts:
+        logger.info("Running init script: %s", script_path)
+        try:
+            cmd = [sys.executable, script_path] if script_path.endswith('.py') else ["sh", script_path]
+            result = subprocess.run(
+                cmd, env=os.environ,
+                capture_output=True, text=True, timeout=300,
+            )
+            if result.stdout:
+                logger.info("  stdout: %s", result.stdout.rstrip())
+            if result.returncode != 0:
+                logger.error("Init script %s failed (exit %d): %s", script_path, result.returncode, result.stderr)
+            else:
+                logger.info("Init script %s completed successfully", script_path)
+        except subprocess.TimeoutExpired:
+            logger.error("Init script %s timed out after 300s", script_path)
+        except Exception as e:
+            logger.error("Failed to execute init script %s: %s", script_path, e)
+
+
+_EXTRA_INTROSPECTION_MODULES = (
+    ("apigateway_v1", "apigateway_v1"),
+    ("ses_v2", "ses_v2"),
+)
+
+
+def _service_modules() -> list:
+    """Return list of (canonical_name, module) for every registered service module.
+
+    Uses SERVICE_REGISTRY as the source of truth so new upstream services are
+    picked up automatically. Modules are loaded lazily via _get_module.
+    """
+    seen_modules: set = set()
+    result = []
+    for svc_name, cfg in SERVICE_REGISTRY.items():
+        mod_name = cfg["module"]
+        if mod_name in seen_modules:
+            continue
+        seen_modules.add(mod_name)
+        result.append((svc_name, _get_module(mod_name)))
+    for svc_name, mod_name in _EXTRA_INTROSPECTION_MODULES:
+        if mod_name in seen_modules:
+            continue
+        seen_modules.add(mod_name)
+        result.append((svc_name, _get_module(mod_name)))
+    return result
+
+
+# Extra aliases for the /_ministack/handlers/<service> endpoint so users can
+# look up services using common short names (e.g. "lambda", "stepfunctions").
+_HANDLER_LOOKUP_ALIASES = {
+    **SERVICE_NAME_ALIASES,
+    "lambda": "lambda",
+    "iam": "iam",
+    "sts": "iam",
+    "ses-v2": "ses_v2",
+    "sesv2": "ses_v2",
+    "apigateway-v1": "apigateway_v1",
+    "apigatewayv1": "apigateway_v1",
+    "logs": "logs",
+    "emr": "elasticmapreduce",
+    "alb": "elasticloadbalancing",
+    "efs": "elasticfilesystem",
+    "cfn": "cloudformation",
+    "sf": "states",
+    "sfn": "states",
+    "cw": "monitoring",
+    "cwl": "logs",
+    "sm": "secretsmanager",
+    "eb": "events",
+    "ddb": "dynamodb",
+}
+
+
+def _resolve_service_module(service_name: str):
+    """Resolve a service name (or alias) to its (canonical_name, module) pair."""
+    name = service_name.lower().strip()
+    canonical = _HANDLER_LOOKUP_ALIASES.get(name, name)
+    for svc_name, mod in _service_modules():
+        if svc_name == canonical:
+            return svc_name, mod
+    return None, None
+
+
+def _get_all_state() -> dict:
+    """Collect summary state from every service module."""
+    state = {}
+    for name, mod in _service_modules():
+        try:
+            summary_fn = getattr(mod, "get_state_summary", None)
+            if summary_fn is None:
+                continue
+            state[name] = summary_fn()
+        except Exception as e:
+            logger.warning("get_state_summary() failed for %s: %s", name, e)
+            state[name] = {"error": str(e)}
+    return {"services": state}
+
+
+def _get_all_handlers() -> dict:
+    """Collect SUPPORTED_ACTIONS from every service module."""
+    handlers = {}
+    for name, mod in _service_modules():
+        actions = getattr(mod, "SUPPORTED_ACTIONS", None)
+        if actions is None:
+            continue
+        handlers[name] = {"actions": list(actions), "count": len(actions)}
+    return {"services": handlers}
+
+
+def _get_service_info(service_name: str) -> dict | None:
+    """Return detailed info for a single service: docstring, actions, and current state."""
+    name, mod = _resolve_service_module(service_name)
+    if mod is None:
+        return None
+    docstring = (mod.__doc__ or "").strip()
+    actions = getattr(mod, "SUPPORTED_ACTIONS", [])
+    try:
+        summary_fn = getattr(mod, "get_state_summary", None)
+        state = summary_fn() if summary_fn else {}
+    except Exception:
+        state = {}
+    return {
+        "service": name,
+        "description": docstring,
+        "supported_actions": actions,
+        "action_count": len(actions),
+        "state": state,
+    }
+
+
+def _reset_all_state():
+    """Wipe all in-memory state across every service module, and persisted files if enabled."""
+
+    from ministack.core.persistence import PERSIST_STATE, STATE_DIR
+
+    # Stateful modules that don't have a routing entry in SERVICE_REGISTRY but
+    # still need reset() — REST API v1 (served via the apigateway module),
+    # SES v2 (served via the ses module), and EventBridge Pipes (CFN-only
+    # provisioner with a background poller thread that reset() must stop).
+    _extra_reset_modules = ("apigateway_v1", "ses_v2", "pipes")
+
+    module_names = {cfg["module"] for cfg in SERVICE_REGISTRY.values()}
+    module_names.update(_extra_reset_modules)
+
+    for mod_name in module_names:
+        if mod_name in _loaded_modules:
+            mod = _loaded_modules[mod_name]
+            try:
+                mod.reset()
+            except Exception as e:
+                logger.warning("reset() failed for %s: %s", mod_name, e)
+
+    S3_DATA_DIR = os.environ.get("S3_DATA_DIR", "/tmp/ministack-data/s3")
+    S3_PERSIST = os.environ.get("S3_PERSIST", "0") == "1"
+
+    # Wipe persisted files so a subsequent restart doesn't reload old state
+    if PERSIST_STATE and os.path.isdir(STATE_DIR):
+        for fname in os.listdir(STATE_DIR):
+            if fname.endswith(".json"):
+                try:
+                    os.remove(os.path.join(STATE_DIR, fname))
+                except Exception as e:
+                    logger.warning("reset: failed to remove %s: %s", fname, e)
+        logger.info("Wiped persisted state files in %s", STATE_DIR)
+
+    if S3_PERSIST and os.path.isdir(S3_DATA_DIR):
+        for entry in os.listdir(S3_DATA_DIR):
+            entry_path = os.path.join(S3_DATA_DIR, entry)
+            try:
+                if os.path.isdir(entry_path):
+                    shutil.rmtree(entry_path)
+                else:
+                    os.remove(entry_path)
+            except Exception as e:
+                logger.warning("reset: failed to remove S3 data %s: %s", entry, e)
+        logger.info("Wiped S3 persisted data in %s", S3_DATA_DIR)
+
+    logger.info("State reset complete")
+
+
+def _pid_file(port: int) -> str:
+    return os.path.join(tempfile.gettempdir(), f"ministack-{port}.pid")
+
+
+def main():
+    from hypercorn.config import Config as HypercornConfig
+    from hypercorn.asyncio import serve as hypercorn_serve
+
+    parser = argparse.ArgumentParser(description="MiniStack — Local AWS Service Emulator")
+    parser.add_argument("-d", "--detach", action="store_true", help="Run in the background (detached mode)")
+    parser.add_argument("--stop", action="store_true", help="Stop a detached MiniStack server")
+    args = parser.parse_args()
+
+    port = int(_resolve_port())
+
+    if args.stop:
+        pf = _pid_file(port)
+        if not os.path.exists(pf):
+            print(f"No MiniStack PID file found for port {port}. Is it running?")
+            raise SystemExit(1)
+        with open(pf) as f:
+            pid = int(f.read().strip())
+        try:
+            os.kill(pid, signal.SIGTERM)
+            print(f"MiniStack (PID {pid}) on port {port} stopped.")
+        except ProcessLookupError:
+            print(f"MiniStack (PID {pid}) was not running. Cleaning up PID file.")
+        os.remove(pf)
+        return
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        if s.connect_ex(("127.0.0.1", port)) == 0:
+            print(f"ERROR: Port {port} is already in use. Is MiniStack already running?\n"
+                  f"  Stop it with: ministack --stop\n"
+                  f"  Or use a different port: GATEWAY_PORT=4567 ministack")
+            raise SystemExit(1)
+
+    if args.detach:
+        log_file = os.path.join(os.environ.get("TMPDIR", "/tmp"), f"ministack-{port}.log")
+        # Keep a reference to the log file handle — Popen inherits the fd so
+        # closing it here would break child process logging.  The handle is
+        # intentionally kept open for the lifetime of this (short-lived) parent
+        # process; the OS reclaims it when the parent exits.
+        log_fh = open(log_file, "w")
+        proc = subprocess.Popen(
+            [sys.executable, "-m", "hypercorn", "ministack.app:app",
+             "--bind", f"0.0.0.0:{port}",
+             "--log-level", LOG_LEVEL.upper(),
+             "--keep-alive", "75"],
+            stdout=log_fh,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+        pf = _pid_file(port)
+        with open(pf, "w") as f:
+            f.write(str(proc.pid))
+        print(f"MiniStack started in background (PID {proc.pid}) on port {port}.")
+        print(f"  Logs: {log_file}")
+        print(f"  Stop: ministack --stop")
+        return
+
+    # Foreground — write PID file and clean up on exit
+    pf = _pid_file(port)
+    with open(pf, "w") as f:
+        f.write(str(os.getpid()))
+
+    def _cleanup(*_):
+        try:
+            os.remove(pf)
+        except OSError:
+            pass
+
+    signal.signal(signal.SIGTERM, lambda *_: (_cleanup(), sys.exit(0)))
+    try:
+        # Suppress health-check access logs at INFO level (reported by @McDoit).
+        # Visible when LOG_LEVEL=DEBUG.
+        class _HealthLogFilter(logging.Filter):
+            def filter(self, record):
+                if LOG_LEVEL == "DEBUG":
+                    return True
+                return not any(p in record.getMessage() for p in _HEALTH_PATHS)
+
+        logging.getLogger("hypercorn.access").addFilter(_HealthLogFilter())
+
+        config = HypercornConfig()
+        config.bind = [f"0.0.0.0:{port}"]
+        config.keep_alive_timeout = 75
+        config.loglevel = LOG_LEVEL.upper()
+
+        asyncio.run(hypercorn_serve(app, config))
+    finally:
+        _cleanup()
+
+
+if __name__ == "__main__":
+    main()

aws_infra/ministack/core/hypercorn_compat.py

@@ -0,0 +1,43 @@
+"""Compatibility shims for the hypercorn/h11 stack.
+
+h11 serialises ``InformationalResponse`` with an empty reason phrase by
+default, producing ``HTTP/1.1 100 \\r\\n`` on the wire. boto3 < 1.40's
+bundled urllib3 parses this strictly and aborts with ``BadStatusLine``
+when the client is waiting on ``Expect: 100-continue`` (e.g. S3
+``upload_file``). Injecting the standard reason phrase makes the wire
+output ``HTTP/1.1 100 Continue\\r\\n``, which every SDK version accepts.
+
+Issue: https://github.com/ministackorg/ministack/issues/389
+Remove this module if h11 ever ships a default reason upstream.
+"""
+
+import h11
+
+# RFC 9110 § 15.2 informational response reason phrases.
+_DEFAULT_REASONS = {
+    100: b"Continue",
+    101: b"Switching Protocols",
+    102: b"Processing",
+    103: b"Early Hints",
+}
+
+_original_post_init = h11.InformationalResponse.__post_init__
+
+
+def _patched_post_init(self) -> None:
+    _original_post_init(self)
+    if not self.reason:
+        default = _DEFAULT_REASONS.get(self.status_code)
+        if default is not None:
+            # Frozen dataclass — bypass normal attribute protection.
+            object.__setattr__(self, "reason", default)
+
+
+_patched_post_init._ministack_patched = True  # type: ignore[attr-defined]
+
+
+def install() -> None:
+    """Install the reason-phrase patch. Idempotent."""
+    if getattr(h11.InformationalResponse.__post_init__, "_ministack_patched", False):
+        return
+    h11.InformationalResponse.__post_init__ = _patched_post_init

aws_infra/ministack/core/lambda_runtime.py

@@ -0,0 +1,629 @@
+"""
+Lambda warm/cold start worker pool.
+Each function gets a persistent worker process (Python or Node.js) that imports
+the handler once (cold start) and then handles subsequent invocations without
+re-importing (warm).
+"""
+
+import base64
+import json
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import queue
+import tempfile
+import threading
+import time
+import zipfile
+import queue
+
+logger = logging.getLogger("lambda_runtime")
+
+_workers: dict = {}
+_lock = threading.Lock()
+
+# ---------------------------------------------------------------------------
+# Python worker script (runs inside a persistent subprocess)
+# ---------------------------------------------------------------------------
+
+_PYTHON_WORKER_SCRIPT = '''
+import sys, json, importlib, traceback, os
+
+def run():
+    # Redirect print() to stderr so stdout stays clean for JSON-line protocol
+    _real_stdout = sys.stdout
+    sys.stdout = sys.stderr
+
+    init = json.loads(sys.stdin.readline())
+    code_dir = init["code_dir"]
+    module_name = init["module"]
+    handler_name = init["handler"]
+    env = init.get("env", {})
+    os.environ.update(env)
+    sys.path.insert(0, code_dir)
+    for _ld in filter(None, os.environ.get("_LAMBDA_LAYERS_DIRS", "").split(os.pathsep)):
+        _py = os.path.join(_ld, "python")
+        if os.path.isdir(_py):
+            sys.path.insert(0, _py)
+        sys.path.insert(0, _ld)
+    try:
+        mod = importlib.import_module(module_name)
+        handler_fn = getattr(mod, handler_name)
+        _real_stdout.write(json.dumps({"status": "ready", "cold": True}) + "\\n")
+        _real_stdout.flush()
+    except Exception as e:
+        _real_stdout.write(json.dumps({"status": "error", "error": str(e)}) + "\\n")
+        _real_stdout.flush()
+        return
+
+    while True:
+        line = sys.stdin.readline()
+        if not line:
+            break
+        event = json.loads(line)
+        context = type("Context", (), {
+            "function_name": init.get("function_name", ""),
+            "memory_limit_in_mb": init.get("memory", 128),
+            "invoked_function_arn": init.get("arn", ""),
+            "aws_request_id": event.pop("_request_id", ""),
+        })()
+        try:
+            result = handler_fn(event, context)
+            _real_stdout.write(json.dumps({"status": "ok", "result": result}) + "\\n")
+        except Exception as e:
+            _real_stdout.write(json.dumps({"status": "error", "error": str(e), "trace": traceback.format_exc()}) + "\\n")
+        _real_stdout.flush()
+
+run()
+'''
+
+# ---------------------------------------------------------------------------
+# Node.js worker script (runs inside a persistent subprocess)
+# ---------------------------------------------------------------------------
+
+_NODEJS_WORKER_SCRIPT = r'''
+const readline = require("readline");
+const path = require("path");
+const http = require("http");
+const https = require("https");
+const url = require("url");
+
+// Redirect stdout to stderr so stdout stays clean for JSON-line protocol
+const _realStdoutWrite = process.stdout.write.bind(process.stdout);
+const _stderrWrite = process.stderr.write.bind(process.stderr);
+process.stdout.write = function(chunk, encoding, callback) {
+  return _stderrWrite(chunk, encoding, callback);
+};
+
+function patchAwsSdk() {
+  const endpoint = process.env.AWS_ENDPOINT_URL
+    || process.env.LOCALSTACK_ENDPOINT
+    || process.env.MINISTACK_ENDPOINT;
+  if (!endpoint) return;
+
+  const parsed = url.parse(endpoint);
+  const msHost = parsed.hostname;
+  const msPort = parseInt(parsed.port || "4566", 10);
+
+  // Patch aws-sdk v2 global config
+  try {
+    const AWS = require("aws-sdk");
+    AWS.config.update({
+      endpoint: endpoint,
+      region: process.env.AWS_REGION || process.env.FBT_AWS_REGION || "us-east-1",
+      s3ForcePathStyle: true,
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID || "test",
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || "test",
+    });
+    const origHandle = AWS.NodeHttpClient.prototype.handleRequest;
+    AWS.NodeHttpClient.prototype.handleRequest = function(req, opts, cb, errCb) {
+      if (req.endpoint && req.endpoint.protocol === "http:") {
+        if (opts && opts.agent instanceof https.Agent) {
+          opts = Object.assign({}, opts, { agent: new http.Agent({ keepAlive: true }) });
+        }
+      }
+      return origHandle.call(this, req, opts, cb, errCb);
+    };
+  } catch (_) {}
+
+  // Patch https.request for bundled SDK
+  const origHttpsReq = https.request;
+  https.request = function(options, callback) {
+    if (typeof options === "string") options = url.parse(options);
+    else if (options instanceof url.URL) options = url.parse(options.toString());
+    else options = Object.assign({}, options);
+
+    const host = options.hostname || options.host || "";
+    if (host.endsWith(".amazonaws.com") || host.endsWith(".amazonaws.com.cn")) {
+      options.protocol = "http:";
+      options.hostname = msHost;
+      options.host = msHost + ":" + msPort;
+      options.port = msPort;
+      options.path = options.path || "/";
+      if (options.agent instanceof https.Agent) {
+        options.agent = new http.Agent({ keepAlive: true });
+      } else if (options.agent === undefined) {
+        options.agent = new http.Agent({ keepAlive: true });
+      }
+      delete options._defaultAgent;
+      return http.request(options, callback);
+    }
+
+    // Downgrade ES HTTPS to HTTP for local Elasticsearch
+    var esHost = process.env.ES_ENDPOINT ? process.env.ES_ENDPOINT.split(":")[0] : null;
+    if (esHost && (host === esHost || host.startsWith(esHost + ":"))) {
+      var esPort = process.env.ES_ENDPOINT ? parseInt(process.env.ES_ENDPOINT.split(":")[1] || "9200", 10) : 9200;
+      options.protocol = "http:";
+      options.hostname = esHost;
+      options.host = esHost + ":" + esPort;
+      options.port = esPort;
+      options.rejectUnauthorized = false;
+      if (options.agent instanceof https.Agent) {
+        options.agent = new http.Agent({ keepAlive: true });
+      } else if (options.agent === undefined) {
+        options.agent = new http.Agent({ keepAlive: true });
+      }
+      delete options._defaultAgent;
+      return http.request(options, callback);
+    }
+
+    return origHttpsReq.call(https, options, callback);
+  };
+  https.get = function(options, callback) {
+    var req = https.request(options, callback);
+    req.end();
+    return req;
+  };
+}
+
+let handlerFn = null;
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+let lineNum = 0;
+
+rl.on("line", async (line) => {
+  lineNum++;
+  try {
+    const msg = JSON.parse(line);
+
+    // First line is the init payload
+    if (lineNum === 1) {
+      const { code_dir, module: modPath, handler: handlerName, env } = msg;
+      Object.assign(process.env, env || {});
+      process.env.LAMBDA_TASK_ROOT = code_dir;
+      process.env.AWS_LAMBDA_FUNCTION_NAME = msg.function_name || process.env.AWS_LAMBDA_FUNCTION_NAME || "";
+      process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE = String(msg.memory || process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE || "128");
+      process.env._LAMBDA_FUNCTION_ARN = msg.arn || process.env._LAMBDA_FUNCTION_ARN || "";
+      patchAwsSdk();
+      try {
+        const fullPath = path.resolve(code_dir, modPath);
+        let mod;
+        let resolvedPath;
+        try {
+          resolvedPath = require.resolve(fullPath);
+        } catch (resolveErr) {
+          if (resolveErr.code === "MODULE_NOT_FOUND") {
+            const fs = require("fs");
+            const mjsPath = fullPath + ".mjs";
+            if (fs.existsSync(mjsPath)) {
+              resolvedPath = mjsPath;
+            } else {
+              throw resolveErr;
+            }
+          } else {
+            throw resolveErr;
+          }
+        }
+        try {
+          mod = require(resolvedPath);
+        } catch (reqErr) {
+          if (reqErr.code === "ERR_REQUIRE_ESM") {
+            const { pathToFileURL } = require("url");
+            mod = await import(pathToFileURL(resolvedPath).href);
+          } else {
+            throw reqErr;
+          }
+        }
+        handlerFn = mod[handlerName] || (mod.default && mod.default[handlerName]) || mod.default;
+        if (typeof handlerFn !== "function") {
+          _realStdoutWrite(JSON.stringify({
+            status: "error",
+            error: `Handler ${handlerName} is not a function in ${modPath}`
+          }) + "\n");
+          return;
+        }
+        _realStdoutWrite(JSON.stringify({ status: "ready", cold: true }) + "\n");
+      } catch (e) {
+        _realStdoutWrite(JSON.stringify({
+          status: "error", error: e.message
+        }) + "\n");
+      }
+      return;
+    }
+
+    // Subsequent lines are event invocations
+    const event = msg;
+    const context = {
+      functionName: event._function_name || "",
+      memoryLimitInMB: event._memory || "128",
+      invokedFunctionArn: event._arn || "",
+      awsRequestId: event._request_id || "",
+      getRemainingTimeInMillis: () => 300000,
+      done: () => {},
+      succeed: () => {},
+      fail: () => {},
+    };
+    delete event._request_id;
+    delete event._function_name;
+    delete event._memory;
+    delete event._arn;
+
+    try {
+      let settled = false;
+      const settle = (err, res) => {
+        if (settled) return;
+        settled = true;
+        if (err) {
+          _realStdoutWrite(JSON.stringify({
+            status: "error", error: String(err.message || err), trace: err.stack || ""
+          }) + "\n");
+        } else {
+          _realStdoutWrite(JSON.stringify({ status: "ok", result: res }) + "\n");
+        }
+      };
+      const callback = (err, res) => settle(err, res);
+      context.done = (err, res) => settle(err, res);
+      context.succeed = (res) => settle(null, res);
+      context.fail = (err) => settle(err || new Error("fail"));
+
+      const result = handlerFn(event, context, callback);
+      if (result && typeof result.then === "function") {
+        // Async/Promise handler
+        result.then(res => settle(null, res), err => settle(err));
+      } else if (handlerFn.length < 3 && result !== undefined) {
+        // Sync handler that doesn't accept callback and returned a value
+        settle(null, result);
+      }
+      // If handler accepts callback (arity >= 3) or returned undefined,
+      // we wait for callback/context.done/context.succeed/context.fail
+    } catch (e) {
+      _realStdoutWrite(JSON.stringify({
+        status: "error", error: e.message, trace: e.stack
+      }) + "\n");
+    }
+  } catch (e) {
+    _realStdoutWrite(JSON.stringify({
+      status: "error", error: "JSON parse error: " + e.message
+    }) + "\n");
+  }
+});
+'''
+
+
+def _detect_runtime_binary(runtime: str) -> tuple[str, str]:
+    """Return (binary, worker_script_content) for the given Lambda runtime string."""
+    if runtime.startswith("python"):
+        return sys.executable, _PYTHON_WORKER_SCRIPT
+    if runtime.startswith("nodejs"):
+        return "node", _NODEJS_WORKER_SCRIPT
+    return "", ""
+
+
+def _worker_script_extension(runtime: str) -> str:
+    if runtime.startswith("python"):
+        return ".py"
+    if runtime.startswith("nodejs"):
+        return ".js"
+    return ".py"
+
+
+class Worker:
+    def __init__(self, func_name: str, config: dict, code_zip: bytes):
+        self.func_name = func_name
+        self.config = config
+        self.code_zip = code_zip
+        self._proc = None
+        self._tmpdir = None
+        self._lock = threading.Lock()
+        self._cold = True
+        self._start_time = None
+        self._stderr_queue: queue.Queue = queue.Queue()
+        self._stderr_thread: threading.Thread | None = None
+
+    def _read_stderr(self):
+        """Background daemon thread: continuously drain stderr into queue."""
+        try:
+            for line in self._proc.stderr:
+                self._stderr_queue.put(line.rstrip("\n"))
+        except Exception:
+            pass
+
+    def _spawn(self):
+        """Extract zip and start worker process."""
+        self._tmpdir = tempfile.mkdtemp(prefix=f"ministack-lambda-{self.func_name}-")
+        runtime = self.config.get("Runtime", "python3.12")
+        binary, worker_script = _detect_runtime_binary(runtime)
+        if not binary:
+            raise RuntimeError(f"Unsupported runtime: {runtime}")
+
+        ext = _worker_script_extension(runtime)
+        worker_path = os.path.join(self._tmpdir, f"_worker{ext}")
+        with open(worker_path, "w") as f:
+            f.write(worker_script)
+
+        code_dir = os.path.join(self._tmpdir, "code")
+        os.makedirs(code_dir)
+        with open(os.path.join(self._tmpdir, "code.zip"), "wb") as f:
+            f.write(self.code_zip)
+        with zipfile.ZipFile(os.path.join(self._tmpdir, "code.zip")) as zf:
+            zf.extractall(code_dir)
+
+        # Extract Lambda Layers and build search paths for the worker process.
+        # This mirrors the layer handling in lambda_svc._execute_function_local().
+        layers_dirs: list[str] = []
+        layer_refs = self.config.get("Layers", [])
+        if layer_refs:
+            from ministack.services.lambda_svc import _resolve_layer_zip
+        for layer_ref in layer_refs:
+            layer_arn = layer_ref if isinstance(layer_ref, str) else layer_ref.get("Arn", "")
+            if not layer_arn:
+                continue
+            try:
+                layer_data = _resolve_layer_zip(layer_arn)
+                if layer_data:
+                    layer_dir = os.path.join(self._tmpdir, f"layer_{len(layers_dirs)}")
+                    os.makedirs(layer_dir)
+                    lzip = os.path.join(self._tmpdir, f"layer_{len(layers_dirs)}.zip")
+                    try:
+                        with open(lzip, "wb") as lf:
+                            lf.write(layer_data)
+                        with zipfile.ZipFile(lzip) as lzf:
+                            # Validate paths to prevent zip-slip attacks
+                            for member in lzf.namelist():
+                                resolved = os.path.realpath(os.path.join(layer_dir, member))
+                                if not resolved.startswith(os.path.realpath(layer_dir) + os.sep) and resolved != os.path.realpath(layer_dir):
+                                    raise RuntimeError(f"Zip entry escapes target dir: {member}")
+                            lzf.extractall(layer_dir)
+                    except (OSError, zipfile.BadZipFile, zipfile.LargeFileError) as e:
+                        logger.error("Failed to extract layer %s", layer_arn, exc_info=True)
+                        raise RuntimeError(f"Failed to extract layer {layer_arn}") from e
+                    layers_dirs.append(layer_dir)
+            except RuntimeError:
+                raise
+            except Exception as e:
+                logger.error("Unexpected error resolving layer %s: %s", layer_arn, e)
+                raise RuntimeError(f"Failed to resolve layer {layer_arn}") from e
+
+        # Symlink layer node_modules packages into the code directory so that
+        # Node.js ESM import() can resolve them via ancestor-tree lookup.
+        # ESM does not use NODE_PATH, so packages must be physically reachable
+        # from the handler file's directory tree.
+        if layers_dirs and runtime.startswith("nodejs"):
+            code_nm = os.path.join(code_dir, "node_modules")
+            os.makedirs(code_nm, exist_ok=True)
+            for ld in layers_dirs:
+                layer_nm = os.path.join(ld, "nodejs", "node_modules")
+                if os.path.isdir(layer_nm):
+                    for pkg in os.listdir(layer_nm):
+                        src = os.path.join(layer_nm, pkg)
+                        dst = os.path.join(code_nm, pkg)
+                        if not os.path.exists(dst):
+                            os.symlink(src, dst)
+
+        handler = self.config.get("Handler", "index.handler")
+        module_name, handler_name = handler.rsplit(".", 1)
+        env_vars = self.config.get("Environment", {}).get("Variables", {})
+        spawn_env = {**os.environ, **env_vars}
+        # Restore the internal endpoint URL so Lambda SDK calls reach
+        # this MiniStack instance, not a host-mapped port that may be
+        # unreachable from inside the container.
+        for key in ("AWS_ENDPOINT_URL", "LOCALSTACK_HOSTNAME"):
+            if key in os.environ:
+                spawn_env[key] = os.environ[key]
+        spawn_env.setdefault("LAMBDA_TASK_ROOT", code_dir)
+        spawn_env.setdefault("AWS_LAMBDA_FUNCTION_NAME", self.config.get("FunctionName", ""))
+        spawn_env.setdefault("AWS_LAMBDA_FUNCTION_MEMORY_SIZE", str(self.config.get("MemorySize", 128)))
+        spawn_env.setdefault("_LAMBDA_FUNCTION_ARN", self.config.get("FunctionArn", ""))
+
+        # Set layer paths so worker runtimes can find packages from extracted layers.
+        # _LAMBDA_LAYERS_DIRS is consumed by the Python worker; Node.js layer resolution
+        # is handled via NODE_PATH populated from each layer's nodejs paths below.
+        if layers_dirs:
+            spawn_env["_LAMBDA_LAYERS_DIRS"] = os.pathsep.join(layers_dirs)
+            # NODE_PATH is used by the CJS require() resolver in Node.js workers.
+            # ESM import() does not use NODE_PATH — layer packages are instead
+            # symlinked into code/node_modules/ above for ancestor-tree resolution.
+            node_paths = []
+            for ld in layers_dirs:
+                nm = os.path.join(ld, "nodejs", "node_modules")
+                if os.path.isdir(nm):
+                    node_paths.append(nm)
+                nj = os.path.join(ld, "nodejs")
+                if os.path.isdir(nj):
+                    node_paths.append(nj)
+            if node_paths:
+                existing = spawn_env.get("NODE_PATH")
+                if existing:
+                    spawn_env["NODE_PATH"] = os.pathsep.join(node_paths + [existing])
+                else:
+                    spawn_env["NODE_PATH"] = os.pathsep.join(node_paths)
+
+        self._proc = subprocess.Popen(
+            [binary, worker_path],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+            env=spawn_env,
+        )
+
+        self._stderr_queue = queue.Queue()
+        self._stderr_thread = threading.Thread(
+            target=self._read_stderr, daemon=True, name=f"stderr-{self.func_name}"
+        )
+        self._stderr_thread.start()
+
+        init = {
+            "code_dir": code_dir,
+            "module": module_name,
+            "handler": handler_name,
+            "env": env_vars,
+            "function_name": self.config.get("FunctionName", ""),
+            "memory": self.config.get("MemorySize", 128),
+            "arn": self.config.get("FunctionArn", ""),
+        }
+        self._proc.stdin.write(json.dumps(init) + "\n")
+        self._proc.stdin.flush()
+
+        # Read init response, skipping non-JSON lines (stray console output from modules)
+        response = None
+        for _ in range(200):
+            response_line = self._proc.stdout.readline()
+            if not response_line:
+                stderr_out = ""
+                try:
+                    stderr_out = self._proc.stderr.read(4096)
+                except Exception:
+                    pass
+                raise RuntimeError(f"Worker process exited immediately. stderr: {stderr_out}")
+            response_line = response_line.strip()
+            if not response_line or not response_line.startswith("{"):
+                continue
+            try:
+                response = json.loads(response_line)
+                break
+            except json.JSONDecodeError:
+                continue
+        if response is None:
+            raise RuntimeError("No JSON init response from worker")
+        if response.get("status") != "ready":
+            raise RuntimeError(f"Worker init failed: {response.get('error')}")
+
+        self._start_time = time.time()
+        logger.info("Lambda worker spawned for %s (%s, cold start)", self.func_name, runtime)
+
+    def _drain_stderr(self) -> str:
+        """Collect all currently available stderr lines (non-blocking)."""
+        lines = []
+        try:
+            while True:
+                lines.append(self._stderr_queue.get_nowait())
+        except queue.Empty:
+            pass
+        return "\n".join(lines)
+
+    def invoke(self, event: dict, request_id: str) -> dict:
+        with self._lock:
+            cold = self._cold
+
+            if self._proc is None or self._proc.poll() is not None:
+                self._spawn()
+                cold = True
+                self._cold = False
+            else:
+                cold = False
+
+            timeout = self.config.get("Timeout", 30)
+            event["_request_id"] = request_id
+            result_box: list = []
+
+            def _read_response():
+                try:
+                    self._proc.stdin.write(json.dumps(event) + "\n")
+                    self._proc.stdin.flush()
+                    for _ in range(200):
+                        response_line = self._proc.stdout.readline()
+                        if not response_line:
+                            result_box.append({"status": "error", "error": "Worker process died"})
+                            return
+                        response_line = response_line.strip()
+                        if not response_line:
+                            continue
+                        if response_line.startswith("{"):
+                            try:
+                                response = json.loads(response_line)
+                                result_box.append(response)
+                                return
+                            except json.JSONDecodeError:
+                                continue
+                    result_box.append({"status": "error", "error": "No JSON response from worker after 200 lines"})
+                except Exception as e:
+                    result_box.append({"status": "error", "error": str(e)})
+
+            reader = threading.Thread(target=_read_response, daemon=True)
+            reader.start()
+            reader.join(timeout=timeout)
+
+            if reader.is_alive():
+                # Timeout — kill the worker process
+                logger.warning("Lambda %s timed out after %ds — killing worker", self.func_name, timeout)
+                if self._proc:
+                    self._proc.kill()
+                self._proc = None
+                return {
+                    "status": "error",
+                    "error": f"Task timed out after {timeout}.00 seconds",
+                    "cold_start": cold,
+                    "log": self._drain_stderr(),
+                }
+
+            if not result_box:
+                self._proc = None
+                return {"status": "error", "error": "Worker returned no response", "cold_start": cold}
+
+            response = result_box[0]
+            if response.get("status") == "error":
+                self._proc = None
+            response["cold_start"] = cold
+            response["log"] = self._drain_stderr()
+            return response
+
+    def kill(self):
+        if self._proc and self._proc.poll() is None:
+            self._proc.terminate()
+            self._proc = None
+        if self._tmpdir and os.path.exists(self._tmpdir):
+            shutil.rmtree(self._tmpdir, ignore_errors=True)
+
+
+def get_or_create_worker(func_name: str, config: dict, code_zip: bytes,
+                         qualifier: str = "$LATEST") -> Worker:
+    key = f"{func_name}:{qualifier}"
+    with _lock:
+        worker = _workers.get(key)
+        if worker is not None:
+            return worker
+        worker = Worker(func_name, config, code_zip)
+        _workers[key] = worker
+        return worker
+
+
+def invalidate_worker(func_name: str, qualifier: str = None):
+    """Kill and remove workers for a function.
+
+    If qualifier is provided, only kill that specific version/alias worker.
+    Otherwise kill all workers for the function (used on delete).
+    """
+    with _lock:
+        if qualifier is not None:
+            key = f"{func_name}:{qualifier}"
+            worker = _workers.pop(key, None)
+            if worker:
+                worker.kill()
+        else:
+            to_remove = [k for k in _workers if k.startswith(f"{func_name}:")]
+            for k in to_remove:
+                worker = _workers.pop(k, None)
+                if worker:
+                    worker.kill()
+
+
+def reset():
+    """Terminate all warm workers, clean up temp dirs, and clear the pool."""
+    with _lock:
+        for worker in list(_workers.values()):
+            worker.kill()
+        _workers.clear()

aws_infra/ministack/core/persistence.py

@@ -0,0 +1,94 @@
+"""
+State persistence for MiniStack services.
+When PERSIST_STATE=1, service state is saved to STATE_DIR on shutdown
+and reloaded on startup.
+"""
+
+import ast
+import json
+import logging
+import os
+import tempfile
+
+from ministack.core.responses import AccountScopedDict
+
+logger = logging.getLogger("persistence")
+
+PERSIST_STATE = os.environ.get("PERSIST_STATE", "0") == "1"
+STATE_DIR = os.environ.get("STATE_DIR", "/tmp/ministack-state")
+
+
+def _json_default(obj):
+    """JSON encoder fallback for AccountScopedDict and tuple keys."""
+    if isinstance(obj, AccountScopedDict):
+        # Serialize all accounts' data with string keys
+        result = {}
+        for k, v in obj._data.items():
+            # k is (account_id, original_key) tuple
+            result[f"{k[0]}\x00{k[1]!r}"] = v
+        return {"__scoped__": True, "data": result}
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def _json_object_hook(obj):
+    """JSON decoder hook to restore AccountScopedDict from serialized form."""
+    if obj.get("__scoped__"):
+        asd = AccountScopedDict()
+        for k, v in obj["data"].items():
+            account_id, key_repr = k.split("\x00", 1)
+            # Restore the original key (was serialized with repr())
+            try:
+                original_key = ast.literal_eval(key_repr)
+            except (ValueError, SyntaxError):
+                original_key = key_repr
+            asd._data[(account_id, original_key)] = v
+        return asd
+    return obj
+
+
+def save_state(service: str, data: dict) -> None:
+    if not PERSIST_STATE:
+        return
+    try:
+        os.makedirs(STATE_DIR, exist_ok=True)
+        path = os.path.join(STATE_DIR, f"{service}.json")
+        tmp = path + ".tmp"
+        try:
+            with open(tmp, "w") as f:
+                json.dump(data, f, default=_json_default)
+            os.replace(tmp, path)
+        except BaseException:
+            # Clean up temp file on any failure to avoid stale partial writes
+            try:
+                os.remove(tmp)
+            except OSError:
+                pass
+            raise
+        logger.info("Persistence: saved %s state to %s", service, path)
+    except Exception as e:
+        logger.error("Persistence: failed to save %s: %s", service, e)
+
+
+def load_state(service: str) -> dict | None:
+    if not PERSIST_STATE:
+        return None
+    path = os.path.join(STATE_DIR, f"{service}.json")
+    if not os.path.exists(path):
+        return None
+    try:
+        with open(path) as f:
+            data = json.load(f, object_hook=_json_object_hook)
+        logger.info("Persistence: loaded %s state from %s", service, path)
+        return data
+    except (json.JSONDecodeError, OSError) as e:
+        logger.error("Persistence: failed to load %s: %s", service, e)
+        return None
+
+
+def save_all(services: dict) -> None:
+    """Save all service states. services = {name: get_state_fn}"""
+    for name, get_state in services.items():
+        try:
+            save_state(name, get_state())
+        except Exception as e:
+            logger.error("Persistence: error getting state for %s: %s", name, e)

aws_infra/ministack/core/responses.py

@@ -0,0 +1,266 @@
+"""
+AWS Response formatting utilities.
+Handles XML responses (S3, SQS, SNS, IAM, STS, CloudWatch) and
+JSON responses (DynamoDB, Lambda, SecretsManager, CloudWatch Logs).
+"""
+
+import contextvars
+import hashlib
+import json
+import os
+import re
+import uuid
+from datetime import datetime, timezone
+from xml.etree.ElementTree import Element, SubElement, tostring
+
+# Request-scoped account ID for multi-tenancy.
+# Set per-request in app.py from the Authorization header.
+_request_account_id: contextvars.ContextVar[str] = contextvars.ContextVar(
+    "_request_account_id",
+    default=os.environ.get("MINISTACK_ACCOUNT_ID", "000000000000"),
+)
+
+_12_DIGIT_RE = re.compile(r"^\d{12}$")
+
+
+def set_request_account_id(access_key_id: str) -> None:
+    """Set the account ID for the current request from the access key.
+    If the access key is a 12-digit number, use it as the account ID.
+    Otherwise fall back to the MINISTACK_ACCOUNT_ID env var or 000000000000."""
+    if access_key_id and _12_DIGIT_RE.match(access_key_id):
+        _request_account_id.set(access_key_id)
+    else:
+        _request_account_id.set(
+            os.environ.get("MINISTACK_ACCOUNT_ID", "000000000000")
+        )
+
+
+def get_account_id() -> str:
+    """Return the account ID for the current request."""
+    return _request_account_id.get()
+
+
+# Request-scoped region. Set per-request in app.py from the SigV4 Authorization
+# header's Credential scope. Fixes #398 (CDK bootstrap resources inheriting the
+# wrong region when MINISTACK_REGION differs from the caller's AWS_REGION).
+_request_region: contextvars.ContextVar[str] = contextvars.ContextVar(
+    "_request_region",
+    default=os.environ.get("MINISTACK_REGION", "us-east-1"),
+)
+
+
+def set_request_region(region: str | None) -> None:
+    """Set the region for the current request. Falls back to MINISTACK_REGION /
+    ``us-east-1`` when the caller supplies nothing."""
+    if region:
+        _request_region.set(region)
+    else:
+        _request_region.set(os.environ.get("MINISTACK_REGION", "us-east-1"))
+
+
+def get_region() -> str:
+    """Return the region for the current request."""
+    return _request_region.get()
+
+
+class AccountScopedDict:
+    """A dict-like container that namespaces keys by the current request's account ID.
+
+    Stores data as ``{account_id}\\x00{key}`` internally so that identical
+    resource names in different accounts never collide. All standard dict
+    operations (get, set, delete, iteration, ``in``, ``len``) are scoped to the
+    caller's account automatically via ``get_account_id()``.
+
+    This is a drop-in replacement for ``dict`` in service module-level state,
+    e.g. ``_roles = AccountScopedDict()`` instead of ``_roles: dict = {}``.
+    """
+
+    __slots__ = ("_data",)
+
+    def __init__(self):
+        self._data: dict = {}
+
+    # -- internal helpers --------------------------------------------------
+
+    def _scoped(self, key):
+        return (get_account_id(), key)
+
+    def _unscope(self, scoped_key):
+        return scoped_key[1]
+
+    def _prefix(self):
+        return get_account_id()
+
+    def _is_mine(self, scoped_key):
+        return scoped_key[0] == get_account_id()
+
+    # -- dict interface ----------------------------------------------------
+
+    def __setitem__(self, key, value):
+        self._data[self._scoped(key)] = value
+
+    def __getitem__(self, key):
+        return self._data[self._scoped(key)]
+
+    def __delitem__(self, key):
+        del self._data[self._scoped(key)]
+
+    def __contains__(self, key):
+        return self._scoped(key) in self._data
+
+    def __len__(self):
+        return sum(1 for k in self._data if self._is_mine(k))
+
+    def __bool__(self):
+        return any(self._is_mine(k) for k in self._data)
+
+    def __iter__(self):
+        for k in self._data:
+            if self._is_mine(k):
+                yield self._unscope(k)
+
+    def get(self, key, default=None):
+        return self._data.get(self._scoped(key), default)
+
+    def pop(self, key, *args):
+        return self._data.pop(self._scoped(key), *args)
+
+    def setdefault(self, key, default=None):
+        return self._data.setdefault(self._scoped(key), default)
+
+    def keys(self):
+        return [self._unscope(k) for k in self._data if self._is_mine(k)]
+
+    def values(self):
+        return [v for k, v in self._data.items() if self._is_mine(k)]
+
+    def items(self):
+        return [(self._unscope(k), v) for k, v in self._data.items() if self._is_mine(k)]
+
+    def update(self, other):
+        if isinstance(other, AccountScopedDict):
+            self._data.update(other._data)
+        elif isinstance(other, dict):
+            for k, v in other.items():
+                self[k] = v
+
+    def clear(self):
+        """Clear ALL accounts' data (used by reset)."""
+        self._data.clear()
+
+    def to_dict(self):
+        """Convert ALL accounts' data to a plain dict for serialization.
+        Keys are stored as (account_id, original_key) tuples."""
+        return dict(self._data)
+
+    @classmethod
+    def from_dict(cls, data):
+        """Restore from a plain dict produced by to_dict()."""
+        obj = cls()
+        obj._data = dict(data)
+        return obj
+
+    def __repr__(self):
+        return f"AccountScopedDict({dict(self.items())})"
+
+
+def xml_response(root_tag: str, namespace: str, children: dict, status: int = 200) -> tuple:
+    """Build an AWS-style XML response."""
+    root = Element(root_tag, xmlns=namespace)
+    _dict_to_xml(root, children)
+
+    # Add RequestId in ResponseMetadata
+    metadata = SubElement(root, "ResponseMetadata")
+    req_id = SubElement(metadata, "RequestId")
+    req_id.text = str(uuid.uuid4())
+
+    body = b'<?xml version="1.0" encoding="UTF-8"?>\n' + tostring(root, encoding="unicode").encode("utf-8")
+    return status, {"Content-Type": "application/xml"}, body
+
+
+def _dict_to_xml(parent: Element, data):
+    """Recursively convert dict/list to XML elements."""
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if isinstance(value, list):
+                for item in value:
+                    child = SubElement(parent, key)
+                    if isinstance(item, dict):
+                        _dict_to_xml(child, item)
+                    else:
+                        child.text = str(item)
+            elif isinstance(value, dict):
+                child = SubElement(parent, key)
+                _dict_to_xml(child, value)
+            else:
+                child = SubElement(parent, key)
+                child.text = str(value) if value is not None else ""
+    elif isinstance(data, str):
+        parent.text = data
+
+
+def json_response(data: dict, status: int = 200) -> tuple:
+    """Build an AWS-style JSON response."""
+    body = json.dumps(data, ensure_ascii=False).encode("utf-8")
+    return status, {"Content-Type": "application/x-amz-json-1.0"}, body
+
+
+def error_response_xml(code: str, message: str, status: int, namespace: str = "http://s3.amazonaws.com/doc/2006-03-01/") -> tuple:
+    """AWS-style XML error response."""
+    root = Element("ErrorResponse", xmlns=namespace)
+    error = SubElement(root, "Error")
+    t = SubElement(error, "Type")
+    t.text = "Sender" if status < 500 else "Receiver"
+    c = SubElement(error, "Code")
+    c.text = code
+    m = SubElement(error, "Message")
+    m.text = message
+    req = SubElement(root, "RequestId")
+    req.text = str(uuid.uuid4())
+
+    body = b'<?xml version="1.0" encoding="UTF-8"?>\n' + tostring(root, encoding="unicode").encode("utf-8")
+    return status, {"Content-Type": "application/xml"}, body
+
+
+def error_response_json(code: str, message: str, status: int = 400) -> tuple:
+    """AWS-style JSON error response."""
+    data = {
+        "__type": code,
+        "message": message,
+    }
+    return json_response(data, status)
+
+
+def now_iso() -> str:
+    """Current time in AWS ISO format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+def now_rfc7231() -> str:
+    """Current time in RFC 7231 format for HTTP headers (e.g. Last-Modified)."""
+    return datetime.now(timezone.utc).strftime("%a, %d %b %Y %H:%M:%S GMT")
+
+
+def iso_to_rfc7231(iso_str: str) -> str:
+    """Convert an ISO 8601 timestamp to RFC 7231 format."""
+    try:
+        dt = datetime.fromisoformat(iso_str.replace("Z", "+00:00"))
+        return dt.strftime("%a, %d %b %Y %H:%M:%S GMT")
+    except (ValueError, AttributeError):
+        return iso_str
+
+
+def now_epoch() -> float:
+    return datetime.now(timezone.utc).timestamp()
+
+
+def md5_hash(data: bytes) -> str:
+    return hashlib.md5(data).hexdigest()
+
+
+def sha256_hash(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def new_uuid() -> str:
+    return str(uuid.uuid4())

aws_infra/ministack/core/router.py

@@ -0,0 +1,559 @@
+"""
+AWS API Request Router.
+Routes incoming requests to the correct service handler based on:
+  - Authorization header (AWS4-HMAC-SHA256 ... SignedHeaders=host;...)
+  - X-Amz-Target header (e.g., DynamoDB_20120810.PutItem)
+  - Host header (e.g., sqs.us-east-1.amazonaws.com)
+  - URL path patterns (e.g., /2015-03-31/functions for Lambda)
+"""
+
+import logging
+import os
+import re
+
+logger = logging.getLogger("ministack")
+
+# Service detection patterns
+SERVICE_PATTERNS = {
+    "s3": {
+        "host_patterns": [r"s3[\.\-]", r"\.s3\."],
+        "path_patterns": [r"^/(?!2\d{3}-)"],  # S3 is the fallback for non-API paths
+    },
+    "sqs": {
+        "host_patterns": [r"sqs\."],
+        "target_prefixes": ["AmazonSQS"],
+        "path_patterns": [r"/queue/", r"Action="],
+    },
+    "sns": {
+        "host_patterns": [r"sns\."],
+        "target_prefixes": ["AmazonSNS"],
+    },
+    "dynamodb": {
+        "target_prefixes": ["DynamoDB_20120810"],
+        "host_patterns": [r"dynamodb\."],
+    },
+    "lambda": {
+        "path_patterns": [r"^/2015-03-31/", r"^/2018-10-31/layers"],
+        "host_patterns": [r"lambda\."],
+    },
+    "iam": {
+        "host_patterns": [r"iam\."],
+        "path_patterns": [r"Action=.*(CreateRole|GetRole|ListRoles|PutRolePolicy)"],
+    },
+    "sts": {
+        "host_patterns": [r"sts\."],
+        "target_prefixes": ["AWSSecurityTokenService"],
+    },
+    "secretsmanager": {
+        "target_prefixes": ["secretsmanager"],
+        "host_patterns": [r"secretsmanager\."],
+    },
+    "monitoring": {
+        "host_patterns": [r"monitoring\."],
+        "target_prefixes": ["GraniteServiceVersion20100801"],
+    },
+    "logs": {
+        "target_prefixes": ["Logs_20140328"],
+        "host_patterns": [r"logs\."],
+    },
+    "ssm": {
+        "target_prefixes": ["AmazonSSM"],
+        "host_patterns": [r"ssm\."],
+    },
+    "events": {
+        "target_prefixes": ["AmazonEventBridge", "AWSEvents"],
+        "host_patterns": [r"events\."],
+    },
+    "kinesis": {
+        "target_prefixes": ["Kinesis_20131202"],
+        "host_patterns": [r"kinesis\."],
+    },
+    "ses": {
+        "host_patterns": [r"email\."],
+        "path_patterns": [r"Action=Send"],
+    },
+    "states": {
+        "target_prefixes": ["AWSStepFunctions"],
+        "host_patterns": [r"states\."],
+    },
+    "ecs": {
+        "target_prefixes": ["AmazonEC2ContainerServiceV20141113"],
+        "host_patterns": [r"ecs\."],
+        "path_patterns": [r"^/clusters", r"^/taskdefinitions", r"^/tasks", r"^/services", r"^/stoptask"],
+    },
+    "rds": {
+        "host_patterns": [r"rds\."],
+        "path_patterns": [r"Action=.*DB"],
+    },
+    "elasticache": {
+        "host_patterns": [r"elasticache\."],
+        "path_patterns": [r"Action=.*Cache"],
+    },
+    "glue": {
+        "target_prefixes": ["AWSGlue"],
+        "host_patterns": [r"glue\."],
+    },
+    "athena": {
+        "target_prefixes": ["AmazonAthena"],
+        "host_patterns": [r"athena\."],
+    },
+    "firehose": {
+        "target_prefixes": ["Firehose_20150804"],
+        "host_patterns": [r"firehose\.", r"kinesis-firehose\."],
+    },
+    "apigateway": {
+        "host_patterns": [r"apigateway\.", r"execute-api\."],
+        "path_patterns": [r"^/v2/apis"],
+    },
+    "route53": {
+        "host_patterns": [r"route53\."],
+        "path_patterns": [r"^/2013-04-01/"],
+    },
+    "cognito-idp": {
+        "target_prefixes": ["AWSCognitoIdentityProviderService"],
+        "host_patterns": [r"cognito-idp\."],
+    },
+    "cognito-identity": {
+        "target_prefixes": ["AWSCognitoIdentityService"],
+        "host_patterns": [r"cognito-identity\."],
+    },
+    "elasticmapreduce": {
+        "target_prefixes": ["ElasticMapReduce"],
+        "host_patterns": [r"elasticmapreduce\."],
+    },
+    "elasticfilesystem": {
+        "host_patterns": [r"elasticfilesystem\."],
+        "path_prefixes": ["/2015-02-01/"],
+        "credential_scope": "elasticfilesystem",
+    },
+    "ecr": {
+        "target_prefixes": ["AmazonEC2ContainerRegistry_V20150921"],
+        "host_patterns": [r"api\.ecr\.", r"ecr\."],
+        "credential_scope": "ecr",
+    },
+    "ec2": {
+        "host_patterns": [r"ec2\."],
+        "path_patterns": [r"Action=.*Instance", r"Action=.*Security", r"Action=.*KeyPair",
+                          r"Action=.*Vpc", r"Action=.*Subnet", r"Action=.*Address",
+                          r"Action=.*Image", r"Action=.*Tag", r"Action=.*InternetGateway",
+                          r"Action=.*AvailabilityZone"],
+    },
+    "elasticloadbalancing": {
+        "host_patterns": [r"elasticloadbalancing\."],
+    },
+    "acm": {
+        "target_prefixes": ["CertificateManager"],
+        "host_patterns": [r"acm\."],
+        "credential_scope": "acm",
+    },
+    "wafv2": {
+        "target_prefixes": ["AWSWAF_20190729"],
+        "host_patterns": [r"wafv2\."],
+        "credential_scope": "wafv2",
+    },
+    "cloudformation": {
+        "host_patterns": [r"cloudformation\."],
+    },
+    "kms": {
+        "target_prefixes": ["TrentService"],
+        "host_patterns": [r"kms\."]
+    },
+    "cloudfront": {
+        "host_patterns": [r"cloudfront\."],
+        "credential_scope": "cloudfront",
+    },
+    "codebuild": {
+        "target_prefixes": ["CodeBuild_20161006"],
+        "host_patterns": [r"codebuild\."],
+        "credential_scope": "codebuild",
+    },
+    "transfer": {
+        "target_prefixes": ["TransferService"],
+        "host_patterns": [r"transfer\."],
+        "credential_scope": "transfer",
+    },
+    "appsync": {
+        "host_patterns": [r"appsync\."],
+        "path_prefixes": ["/v1/apis", "/v1/tags"],
+        "credential_scope": "appsync",
+    },
+    "servicediscovery": {
+        "target_prefixes": ["Route53AutoNaming_v20170314"],
+        "host_patterns": [r"servicediscovery\."],
+        "credential_scope": "servicediscovery",
+    },
+    "s3files": {
+        "host_patterns": [r"s3files\."],
+        "credential_scope": "s3files",
+        "path_prefixes": ["/file-systems", "/mount-targets", "/access-points"],
+    },
+    "rds-data": {
+        "host_patterns": [r"rds-data\."],
+        "credential_scope": "rds-data",
+    },
+    "autoscaling": {
+        "host_patterns": [r"autoscaling\."],
+        "credential_scope": "autoscaling",
+    },
+    "appconfig": {
+        "host_patterns": [r"appconfig\."],
+        "path_prefixes": ["/applications", "/deploymentstrategies", "/deployementstrategies"],
+        "credential_scope": "appconfig",
+    },
+    "appconfigdata": {
+        "host_patterns": [r"appconfigdata\."],
+        "path_prefixes": ["/configurationsessions", "/configuration"],
+        "credential_scope": "appconfigdata",
+    },
+    "scheduler": {
+        "host_patterns": [r"scheduler\."],
+        "path_prefixes": ["/schedules", "/schedule-groups"],
+        "credential_scope": "scheduler",
+    },
+    "eks": {
+        "host_patterns": [r"eks\."],
+        "credential_scope": "eks",
+    },
+    "tagging": {
+        "target_prefixes": ["ResourceGroupsTaggingAPI_20170126"],
+        "host_patterns": [r"tagging\."],
+        "credential_scope": "tagging",
+    },
+}
+
+
+def detect_service(method: str, path: str, headers: dict, query_params: dict) -> str:
+    """Detect which AWS service a request is targeting."""
+    host = headers.get("host", "")
+    target = headers.get("x-amz-target", "")
+    auth = headers.get("authorization", "")
+    content_type = headers.get("content-type", "")
+
+    # 1. Check X-Amz-Target header (most reliable for JSON-based services)
+    if target:
+        for svc, patterns in SERVICE_PATTERNS.items():
+            for prefix in patterns.get("target_prefixes", []):
+                if target.startswith(prefix):
+                    return svc
+
+    # 2. Check Authorization header for service name in credential scope
+    if auth:
+        match = re.search(r"Credential=[^/]+/[^/]+/[^/]+/([^/]+)/", auth)
+        if match:
+            svc_name = match.group(1)
+            if svc_name in SERVICE_PATTERNS:
+                return svc_name
+            # Map common credential scope names
+            scope_map = {
+                "monitoring": "monitoring",
+                "execute-api": "apigateway",
+                "ses": "ses",
+                "states": "states",
+                "kinesis": "kinesis",
+                "events": "events",
+                "ssm": "ssm",
+                "ecs": "ecs",
+                "rds": "rds",
+                "elasticache": "elasticache",
+                "glue": "glue",
+                "athena": "athena",
+                "kinesis-firehose": "firehose",
+                "route53": "route53",
+                "acm": "acm",
+                "wafv2": "wafv2",
+                "cognito-idp": "cognito-idp",
+                "cognito-identity": "cognito-identity",
+                "ecr": "ecr",
+                "elasticmapreduce": "elasticmapreduce",
+                "elasticloadbalancing": "elasticloadbalancing",
+                "elasticfilesystem": "elasticfilesystem",
+                "cloudformation": "cloudformation",
+                "kms": "kms",
+                "cloudfront": "cloudfront",
+                "codebuild": "codebuild",
+                "transfer": "transfer",
+                "appsync": "appsync",
+                "servicediscovery": "servicediscovery",
+                "s3files": "s3files",
+                "rds-data": "rds-data",
+                "autoscaling": "autoscaling",
+                "appconfig": "appconfig",
+                "appconfigdata": "appconfigdata",
+                "scheduler": "scheduler",
+                "eks": "eks",
+                "tagging": "tagging",
+            }
+            if svc_name in scope_map:
+                return scope_map[svc_name]
+
+    # 3. Check query parameters for Action-based APIs (SQS, SNS, IAM, STS, CloudWatch)
+    action = query_params.get("Action", [""])[0] if isinstance(query_params.get("Action"), list) else query_params.get("Action", "")
+    if action:
+        action_service_map = {
+            # SQS actions
+            "SendMessage": "sqs", "ReceiveMessage": "sqs", "DeleteMessage": "sqs",
+            "CreateQueue": "sqs", "DeleteQueue": "sqs", "ListQueues": "sqs",
+            "GetQueueUrl": "sqs", "GetQueueAttributes": "sqs", "SetQueueAttributes": "sqs",
+            "PurgeQueue": "sqs", "ChangeMessageVisibility": "sqs",
+            "ChangeMessageVisibilityBatch": "sqs",
+            "SendMessageBatch": "sqs", "DeleteMessageBatch": "sqs",
+            "ListQueueTags": "sqs", "TagQueue": "sqs", "UntagQueue": "sqs",
+            # SNS actions
+            "Publish": "sns", "Subscribe": "sns", "Unsubscribe": "sns",
+            "CreateTopic": "sns", "DeleteTopic": "sns", "ListTopics": "sns",
+            "ListSubscriptions": "sns", "ConfirmSubscription": "sns",
+            "SetTopicAttributes": "sns", "GetTopicAttributes": "sns",
+            "ListSubscriptionsByTopic": "sns",
+            "GetSubscriptionAttributes": "sns", "SetSubscriptionAttributes": "sns",
+            "PublishBatch": "sns",
+            # Note: ListTagsForResource is shared by SNS, RDS, and ElastiCache.
+            # Routed via credential scope or host header instead.
+            "TagResource": "sns", "UntagResource": "sns",
+            "CreatePlatformApplication": "sns", "CreatePlatformEndpoint": "sns",
+            # IAM actions
+            "CreateRole": "iam", "GetRole": "iam", "ListRoles": "iam",
+            "DeleteRole": "iam", "CreateUser": "iam", "GetUser": "iam",
+            "ListUsers": "iam", "DeleteUser": "iam",
+            "CreatePolicy": "iam", "GetPolicy": "iam", "DeletePolicy": "iam",
+            "GetPolicyVersion": "iam", "ListPolicyVersions": "iam",
+            "CreatePolicyVersion": "iam", "DeletePolicyVersion": "iam",
+            "ListPolicies": "iam",
+            "AttachRolePolicy": "iam", "DetachRolePolicy": "iam",
+            "ListAttachedRolePolicies": "iam",
+            "PutRolePolicy": "iam", "GetRolePolicy": "iam",
+            "DeleteRolePolicy": "iam", "ListRolePolicies": "iam",
+            "CreateAccessKey": "iam", "ListAccessKeys": "iam", "DeleteAccessKey": "iam",
+            "CreateInstanceProfile": "iam", "DeleteInstanceProfile": "iam",
+            "GetInstanceProfile": "iam", "AddRoleToInstanceProfile": "iam",
+            "RemoveRoleFromInstanceProfile": "iam",
+            "ListInstanceProfiles": "iam", "ListInstanceProfilesForRole": "iam",
+            "UpdateAssumeRolePolicy": "iam",
+            "AttachUserPolicy": "iam", "DetachUserPolicy": "iam",
+            "ListAttachedUserPolicies": "iam",
+            "TagRole": "iam", "UntagRole": "iam", "ListRoleTags": "iam",
+            "TagUser": "iam", "UntagUser": "iam", "ListUserTags": "iam",
+            "SimulatePrincipalPolicy": "iam", "SimulateCustomPolicy": "iam",
+            # STS actions
+            "GetCallerIdentity": "sts", "AssumeRole": "sts",
+            "GetSessionToken": "sts", "AssumeRoleWithWebIdentity": "sts",
+            "AssumeRoleWithSAML": "sts",
+            # CloudWatch actions
+            "PutMetricData": "monitoring", "GetMetricData": "monitoring",
+            "ListMetrics": "monitoring", "PutMetricAlarm": "monitoring",
+            "DescribeAlarms": "monitoring", "DeleteAlarms": "monitoring",
+            "GetMetricStatistics": "monitoring", "SetAlarmState": "monitoring",
+            "EnableAlarmActions": "monitoring", "DisableAlarmActions": "monitoring",
+            "DescribeAlarmsForMetric": "monitoring", "DescribeAlarmHistory": "monitoring",
+            "PutCompositeAlarm": "monitoring",
+            # SES actions
+            "SendEmail": "ses", "SendRawEmail": "ses",
+            "VerifyEmailIdentity": "ses", "VerifyEmailAddress": "ses",
+            "VerifyDomainIdentity": "ses", "VerifyDomainDkim": "ses",
+            "ListIdentities": "ses", "DeleteIdentity": "ses",
+            "GetSendQuota": "ses", "GetSendStatistics": "ses",
+            "ListVerifiedEmailAddresses": "ses",
+            "GetIdentityVerificationAttributes": "ses",
+            "GetIdentityDkimAttributes": "ses",
+            "SetIdentityNotificationTopic": "ses",
+            "SetIdentityFeedbackForwardingEnabled": "ses",
+            "CreateConfigurationSet": "ses", "DeleteConfigurationSet": "ses",
+            "DescribeConfigurationSet": "ses", "ListConfigurationSets": "ses",
+            # Note: GetTemplate is shared by SES and CloudFormation.
+            # Routed via credential scope or host header instead.
+            "CreateTemplate": "ses",
+            "DeleteTemplate": "ses", "ListTemplates": "ses", "UpdateTemplate": "ses",
+            "SendTemplatedEmail": "ses", "SendBulkTemplatedEmail": "ses",
+            # RDS actions
+            "CreateDBInstance": "rds", "DeleteDBInstance": "rds", "DescribeDBInstances": "rds",
+            "StartDBInstance": "rds", "StopDBInstance": "rds", "RebootDBInstance": "rds",
+            "ModifyDBInstance": "rds", "CreateDBCluster": "rds", "DeleteDBCluster": "rds",
+            "ModifyDBCluster": "rds",
+            "DescribeDBClusters": "rds", "CreateDBSubnetGroup": "rds", "DescribeDBSubnetGroups": "rds",
+            "DeleteDBSubnetGroup": "rds",
+            "CreateDBParameterGroup": "rds", "DescribeDBParameterGroups": "rds",
+            "DeleteDBParameterGroup": "rds", "DescribeDBParameters": "rds",
+            "ModifyDBParameterGroup": "rds", "ResetDBParameterGroup": "rds",
+            "CreateDBClusterParameterGroup": "rds", "DescribeDBClusterParameterGroups": "rds",
+            "DeleteDBClusterParameterGroup": "rds", "DescribeDBClusterParameters": "rds",
+            "ModifyDBClusterParameterGroup": "rds", "ResetDBClusterParameterGroup": "rds",
+            "DescribeDBEngineVersions": "rds",
+            "DescribeOrderableDBInstanceOptions": "rds",
+            "CreateDBSnapshot": "rds", "DeleteDBSnapshot": "rds", "DescribeDBSnapshots": "rds",
+            "CreateDBInstanceReadReplica": "rds", "RestoreDBInstanceFromDBSnapshot": "rds",
+            "AddTagsToResource": "rds", "RemoveTagsFromResource": "rds",
+            # ElastiCache actions
+            "CreateCacheCluster": "elasticache", "DeleteCacheCluster": "elasticache",
+            "DescribeCacheClusters": "elasticache", "ModifyCacheCluster": "elasticache",
+            "RebootCacheCluster": "elasticache",
+            "CreateReplicationGroup": "elasticache", "DeleteReplicationGroup": "elasticache",
+            "DescribeReplicationGroups": "elasticache", "ModifyReplicationGroup": "elasticache",
+            "CreateCacheSubnetGroup": "elasticache", "DescribeCacheSubnetGroups": "elasticache",
+            "DeleteCacheSubnetGroup": "elasticache",
+            "CreateCacheParameterGroup": "elasticache", "DescribeCacheParameterGroups": "elasticache",
+            "DeleteCacheParameterGroup": "elasticache",
+            "DescribeCacheParameters": "elasticache", "ModifyCacheParameterGroup": "elasticache",
+            "DescribeCacheEngineVersions": "elasticache",
+            "CreateSnapshot": "elasticache", "DeleteSnapshot": "elasticache",
+            "DescribeSnapshots": "elasticache",
+            "IncreaseReplicaCount": "elasticache", "DecreaseReplicaCount": "elasticache",
+            # EC2 actions
+            "RunInstances": "ec2", "DescribeInstances": "ec2", "TerminateInstances": "ec2",
+            "StopInstances": "ec2", "StartInstances": "ec2", "RebootInstances": "ec2",
+            "DescribeImages": "ec2",
+            "CreateSecurityGroup": "ec2", "DeleteSecurityGroup": "ec2",
+            "DescribeSecurityGroups": "ec2",
+            "AuthorizeSecurityGroupIngress": "ec2", "RevokeSecurityGroupIngress": "ec2",
+            "AuthorizeSecurityGroupEgress": "ec2", "RevokeSecurityGroupEgress": "ec2",
+            "CreateKeyPair": "ec2", "DeleteKeyPair": "ec2", "DescribeKeyPairs": "ec2",
+            "ImportKeyPair": "ec2",
+            "DescribeVpcs": "ec2", "CreateVpc": "ec2", "DeleteVpc": "ec2",
+            "DescribeSubnets": "ec2", "CreateSubnet": "ec2", "DeleteSubnet": "ec2",
+            "CreateInternetGateway": "ec2", "DeleteInternetGateway": "ec2",
+            "DescribeInternetGateways": "ec2",
+            "AttachInternetGateway": "ec2", "DetachInternetGateway": "ec2",
+            "DescribeAvailabilityZones": "ec2",
+            "AllocateAddress": "ec2", "ReleaseAddress": "ec2",
+            "AssociateAddress": "ec2", "DisassociateAddress": "ec2",
+            "DescribeAddresses": "ec2",
+            "CreateTags": "ec2", "DeleteTags": "ec2", "DescribeTags": "ec2",
+            "ModifyVpcAttribute": "ec2", "ModifySubnetAttribute": "ec2",
+            "CreateRouteTable": "ec2", "DeleteRouteTable": "ec2", "DescribeRouteTables": "ec2",
+            "AssociateRouteTable": "ec2", "DisassociateRouteTable": "ec2",
+            "CreateRoute": "ec2", "ReplaceRoute": "ec2", "DeleteRoute": "ec2",
+            "CreateNetworkInterface": "ec2", "DeleteNetworkInterface": "ec2",
+            "DescribeNetworkInterfaces": "ec2",
+            "AttachNetworkInterface": "ec2", "DetachNetworkInterface": "ec2",
+            "CreateVpcEndpoint": "ec2", "DeleteVpcEndpoints": "ec2",
+            "DescribeVpcEndpoints": "ec2",
+            # ELBv2 / ALB actions
+            "CreateLoadBalancer": "elasticloadbalancing",
+            "DescribeLoadBalancers": "elasticloadbalancing",
+            "DeleteLoadBalancer": "elasticloadbalancing",
+            "DescribeLoadBalancerAttributes": "elasticloadbalancing",
+            "ModifyLoadBalancerAttributes": "elasticloadbalancing",
+            "CreateTargetGroup": "elasticloadbalancing",
+            "DescribeTargetGroups": "elasticloadbalancing",
+            "ModifyTargetGroup": "elasticloadbalancing",
+            "DeleteTargetGroup": "elasticloadbalancing",
+            "DescribeTargetGroupAttributes": "elasticloadbalancing",
+            "ModifyTargetGroupAttributes": "elasticloadbalancing",
+            "CreateListener": "elasticloadbalancing",
+            "DescribeListeners": "elasticloadbalancing",
+            "ModifyListener": "elasticloadbalancing",
+            "DeleteListener": "elasticloadbalancing",
+            "CreateRule": "elasticloadbalancing",
+            "DescribeRules": "elasticloadbalancing",
+            "ModifyRule": "elasticloadbalancing",
+            "DeleteRule": "elasticloadbalancing",
+            "SetRulePriorities": "elasticloadbalancing",
+            "RegisterTargets": "elasticloadbalancing",
+            "DeregisterTargets": "elasticloadbalancing",
+            "DescribeTargetHealth": "elasticloadbalancing",
+            "AddTags": "elasticloadbalancing",
+            "RemoveTags": "elasticloadbalancing",
+            "DescribeTags": "elasticloadbalancing",
+            # EBS Volumes
+            "CreateVolume": "ec2", "DeleteVolume": "ec2", "DescribeVolumes": "ec2",
+            "DescribeVolumeStatus": "ec2", "AttachVolume": "ec2", "DetachVolume": "ec2",
+            "ModifyVolume": "ec2", "DescribeVolumesModifications": "ec2",
+            "EnableVolumeIO": "ec2", "ModifyVolumeAttribute": "ec2",
+            "DescribeVolumeAttribute": "ec2",
+            # CloudFormation actions
+            "CreateStack": "cloudformation", "DescribeStacks": "cloudformation",
+            "UpdateStack": "cloudformation", "DeleteStack": "cloudformation",
+            "ListStacks": "cloudformation",
+            "DescribeStackEvents": "cloudformation",
+            "DescribeStackResource": "cloudformation", "DescribeStackResources": "cloudformation",
+            "ListStackResources": "cloudformation",
+            "GetTemplateSummary": "cloudformation",
+            "ValidateTemplate": "cloudformation",
+            "CreateChangeSet": "cloudformation", "DescribeChangeSet": "cloudformation",
+            "ExecuteChangeSet": "cloudformation", "DeleteChangeSet": "cloudformation",
+            "ListChangeSets": "cloudformation",
+            "ListExports": "cloudformation", "ListImports": "cloudformation",
+            "UpdateTerminationProtection": "cloudformation",
+            "SetStackPolicy": "cloudformation", "GetStackPolicy": "cloudformation",
+            # EBS Snapshots
+            # Note: CreateSnapshot, DeleteSnapshot, DescribeSnapshots are intentionally
+            # omitted here because they conflict with ElastiCache actions of the same
+            # name. These are routed via credential scope or host header instead.
+            "CopySnapshot": "ec2", "ModifySnapshotAttribute": "ec2",
+            "DescribeSnapshotAttribute": "ec2",
+            # AutoScaling actions
+            "CreateAutoScalingGroup": "autoscaling", "DescribeAutoScalingGroups": "autoscaling",
+            "UpdateAutoScalingGroup": "autoscaling", "DeleteAutoScalingGroup": "autoscaling",
+            "CreateLaunchConfiguration": "autoscaling", "DescribeLaunchConfigurations": "autoscaling",
+            "DeleteLaunchConfiguration": "autoscaling",
+            "PutScalingPolicy": "autoscaling", "DescribePolicies": "autoscaling",
+            "DeletePolicy": "autoscaling",
+            "PutLifecycleHook": "autoscaling", "DescribeLifecycleHooks": "autoscaling",
+            "DeleteLifecycleHook": "autoscaling",
+            "PutScheduledUpdateGroupAction": "autoscaling", "DescribeScheduledActions": "autoscaling",
+            "DeleteScheduledAction": "autoscaling",
+            "DescribeAutoScalingInstances": "autoscaling",
+        }
+        if action in action_service_map:
+            return action_service_map[action]
+
+    # 4. Check URL path patterns
+    path_lower = path.lower()
+    if path_lower.startswith("/v1/apis") or path_lower.startswith("/v1/tags/arn:aws:appsync"):
+        return "appsync"
+    if path_lower.startswith("/2020-05-31/"):
+        return "cloudfront"
+    if path_lower.startswith("/2013-04-01/"):
+        return "route53"
+    if path_lower.startswith("/v2/apis"):
+        return "apigateway"
+    if (path_lower.startswith("/restapis") or path_lower.startswith("/apikeys")
+            or path_lower.startswith("/usageplans") or path_lower.startswith("/domainnames")):
+        return "apigateway"
+    if path_lower.startswith("/2015-03-31/functions"):
+        return "lambda"
+    if path_lower.startswith(("/oauth2/", "/login", "/logout")):
+        return "cognito-idp"
+    if path_lower.startswith("/oauth2/authorize"):
+        return "cognito-idp"
+    if path_lower.startswith("/saml2/idpresponse"):
+        return "cognito-idp"
+    if path_lower.startswith(("/clusters", "/taskdefinitions", "/tasks", "/services", "/stoptask")):
+        return "ecs"
+    # smithy-rpc-v2-cbor path: /service/ServiceName/operation/ActionName
+    if "/service/" in path_lower and "/operation/" in path_lower:
+        if "granite" in path_lower or "cloudwatch" in path_lower:
+            return "monitoring"
+
+    # 5. Check host header patterns
+    for svc, patterns in SERVICE_PATTERNS.items():
+        for hp in patterns.get("host_patterns", []):
+            if re.search(hp, host):
+                return svc
+
+    # 6. Default to S3 (same as real LocalStack behavior)
+    return "s3"
+
+
+def extract_region(headers: dict) -> str:
+    """Extract AWS region from the request."""
+    auth = headers.get("authorization", "")
+    match = re.search(r"Credential=[^/]+/[^/]+/([^/]+)/", auth)
+    if match:
+        return match.group(1)
+    return os.environ.get("MINISTACK_REGION", "us-east-1")
+
+
+def extract_access_key_id(headers: dict) -> str:
+    """Extract the AWS access key ID from the Authorization header."""
+    auth = headers.get("authorization", "")
+    if auth:
+        match = re.search(r"Credential=([^/]+)/", auth)
+        if match:
+            return match.group(1)
+    return ""
+
+
+def extract_account_id(headers: dict) -> str:
+    """Extract account ID from credentials or env var.
+    If the access key is a 12-digit number, use it as the account ID."""
+    from ministack.core.responses import get_account_id
+    return get_account_id()

aws_infra/ministack/services/acm.py

@@ -0,0 +1,278 @@
+"""
+ACM (Certificate Manager) Service Emulator.
+JSON-based API via X-Amz-Target.
+Supports: RequestCertificate, DescribeCertificate, ListCertificates,
+          DeleteCertificate, GetCertificate, ImportCertificate,
+          AddTagsToCertificate, RemoveTagsFromCertificate, ListTagsForCertificate,
+          UpdateCertificateOptions, RenewCertificate, ResendValidationEmail.
+"""
+
+import copy
+import json
+import os
+import logging
+import time
+
+from ministack.core.persistence import PERSIST_STATE, load_state
+
+from ministack.core.responses import AccountScopedDict, get_account_id, error_response_json, json_response, new_uuid, now_iso, get_region
+
+logger = logging.getLogger("acm")
+
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+
+_certificates = AccountScopedDict()  # arn -> certificate dict
+
+
+def get_state():
+    return copy.deepcopy({"_certificates": _certificates})
+
+
+def restore_state(data):
+    _certificates.update(data.get("_certificates", {}))
+
+
+_restored = load_state("acm")
+if _restored:
+    restore_state(_restored)
+
+
+def _future_iso(seconds):
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(time.time() + seconds))
+
+
+def _epoch(iso_or_epoch):
+    """Convert ISO timestamp to epoch float if needed. ACM API returns epoch floats."""
+    if isinstance(iso_or_epoch, (int, float)):
+        return float(iso_or_epoch)
+    try:
+        return time.mktime(time.strptime(iso_or_epoch, "%Y-%m-%dT%H:%M:%SZ")) - time.timezone
+    except (ValueError, TypeError):
+        return time.time()
+
+
+def _cert_arn():
+    return f"arn:aws:acm:{get_region()}:{get_account_id()}:certificate/{new_uuid()}"
+
+
+def _validation_options(domain, method):
+    return {
+        "DomainName": domain,
+        "ValidationMethod": method,
+        "ValidationStatus": "SUCCESS",
+        "ResourceRecord": {
+            "Name": f"_acme-challenge.{domain}.",
+            "Type": "CNAME",
+            "Value": f"fake-validation-{new_uuid()[:8]}.acm.amazonaws.com.",
+        },
+    }
+
+
+def _cert_shape(cert):
+    return {
+        "CertificateArn": cert["CertificateArn"],
+        "DomainName": cert["DomainName"],
+        "SubjectAlternativeNames": cert.get("SubjectAlternativeNames", [cert["DomainName"]]),
+        "Status": cert["Status"],
+        "Type": cert.get("Type", "AMAZON_ISSUED"),
+        "KeyAlgorithm": "RSA_2048",
+        "SignatureAlgorithm": "SHA256WITHRSA",
+        "InUseBy": cert.get("InUseBy", []),
+        "CreatedAt": _epoch(cert["CreatedAt"]),
+        "IssuedAt": _epoch(cert.get("IssuedAt", cert["CreatedAt"])),
+        "NotBefore": _epoch(cert.get("NotBefore", cert["CreatedAt"])),
+        "NotAfter": _epoch(cert.get("NotAfter", _future_iso(365 * 24 * 3600))),
+        "DomainValidationOptions": cert.get("DomainValidationOptions", []),
+        "Options": cert.get("Options", {}),
+        "Tags": cert.get("Tags", []),
+    }
+
+
+async def handle_request(method, path, headers, body, query_params):
+    target = headers.get("x-amz-target", "")
+    action = target.split(".")[-1] if "." in target else ""
+
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError:
+        return error_response_json("SerializationException", "Invalid JSON", 400)
+
+    handlers = {
+        "RequestCertificate": _request_certificate,
+        "DescribeCertificate": _describe_certificate,
+        "ListCertificates": _list_certificates,
+        "DeleteCertificate": _delete_certificate,
+        "GetCertificate": _get_certificate,
+        "ImportCertificate": _import_certificate,
+        "AddTagsToCertificate": _add_tags,
+        "RemoveTagsFromCertificate": _remove_tags,
+        "ListTagsForCertificate": _list_tags,
+        "UpdateCertificateOptions": _update_options,
+        "RenewCertificate": _renew_certificate,
+        "ResendValidationEmail": _resend_validation_email,
+    }
+
+    handler = handlers.get(action)
+    if not handler:
+        return error_response_json("InvalidAction", f"Unknown action: {action}", 400)
+    return handler(data)
+
+
+def _request_certificate(data):
+    domain = data.get("DomainName", "")
+    if not domain:
+        return error_response_json("InvalidParameterException", "DomainName is required", 400)
+    method = data.get("ValidationMethod", "DNS")
+    sans = data.get("SubjectAlternativeNames", [domain])
+    if domain not in sans:
+        sans = [domain] + sans
+    arn = _cert_arn()
+    now = now_iso()
+    _certificates[arn] = {
+        "CertificateArn": arn,
+        "DomainName": domain,
+        "SubjectAlternativeNames": sans,
+        "Status": "ISSUED",
+        "Type": "AMAZON_ISSUED",
+        "CreatedAt": now,
+        "IssuedAt": now,
+        "NotBefore": now,
+        "NotAfter": _future_iso(365 * 24 * 3600),
+        "DomainValidationOptions": [_validation_options(d, method) for d in sans],
+        "ValidationMethod": method,
+        "Tags": data.get("Tags", []),
+        "Options": {},
+    }
+    logger.info("RequestCertificate: %s -> %s", domain, arn)
+    return json_response({"CertificateArn": arn})
+
+
+def _describe_certificate(data):
+    arn = data.get("CertificateArn", "")
+    cert = _certificates.get(arn)
+    if not cert:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    return json_response({"Certificate": _cert_shape(cert)})
+
+
+def _list_certificates(data):
+    statuses = data.get("CertificateStatuses", [])
+    summaries = []
+    for arn, cert in _certificates.items():
+        if statuses and cert["Status"] not in statuses:
+            continue
+        summaries.append({
+            "CertificateArn": arn,
+            "DomainName": cert["DomainName"],
+            "Status": cert["Status"],
+        })
+    return json_response({"CertificateSummaryList": summaries, "NextToken": None})
+
+
+def _delete_certificate(data):
+    arn = data.get("CertificateArn", "")
+    if arn not in _certificates:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    del _certificates[arn]
+    return json_response({})
+
+
+def _get_certificate(data):
+    arn = data.get("CertificateArn", "")
+    if arn not in _certificates:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    fake_pem = "-----BEGIN CERTIFICATE-----\nMIIFakeCertificateDataHere\n-----END CERTIFICATE-----"
+    fake_chain = "-----BEGIN CERTIFICATE-----\nMIIFakeChainDataHere\n-----END CERTIFICATE-----"
+    return json_response({"Certificate": fake_pem, "CertificateChain": fake_chain})
+
+
+def _import_certificate(data):
+    arn = data.get("CertificateArn") or _cert_arn()
+    now = now_iso()
+    _certificates[arn] = {
+        "CertificateArn": arn,
+        "DomainName": "imported.example.com",
+        "SubjectAlternativeNames": ["imported.example.com"],
+        "Status": "ISSUED",
+        "Type": "IMPORTED",
+        "CreatedAt": now,
+        "IssuedAt": now,
+        "NotBefore": now,
+        "NotAfter": _future_iso(365 * 24 * 3600),
+        "DomainValidationOptions": [],
+        "Tags": data.get("Tags", []),
+        "Options": {},
+    }
+    return json_response({"CertificateArn": arn})
+
+
+def _add_tags(data):
+    arn = data.get("CertificateArn", "")
+    cert = _certificates.get(arn)
+    if not cert:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    existing = {t["Key"]: t for t in cert.get("Tags", [])}
+    for tag in data.get("Tags", []):
+        existing[tag["Key"]] = tag
+    cert["Tags"] = list(existing.values())
+    return json_response({})
+
+
+def _remove_tags(data):
+    arn = data.get("CertificateArn", "")
+    cert = _certificates.get(arn)
+    if not cert:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    remove_keys = {t["Key"] for t in data.get("Tags", [])}
+    cert["Tags"] = [t for t in cert.get("Tags", []) if t["Key"] not in remove_keys]
+    return json_response({})
+
+
+def _list_tags(data):
+    arn = data.get("CertificateArn", "")
+    cert = _certificates.get(arn)
+    if not cert:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    return json_response({"Tags": cert.get("Tags", [])})
+
+
+def _update_options(data):
+    arn = data.get("CertificateArn", "")
+    cert = _certificates.get(arn)
+    if not cert:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    cert["Options"] = data.get("Options", {})
+    return json_response({})
+
+
+def _renew_certificate(data):
+    arn = data.get("CertificateArn", "")
+    if arn not in _certificates:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    return json_response({})
+
+
+def _resend_validation_email(data):
+    arn = data.get("CertificateArn", "")
+    if arn not in _certificates:
+        return error_response_json("ResourceNotFoundException", f"Certificate {arn} not found", 400)
+    return json_response({})
+
+
+SUPPORTED_ACTIONS = [
+    "RequestCertificate", "DescribeCertificate", "ListCertificates",
+    "DeleteCertificate", "GetCertificate", "ImportCertificate",
+    "AddTagsToCertificate", "RemoveTagsFromCertificate",
+    "ListTagsForCertificate", "UpdateCertificateOptions",
+    "RenewCertificate", "ResendValidationEmail",
+]
+
+
+def get_state_summary() -> dict:
+    return {
+        "certificates": {"count": len(_certificates), "ids": list(_certificates.keys())},
+    }
+
+
+def reset():
+    _certificates.clear()

aws_infra/ministack/services/alb.py

@@ -0,0 +1,1169 @@
+"""
+ALB / ELBv2 (Elastic Load Balancing v2) Service Emulator.
+Query API (Action=...) with XML responses. In-memory only.
+
+Supports:
+  Load Balancers:       CreateLoadBalancer, DescribeLoadBalancers, DeleteLoadBalancer,
+                        ModifyLoadBalancerAttributes, DescribeLoadBalancerAttributes
+  Target Groups:        CreateTargetGroup, DescribeTargetGroups, ModifyTargetGroup,
+                        DeleteTargetGroup, DescribeTargetGroupAttributes,
+                        ModifyTargetGroupAttributes
+  Listeners:            CreateListener, DescribeListeners, ModifyListener, DeleteListener,
+                        DescribeListenerAttributes, ModifyListenerAttributes
+  Rules:                CreateRule, DescribeRules, ModifyRule, DeleteRule,
+                        SetRulePriorities
+  Target Registration:  RegisterTargets, DeregisterTargets, DescribeTargetHealth
+  Tags:                 AddTags, RemoveTags, DescribeTags
+"""
+
+import base64
+import copy
+import fnmatch
+import json
+import logging
+import os
+import random
+import string
+import time
+from urllib.parse import parse_qs
+
+from ministack.core.persistence import PERSIST_STATE, load_state
+from ministack.core.responses import AccountScopedDict, get_account_id, new_uuid, get_region
+
+logger = logging.getLogger("alb")
+
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+NS = "http://elasticloadbalancing.amazonaws.com/doc/2015-12-01/"
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+_lbs = AccountScopedDict()        # lb_arn   -> LB record
+_tgs = AccountScopedDict()        # tg_arn   -> TG record
+_listeners = AccountScopedDict()  # l_arn    -> Listener record
+_rules = AccountScopedDict()      # r_arn    -> Rule record
+_targets = AccountScopedDict()    # tg_arn   -> [target dict]
+_tags = AccountScopedDict()       # res_arn  -> [{Key, Value}]
+_lb_attrs = AccountScopedDict()   # lb_arn   -> [{Key, Value}]
+_tg_attrs = AccountScopedDict()   # tg_arn   -> [{Key, Value}]
+_listener_attrs = AccountScopedDict()  # l_arn -> [{Key, Value}]
+
+
+def get_state():
+    return copy.deepcopy({
+        "_lbs": _lbs,
+        "_tgs": _tgs,
+        "_listeners": _listeners,
+        "_rules": _rules,
+        "_targets": _targets,
+        "_tags": _tags,
+        "_lb_attrs": _lb_attrs,
+        "_tg_attrs": _tg_attrs,
+        "_listener_attrs": _listener_attrs,
+    })
+
+
+def restore_state(data):
+    _lbs.update(data.get("_lbs", {}))
+    _tgs.update(data.get("_tgs", {}))
+    _listeners.update(data.get("_listeners", {}))
+    _rules.update(data.get("_rules", {}))
+    _targets.update(data.get("_targets", {}))
+    _tags.update(data.get("_tags", {}))
+    _lb_attrs.update(data.get("_lb_attrs", {}))
+    _tg_attrs.update(data.get("_tg_attrs", {}))
+    _listener_attrs.update(data.get("_listener_attrs", {}))
+
+
+_restored = load_state("alb")
+if _restored:
+    restore_state(_restored)
+
+# ---------------------------------------------------------------------------
+# Small helpers
+# ---------------------------------------------------------------------------
+
+def _p(params, key, default=""):
+    val = params.get(key, [default])
+    return (val[0] if val else default) if isinstance(val, list) else val
+
+
+def _parse_member_list(params, prefix):
+    items, i = [], 1
+    while True:
+        v = _p(params, f"{prefix}.member.{i}")
+        if not v:
+            break
+        items.append(v)
+        i += 1
+    return items
+
+
+def _parse_tags(params):
+    tags, i = [], 1
+    while True:
+        k = _p(params, f"Tags.member.{i}.Key")
+        if not k:
+            break
+        tags.append({"Key": k, "Value": _p(params, f"Tags.member.{i}.Value")})
+        i += 1
+    return tags
+
+
+def _parse_actions(params, prefix="DefaultActions"):
+    actions, i = [], 1
+    while True:
+        t = _p(params, f"{prefix}.member.{i}.Type")
+        if not t:
+            break
+        action = {"Type": t, "Order": int(_p(params, f"{prefix}.member.{i}.Order", str(i)))}
+        tg = _p(params, f"{prefix}.member.{i}.TargetGroupArn")
+        if tg:
+            action["TargetGroupArn"] = tg
+        rc_code = _p(params, f"{prefix}.member.{i}.RedirectConfig.StatusCode")
+        if rc_code:
+            action["RedirectConfig"] = {
+                "Protocol": _p(params, f"{prefix}.member.{i}.RedirectConfig.Protocol", "#{protocol}"),
+                "Port": _p(params, f"{prefix}.member.{i}.RedirectConfig.Port", "#{port}"),
+                "Host": _p(params, f"{prefix}.member.{i}.RedirectConfig.Host", "#{host}"),
+                "Path": _p(params, f"{prefix}.member.{i}.RedirectConfig.Path", "/#{path}"),
+                "StatusCode": rc_code,
+            }
+        fr_code = _p(params, f"{prefix}.member.{i}.FixedResponseConfig.StatusCode")
+        if fr_code:
+            action["FixedResponseConfig"] = {
+                "StatusCode": fr_code,
+                "ContentType": _p(params, f"{prefix}.member.{i}.FixedResponseConfig.ContentType", "text/plain"),
+                "MessageBody": _p(params, f"{prefix}.member.{i}.FixedResponseConfig.MessageBody", ""),
+            }
+        actions.append(action)
+        i += 1
+    return actions
+
+
+def _parse_conditions(params, prefix="Conditions"):
+    conditions, i = [], 1
+    while True:
+        field = _p(params, f"{prefix}.member.{i}.Field")
+        if not field:
+            break
+        values, j = [], 1
+        while True:
+            v = _p(params, f"{prefix}.member.{i}.Values.member.{j}")
+            if not v:
+                break
+            values.append(v)
+            j += 1
+        conditions.append({"Field": field, "Values": values})
+        i += 1
+    return conditions
+
+
+def _parse_targets_param(params, prefix="Targets"):
+    targets, i = [], 1
+    while True:
+        tid = _p(params, f"{prefix}.member.{i}.Id")
+        if not tid:
+            break
+        t = {"Id": tid}
+        port = _p(params, f"{prefix}.member.{i}.Port")
+        if port:
+            t["Port"] = int(port)
+        targets.append(t)
+        i += 1
+    return targets
+
+
+def _now_iso():
+    return time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
+
+
+def _short_id():
+    return "".join(random.choices(string.ascii_lowercase + string.digits, k=16))
+
+# ---------------------------------------------------------------------------
+# XML builders
+# ---------------------------------------------------------------------------
+
+def _xml(status, action, inner):
+    body = (
+        f'<?xml version="1.0" encoding="UTF-8"?>'
+        f'<{action}Response xmlns="{NS}">'
+        f'<{action}Result>{inner}</{action}Result>'
+        f'<ResponseMetadata><RequestId>{new_uuid()}</RequestId></ResponseMetadata>'
+        f'</{action}Response>'
+    ).encode("utf-8")
+    return status, {"Content-Type": "text/xml"}, body
+
+
+def _empty(action):
+    body = (
+        f'<?xml version="1.0" encoding="UTF-8"?>'
+        f'<{action}Response xmlns="{NS}">'
+        f'<{action}Result/>'
+        f'<ResponseMetadata><RequestId>{new_uuid()}</RequestId></ResponseMetadata>'
+        f'</{action}Response>'
+    ).encode("utf-8")
+    return 200, {"Content-Type": "text/xml"}, body
+
+
+def _error(code, message, status=400):
+    body = (
+        f'<?xml version="1.0" encoding="UTF-8"?>'
+        f'<ErrorResponse xmlns="{NS}">'
+        f'<Error><Code>{code}</Code><Message>{message}</Message></Error>'
+        f'<RequestId>{new_uuid()}</RequestId>'
+        f'</ErrorResponse>'
+    ).encode("utf-8")
+    return status, {"Content-Type": "text/xml"}, body
+
+
+def _attrs_xml(attrs):
+    return "".join(
+        f"<member><Key>{a['Key']}</Key><Value>{a['Value']}</Value></member>"
+        for a in attrs
+    )
+
+# ---------------------------------------------------------------------------
+# XML serialisers for each resource type
+# ---------------------------------------------------------------------------
+
+def _lb_xml(lb):
+    azs = "".join(
+        f"<member><ZoneName>{get_region()}a</ZoneName><SubnetId>{s}</SubnetId>"
+        f"<LoadBalancerAddresses/></member>"
+        for s in lb.get("Subnets", [])
+    )
+    sgs = "".join(f"<member>{sg}</member>" for sg in lb.get("SecurityGroups", []))
+    return (
+        f"<member>"
+        f"<LoadBalancerArn>{lb['LoadBalancerArn']}</LoadBalancerArn>"
+        f"<LoadBalancerName>{lb['LoadBalancerName']}</LoadBalancerName>"
+        f"<DNSName>{lb['DNSName']}</DNSName>"
+        f"<CanonicalHostedZoneId>Z35SXDOTRQ7X7K</CanonicalHostedZoneId>"
+        f"<CreatedTime>{lb['CreatedTime']}</CreatedTime>"
+        f"<Scheme>{lb['Scheme']}</Scheme>"
+        f"<VpcId>{lb.get('VpcId','')}</VpcId>"
+        f"<State><Code>{lb['State']}</Code></State>"
+        f"<Type>{lb['Type']}</Type>"
+        f"<AvailabilityZones>{azs}</AvailabilityZones>"
+        f"<SecurityGroups>{sgs}</SecurityGroups>"
+        f"<IpAddressType>{lb.get('IpAddressType','ipv4')}</IpAddressType>"
+        f"</member>"
+    )
+
+
+def _tg_xml(tg):
+    lb_arns = "".join(f"<member>{a}</member>" for a in tg.get("LoadBalancerArns", []))
+    return (
+        f"<member>"
+        f"<TargetGroupArn>{tg['TargetGroupArn']}</TargetGroupArn>"
+        f"<TargetGroupName>{tg['TargetGroupName']}</TargetGroupName>"
+        f"<Protocol>{tg.get('Protocol','HTTP')}</Protocol>"
+        f"<Port>{tg.get('Port',80)}</Port>"
+        f"<VpcId>{tg.get('VpcId','')}</VpcId>"
+        f"<HealthCheckProtocol>{tg.get('HealthCheckProtocol','HTTP')}</HealthCheckProtocol>"
+        f"<HealthCheckPort>{tg.get('HealthCheckPort','traffic-port')}</HealthCheckPort>"
+        f"<HealthCheckEnabled>{str(tg.get('HealthCheckEnabled',True)).lower()}</HealthCheckEnabled>"
+        f"<HealthCheckPath>{tg.get('HealthCheckPath','/')}</HealthCheckPath>"
+        f"<HealthCheckIntervalSeconds>{tg.get('HealthCheckIntervalSeconds',30)}</HealthCheckIntervalSeconds>"
+        f"<HealthCheckTimeoutSeconds>{tg.get('HealthCheckTimeoutSeconds',5)}</HealthCheckTimeoutSeconds>"
+        f"<HealthyThresholdCount>{tg.get('HealthyThresholdCount',5)}</HealthyThresholdCount>"
+        f"<UnhealthyThresholdCount>{tg.get('UnhealthyThresholdCount',2)}</UnhealthyThresholdCount>"
+        f"<Matcher><HttpCode>{tg.get('Matcher',{}).get('HttpCode','200')}</HttpCode></Matcher>"
+        f"<LoadBalancerArns>{lb_arns}</LoadBalancerArns>"
+        f"<TargetType>{tg.get('TargetType','instance')}</TargetType>"
+        f"</member>"
+    )
+
+
+def _action_xml(a):
+    inner = f"<Type>{a['Type']}</Type><Order>{a.get('Order',1)}</Order>"
+    if "TargetGroupArn" in a:
+        inner += f"<TargetGroupArn>{a['TargetGroupArn']}</TargetGroupArn>"
+    if "RedirectConfig" in a:
+        rc = a["RedirectConfig"]
+        inner += (
+            f"<RedirectConfig>"
+            f"<Protocol>{rc.get('Protocol','#{protocol}')}</Protocol>"
+            f"<Port>{rc.get('Port','#{port}')}</Port>"
+            f"<Host>{rc.get('Host','#{host}')}</Host>"
+            f"<Path>{rc.get('Path','/#{path}')}</Path>"
+            f"<StatusCode>{rc.get('StatusCode','HTTP_301')}</StatusCode>"
+            f"</RedirectConfig>"
+        )
+    if "FixedResponseConfig" in a:
+        frc = a["FixedResponseConfig"]
+        inner += (
+            f"<FixedResponseConfig>"
+            f"<StatusCode>{frc.get('StatusCode','200')}</StatusCode>"
+            f"<ContentType>{frc.get('ContentType','text/plain')}</ContentType>"
+            f"<MessageBody>{frc.get('MessageBody','')}</MessageBody>"
+            f"</FixedResponseConfig>"
+        )
+    return f"<member>{inner}</member>"
+
+
+def _listener_xml(l):
+    acts = "".join(_action_xml(a) for a in l.get("DefaultActions", []))
+    return (
+        f"<member>"
+        f"<ListenerArn>{l['ListenerArn']}</ListenerArn>"
+        f"<LoadBalancerArn>{l['LoadBalancerArn']}</LoadBalancerArn>"
+        f"<Port>{l.get('Port',80)}</Port>"
+        f"<Protocol>{l.get('Protocol','HTTP')}</Protocol>"
+        f"<DefaultActions>{acts}</DefaultActions>"
+        f"</member>"
+    )
+
+
+def _rule_xml(r):
+    conds = "".join(
+        f"<member><Field>{c['Field']}</Field>"
+        f"<Values>{''.join(f'<member>{v}</member>' for v in c.get('Values',[]))}</Values>"
+        f"</member>"
+        for c in r.get("Conditions", [])
+    )
+    acts = "".join(_action_xml(a) for a in r.get("Actions", []))
+    return (
+        f"<member>"
+        f"<RuleArn>{r['RuleArn']}</RuleArn>"
+        f"<Priority>{r['Priority']}</Priority>"
+        f"<Conditions>{conds}</Conditions>"
+        f"<Actions>{acts}</Actions>"
+        f"<IsDefault>{str(r.get('IsDefault',False)).lower()}</IsDefault>"
+        f"</member>"
+    )
+
+# ---------------------------------------------------------------------------
+# Load Balancer handlers
+# ---------------------------------------------------------------------------
+
+def _create_lb(params):
+    name = _p(params, "Name")
+    if not name:
+        return _error("ValidationError", "Name is required")
+    for lb in _lbs.values():
+        if lb["LoadBalancerName"] == name:
+            return _error("DuplicateLoadBalancerName",
+                          f"A load balancer with name '{name}' already exists.")
+    lid = _short_id()
+    arn = f"arn:aws:elasticloadbalancing:{get_region()}:{get_account_id()}:loadbalancer/app/{name}/{lid}"
+    lb = {
+        "LoadBalancerArn": arn,
+        "LoadBalancerName": name,
+        "DNSName": f"{name}-{lid[:8]}.{get_region()}.elb.amazonaws.com",
+        "Scheme": _p(params, "Scheme", "internet-facing"),
+        "VpcId": _p(params, "VpcId", "vpc-00000001"),
+        "State": "active",
+        "Type": _p(params, "Type", "application"),
+        "Subnets": _parse_member_list(params, "Subnets"),
+        "SecurityGroups": _parse_member_list(params, "SecurityGroups"),
+        "IpAddressType": _p(params, "IpAddressType", "ipv4"),
+        "CreatedTime": _now_iso(),
+    }
+    _lbs[arn] = lb
+    _tags[arn] = _parse_tags(params)
+    _lb_attrs[arn] = [
+        {"Key": "access_logs.s3.enabled", "Value": "false"},
+        {"Key": "deletion_protection.enabled", "Value": "false"},
+        {"Key": "idle_timeout.timeout_seconds", "Value": "60"},
+    ]
+    return _xml(200, "CreateLoadBalancer", f"<LoadBalancers>{_lb_xml(lb)}</LoadBalancers>")
+
+
+def _describe_lbs(params):
+    arn_filter = _parse_member_list(params, "LoadBalancerArns")
+    name_filter = _parse_member_list(params, "Names")
+    results = list(_lbs.values())
+    if arn_filter:
+        results = [lb for lb in results if lb["LoadBalancerArn"] in arn_filter]
+        if not results:
+            return _error("LoadBalancerNotFound", "One or more load balancers not found", 400)
+    if name_filter:
+        results = [lb for lb in results if lb["LoadBalancerName"] in name_filter]
+        if not results:
+            return _error("LoadBalancerNotFound", "One or more load balancers not found", 400)
+    return _xml(200, "DescribeLoadBalancers",
+                f"<LoadBalancers>{''.join(_lb_xml(lb) for lb in results)}</LoadBalancers>")
+
+
+def _delete_lb(params):
+    arn = _p(params, "LoadBalancerArn")
+    _lbs.pop(arn, None)
+    _lb_attrs.pop(arn, None)
+    _tags.pop(arn, None)
+    return _empty("DeleteLoadBalancer")
+
+
+def _describe_lb_attrs(params):
+    arn = _p(params, "LoadBalancerArn")
+    if arn not in _lbs:
+        return _error("LoadBalancerNotFound", f"Load balancer '{arn}' not found.")
+    return _xml(200, "DescribeLoadBalancerAttributes",
+                f"<Attributes>{_attrs_xml(_lb_attrs.get(arn,[]))}</Attributes>")
+
+
+def _modify_lb_attrs(params):
+    arn = _p(params, "LoadBalancerArn")
+    if arn not in _lbs:
+        return _error("LoadBalancerNotFound", f"Load balancer '{arn}' not found.")
+    attrs = _lb_attrs.setdefault(arn, [])
+    idx = {a["Key"]: i for i, a in enumerate(attrs)}
+    i = 1
+    while True:
+        key = _p(params, f"Attributes.member.{i}.Key")
+        if not key:
+            break
+        val = _p(params, f"Attributes.member.{i}.Value")
+        if key in idx:
+            attrs[idx[key]]["Value"] = val
+        else:
+            attrs.append({"Key": key, "Value": val})
+            idx[key] = len(attrs) - 1
+        i += 1
+    return _xml(200, "ModifyLoadBalancerAttributes",
+                f"<Attributes>{_attrs_xml(attrs)}</Attributes>")
+
+
+
+# ---------------------------------------------------------------------------
+# Target Group handlers
+# ---------------------------------------------------------------------------
+
+def _create_tg(params):
+    name = _p(params, "Name")
+    if not name:
+        return _error("ValidationError", "Name is required")
+    for tg in _tgs.values():
+        if tg["TargetGroupName"] == name:
+            return _error("DuplicateTargetGroupName",
+                          f"A target group with name '{name}' already exists.")
+    tid = _short_id()
+    arn = f"arn:aws:elasticloadbalancing:{get_region()}:{get_account_id()}:targetgroup/{name}/{tid}"
+    tg = {
+        "TargetGroupArn": arn,
+        "TargetGroupName": name,
+        "Protocol": _p(params, "Protocol", "HTTP"),
+        "Port": int(_p(params, "Port", "80") or 80),
+        "VpcId": _p(params, "VpcId", ""),
+        "HealthCheckProtocol": _p(params, "HealthCheckProtocol", "HTTP"),
+        "HealthCheckPort": _p(params, "HealthCheckPort", "traffic-port"),
+        "HealthCheckEnabled": _p(params, "HealthCheckEnabled", "true").lower() == "true",
+        "HealthCheckPath": _p(params, "HealthCheckPath", "/"),
+        "HealthCheckIntervalSeconds": int(_p(params, "HealthCheckIntervalSeconds", "30") or 30),
+        "HealthCheckTimeoutSeconds": int(_p(params, "HealthCheckTimeoutSeconds", "5") or 5),
+        "HealthyThresholdCount": int(_p(params, "HealthyThresholdCount", "5") or 5),
+        "UnhealthyThresholdCount": int(_p(params, "UnhealthyThresholdCount", "2") or 2),
+        "Matcher": {"HttpCode": _p(params, "Matcher.HttpCode", "200")},
+        "LoadBalancerArns": [],
+        "TargetType": _p(params, "TargetType", "instance"),
+    }
+    _tgs[arn] = tg
+    _targets[arn] = []
+    _tags[arn] = _parse_tags(params)
+    _tg_attrs[arn] = [
+        {"Key": "deregistration_delay.timeout_seconds", "Value": "300"},
+        {"Key": "stickiness.enabled", "Value": "false"},
+        {"Key": "stickiness.type", "Value": "lb_cookie"},
+    ]
+    return _xml(200, "CreateTargetGroup", f"<TargetGroups>{_tg_xml(tg)}</TargetGroups>")
+
+
+def _describe_tgs(params):
+    arn_filter = _parse_member_list(params, "TargetGroupArns")
+    name_filter = _parse_member_list(params, "Names")
+    lb_arn = _p(params, "LoadBalancerArn")
+    results = list(_tgs.values())
+    if arn_filter:
+        results = [tg for tg in results if tg["TargetGroupArn"] in arn_filter]
+        if not results:
+            return _error("TargetGroupNotFound", "One or more target groups not found", 400)
+    if name_filter:
+        results = [tg for tg in results if tg["TargetGroupName"] in name_filter]
+    if lb_arn:
+        results = [tg for tg in results if lb_arn in tg.get("LoadBalancerArns", [])]
+    return _xml(200, "DescribeTargetGroups",
+                f"<TargetGroups>{''.join(_tg_xml(tg) for tg in results)}</TargetGroups>")
+
+
+def _modify_tg(params):
+    arn = _p(params, "TargetGroupArn")
+    tg = _tgs.get(arn)
+    if not tg:
+        return _error("TargetGroupNotFound", f"Target group '{arn}' not found.")
+    for field, param in [("HealthCheckProtocol", "HealthCheckProtocol"),
+                         ("HealthCheckPort", "HealthCheckPort"),
+                         ("HealthCheckPath", "HealthCheckPath")]:
+        v = _p(params, param)
+        if v:
+            tg[field] = v
+    for field, param, cast in [
+        ("HealthCheckEnabled", "HealthCheckEnabled", lambda v: v.lower() == "true"),
+        ("HealthCheckIntervalSeconds", "HealthCheckIntervalSeconds", int),
+        ("HealthCheckTimeoutSeconds", "HealthCheckTimeoutSeconds", int),
+        ("HealthyThresholdCount", "HealthyThresholdCount", int),
+        ("UnhealthyThresholdCount", "UnhealthyThresholdCount", int),
+    ]:
+        v = _p(params, param)
+        if v:
+            tg[field] = cast(v)
+    http_code = _p(params, "Matcher.HttpCode")
+    if http_code:
+        tg["Matcher"]["HttpCode"] = http_code
+    return _xml(200, "ModifyTargetGroup", f"<TargetGroups>{_tg_xml(tg)}</TargetGroups>")
+
+
+def _delete_tg(params):
+    arn = _p(params, "TargetGroupArn")
+    if arn not in _tgs:
+        return _error("TargetGroupNotFound", f"Target group '{arn}' not found", 400)
+    _tgs.pop(arn, None)
+    _targets.pop(arn, None)
+    _tg_attrs.pop(arn, None)
+    _tags.pop(arn, None)
+    return _empty("DeleteTargetGroup")
+
+
+def _describe_tg_attrs(params):
+    arn = _p(params, "TargetGroupArn")
+    if arn not in _tgs:
+        return _error("TargetGroupNotFound", f"Target group '{arn}' not found.")
+    return _xml(200, "DescribeTargetGroupAttributes",
+                f"<Attributes>{_attrs_xml(_tg_attrs.get(arn,[]))}</Attributes>")
+
+
+def _modify_tg_attrs(params):
+    arn = _p(params, "TargetGroupArn")
+    if arn not in _tgs:
+        return _error("TargetGroupNotFound", f"Target group '{arn}' not found.")
+    attrs = _tg_attrs.setdefault(arn, [])
+    idx = {a["Key"]: i for i, a in enumerate(attrs)}
+    i = 1
+    while True:
+        key = _p(params, f"Attributes.member.{i}.Key")
+        if not key:
+            break
+        val = _p(params, f"Attributes.member.{i}.Value")
+        if key in idx:
+            attrs[idx[key]]["Value"] = val
+        else:
+            attrs.append({"Key": key, "Value": val})
+            idx[key] = len(attrs) - 1
+        i += 1
+    return _xml(200, "ModifyTargetGroupAttributes",
+                f"<Attributes>{_attrs_xml(attrs)}</Attributes>")
+
+
+# ---------------------------------------------------------------------------
+# Listener handlers
+# ---------------------------------------------------------------------------
+
+def _create_listener(params):
+    lb_arn = _p(params, "LoadBalancerArn")
+    if lb_arn not in _lbs:
+        return _error("LoadBalancerNotFound", f"Load balancer '{lb_arn}' not found.")
+    lid = _short_id()
+    lb = _lbs[lb_arn]
+    lb_name = lb["LoadBalancerName"]
+    lb_id = lb_arn.split("/")[-1]
+    l_arn = (f"arn:aws:elasticloadbalancing:{get_region()}:{get_account_id()}"
+             f":listener/app/{lb_name}/{lb_id}/{lid}")
+    actions = _parse_actions(params, "DefaultActions")
+    for action in actions:
+        tg_arn = action.get("TargetGroupArn")
+        if tg_arn and tg_arn in _tgs and lb_arn not in _tgs[tg_arn]["LoadBalancerArns"]:
+            _tgs[tg_arn]["LoadBalancerArns"].append(lb_arn)
+    listener = {
+        "ListenerArn": l_arn,
+        "LoadBalancerArn": lb_arn,
+        "Port": int(_p(params, "Port", "80") or 80),
+        "Protocol": _p(params, "Protocol", "HTTP"),
+        "DefaultActions": actions,
+    }
+    _listeners[l_arn] = listener
+    _listener_attrs[l_arn] = [
+        {"Key": "routing.http.response.server.enabled", "Value": "true"},
+    ]
+    _tags[l_arn] = _parse_tags(params)
+    # auto-create default rule
+    rule_id = _short_id()
+    rule_arn = (f"arn:aws:elasticloadbalancing:{get_region()}:{get_account_id()}"
+                f":listener-rule/app/{lb_name}/{lb_id}/{lid}/{rule_id}")
+    _rules[rule_arn] = {
+        "RuleArn": rule_arn, "ListenerArn": l_arn,
+        "Priority": "default", "Conditions": [],
+        "Actions": actions, "IsDefault": True,
+    }
+    return _xml(200, "CreateListener", f"<Listeners>{_listener_xml(listener)}</Listeners>")
+
+
+def _describe_listeners(params):
+    lb_arn = _p(params, "LoadBalancerArn")
+    arn_filter = _parse_member_list(params, "ListenerArns")
+    results = list(_listeners.values())
+    if lb_arn:
+        results = [l for l in results if l["LoadBalancerArn"] == lb_arn]
+    if arn_filter:
+        results = [l for l in results if l["ListenerArn"] in arn_filter]
+    return _xml(200, "DescribeListeners",
+                f"<Listeners>{''.join(_listener_xml(l) for l in results)}</Listeners>")
+
+
+def _modify_listener(params):
+    arn = _p(params, "ListenerArn")
+    listener = _listeners.get(arn)
+    if not listener:
+        return _error("ListenerNotFound", f"Listener '{arn}' not found.")
+    port = _p(params, "Port")
+    if port:
+        listener["Port"] = int(port)
+    protocol = _p(params, "Protocol")
+    if protocol:
+        listener["Protocol"] = protocol
+    actions = _parse_actions(params, "DefaultActions")
+    if actions:
+        listener["DefaultActions"] = actions
+    return _xml(200, "ModifyListener", f"<Listeners>{_listener_xml(listener)}</Listeners>")
+
+
+def _delete_listener(params):
+    arn = _p(params, "ListenerArn")
+    if arn not in _listeners:
+        return _error("ListenerNotFound", f"Listener '{arn}' not found", 400)
+    _listeners.pop(arn, None)
+    _listener_attrs.pop(arn, None)
+    _tags.pop(arn, None)
+    for rarn in [k for k, v in list(_rules.items()) if v.get("ListenerArn") == arn]:
+        _rules.pop(rarn, None)
+    return _empty("DeleteListener")
+
+
+def _describe_listener_attrs(params):
+    arn = _p(params, "ListenerArn")
+    if arn not in _listeners:
+        return _error("ListenerNotFound", f"Listener '{arn}' not found.")
+    attrs = _listener_attrs.get(arn, [])
+    return _xml(200, "DescribeListenerAttributes",
+                f"<Attributes>{_attrs_xml(attrs)}</Attributes>")
+
+
+def _modify_listener_attrs(params):
+    arn = _p(params, "ListenerArn")
+    if arn not in _listeners:
+        return _error("ListenerNotFound", f"Listener '{arn}' not found.")
+    attrs = _listener_attrs.setdefault(arn, [])
+    idx = {a["Key"]: i for i, a in enumerate(attrs)}
+    i = 1
+    while True:
+        key = _p(params, f"Attributes.member.{i}.Key")
+        if not key:
+            break
+        val = _p(params, f"Attributes.member.{i}.Value")
+        if key in idx:
+            attrs[idx[key]]["Value"] = val
+        else:
+            attrs.append({"Key": key, "Value": val})
+            idx[key] = len(attrs) - 1
+        i += 1
+    return _xml(200, "ModifyListenerAttributes",
+                f"<Attributes>{_attrs_xml(attrs)}</Attributes>")
+
+
+# ---------------------------------------------------------------------------
+# Rule handlers
+# ---------------------------------------------------------------------------
+
+def _create_rule(params):
+    l_arn = _p(params, "ListenerArn")
+    if l_arn not in _listeners:
+        return _error("ListenerNotFound", f"Listener '{l_arn}' not found.")
+    listener = _listeners[l_arn]
+    lb_arn = listener["LoadBalancerArn"]
+    lb_name = _lbs[lb_arn]["LoadBalancerName"]
+    lb_id = lb_arn.split("/")[-1]
+    l_id = l_arn.split("/")[-1]
+    rule_id = _short_id()
+    rule_arn = (f"arn:aws:elasticloadbalancing:{get_region()}:{get_account_id()}"
+                f":listener-rule/app/{lb_name}/{lb_id}/{l_id}/{rule_id}")
+    rule = {
+        "RuleArn": rule_arn, "ListenerArn": l_arn,
+        "Priority": _p(params, "Priority", "1"),
+        "Conditions": _parse_conditions(params),
+        "Actions": _parse_actions(params, "Actions"),
+        "IsDefault": False,
+    }
+    _rules[rule_arn] = rule
+    _tags[rule_arn] = _parse_tags(params)
+    return _xml(200, "CreateRule", f"<Rules>{_rule_xml(rule)}</Rules>")
+
+
+def _describe_rules(params):
+    l_arn = _p(params, "ListenerArn")
+    arn_filter = _parse_member_list(params, "RuleArns")
+    results = list(_rules.values())
+    if l_arn:
+        results = [r for r in results if r.get("ListenerArn") == l_arn]
+    if arn_filter:
+        results = [r for r in results if r["RuleArn"] in arn_filter]
+    return _xml(200, "DescribeRules", f"<Rules>{''.join(_rule_xml(r) for r in results)}</Rules>")
+
+
+def _modify_rule(params):
+    arn = _p(params, "RuleArn")
+    rule = _rules.get(arn)
+    if not rule:
+        return _error("RuleNotFound", f"Rule '{arn}' not found.")
+    conds = _parse_conditions(params)
+    if conds:
+        rule["Conditions"] = conds
+    acts = _parse_actions(params, "Actions")
+    if acts:
+        rule["Actions"] = acts
+    return _xml(200, "ModifyRule", f"<Rules>{_rule_xml(rule)}</Rules>")
+
+
+def _delete_rule(params):
+    arn = _p(params, "RuleArn")
+    if _rules.get(arn, {}).get("IsDefault"):
+        return _error("OperationNotPermitted", "Cannot delete a default rule.")
+    _rules.pop(arn, None)
+    _tags.pop(arn, None)
+    return _empty("DeleteRule")
+
+
+def _set_rule_priorities(params):
+    updated, i = [], 1
+    while True:
+        arn = _p(params, f"RulePriorities.member.{i}.RuleArn")
+        if not arn:
+            break
+        priority = _p(params, f"RulePriorities.member.{i}.Priority")
+        if arn in _rules:
+            _rules[arn]["Priority"] = priority
+            updated.append(_rules[arn])
+        i += 1
+    return _xml(200, "SetRulePriorities",
+                f"<Rules>{''.join(_rule_xml(r) for r in updated)}</Rules>")
+
+
+# ---------------------------------------------------------------------------
+# Target registration handlers
+# ---------------------------------------------------------------------------
+
+def _register_targets(params):
+    tg_arn = _p(params, "TargetGroupArn")
+    if tg_arn not in _tgs:
+        return _error("TargetGroupNotFound", f"Target group '{tg_arn}' not found.")
+    new_tgts = _parse_targets_param(params)
+    existing = _targets.setdefault(tg_arn, [])
+    existing_ids = {t["Id"] for t in existing}
+    for t in new_tgts:
+        if t["Id"] not in existing_ids:
+            existing.append(t)
+            existing_ids.add(t["Id"])
+    return _empty("RegisterTargets")
+
+
+def _deregister_targets(params):
+    tg_arn = _p(params, "TargetGroupArn")
+    if tg_arn not in _tgs:
+        return _error("TargetGroupNotFound", f"Target group '{tg_arn}' not found.")
+    to_remove = {t["Id"] for t in _parse_targets_param(params)}
+    _targets[tg_arn] = [t for t in _targets.get(tg_arn, []) if t["Id"] not in to_remove]
+    return _empty("DeregisterTargets")
+
+
+def _describe_target_health(params):
+    tg_arn = _p(params, "TargetGroupArn")
+    if tg_arn not in _tgs:
+        return _error("TargetGroupNotFound", f"Target group '{tg_arn}' not found.")
+    registered = _targets.get(tg_arn, [])
+    target_filter = {t["Id"] for t in _parse_targets_param(params)}
+    if target_filter:
+        registered = [t for t in registered if t["Id"] in target_filter]
+    default_port = _tgs[tg_arn].get("Port", 80)
+    descs = "".join(
+        f"<member>"
+        f"<Target><Id>{t['Id']}</Id><Port>{t.get('Port', default_port)}</Port></Target>"
+        f"<HealthStatus>healthy</HealthStatus>"
+        f"<TargetHealth><State>healthy</State></TargetHealth>"
+        f"</member>"
+        for t in registered
+    )
+    return _xml(200, "DescribeTargetHealth",
+                f"<TargetHealthDescriptions>{descs}</TargetHealthDescriptions>")
+
+
+# ---------------------------------------------------------------------------
+# Tag handlers
+# ---------------------------------------------------------------------------
+
+def _add_tags(params):
+    arns = _parse_member_list(params, "ResourceArns")
+    new_tags = _parse_tags(params)
+    for arn in arns:
+        existing = _tags.setdefault(arn, [])
+        idx = {t["Key"]: i for i, t in enumerate(existing)}
+        for tag in new_tags:
+            if tag["Key"] in idx:
+                existing[idx[tag["Key"]]]["Value"] = tag["Value"]
+            else:
+                existing.append(tag)
+                idx[tag["Key"]] = len(existing) - 1
+    return _empty("AddTags")
+
+
+def _remove_tags(params):
+    arns = _parse_member_list(params, "ResourceArns")
+    key_set = set(_parse_member_list(params, "TagKeys"))
+    for arn in arns:
+        if arn in _tags:
+            _tags[arn] = [t for t in _tags[arn] if t["Key"] not in key_set]
+    return _empty("RemoveTags")
+
+
+def _describe_tags(params):
+    arns = _parse_member_list(params, "ResourceArns")
+    descs = ""
+    for arn in arns:
+        tags_xml = "".join(
+            f"<member><Key>{t['Key']}</Key><Value>{t['Value']}</Value></member>"
+            for t in _tags.get(arn, [])
+        )
+        descs += f"<member><ResourceArn>{arn}</ResourceArn><Tags>{tags_xml}</Tags></member>"
+    return _xml(200, "DescribeTags", f"<TagDescriptions>{descs}</TagDescriptions>")
+
+
+# ---------------------------------------------------------------------------
+# Action map, request routing, and reset
+# ---------------------------------------------------------------------------
+
+_ACTION_MAP = {
+    "CreateLoadBalancer": _create_lb,
+    "DescribeLoadBalancers": _describe_lbs,
+    "DeleteLoadBalancer": _delete_lb,
+    "DescribeLoadBalancerAttributes": _describe_lb_attrs,
+    "ModifyLoadBalancerAttributes": _modify_lb_attrs,
+    "CreateTargetGroup": _create_tg,
+    "DescribeTargetGroups": _describe_tgs,
+    "ModifyTargetGroup": _modify_tg,
+    "DeleteTargetGroup": _delete_tg,
+    "DescribeTargetGroupAttributes": _describe_tg_attrs,
+    "ModifyTargetGroupAttributes": _modify_tg_attrs,
+    "CreateListener": _create_listener,
+    "DescribeListeners": _describe_listeners,
+    "DescribeListenerAttributes": _describe_listener_attrs,
+    "ModifyListenerAttributes": _modify_listener_attrs,
+    "ModifyListener": _modify_listener,
+    "DeleteListener": _delete_listener,
+    "CreateRule": _create_rule,
+    "DescribeRules": _describe_rules,
+    "ModifyRule": _modify_rule,
+    "DeleteRule": _delete_rule,
+    "SetRulePriorities": _set_rule_priorities,
+    "RegisterTargets": _register_targets,
+    "DeregisterTargets": _deregister_targets,
+    "DescribeTargetHealth": _describe_target_health,
+    "AddTags": _add_tags,
+    "RemoveTags": _remove_tags,
+    "DescribeTags": _describe_tags,
+}
+
+
+async def handle_request(method, path, headers, body, query_params):
+    params = dict(query_params)
+    if method == "POST" and body:
+        raw = body if isinstance(body, str) else body.decode("utf-8", errors="replace")
+        for k, v in parse_qs(raw).items():
+            params[k] = v
+    action = _p(params, "Action")
+    handler = _ACTION_MAP.get(action)
+    if not handler:
+        return _error("InvalidAction", f"Unknown ELBv2 action: {action}", 400)
+    return handler(params)
+
+
+# ---------------------------------------------------------------------------
+# Data-plane: host/name lookup
+# ---------------------------------------------------------------------------
+
+def find_lb_for_host(host):
+    hostname = host.split(":")[0].lower()
+    for lb in _lbs.values():
+        if lb["DNSName"].lower() == hostname:
+            return lb
+        if hostname == f"{lb['LoadBalancerName'].lower()}.alb.localhost":
+            return lb
+    return None
+
+
+def _find_lb_by_name(name):
+    name_lc = name.lower()
+    for lb in _lbs.values():
+        if lb["LoadBalancerName"].lower() == name_lc:
+            return lb
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Data-plane: rule matching
+# ---------------------------------------------------------------------------
+
+def _match_condition(cond, method, path, headers, query_params):
+    field = cond.get("Field", "")
+    values = cond.get("Values", [])
+
+    if field == "path-pattern":
+        return any(fnmatch.fnmatch(path, v) for v in values)
+
+    if field == "host-header":
+        hostname = headers.get("host", "").split(":")[0]
+        return any(fnmatch.fnmatch(hostname, v) for v in values)
+
+    if field == "http-method":
+        return method.upper() in [v.upper() for v in values]
+
+    if field == "query-string":
+        # Values stored as "key=value" strings
+        for v in values:
+            if "=" in v:
+                k, expected = v.split("=", 1)
+                actual = query_params.get(k, [""])[0] if isinstance(query_params.get(k), list) else query_params.get(k, "")
+                if actual != expected:
+                    return False
+            else:
+                if v not in query_params:
+                    return False
+        return True
+
+    if field == "http-header":
+        cfg = cond.get("HttpHeaderConfig", {})
+        hname = cfg.get("HttpHeaderName", "").lower()
+        hvals = cfg.get("Values", values)
+        actual = headers.get(hname, "")
+        return any(fnmatch.fnmatch(actual, v) for v in hvals)
+
+    # source-ip is not implemented (no real network in emulator) — always matches.
+    # Unknown condition types also always match to avoid silently dropping traffic.
+    return True
+
+
+def _rule_sort_key(rule):
+    p = rule.get("Priority", "default")
+    if p == "default":
+        return (1, 0)
+    try:
+        return (0, int(p))
+    except (ValueError, TypeError):
+        return (0, 9999)
+
+
+# ---------------------------------------------------------------------------
+# Data-plane: action execution
+# ---------------------------------------------------------------------------
+
+async def _execute_action(action, method, path, headers, body, query_params):
+    atype = action.get("Type", "").lower()
+
+    if atype == "fixed-response":
+        frc = action.get("FixedResponseConfig", {})
+        code = int(frc.get("StatusCode", "200"))
+        ct = frc.get("ContentType", "text/plain")
+        msg = frc.get("MessageBody", "")
+        return code, {"Content-Type": ct}, msg.encode("utf-8")
+
+    if atype == "redirect":
+        rc = action.get("RedirectConfig", {})
+        code = int(rc.get("StatusCode", "HTTP_301").replace("HTTP_", ""))
+        src_host = headers.get("host", "localhost").split(":")[0]
+        proto = rc.get("Protocol", "#{protocol}").replace("#{protocol}", "http")
+        rhost = rc.get("Host", "#{host}").replace("#{host}", src_host)
+        rport = rc.get("Port", "#{port}").replace("#{port}", "")
+        rpath = rc.get("Path", "/#{path}").replace("#{path}", path.lstrip("/"))
+        location = f"{proto}://{rhost}"
+        if rport and rport not in ("80", "443", ""):
+            location += f":{rport}"
+        location += rpath
+        return code, {"Location": location, "Content-Type": "text/plain"}, b""
+
+    if atype == "forward":
+        tg_arn = action.get("TargetGroupArn", "")
+        return await _forward_to_tg(tg_arn, method, path, headers, body, query_params)
+
+    return (502, {"Content-Type": "application/json"},
+            json.dumps({"message": f"Unsupported action type: {atype}"}).encode())
+
+
+async def _forward_to_tg(tg_arn, method, path, headers, body, query_params):
+    tg = _tgs.get(tg_arn)
+    if not tg:
+        return (502, {"Content-Type": "application/json"},
+                json.dumps({"message": f"Target group '{tg_arn}' not found"}).encode())
+
+    registered = _targets.get(tg_arn, [])
+    if not registered:
+        return (503, {"Content-Type": "application/json"},
+                json.dumps({"message": "No registered targets in target group"}).encode())
+
+    target_type = tg.get("TargetType", "instance")
+
+    if target_type == "lambda":
+        func_id = registered[0]["Id"]
+        func_name = func_id.split(":function:")[-1].split(":")[0] if ":function:" in func_id else func_id
+        return await _invoke_lambda_target(func_name, tg_arn, method, path,
+                                           headers, body, query_params)
+
+    return (502, {"Content-Type": "application/json"},
+            json.dumps({"message": f"Target type '{target_type}' not supported."}).encode())
+
+
+async def _invoke_lambda_target(func_name, tg_arn, method, path, headers, body, query_params):
+    try:
+        from ministack.services import lambda_svc
+    except ImportError:
+        return (502, {"Content-Type": "application/json"},
+                json.dumps({"message": "Lambda service unavailable"}).encode())
+
+    if func_name not in lambda_svc._functions:
+        return (502, {"Content-Type": "application/json"},
+                json.dumps({"message": f"Lambda function '{func_name}' not found"}).encode())
+
+    body_str = None
+    is_b64 = False
+    if body:
+        try:
+            body_str = body.decode("utf-8")
+        except UnicodeDecodeError:
+            body_str = base64.b64encode(body).decode("ascii")
+            is_b64 = True
+
+    qs_single = {k: (v[0] if isinstance(v, list) else v) for k, v in query_params.items()}
+    qs_multi = {k: (v if isinstance(v, list) else [v]) for k, v in query_params.items()}
+
+    event = {
+        "requestContext": {"elb": {"targetGroupArn": tg_arn}},
+        "httpMethod": method.upper(),
+        "path": path,
+        "queryStringParameters": qs_single,
+        "multiValueQueryStringParameters": qs_multi,
+        "headers": {k.lower(): v for k, v in headers.items()},
+        "multiValueHeaders": {k.lower(): [v] for k, v in headers.items()},
+        "body": body_str,
+        "isBase64Encoded": is_b64,
+    }
+
+    _, resp_headers, resp_body = await lambda_svc._invoke(func_name, event, {})
+
+    if resp_headers.get("X-Amz-Function-Error"):
+        raw = resp_body.decode("utf-8", errors="replace") if isinstance(resp_body, bytes) else str(resp_body)
+        return (502, {"Content-Type": "application/json"},
+                json.dumps({"message": f"Lambda error: {raw}"}).encode())
+
+    try:
+        result = json.loads(resp_body) if isinstance(resp_body, bytes) else resp_body
+        if not isinstance(result, dict):
+            return (200, {"Content-Type": "text/plain"},
+                    str(result).encode("utf-8"))
+
+        resp_code = int(result.get("statusCode", 200))
+        out_headers = dict(result.get("headers") or {})
+        for k, vals in (result.get("multiValueHeaders") or {}).items():
+            out_headers[k] = vals[-1]
+
+        out_body = result.get("body", "")
+        if result.get("isBase64Encoded"):
+            out_body = base64.b64decode(out_body)
+        elif isinstance(out_body, str):
+            out_body = out_body.encode("utf-8")
+        elif not isinstance(out_body, bytes):
+            out_body = json.dumps(out_body).encode("utf-8")
+
+        return resp_code, out_headers, out_body
+
+    except Exception:
+        raw = resp_body if isinstance(resp_body, bytes) else str(resp_body).encode()
+        return 200, {"Content-Type": "text/plain"}, raw
+
+
+# ---------------------------------------------------------------------------
+# Data-plane: main dispatcher
+# ---------------------------------------------------------------------------
+
+async def dispatch_request(lb, method, path, headers, body, query_params, port=80):
+    lb_arn = lb["LoadBalancerArn"]
+
+    candidates = [l for l in _listeners.values() if l["LoadBalancerArn"] == lb_arn]
+    matching = [l for l in candidates if l.get("Port", 80) == port] or candidates
+
+    if not matching:
+        return (503, {"Content-Type": "application/json"},
+                json.dumps({"message": f"No listeners configured for '{lb['LoadBalancerName']}'"}).encode())
+
+    listener = matching[0]
+    l_arn = listener["ListenerArn"]
+
+    listener_rules = sorted(
+        (r for r in _rules.values() if r.get("ListenerArn") == l_arn),
+        key=_rule_sort_key,
+    )
+
+    for rule in listener_rules:
+        conditions = rule.get("Conditions", [])
+        is_default = rule.get("IsDefault", False)
+        matched = is_default or all(
+            _match_condition(c, method, path, headers, query_params)
+            for c in conditions
+        )
+        if matched:
+            actions = rule.get("Actions") or listener.get("DefaultActions", [])
+            if actions:
+                return await _execute_action(actions[0], method, path,
+                                             headers, body, query_params)
+
+    return (502, {"Content-Type": "application/json"},
+            json.dumps({"message": "No matching ALB rule found"}).encode())
+
+
+# ---------------------------------------------------------------------------
+# Supported Actions
+# ---------------------------------------------------------------------------
+
+SUPPORTED_ACTIONS = [
+    "CreateLoadBalancer", "DeleteLoadBalancer", "DescribeLoadBalancers",
+    "ModifyLoadBalancerAttributes", "AddTags", "RemoveTags", "DescribeTags",
+    "CreateTargetGroup", "DeleteTargetGroup", "DescribeTargetGroups",
+    "ModifyTargetGroup", "ModifyTargetGroupAttributes", "CreateListener",
+    "DeleteListener", "DescribeListeners", "ModifyListener", "CreateRule",
+    "DeleteRule", "DescribeRules", "ModifyRule", "RegisterTargets",
+    "DeregisterTargets", "DescribeTargetHealth", "SetRulePriorities",
+]
+
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+def get_state_summary() -> dict:
+    return {
+        "load_balancers": {"count": len(_lbs), "names": list(_lbs.keys())},
+        "target_groups": {"count": len(_tgs), "names": list(_tgs.keys())},
+        "listeners": {"count": len(_listeners), "ids": list(_listeners.keys())},
+        "rules": {"count": len(_rules), "ids": list(_rules.keys())},
+        "targets": {"count": sum(len(tgts) for tgts in _targets.values())},
+        "tags": {"count": sum(len(tags) for tags in _tags.values())},
+        "load_balancer_attributes": {"count": sum(len(attrs) for attrs in _lb_attrs.values())},
+        "target_group_attributes": {"count": sum(len(attrs) for attrs in _tg_attrs.values())},
+    }
+
+
+def reset():
+    _lbs.clear()
+    _tgs.clear()
+    _listeners.clear()
+    _rules.clear()
+    _targets.clear()
+    _tags.clear()
+    _lb_attrs.clear()
+    _tg_attrs.clear()
+    _listener_attrs.clear()

aws_infra/ministack/services/apigateway.py

@@ -0,0 +1,1456 @@
+"""
+API Gateway HTTP API v2 Emulator.
+
+Control plane endpoints implemented:
+  POST   /v2/apis                                    — CreateApi
+  GET    /v2/apis                                    — GetApis
+  GET    /v2/apis/{apiId}                            — GetApi
+  PATCH  /v2/apis/{apiId}                            — UpdateApi
+  DELETE /v2/apis/{apiId}                            — DeleteApi
+  POST   /v2/apis/{apiId}/routes                     — CreateRoute
+  GET    /v2/apis/{apiId}/routes                     — GetRoutes
+  GET    /v2/apis/{apiId}/routes/{routeId}           — GetRoute
+  PATCH  /v2/apis/{apiId}/routes/{routeId}           — UpdateRoute
+  DELETE /v2/apis/{apiId}/routes/{routeId}           — DeleteRoute
+  POST   /v2/apis/{apiId}/integrations               — CreateIntegration
+  GET    /v2/apis/{apiId}/integrations               — GetIntegrations
+  GET    /v2/apis/{apiId}/integrations/{integId}     — GetIntegration
+  PATCH  /v2/apis/{apiId}/integrations/{integId}     — UpdateIntegration
+  DELETE /v2/apis/{apiId}/integrations/{integId}     — DeleteIntegration
+  POST   /v2/apis/{apiId}/stages                     — CreateStage
+  GET    /v2/apis/{apiId}/stages                     — GetStages
+  GET    /v2/apis/{apiId}/stages/{stageName}         — GetStage
+  PATCH  /v2/apis/{apiId}/stages/{stageName}         — UpdateStage
+  DELETE /v2/apis/{apiId}/stages/{stageName}         — DeleteStage
+  POST   /v2/apis/{apiId}/deployments                — CreateDeployment
+  GET    /v2/apis/{apiId}/deployments                — GetDeployments
+  GET    /v2/apis/{apiId}/deployments/{deployId}     — GetDeployment
+  DELETE /v2/apis/{apiId}/deployments/{deployId}     — DeleteDeployment
+  GET    /v2/tags/{resourceArn}                      — GetTags
+  POST   /v2/tags/{resourceArn}                      — TagResource
+  DELETE /v2/tags/{resourceArn}                      — UntagResource
+  POST   /v2/apis/{apiId}/authorizers               — CreateAuthorizer
+  GET    /v2/apis/{apiId}/authorizers               — GetAuthorizers
+  GET    /v2/apis/{apiId}/authorizers/{authId}      — GetAuthorizer
+  PATCH  /v2/apis/{apiId}/authorizers/{authId}      — UpdateAuthorizer
+  DELETE /v2/apis/{apiId}/authorizers/{authId}      — DeleteAuthorizer
+
+Data plane:
+  Requests to /{apiId}.execute-api.localhost/{stage}/{path} are forwarded to
+  Lambda (AWS_PROXY) or HTTP backends (HTTP_PROXY) via handle_execute().
+"""
+
+import asyncio
+import json
+import logging
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+
+from ministack.core.responses import AccountScopedDict, get_account_id, error_response_json, new_uuid, get_region
+
+_HOST = os.environ.get("MINISTACK_HOST", "localhost")
+_PORT = os.environ.get("GATEWAY_PORT", "4566")
+
+logger = logging.getLogger("apigateway")
+
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+
+# ---- Module-level state ----
+_apis = AccountScopedDict()          # api_id -> api object
+_routes = AccountScopedDict()        # api_id -> {route_id -> route object}
+_integrations = AccountScopedDict()  # api_id -> {integration_id -> integration object}
+_stages = AccountScopedDict()        # api_id -> {stage_name -> stage object}
+_deployments = AccountScopedDict()   # api_id -> {deployment_id -> deployment object}
+_authorizers = AccountScopedDict()   # api_id -> {authorizer_id -> authorizer object}
+_api_tags = AccountScopedDict()      # resource_arn -> {key -> value}
+_route_responses = AccountScopedDict()         # api_id -> {route_id -> {rr_id -> route_response}}
+_integration_responses = AccountScopedDict()   # api_id -> {integration_id -> {ir_id -> int_response}}
+
+# WebSocket connection registry — connections are not per-account-scoped at the store level
+# because the @connections management API may arrive on any host/account; instead we store
+# the owning account id inside each connection record and check on access.
+# { connectionId -> {apiId, accountId, stage, connectedAt, sourceIp, outbox (asyncio.Queue),
+#                    close_event (asyncio.Event), lastActiveAt, identity} }
+_ws_connections: dict = {}
+
+
+# ---- Response helpers ----
+
+def _apigw_response(data: dict, status: int = 200) -> tuple:
+    """API Gateway v2 uses application/json (not application/x-amz-json-1.0)."""
+    return status, {"Content-Type": "application/json"}, json.dumps(data, ensure_ascii=False).encode("utf-8")
+
+
+def _apigw_error(code: str, message: str, status: int) -> tuple:
+    return status, {"Content-Type": "application/json"}, json.dumps({"message": message, "__type": code}, ensure_ascii=False).encode("utf-8")
+
+
+def _api_arn(api_id: str) -> str:
+    return f"arn:aws:apigateway:{get_region()}::/apis/{api_id}"
+
+
+SUPPORTED_ACTIONS = [
+    "CreateApi", "GetApis", "GetApi", "UpdateApi", "DeleteApi",
+    "CreateRoute", "GetRoutes", "GetRoute", "UpdateRoute", "DeleteRoute",
+    "CreateIntegration", "GetIntegrations", "GetIntegration",
+    "UpdateIntegration", "DeleteIntegration", "CreateStage", "GetStages",
+    "GetStage", "UpdateStage", "DeleteStage", "CreateDeployment",
+    "GetDeployments", "GetDeployment", "DeleteDeployment", "GetTags",
+    "TagResource", "UntagResource", "CreateAuthorizer", "GetAuthorizers",
+    "GetAuthorizer", "UpdateAuthorizer", "DeleteAuthorizer",
+]
+
+
+# ---- Persistence hooks ----
+
+def get_state() -> dict:
+    """Return full module state for persistence."""
+    return {
+        "apis": _apis,
+        "routes": _routes,
+        "integrations": _integrations,
+        "stages": _stages,
+        "deployments": _deployments,
+        "authorizers": _authorizers,
+        "api_tags": _api_tags,
+        "route_responses": _route_responses,
+        "integration_responses": _integration_responses,
+    }
+
+
+def load_persisted_state(data: dict) -> None:
+    """Restore module state from a previously persisted snapshot."""
+    _apis.update(data.get("apis", {}))
+    _routes.update(data.get("routes", {}))
+    _integrations.update(data.get("integrations", {}))
+    _stages.update(data.get("stages", {}))
+    _deployments.update(data.get("deployments", {}))
+    _authorizers.update(data.get("authorizers", {}))
+    _api_tags.update(data.get("api_tags", {}))
+    _route_responses.update(data.get("route_responses", {}))
+    _integration_responses.update(data.get("integration_responses", {}))
+
+
+# ---- Control plane router ----
+
+async def handle_request(method, path, headers, body, query_params):
+    """Route API Gateway v2 control plane requests."""
+    # Dispatch v1 REST API requests first
+    parts = [p for p in path.strip("/").split("/") if p]
+    if parts and parts[0] in ("restapis", "apikeys", "usageplans", "domainnames", "tags"):
+        from ministack.services import apigateway_v1
+        return await apigateway_v1.handle_request(method, path, headers, body, query_params)
+
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError:
+        data = {}
+
+    # Minimum expected: ["v2", <resource>]
+
+    if not parts or parts[0] != "v2":
+        return _apigw_error("NotFoundException", f"Unknown path: {path}", 404)
+
+    resource = parts[1] if len(parts) > 1 else ""
+
+    # /v2/tags/{resourceArn} — tags endpoint
+    if resource == "tags":
+        # resourceArn may contain slashes; rejoin everything after "tags/"
+        resource_arn = "/".join(parts[2:]) if len(parts) > 2 else ""
+        if method == "GET":
+            return _get_tags(resource_arn)
+        if method == "POST":
+            return _tag_resource(resource_arn, data)
+        if method == "DELETE":
+            tag_keys = query_params.get("tagKeys", [])
+            if isinstance(tag_keys, str):
+                tag_keys = [tag_keys]
+            return _untag_resource(resource_arn, tag_keys)
+
+    if resource == "apis":
+        api_id = parts[2] if len(parts) > 2 else None
+        sub = parts[3] if len(parts) > 3 else None
+        sub_id = parts[4] if len(parts) > 4 else None
+
+        # /v2/apis
+        if not api_id:
+            if method == "POST":
+                return _create_api(data)
+            if method == "GET":
+                return _get_apis()
+
+        # /v2/apis/{apiId}
+        if api_id and not sub:
+            if method == "GET":
+                return _get_api(api_id)
+            if method == "DELETE":
+                return _delete_api(api_id)
+            if method == "PATCH":
+                return _update_api(api_id, data)
+
+        # /v2/apis/{apiId}/routes[/{routeId}[/routeresponses[/{routeResponseId}]]]
+        if api_id and sub == "routes":
+            rr_segment = parts[5] if len(parts) > 5 else None
+            rr_id = parts[6] if len(parts) > 6 else None
+            if not sub_id:
+                if method == "POST":
+                    return _create_route(api_id, data)
+                if method == "GET":
+                    return _get_routes(api_id)
+            elif rr_segment == "routeresponses":
+                if not rr_id:
+                    if method == "POST":
+                        return _create_route_response(api_id, sub_id, data)
+                    if method == "GET":
+                        return _get_route_responses(api_id, sub_id)
+                else:
+                    if method == "GET":
+                        return _get_route_response(api_id, sub_id, rr_id)
+                    if method == "PATCH":
+                        return _update_route_response(api_id, sub_id, rr_id, data)
+                    if method == "DELETE":
+                        return _delete_route_response(api_id, sub_id, rr_id)
+            else:
+                if method == "GET":
+                    return _get_route(api_id, sub_id)
+                if method == "PATCH":
+                    return _update_route(api_id, sub_id, data)
+                if method == "DELETE":
+                    return _delete_route(api_id, sub_id)
+
+        # /v2/apis/{apiId}/integrations[/{integrationId}[/integrationresponses[/{irId}]]]
+        if api_id and sub == "integrations":
+            ir_segment = parts[5] if len(parts) > 5 else None
+            ir_id = parts[6] if len(parts) > 6 else None
+            if not sub_id:
+                if method == "POST":
+                    return _create_integration(api_id, data)
+                if method == "GET":
+                    return _get_integrations(api_id)
+            elif ir_segment == "integrationresponses":
+                if not ir_id:
+                    if method == "POST":
+                        return _create_integration_response(api_id, sub_id, data)
+                    if method == "GET":
+                        return _get_integration_responses(api_id, sub_id)
+                else:
+                    if method == "GET":
+                        return _get_integration_response(api_id, sub_id, ir_id)
+                    if method == "PATCH":
+                        return _update_integration_response(api_id, sub_id, ir_id, data)
+                    if method == "DELETE":
+                        return _delete_integration_response(api_id, sub_id, ir_id)
+            else:
+                if method == "GET":
+                    return _get_integration(api_id, sub_id)
+                if method == "PATCH":
+                    return _update_integration(api_id, sub_id, data)
+                if method == "DELETE":
+                    return _delete_integration(api_id, sub_id)
+
+        # /v2/apis/{apiId}/stages[/{stageName}]
+        if api_id and sub == "stages":
+            if not sub_id:
+                if method == "POST":
+                    return _create_stage(api_id, data)
+                if method == "GET":
+                    return _get_stages(api_id)
+            else:
+                if method == "GET":
+                    return _get_stage(api_id, sub_id)
+                if method == "PATCH":
+                    return _update_stage(api_id, sub_id, data)
+                if method == "DELETE":
+                    return _delete_stage(api_id, sub_id)
+
+        # /v2/apis/{apiId}/deployments[/{deploymentId}]
+        if api_id and sub == "deployments":
+            if not sub_id:
+                if method == "POST":
+                    return _create_deployment(api_id, data)
+                if method == "GET":
+                    return _get_deployments(api_id)
+            else:
+                if method == "GET":
+                    return _get_deployment(api_id, sub_id)
+                if method == "DELETE":
+                    return _delete_deployment(api_id, sub_id)
+
+        # /v2/apis/{apiId}/authorizers[/{authorizerId}]
+        if api_id and sub == "authorizers":
+            if not sub_id:
+                if method == "POST":
+                    return _create_authorizer(api_id, data)
+                if method == "GET":
+                    return _get_authorizers(api_id)
+            else:
+                if method == "GET":
+                    return _get_authorizer(api_id, sub_id)
+                if method == "PATCH":
+                    return _update_authorizer(api_id, sub_id, data)
+                if method == "DELETE":
+                    return _delete_authorizer(api_id, sub_id)
+
+    return _apigw_error("NotFoundException", f"Unknown API Gateway path: {path}", 404)
+
+
+# ---- Data plane ----
+
+def _cors_response_headers(cors_cfg: dict, origin: str) -> dict:
+    """Build CORS response headers for a non-OPTIONS dispatched response.
+
+    Per AWS (https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html):
+      - If Origin matches allow_origins (or allow_origins contains "*"), echo
+        the caller's Origin back (or "*"); else omit CORS headers entirely.
+      - allow_credentials is only emitted when true, and requires a concrete
+        origin — never paired with "*".
+      - expose_headers / max_age / etc. are attached if configured.
+    """
+    if not cors_cfg:
+        return {}
+    allowed_origins = [o.lower() for o in cors_cfg.get("allowOrigins", [])]
+    origin_lc = (origin or "").lower()
+    if allowed_origins == ["*"]:
+        allow_origin_value = "*"
+    elif origin_lc and origin_lc in allowed_origins:
+        allow_origin_value = origin  # echo exact caller-supplied casing
+    else:
+        return {}
+
+    out: dict = {"Access-Control-Allow-Origin": allow_origin_value}
+    if cors_cfg.get("allowCredentials") and allow_origin_value != "*":
+        out["Access-Control-Allow-Credentials"] = "true"
+    if cors_cfg.get("exposeHeaders"):
+        out["Access-Control-Expose-Headers"] = ",".join(cors_cfg["exposeHeaders"])
+    if "Origin" not in out.get("Vary", ""):
+        out["Vary"] = "Origin"
+    return out
+
+
+def _cors_preflight_response(cors_cfg: dict, origin: str) -> tuple:
+    """Build the full OPTIONS preflight response from corsConfiguration."""
+    if not cors_cfg:
+        # AWS behaviour: API without CORS configured returns 403 on preflight.
+        return 403, {"Content-Type": "application/json"}, json.dumps(
+            {"message": "CORS not configured"}
+        ).encode()
+
+    base = _cors_response_headers(cors_cfg, origin)
+    if not base:
+        # Origin not in allow_origins — 403, no CORS headers echoed back.
+        return 403, {"Content-Type": "application/json"}, json.dumps(
+            {"message": "CORS origin denied"}
+        ).encode()
+
+    if cors_cfg.get("allowMethods"):
+        base["Access-Control-Allow-Methods"] = ",".join(cors_cfg["allowMethods"])
+    if cors_cfg.get("allowHeaders"):
+        base["Access-Control-Allow-Headers"] = ",".join(cors_cfg["allowHeaders"])
+    if cors_cfg.get("maxAge") is not None:
+        base["Access-Control-Max-Age"] = str(cors_cfg["maxAge"])
+    base["Content-Length"] = "0"
+    return 204, base, b""
+
+
+async def handle_execute(api_id, stage, path, method, headers, body, query_params):
+    """Execute an API request through a deployed API (data plane)."""
+    api = _apis.get(api_id)
+    if not api:
+        return 404, {"Content-Type": "application/json"}, json.dumps({"message": "Not Found"}).encode()
+
+    # CORS preflight: served from the API's corsConfiguration before any route
+    # matching, because AWS responds to OPTIONS itself without invoking the
+    # integration. (#406)
+    cors_cfg = api.get("corsConfiguration") or {}
+    if method == "OPTIONS":
+        return _cors_preflight_response(cors_cfg, headers.get("origin") or headers.get("Origin", ""))
+
+    api_stages = _stages.get(api_id, {})
+    if stage not in api_stages and stage != "$default":
+        return 404, {"Content-Type": "application/json"}, json.dumps({"message": f"Stage '{stage}' not found"}).encode()
+
+    route = _match_route(api_id, method, path)
+    if not route:
+        return 404, {"Content-Type": "application/json"}, json.dumps({"message": "No route found"}).encode()
+
+    integration_id = route.get("target", "").replace("integrations/", "")
+    integration = _integrations.get(api_id, {}).get(integration_id)
+    if not integration:
+        return 500, {"Content-Type": "application/json"}, json.dumps({"message": "No integration configured"}).encode()
+
+    integration_type = integration.get("integrationType", "")
+
+    if integration_type == "AWS_PROXY":
+        route_key = route.get("routeKey", "$default")
+        path_params = None
+        rk_parts = route_key.split(" ", 1)
+        if len(rk_parts) == 2:
+            path_params = _extract_path_params(rk_parts[1], path) or None
+        response = await _invoke_lambda_proxy(integration, api_id, stage, path, method, headers, body, query_params, route_key, path_params)
+    elif integration_type == "HTTP_PROXY":
+        response = await _invoke_http_proxy(integration, path, method, headers, body, query_params)
+    else:
+        return 500, {"Content-Type": "application/json"}, json.dumps({"message": f"Unsupported integration type: {integration_type}"}).encode()
+
+    # Decorate dispatched response with per-API CORS headers (#406) — AWS adds
+    # these in front of the integration response for non-OPTIONS requests.
+    if cors_cfg:
+        status, resp_headers, resp_body = response
+        resp_headers.update(_cors_response_headers(cors_cfg, headers.get("origin") or headers.get("Origin", "")))
+        response = status, resp_headers, resp_body
+    return response
+
+
+def _match_route(api_id, method, path):
+    """Find the best matching route for method+path. $default route is the fallback."""
+    routes = _routes.get(api_id, {})
+    # First pass: look for a specific method+path match (skip $default)
+    for route in routes.values():
+        key = route.get("routeKey", "")
+        if key == "$default":
+            continue
+        parts = key.split(" ", 1)
+        if len(parts) == 2:
+            r_method, r_path = parts
+            if (r_method == "ANY" or r_method == method) and _path_matches(r_path, path):
+                return route
+    # Second pass: $default catch-all
+    for route in routes.values():
+        if route.get("routeKey") == "$default":
+            return route
+    return None
+
+
+def _extract_path_params(route_path: str, request_path: str) -> dict | None:
+    """
+    Extract path parameter values from a request path using the route template.
+
+    Returns a dict of {paramName: value} on match, or None if no match.
+    Supports:
+      {param}   — single path segment (no slashes)
+      {proxy+}  — greedy match (one or more path segments, may include slashes)
+    """
+    parts = re.split(r"(\{[^}]+\})", route_path)
+    pattern_parts = []
+    param_names = []
+    for part in parts:
+        if part.startswith("{") and part.endswith("}"):
+            inner = part[1:-1]
+            if inner.endswith("+"):
+                param_names.append(inner[:-1])
+                pattern_parts.append("(.+)")
+            else:
+                param_names.append(inner)
+                pattern_parts.append("([^/]+)")
+        else:
+            pattern_parts.append(re.escape(part))
+    m = re.fullmatch("".join(pattern_parts), request_path)
+    if not m:
+        return None
+    return dict(zip(param_names, m.groups())) if param_names else {}
+
+
+def _path_matches(route_path: str, request_path: str) -> bool:
+    """Match a route path against a request path."""
+    return _extract_path_params(route_path, request_path) is not None
+
+
+async def _invoke_lambda_proxy(integration, api_id, stage, path, method, headers, body, query_params, route_key="$default", path_params=None):
+    """Invoke a Lambda function using the API Gateway v2 proxy event format."""
+    from ministack.core.lambda_runtime import get_or_create_worker
+    from ministack.services import lambda_svc
+
+    # integrationUri is typically a Lambda ARN; strip the trailing /invocations
+    # that the apigateway:lambda:path form appends, then parse name + qualifier.
+    # Qualified aliases (arn:...:function:<name>:<alias>) must resolve to the
+    # alias's target version, not be treated as the function name itself (#407).
+    uri = integration.get("integrationUri", "").replace("/invocations", "")
+    func_name, qualifier = lambda_svc._resolve_name_and_qualifier(uri)
+    func_data, func_config = lambda_svc._get_func_record_for_qualifier(func_name, qualifier)
+    if func_data is None:
+        return 502, {"Content-Type": "application/json"}, json.dumps({
+            "message": f"Lambda function '{func_name}'" +
+                       (f" (qualifier '{qualifier}')" if qualifier else "") +
+                       " not found"
+        }).encode()
+
+    # Build API Gateway v2 proxy event (payload format 2.0)
+    # AWS API Gateway v2 joins multi-value query params with commas
+    qs = {k: ",".join(v) for k, v in query_params.items()} if query_params else None
+    raw_qs = "&".join(f"{k}={val}" for k, vals in query_params.items() for val in vals)
+    event = {
+        "version": "2.0",
+        "routeKey": route_key,
+        "rawPath": path,
+        "rawQueryString": raw_qs,
+        "headers": dict(headers),
+        "queryStringParameters": qs,
+        "requestContext": {
+            "accountId": get_account_id(),
+            "apiId": api_id,
+            "domainName": f"{api_id}.execute-api.{_HOST}",
+            "http": {
+                "method": method,
+                "path": path,
+                "protocol": "HTTP/1.1",
+                "sourceIp": "127.0.0.1",
+                "userAgent": headers.get("user-agent", ""),
+            },
+            "requestId": new_uuid(),
+            "routeKey": route_key,
+            "stage": stage,
+            "time": time.strftime("%d/%b/%Y:%H:%M:%S +0000"),
+            "timeEpoch": int(time.time() * 1000),
+        },
+        "pathParameters": path_params,
+        "body": body.decode("utf-8", errors="replace") if body else None,
+        "isBase64Encoded": False,
+    }
+
+    code_zip = func_data.get("code_zip")
+    runtime = func_config.get("Runtime", "")
+    if code_zip and runtime.startswith(("python", "nodejs")):
+        # Key the worker by name+qualifier so versioned / aliased invocations
+        # use their own cached process, matching Lambda.Invoke semantics.
+        worker_key = f"{func_name}:{qualifier}" if qualifier else func_name
+        worker = get_or_create_worker(worker_key, func_config, code_zip)
+        result = await asyncio.to_thread(worker.invoke, event, new_uuid())
+        if result.get("status") == "error":
+            return 502, {"Content-Type": "application/json"}, json.dumps({"message": result.get("error")}).encode()
+        lambda_response = result.get("result", {})
+    else:
+        lambda_response = {"statusCode": 200, "body": "Mock response"}
+
+    status = lambda_response.get("statusCode", 200)
+    resp_headers = {"Content-Type": "application/json"}
+    resp_headers.update(lambda_response.get("headers", {}))
+    resp_body = lambda_response.get("body", "")
+    if isinstance(resp_body, str):
+        resp_body = resp_body.encode("utf-8")
+    elif isinstance(resp_body, dict):
+        resp_body = json.dumps(resp_body, ensure_ascii=False).encode("utf-8")
+
+    return status, resp_headers, resp_body
+
+
+async def _invoke_http_proxy(integration, path, method, headers, body, query_params):
+    """Forward a request to an HTTP backend."""
+    uri = integration.get("integrationUri", "")
+    url = uri.rstrip("/") + path
+
+    req = urllib.request.Request(url, data=body or None, method=method)
+    for k, v in headers.items():
+        if k.lower() not in ("host", "content-length"):
+            req.add_header(k, v)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            resp_body = resp.read()
+            resp_headers = {"Content-Type": resp.headers.get("Content-Type", "application/json")}
+            return resp.status, resp_headers, resp_body
+    except urllib.error.HTTPError as e:
+        return e.code, {"Content-Type": "application/json"}, e.read()
+    except Exception as ex:
+        return 502, {"Content-Type": "application/json"}, json.dumps({"message": str(ex)}).encode()
+
+
+# ---- Control plane: APIs ----
+
+def _resolve_custom_api_id(tags: dict, existing: "AccountScopedDict") -> str | None:
+    """Return a caller-pinned API id from the ``ms-custom-id`` tag, or None
+    if no tag is set (issue #400).
+
+    Raises ``ValueError`` if the requested id is already in use in the caller's
+    account, so misconfigs surface immediately instead of silently falling back
+    to a random id.
+
+    ``ls-custom-id`` (LocalStack's tag) is intentionally NOT supported — callers
+    hitting it get a clear ``BadRequestException`` pointing them at
+    ``ms-custom-id`` so the ministack-native key is the only contract."""
+    if not isinstance(tags, dict):
+        return None
+    if "ls-custom-id" in tags and "ms-custom-id" not in tags:
+        raise ValueError(
+            "ls-custom-id tag is not supported; use 'ms-custom-id' instead"
+        )
+    custom = tags.get("ms-custom-id")
+    if not custom:
+        return None
+    if custom in existing:
+        raise ValueError(
+            f"API id '{custom}' (from ms-custom-id tag) is already in use"
+        )
+    return str(custom)
+
+
+def _create_api(data):
+    tags = data.get("tags", {})
+    try:
+        api_id = _resolve_custom_api_id(tags, _apis) or new_uuid()[:8]
+    except ValueError as exc:
+        msg = str(exc)
+        if "already in use" in msg:
+            return _apigw_error("ConflictException", msg, 409)
+        return _apigw_error("BadRequestException", msg, 400)
+    protocol = data.get("protocolType", "HTTP")
+    # AWS defaults: HTTP → "$request.method $request.path"; WEBSOCKET → "$request.body.action".
+    default_rse = "$request.body.action" if protocol == "WEBSOCKET" else "$request.method $request.path"
+    api = {
+        "apiId": api_id,
+        "name": data.get("name", "unnamed"),
+        "protocolType": protocol,
+        "apiEndpoint": f"http://{api_id}.execute-api.{_HOST}:{_PORT}",
+        "createdDate": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "routeSelectionExpression": data.get("routeSelectionExpression", default_rse),
+        "apiKeySelectionExpression": data.get("apiKeySelectionExpression", "$request.header.x-api-key"),
+        "tags": data.get("tags", {}),
+        "disableSchemaValidation": data.get("disableSchemaValidation", False),
+        "disableExecuteApiEndpoint": data.get("disableExecuteApiEndpoint", False),
+        "version": data.get("version", ""),
+        "description": data.get("description", ""),
+    }
+    if data.get("corsConfiguration"):
+        api["corsConfiguration"] = data["corsConfiguration"]
+    _apis[api_id] = api
+    _routes[api_id] = {}
+    _integrations[api_id] = {}
+    _stages[api_id] = {}
+    _deployments[api_id] = {}
+    _api_tags[_api_arn(api_id)] = dict(data.get("tags", {}))
+    return _apigw_response(api, 201)
+
+
+def _get_api(api_id):
+    api = _apis.get(api_id)
+    if not api:
+        return _apigw_error("NotFoundException", f"API {api_id} not found", 404)
+    return _apigw_response(api)
+
+
+def _get_apis():
+    return _apigw_response({"items": list(_apis.values()), "nextToken": None})
+
+
+def _delete_api(api_id):
+    _apis.pop(api_id, None)
+    _routes.pop(api_id, None)
+    _integrations.pop(api_id, None)
+    _stages.pop(api_id, None)
+    _deployments.pop(api_id, None)
+    _api_tags.pop(_api_arn(api_id), None)
+    return 204, {}, b""
+
+
+def _update_api(api_id, data):
+    api = _apis.get(api_id)
+    if not api:
+        return _apigw_error("NotFoundException", f"API {api_id} not found", 404)
+    for k in ("name", "corsConfiguration", "routeSelectionExpression",
+              "disableSchemaValidation", "disableExecuteApiEndpoint", "version"):
+        if k in data:
+            api[k] = data[k]
+    return _apigw_response(api)
+
+
+# ---- Control plane: Routes ----
+
+def _create_route(api_id, data):
+    if api_id not in _apis:
+        return _apigw_error("NotFoundException", f"API {api_id} not found", 404)
+    route_id = new_uuid()[:8]
+    route = {
+        "routeId": route_id,
+        "routeKey": data.get("routeKey", "$default"),
+        "target": data.get("target", ""),
+        "authorizationType": data.get("authorizationType", "NONE"),
+        "apiKeyRequired": data.get("apiKeyRequired", False),
+        "operationName": data.get("operationName", ""),
+        "requestModels": data.get("requestModels", {}),
+        "requestParameters": data.get("requestParameters", {}),
+    }
+    _routes.setdefault(api_id, {})[route_id] = route
+    return _apigw_response(route, 201)
+
+
+def _get_routes(api_id):
+    return _apigw_response({"items": list(_routes.get(api_id, {}).values()), "nextToken": None})
+
+
+def _get_route(api_id, route_id):
+    route = _routes.get(api_id, {}).get(route_id)
+    if not route:
+        return _apigw_error("NotFoundException", f"Route {route_id} not found", 404)
+    return _apigw_response(route)
+
+
+def _update_route(api_id, route_id, data):
+    route = _routes.get(api_id, {}).get(route_id)
+    if not route:
+        return _apigw_error("NotFoundException", f"Route {route_id} not found", 404)
+    for k in ("routeKey", "target", "authorizationType", "apiKeyRequired", "operationName"):
+        if k in data:
+            route[k] = data[k]
+    return _apigw_response(route)
+
+
+def _delete_route(api_id, route_id):
+    _routes.get(api_id, {}).pop(route_id, None)
+    return 204, {}, b""
+
+
+# ---- Control plane: Integrations ----
+
+def _create_integration(api_id, data):
+    if api_id not in _apis:
+        return _apigw_error("NotFoundException", f"API {api_id} not found", 404)
+    int_id = new_uuid()[:8]
+    integration = {
+        "integrationId": int_id,
+        "integrationType": data.get("integrationType", "AWS_PROXY"),
+        "integrationUri": data.get("integrationUri", ""),
+        "integrationMethod": data.get("integrationMethod", "POST"),
+        "payloadFormatVersion": data.get("payloadFormatVersion", "2.0"),
+        "timeoutInMillis": data.get("timeoutInMillis", 30000),
+        "connectionType": data.get("connectionType", "INTERNET"),
+        "description": data.get("description", ""),
+        "requestParameters": data.get("requestParameters", {}),
+        "requestTemplates": data.get("requestTemplates", {}),
+        "responseParameters": data.get("responseParameters", {}),
+    }
+    _integrations.setdefault(api_id, {})[int_id] = integration
+    return _apigw_response(integration, 201)
+
+
+def _get_integrations(api_id):
+    return _apigw_response({"items": list(_integrations.get(api_id, {}).values()), "nextToken": None})
+
+
+def _get_integration(api_id, int_id):
+    integration = _integrations.get(api_id, {}).get(int_id)
+    if not integration:
+        return _apigw_error("NotFoundException", f"Integration {int_id} not found", 404)
+    return _apigw_response(integration)
+
+
+def _update_integration(api_id, int_id, data):
+    integration = _integrations.get(api_id, {}).get(int_id)
+    if not integration:
+        return _apigw_error("NotFoundException", f"Integration {int_id} not found", 404)
+    for k in ("integrationType", "integrationUri", "integrationMethod",
+              "payloadFormatVersion", "timeoutInMillis", "connectionType",
+              "description", "requestParameters", "requestTemplates", "responseParameters"):
+        if k in data:
+            integration[k] = data[k]
+    return _apigw_response(integration)
+
+
+def _delete_integration(api_id, int_id):
+    _integrations.get(api_id, {}).pop(int_id, None)
+    return 204, {}, b""
+
+
+# ---- Control plane: Stages ----
+
+def _create_stage(api_id, data):
+    if api_id not in _apis:
+        return _apigw_error("NotFoundException", f"API {api_id} not found", 404)
+    stage_name = data.get("stageName", "$default")
+    stage = {
+        "stageName": stage_name,
+        "autoDeploy": data.get("autoDeploy", False),
+        "createdDate": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "lastUpdatedDate": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "stageVariables": data.get("stageVariables", {}),
+        "description": data.get("description", ""),
+        "defaultRouteSettings": data.get("defaultRouteSettings", {}),
+        "routeSettings": data.get("routeSettings", {}),
+        "tags": data.get("tags", {}),
+    }
+    _stages.setdefault(api_id, {})[stage_name] = stage
+    return _apigw_response(stage, 201)
+
+
+def _get_stages(api_id):
+    return _apigw_response({"items": list(_stages.get(api_id, {}).values()), "nextToken": None})
+
+
+def _get_stage(api_id, stage_name):
+    stage = _stages.get(api_id, {}).get(stage_name)
+    if not stage:
+        return _apigw_error("NotFoundException", f"Stage '{stage_name}' not found", 404)
+    return _apigw_response(stage)
+
+
+def _update_stage(api_id, stage_name, data):
+    stage = _stages.get(api_id, {}).get(stage_name)
+    if not stage:
+        return _apigw_error("NotFoundException", f"Stage '{stage_name}' not found", 404)
+    for k in ("autoDeploy", "stageVariables", "description",
+              "defaultRouteSettings", "routeSettings"):
+        if k in data:
+            stage[k] = data[k]
+    stage["lastUpdatedDate"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    return _apigw_response(stage)
+
+
+def _delete_stage(api_id, stage_name):
+    _stages.get(api_id, {}).pop(stage_name, None)
+    return 204, {}, b""
+
+
+# ---- Control plane: Deployments ----
+
+def _create_deployment(api_id, data):
+    if api_id not in _apis:
+        return _apigw_error("NotFoundException", f"API {api_id} not found", 404)
+    deployment_id = new_uuid()[:8]
+    deployment = {
+        "deploymentId": deployment_id,
+        "deploymentStatus": "DEPLOYED",
+        "createdDate": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "description": data.get("description", ""),
+    }
+    _deployments.setdefault(api_id, {})[deployment_id] = deployment
+    return _apigw_response(deployment, 201)
+
+
+def _get_deployments(api_id):
+    return _apigw_response({"items": list(_deployments.get(api_id, {}).values()), "nextToken": None})
+
+
+def _get_deployment(api_id, deployment_id):
+    deployment = _deployments.get(api_id, {}).get(deployment_id)
+    if not deployment:
+        return _apigw_error("NotFoundException", f"Deployment {deployment_id} not found", 404)
+    return _apigw_response(deployment)
+
+
+def _delete_deployment(api_id, deployment_id):
+    _deployments.get(api_id, {}).pop(deployment_id, None)
+    return 204, {}, b""
+
+
+# ---- Control plane: Tags ----
+
+def _get_tags(resource_arn: str):
+    tags = _api_tags.get(resource_arn, {})
+    return _apigw_response({"tags": tags})
+
+
+def _tag_resource(resource_arn: str, data: dict):
+    tags = data.get("tags", {})
+    _api_tags.setdefault(resource_arn, {}).update(tags)
+    return 201, {}, b""
+
+
+def _untag_resource(resource_arn: str, tag_keys: list):
+    existing = _api_tags.get(resource_arn, {})
+    for key in tag_keys:
+        existing.pop(key, None)
+    return 204, {}, b""
+
+
+# ---- Control plane: Authorizers ----
+
+def _create_authorizer(api_id, data):
+    if api_id not in _apis:
+        return _apigw_error("NotFoundException", f"API {api_id} not found", 404)
+    auth_id = new_uuid()[:8]
+    authorizer = {
+        "authorizerId": auth_id,
+        "authorizerType": data.get("authorizerType", "JWT"),
+        "name": data.get("name", ""),
+        "identitySource": data.get("identitySource", ["$request.header.Authorization"]),
+        "jwtConfiguration": data.get("jwtConfiguration", {}),
+        "authorizerUri": data.get("authorizerUri", ""),
+        "authorizerPayloadFormatVersion": data.get("authorizerPayloadFormatVersion", "2.0"),
+        "authorizerResultTtlInSeconds": data.get("authorizerResultTtlInSeconds", 300),
+        "enableSimpleResponses": data.get("enableSimpleResponses", False),
+        "authorizerCredentialsArn": data.get("authorizerCredentialsArn", ""),
+    }
+    _authorizers.setdefault(api_id, {})[auth_id] = authorizer
+    return _apigw_response(authorizer, 201)
+
+
+def _get_authorizers(api_id):
+    return _apigw_response({"items": list(_authorizers.get(api_id, {}).values()), "nextToken": None})
+
+
+def _get_authorizer(api_id, auth_id):
+    authorizer = _authorizers.get(api_id, {}).get(auth_id)
+    if not authorizer:
+        return _apigw_error("NotFoundException", f"Authorizer {auth_id} not found", 404)
+    return _apigw_response(authorizer)
+
+
+def _update_authorizer(api_id, auth_id, data):
+    authorizer = _authorizers.get(api_id, {}).get(auth_id)
+    if not authorizer:
+        return _apigw_error("NotFoundException", f"Authorizer {auth_id} not found", 404)
+    for k in ("name", "identitySource", "jwtConfiguration", "authorizerUri",
+              "authorizerPayloadFormatVersion", "authorizerResultTtlInSeconds",
+              "enableSimpleResponses", "authorizerCredentialsArn"):
+        if k in data:
+            authorizer[k] = data[k]
+    return _apigw_response(authorizer)
+
+
+def _delete_authorizer(api_id, auth_id):
+    _authorizers.get(api_id, {}).pop(auth_id, None)
+    return 204, {}, b""
+
+
+def reset():
+    _apis.clear()
+    _routes.clear()
+    _integrations.clear()
+    _stages.clear()
+    _deployments.clear()
+    _authorizers.clear()
+    _api_tags.clear()
+    _route_responses.clear()
+    _integration_responses.clear()
+    # Signal any live WS connections to shut down, then drop registry.
+    for conn in list(_ws_connections.values()):
+        ev = conn.get("close_event")
+        if ev is not None:
+            try:
+                ev.set()
+            except Exception:
+                pass
+    _ws_connections.clear()
+
+
+# ==========================================================================
+# Route responses (WebSocket)
+# ==========================================================================
+
+def _create_route_response(api_id, route_id, data):
+    routes = _routes.get(api_id, {})
+    if route_id not in routes:
+        return _apigw_error("NotFoundException", f"Route {route_id} not found", 404)
+    rr_id = new_uuid()[:8]
+    rr = {
+        "routeResponseId": rr_id,
+        "routeResponseKey": data.get("routeResponseKey", "$default"),
+        "modelSelectionExpression": data.get("modelSelectionExpression"),
+        "responseModels": data.get("responseModels", {}),
+        "responseParameters": data.get("responseParameters", {}),
+    }
+    by_route = _route_responses.setdefault(api_id, {}).setdefault(route_id, {})
+    by_route[rr_id] = rr
+    return _apigw_response(rr, 201)
+
+
+def _get_route_responses(api_id, route_id):
+    items = list(_route_responses.get(api_id, {}).get(route_id, {}).values())
+    return _apigw_response({"items": items})
+
+
+def _get_route_response(api_id, route_id, rr_id):
+    rr = _route_responses.get(api_id, {}).get(route_id, {}).get(rr_id)
+    if not rr:
+        return _apigw_error("NotFoundException", f"RouteResponse {rr_id} not found", 404)
+    return _apigw_response(rr)
+
+
+def _update_route_response(api_id, route_id, rr_id, data):
+    rr = _route_responses.get(api_id, {}).get(route_id, {}).get(rr_id)
+    if not rr:
+        return _apigw_error("NotFoundException", f"RouteResponse {rr_id} not found", 404)
+    for k in ("routeResponseKey", "modelSelectionExpression", "responseModels", "responseParameters"):
+        if k in data:
+            rr[k] = data[k]
+    return _apigw_response(rr)
+
+
+def _delete_route_response(api_id, route_id, rr_id):
+    _route_responses.get(api_id, {}).get(route_id, {}).pop(rr_id, None)
+    return 204, {}, b""
+
+
+# ==========================================================================
+# Integration responses (WebSocket)
+# ==========================================================================
+
+def _create_integration_response(api_id, integration_id, data):
+    integs = _integrations.get(api_id, {})
+    if integration_id not in integs:
+        return _apigw_error("NotFoundException", f"Integration {integration_id} not found", 404)
+    ir_id = new_uuid()[:8]
+    ir = {
+        "integrationResponseId": ir_id,
+        "integrationResponseKey": data.get("integrationResponseKey", "$default"),
+        "contentHandlingStrategy": data.get("contentHandlingStrategy"),
+        "templateSelectionExpression": data.get("templateSelectionExpression"),
+        "responseParameters": data.get("responseParameters", {}),
+        "responseTemplates": data.get("responseTemplates", {}),
+    }
+    by_int = _integration_responses.setdefault(api_id, {}).setdefault(integration_id, {})
+    by_int[ir_id] = ir
+    return _apigw_response(ir, 201)
+
+
+def _get_integration_responses(api_id, integration_id):
+    items = list(_integration_responses.get(api_id, {}).get(integration_id, {}).values())
+    return _apigw_response({"items": items})
+
+
+def _get_integration_response(api_id, integration_id, ir_id):
+    ir = _integration_responses.get(api_id, {}).get(integration_id, {}).get(ir_id)
+    if not ir:
+        return _apigw_error("NotFoundException", f"IntegrationResponse {ir_id} not found", 404)
+    return _apigw_response(ir)
+
+
+def _update_integration_response(api_id, integration_id, ir_id, data):
+    ir = _integration_responses.get(api_id, {}).get(integration_id, {}).get(ir_id)
+    if not ir:
+        return _apigw_error("NotFoundException", f"IntegrationResponse {ir_id} not found", 404)
+    for k in ("integrationResponseKey", "contentHandlingStrategy", "templateSelectionExpression",
+              "responseParameters", "responseTemplates"):
+        if k in data:
+            ir[k] = data[k]
+    return _apigw_response(ir)
+
+
+def _delete_integration_response(api_id, integration_id, ir_id):
+    _integration_responses.get(api_id, {}).get(integration_id, {}).pop(ir_id, None)
+    return 204, {}, b""
+
+
+# ==========================================================================
+# WebSocket data plane
+# ==========================================================================
+
+def _api_protocol(api_id: str) -> str | None:
+    """Return the protocolType for an API id, checking all accounts.
+
+    WebSocket connections arrive on the execute-api host before we've resolved
+    which account owns the api. We scan every AccountScopedDict bucket to find
+    the owning account, then return (protocol, account_id).
+    """
+    info = _api_owner(api_id)
+    return info[0] if info else None
+
+
+def _api_owner(api_id: str):
+    """Return (protocolType, owner_account_id) for an API or None if unknown."""
+    # AccountScopedDict stores keys as (account_id, original_key). Walk internals
+    # so we can find the owning account without knowing it up front.
+    for (acct, key), api in _apis._data.items():
+        if key == api_id:
+            return (api.get("protocolType", "HTTP"), acct)
+    return None
+
+
+def _match_ws_route(api_id: str, route_key: str):
+    """Find the route for a WS route key (e.g. '$connect', '$disconnect', '$default',
+    or a custom action like 'sendMessage'). Fallback to $default."""
+    routes = _routes.get(api_id, {})
+    for r in routes.values():
+        if r.get("routeKey") == route_key:
+            return r
+    for r in routes.values():
+        if r.get("routeKey") == "$default":
+            return r
+    return None
+
+
+def _evaluate_route_selection(expr: str, payload_text: str) -> str:
+    """Evaluate a WebSocket RouteSelectionExpression against an incoming frame.
+
+    AWS supports '$request.body.<dotted.path>' (the common case) and any plain
+    literal that the client includes. Anything we can't parse falls back to
+    '$default'.
+    """
+    if not expr:
+        return "$default"
+    if expr.startswith("$request.body."):
+        path = expr[len("$request.body."):]
+        try:
+            obj = json.loads(payload_text) if payload_text else {}
+        except (ValueError, TypeError):
+            return "$default"
+        cur = obj
+        for segment in path.split("."):
+            if isinstance(cur, dict) and segment in cur:
+                cur = cur[segment]
+            else:
+                return "$default"
+        return str(cur) if cur is not None else "$default"
+    return "$default"
+
+
+async def _invoke_ws_lambda(api_id: str, account_id: str, route: dict, stage: str,
+                            connection_id: str, event_type: str, message_id: str,
+                            body_text: str, source_ip: str, headers: dict,
+                            query_params: dict | None = None, **kwargs) -> dict | None:
+    """Invoke a WS route's integration. Returns the integration's response dict or None.
+
+    The event shape matches AWS WebSocket v2 proxy (see docs: "Set up integration
+    request in API Gateway" under WebSocket). Headers include the incoming
+    handshake headers for $connect (along with query string params); for
+    MESSAGE/DISCONNECT the body is the frame payload.
+
+    Integration type handling:
+      - AWS / AWS_PROXY → dispatch to Lambda via the warm worker pool.
+      - MOCK            → synthesise a 200 response (no Lambda). Any
+                          `responseTemplates.$default` on a matching
+                          integration response is returned as the body.
+      - anything else   → returns None (caller treats as "no reply").
+                          AWS itself only supports AWS/AWS_PROXY/MOCK for
+                          WebSocket routes, so this also covers the
+                          never-valid HTTP_PROXY case.
+    """
+    from ministack.core.lambda_runtime import get_or_create_worker
+    from ministack.services import lambda_svc
+
+    integration_id = route.get("target", "").replace("integrations/", "")
+    integration = _integrations.get(api_id, {}).get(integration_id)
+    if not integration:
+        return None
+
+    int_type = integration.get("integrationType", "")
+    if int_type == "MOCK":
+        ir_map = _integration_responses.get(api_id, {}).get(integration_id, {})
+        body = ""
+        for ir in ir_map.values():
+            templates = ir.get("responseTemplates", {}) or {}
+            if "$default" in templates:
+                body = templates["$default"]
+                break
+            if templates:
+                body = next(iter(templates.values()))
+                break
+        return {"statusCode": 200, "body": body}
+
+    if int_type not in ("AWS_PROXY", "AWS"):
+        logger.warning(
+            "WebSocket route %s has unsupported integrationType %r; "
+            "AWS only supports AWS / AWS_PROXY / MOCK for WebSocket APIs",
+            route.get("routeKey"), int_type,
+        )
+        return None
+
+    # Parse name + qualifier so alias ARNs resolve to their target version (#407).
+    uri = integration.get("integrationUri", "").replace("/invocations", "")
+    func_name, qualifier = lambda_svc._resolve_name_and_qualifier(uri)
+    func_data, func_config = lambda_svc._get_func_record_for_qualifier(func_name, qualifier)
+    if func_data is None:
+        return None
+
+    request_context = {
+        "routeKey": route.get("routeKey", "$default"),
+        "eventType": event_type,
+        "extendedRequestId": new_uuid(),
+        "requestTime": time.strftime("%d/%b/%Y:%H:%M:%S +0000"),
+        "stage": stage,
+        "connectedAt": int(time.time() * 1000),
+        "requestTimeEpoch": int(time.time() * 1000),
+        "identity": {"sourceIp": source_ip, "userAgent": headers.get("user-agent", "")},
+        "requestId": message_id,
+        "domainName": f"{api_id}.execute-api.{_HOST}",
+        "connectionId": connection_id,
+        "apiId": api_id,
+    }
+    if event_type == "DISCONNECT":
+        # Populated by handle_websocket from the ASGI disconnect message.
+        request_context["disconnectReason"] = kwargs.get("disconnect_reason", "")
+        request_context["disconnectStatusCode"] = int(kwargs.get("disconnect_code", 1005))
+    if event_type == "MESSAGE":
+        request_context["messageId"] = message_id
+
+    event = {
+        "requestContext": request_context,
+        "body": body_text if body_text is not None else "",
+        "isBase64Encoded": False,
+    }
+    if event_type == "CONNECT":
+        event["headers"] = dict(headers)
+        event["multiValueHeaders"] = {k: [v] for k, v in headers.items()}
+        if query_params:
+            # AWS flattens single-valued QS params to string, keeps multi-valued as lists.
+            event["queryStringParameters"] = {
+                k: (v[-1] if isinstance(v, list) else v)
+                for k, v in query_params.items()
+            }
+            event["multiValueQueryStringParameters"] = {
+                k: (v if isinstance(v, list) else [v])
+                for k, v in query_params.items()
+            }
+        else:
+            event["queryStringParameters"] = None
+            event["multiValueQueryStringParameters"] = None
+
+    runtime = func_config.get("Runtime", "")
+    code_zip = func_data.get("code_zip")
+    if code_zip and runtime.startswith(("python", "nodejs")):
+        worker_key = f"{func_name}:{qualifier}" if qualifier else func_name
+        worker = get_or_create_worker(worker_key, func_config, code_zip)
+        result = await asyncio.to_thread(worker.invoke, event, message_id)
+        if result.get("status") == "error":
+            return {"statusCode": 500, "body": result.get("error", "")}
+        return result.get("result", {})
+    # Image/unsupported runtime stub — success without body.
+    return {"statusCode": 200, "body": ""}
+
+
+async def handle_websocket(scope, receive, send, api_id: str, path_override: str | None = None):
+    """Drive a WebSocket session for a $WEBSOCKET API.
+
+    Flow:
+      1. Receive `websocket.connect` from ASGI.
+      2. Invoke `$connect` route Lambda (if any). 2xx → accept; else close.
+      3. Loop on `websocket.receive`: evaluate routeSelectionExpression, dispatch
+         to the matching route's Lambda. If the Lambda returns a body, forward it
+         back on the same socket.
+      4. Concurrently drain the per-connection outbox (fed by @connections
+         PostToConnection) and forward messages to the socket.
+      5. On client disconnect, invoke `$disconnect` route Lambda (fire-and-forget).
+
+    ``path_override`` is used when the caller addressed us via the LocalStack-
+    compat path form (``/_aws/execute-api/{apiId}/{stage}``) so we read the
+    stage from the rewritten path instead of the raw URL.
+    """
+    owner = _api_owner(api_id)
+    if not owner or owner[0] != "WEBSOCKET":
+        # Not a WS API — refuse the upgrade.
+        await receive()  # consume websocket.connect
+        await send({"type": "websocket.close", "code": 1008})
+        return
+
+    protocol, account_id = owner
+
+    # Stage parsing: Host-based URLs look like wss://{apiId}.execute-api.../stage;
+    # path-based compat URLs (#401) use path_override with the rewritten path.
+    # If the first segment isn't a configured stage name but the API has a
+    # ``$default`` stage, route to it (issue #404).
+    path = path_override if path_override is not None else scope.get("path", "")
+    path_parts = path.lstrip("/").split("/", 1)
+    tentative = path_parts[0] if path_parts and path_parts[0] else "$default"
+    configured_stages = _stages.get(api_id, {})
+    if tentative in configured_stages:
+        stage = tentative
+    elif "$default" in configured_stages:
+        stage = "$default"
+    else:
+        stage = tentative  # pass through; downstream will handle unknown-stage
+
+    headers = {}
+    for name, value in scope.get("headers", []):
+        try:
+            headers[name.decode("latin-1").lower()] = value.decode("utf-8")
+        except UnicodeDecodeError:
+            headers[name.decode("latin-1").lower()] = value.decode("latin-1")
+
+    qs = scope.get("query_string", b"").decode("utf-8")
+    from urllib.parse import parse_qs as _pq
+    query_params = {k: v for k, v in _pq(qs, keep_blank_values=True).items()}
+
+    client = scope.get("client") or ("127.0.0.1", 0)
+    source_ip = client[0] if isinstance(client, (tuple, list)) else "127.0.0.1"
+
+    # Wait for websocket.connect.
+    msg = await receive()
+    if msg.get("type") != "websocket.connect":
+        return
+
+    connection_id = new_uuid().replace("-", "")[:16]
+
+    # Set account context so downstream Lambda invocations see the right tenant.
+    from ministack.core.responses import _request_account_id
+    token = _request_account_id.set(account_id)
+    try:
+        # $connect hook
+        connect_route = _match_ws_route(api_id, "$connect")
+        if connect_route is not None:
+            resp = await _invoke_ws_lambda(
+                api_id, account_id, connect_route, stage, connection_id,
+                "CONNECT", new_uuid(), "", source_ip, headers,
+                query_params=query_params,
+            )
+            status = int((resp or {}).get("statusCode", 200))
+            if status < 200 or status >= 300:
+                await send({"type": "websocket.close", "code": 1008})
+                return
+
+        await send({"type": "websocket.accept"})
+
+        outbox: asyncio.Queue = asyncio.Queue()
+        close_event = asyncio.Event()
+        now_epoch = int(time.time())
+        conn_record = {
+            "apiId": api_id,
+            "accountId": account_id,
+            "stage": stage,
+            # Int epoch seconds — matches ministack JSON timestamp convention.
+            "connectedAt": now_epoch,
+            "lastActiveAt": now_epoch,
+            "sourceIp": source_ip,
+            "identity": {"sourceIp": source_ip, "userAgent": headers.get("user-agent", "")},
+            "outbox": outbox,
+            "close_event": close_event,
+        }
+        _ws_connections[connection_id] = conn_record
+
+        selection_expr = None
+        api_obj = _apis.get(api_id)
+        if api_obj:
+            selection_expr = api_obj.get("routeSelectionExpression", "$request.body.action")
+
+        async def _drain_outbox():
+            while not close_event.is_set():
+                try:
+                    item = await asyncio.wait_for(outbox.get(), timeout=0.5)
+                except asyncio.TimeoutError:
+                    continue
+                if item is None:
+                    return
+                if isinstance(item, bytes):
+                    await send({"type": "websocket.send", "bytes": item})
+                else:
+                    await send({"type": "websocket.send", "text": str(item)})
+
+        drain_task = asyncio.create_task(_drain_outbox())
+
+        disconnect_code = 1005  # 1005 = "no status rcvd" per RFC 6455, matches AWS default
+        disconnect_reason = ""
+        try:
+            while True:
+                message = await receive()
+                mtype = message.get("type")
+                if mtype == "websocket.disconnect":
+                    disconnect_code = int(message.get("code", 1005) or 1005)
+                    # ASGI extension: some servers (incl. modern hypercorn) pass the
+                    # close-frame reason; fall back to empty string if not present.
+                    disconnect_reason = message.get("reason") or ""
+                    break
+                if mtype != "websocket.receive":
+                    continue
+                frame_text = message.get("text")
+                frame_bytes = message.get("bytes")
+                payload = frame_text if frame_text is not None else (
+                    frame_bytes.decode("utf-8", errors="replace") if frame_bytes else ""
+                )
+                conn_record["lastActiveAt"] = int(time.time())
+
+                route_key = _evaluate_route_selection(selection_expr or "", payload)
+                route = _match_ws_route(api_id, route_key)
+                if route is None:
+                    # No $default — AWS sends GoneException to the client; we log and continue.
+                    continue
+                msg_id = new_uuid()
+                resp = await _invoke_ws_lambda(
+                    api_id, account_id, route, stage, connection_id, "MESSAGE",
+                    msg_id, payload, source_ip, headers,
+                )
+                if resp is None:
+                    continue
+                body = resp.get("body")
+                if body:
+                    if isinstance(body, (dict, list)):
+                        body = json.dumps(body)
+                    if isinstance(body, bytes):
+                        await send({"type": "websocket.send", "bytes": body})
+                    else:
+                        await send({"type": "websocket.send", "text": str(body)})
+        finally:
+            close_event.set()
+            try:
+                await drain_task
+            except Exception:
+                pass
+            _ws_connections.pop(connection_id, None)
+            # Fire $disconnect route best-effort.
+            disconnect_route = _match_ws_route(api_id, "$disconnect")
+            if disconnect_route is not None:
+                try:
+                    await _invoke_ws_lambda(
+                        api_id, account_id, disconnect_route, stage, connection_id,
+                        "DISCONNECT", new_uuid(), "", source_ip, headers,
+                        disconnect_code=disconnect_code,
+                        disconnect_reason=disconnect_reason,
+                    )
+                except Exception:
+                    logger.exception("error firing $disconnect")
+            try:
+                await send({"type": "websocket.close", "code": 1000})
+            except Exception:
+                pass
+    finally:
+        try:
+            _request_account_id.reset(token)
+        except Exception:
+            pass
+
+
+# ==========================================================================
+# @connections management API
+# ==========================================================================
+
+async def handle_connections_api(method: str, api_id: str, stage: str,
+                                  connection_id: str, body: bytes, headers: dict):
+    """Serve the @connections runtime API.
+
+    Paths (on execute-api host):
+      POST   /{stage}/@connections/{connectionId}  → PostToConnection
+      GET    /{stage}/@connections/{connectionId}  → GetConnection
+      DELETE /{stage}/@connections/{connectionId}  → DeleteConnection
+
+    AWS behaviour:
+      - 410 Gone      if the connection is unknown or already closed.
+      - 403 Forbidden if the caller does not own the API (not enforced locally).
+      - 200           on success; POST returns empty body, GET returns JSON.
+    """
+    conn = _ws_connections.get(connection_id)
+    if not conn or conn.get("apiId") != api_id:
+        return 410, {"Content-Type": "application/json"}, json.dumps(
+            {"message": "GoneException"}
+        ).encode()
+
+    if method == "POST":
+        # Push the message into the connection outbox; drain_task will forward it.
+        try:
+            if body:
+                await conn["outbox"].put(body)
+        except Exception as exc:
+            return 500, {"Content-Type": "application/json"}, json.dumps(
+                {"message": str(exc)}
+            ).encode()
+        return 200, {"Content-Type": "application/json"}, b""
+
+    if method == "GET":
+        payload = {
+            "ConnectedAt": conn.get("connectedAt"),
+            "Identity": conn.get("identity", {}),
+            "LastActiveAt": conn.get("lastActiveAt"),
+        }
+        return 200, {"Content-Type": "application/json"}, json.dumps(payload).encode()
+
+    if method == "DELETE":
+        ev = conn.get("close_event")
+        if ev is not None:
+            try:
+                ev.set()
+            except Exception:
+                pass
+        # Flush the outbox with a sentinel so drain_task exits promptly.
+        try:
+            await conn["outbox"].put(None)
+        except Exception:
+            pass
+        return 204, {}, b""
+
+    return 405, {"Content-Type": "application/json"}, json.dumps(
+        {"message": f"Method {method} not allowed on @connections"}
+    ).encode()
+
+def get_state_summary() -> dict:
+    return {
+        "apis": {"count": len(_apis), "ids": list(_apis.keys())},
+        "routes": {"count": sum(len(r) for r in _routes.values()) if _routes else 0},
+        "integrations": {"count": sum(len(i) for i in _integrations.values()) if _integrations else 0},
+    }

aws_infra/ministack/services/apigateway_v1.py

@@ -0,0 +1,1602 @@
+"""
+API Gateway REST API v1 Emulator.
+
+Control plane endpoints implemented:
+  POST   /restapis                                                         — CreateRestApi
+  GET    /restapis                                                         — GetRestApis
+  GET    /restapis/{id}                                                    — GetRestApi
+  PATCH  /restapis/{id}                                                    — UpdateRestApi
+  DELETE /restapis/{id}                                                    — DeleteRestApi
+  GET    /restapis/{id}/resources                                          — GetResources
+  GET    /restapis/{id}/resources/{resourceId}                             — GetResource
+  POST   /restapis/{id}/resources/{parentId}                               — CreateResource
+  PATCH  /restapis/{id}/resources/{resourceId}                             — UpdateResource
+  DELETE /restapis/{id}/resources/{resourceId}                             — DeleteResource
+  PUT    /restapis/{id}/resources/{resourceId}/methods/{httpMethod}        — PutMethod
+  GET    /restapis/{id}/resources/{resourceId}/methods/{httpMethod}        — GetMethod
+  DELETE /restapis/{id}/resources/{resourceId}/methods/{httpMethod}        — DeleteMethod
+  PUT    /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/responses/{code}       — PutMethodResponse
+  GET    /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/responses/{code}       — GetMethodResponse
+  DELETE /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/responses/{code}       — DeleteMethodResponse
+  PUT    /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/integration            — PutIntegration
+  GET    /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/integration            — GetIntegration
+  DELETE /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/integration            — DeleteIntegration
+  PUT    /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/integration/responses/{code} — PutIntegrationResponse
+  GET    /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/integration/responses/{code} — GetIntegrationResponse
+  DELETE /restapis/{id}/resources/{resourceId}/methods/{httpMethod}/integration/responses/{code} — DeleteIntegrationResponse
+  POST   /restapis/{id}/deployments                                        — CreateDeployment
+  GET    /restapis/{id}/deployments                                        — GetDeployments
+  GET    /restapis/{id}/deployments/{deploymentId}                         — GetDeployment
+  PATCH  /restapis/{id}/deployments/{deploymentId}                         — UpdateDeployment
+  DELETE /restapis/{id}/deployments/{deploymentId}                         — DeleteDeployment
+  POST   /restapis/{id}/stages                                             — CreateStage
+  GET    /restapis/{id}/stages                                             — GetStages
+  GET    /restapis/{id}/stages/{stageName}                                 — GetStage
+  PATCH  /restapis/{id}/stages/{stageName}                                 — UpdateStage
+  DELETE /restapis/{id}/stages/{stageName}                                 — DeleteStage
+  POST   /restapis/{id}/authorizers                                        — CreateAuthorizer
+  GET    /restapis/{id}/authorizers                                        — GetAuthorizers
+  GET    /restapis/{id}/authorizers/{authorizerId}                         — GetAuthorizer
+  PATCH  /restapis/{id}/authorizers/{authorizerId}                         — UpdateAuthorizer
+  DELETE /restapis/{id}/authorizers/{authorizerId}                         — DeleteAuthorizer
+  POST   /restapis/{id}/models                                             — CreateModel
+  GET    /restapis/{id}/models                                             — GetModels
+  GET    /restapis/{id}/models/{modelName}                                 — GetModel
+  DELETE /restapis/{id}/models/{modelName}                                 — DeleteModel
+  GET    /apikeys                                                          — GetApiKeys
+  POST   /apikeys                                                          — CreateApiKey
+  GET    /apikeys/{keyId}                                                  — GetApiKey
+  DELETE /apikeys/{keyId}                                                  — DeleteApiKey
+  GET    /usageplans                                                       — GetUsagePlans
+  POST   /usageplans                                                       — CreateUsagePlan
+  GET    /usageplans/{planId}                                              — GetUsagePlan
+  DELETE /usageplans/{planId}                                              — DeleteUsagePlan
+  GET    /usageplans/{planId}/keys                                         — GetUsagePlanKeys
+  POST   /usageplans/{planId}/keys                                         — CreateUsagePlanKey
+  DELETE /usageplans/{planId}/keys/{keyId}                                 — DeleteUsagePlanKey
+  GET    /domainnames                                                      — GetDomainNames
+  POST   /domainnames                                                      — CreateDomainName
+  GET    /domainnames/{domainName}                                         — GetDomainName
+  DELETE /domainnames/{domainName}                                         — DeleteDomainName
+  GET    /tags/{resourceArn}                                               — GetTags
+  PUT    /tags/{resourceArn}                                               — TagResource
+  DELETE /tags/{resourceArn}                                               — UntagResource
+
+Data plane:
+  Requests to /{apiId}.execute-api.localhost/{stage}/{path} are dispatched
+  when api_id is found in _rest_apis.
+"""
+
+import asyncio
+import datetime
+import json
+import logging
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+
+from ministack.core.responses import AccountScopedDict, get_account_id, new_uuid, get_region
+
+
+def _now_unix():
+    """Return current UTC time as Unix timestamp (float).
+    API Gateway v1 createdDate/lastUpdatedDate fields must be numbers, not strings.
+    Terraform's AWS provider deserializes them as JSON Number and errors on ISO strings."""
+    return int(time.time())
+
+logger = logging.getLogger("apigateway_v1")
+
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+
+# ---- Module-level state ----
+# All per-tenant state uses AccountScopedDict so the same REST API id in two
+# different accounts never collides and list operations don't leak cross-account.
+_rest_apis = AccountScopedDict()           # rest_api_id -> RestApi
+_resources = AccountScopedDict()           # rest_api_id -> {resource_id -> Resource}
+_stages_v1 = AccountScopedDict()           # rest_api_id -> {stage_name -> Stage}
+_deployments_v1 = AccountScopedDict()      # rest_api_id -> {deployment_id -> Deployment}
+_authorizers_v1 = AccountScopedDict()      # rest_api_id -> {authorizer_id -> Authorizer}
+_models = AccountScopedDict()              # rest_api_id -> {model_id -> Model}
+_api_keys = AccountScopedDict()            # key_id -> ApiKey
+_usage_plans = AccountScopedDict()         # plan_id -> UsagePlan
+_usage_plan_keys = AccountScopedDict()     # plan_id -> {key_id -> UsagePlanKey}
+_domain_names = AccountScopedDict()        # domain_name -> DomainName
+_base_path_mappings = AccountScopedDict()  # domain_name -> {base_path -> BasePathMapping}
+_v1_tags = AccountScopedDict()             # resource_arn -> {key -> value}
+
+
+# ---- Helpers ----
+
+def _new_id():
+    """Return a 10-char hex id."""
+    return new_uuid().replace("-", "")[:10]
+
+
+def _v1_response(data, status=200):
+    """API Gateway v1 uses application/json."""
+    return status, {"Content-Type": "application/json"}, json.dumps(data, ensure_ascii=False).encode("utf-8")
+
+
+def _v1_error(code, message, status):
+    # AWS API Gateway errors use __type (double underscore), matching every
+    # other JSON-protocol AWS service. boto3 reads this to populate
+    # ``ClientError.response["Error"]["Code"]``; with plain "type" it falls
+    # back to the numeric HTTP status as the code.
+    return status, {"Content-Type": "application/json"}, json.dumps({"message": message, "__type": code}, ensure_ascii=False).encode("utf-8")
+
+
+def _rest_api_arn(api_id):
+    return f"arn:aws:apigateway:{get_region()}::/restapis/{api_id}"
+
+
+def _compute_path(api_id, resource_id):
+    """Walk the parent chain to build the full resource path."""
+    resources = _resources.get(api_id, {})
+    parts = []
+    rid = resource_id
+    while rid:
+        r = resources.get(rid)
+        if not r:
+            break
+        pp = r.get("pathPart", "")
+        if pp:
+            parts.append(pp)
+        rid = r.get("parentId")
+    if not parts:
+        return "/"
+    parts.reverse()
+    return "/" + "/".join(parts)
+
+
+def _apply_patch(obj, patch_ops):
+    """Apply JSON Patch operations (replace/add/remove) to a dict in place."""
+    for op in patch_ops:
+        operation = op.get("op", "replace")
+        path = op.get("path", "")
+        value = op.get("value")
+
+        # Strip leading slash and split
+        keys = path.lstrip("/").split("/")
+        if not keys or keys == [""]:
+            continue
+
+        if operation in ("replace", "add"):
+            if len(keys) == 1:
+                obj[keys[0]] = value
+            else:
+                # Walk into nested dicts, create if needed
+                target = obj
+                for k in keys[:-1]:
+                    if k not in target or not isinstance(target[k], dict):
+                        target[k] = {}
+                    target = target[k]
+                target[keys[-1]] = value
+        elif operation == "remove":
+            if len(keys) == 1:
+                obj.pop(keys[0], None)
+            else:
+                target = obj
+                for k in keys[:-1]:
+                    if not isinstance(target.get(k), dict):
+                        break
+                    target = target[k]
+                else:
+                    target.pop(keys[-1], None)
+    return obj
+
+
+def _match_resource_tree(api_id, segments):
+    """Match path segments against the resource tree. Returns (resource, path_params) or (None, {})."""
+    resources = _resources.get(api_id, {})
+    root = next((r for r in resources.values() if r.get("path") == "/"), None)
+    if not root:
+        return None, {}
+    if not segments or segments == [""]:
+        return root, {}
+    return _match_recursive(resources, root["id"], segments, {})
+
+
+def _match_recursive(resources, parent_id, segments, params):
+    if not segments:
+        return None, params
+    segment = segments[0]
+    remaining = segments[1:]
+    children = [r for r in resources.values() if r.get("parentId") == parent_id]
+    for child in children:
+        pp = child.get("pathPart", "")
+        if pp.endswith("+}") and pp.startswith("{"):
+            # greedy {proxy+}
+            param_name = pp[1:-2]
+            new_params = dict(params)
+            new_params[param_name] = "/".join([segment] + list(remaining))
+            return child, new_params
+        elif pp.startswith("{") and pp.endswith("}"):
+            param_name = pp[1:-1]
+            new_params = dict(params)
+            new_params[param_name] = segment
+            if not remaining:
+                return child, new_params
+            result, rp = _match_recursive(resources, child["id"], list(remaining), new_params)
+            if result:
+                return result, rp
+        elif pp == segment:
+            if not remaining:
+                return child, params
+            result, rp = _match_recursive(resources, child["id"], list(remaining), dict(params))
+            if result:
+                return result, rp
+    return None, params
+
+
+async def _call_lambda(func_name, event, qualifier=None):
+    """Invoke a Lambda function and return the parsed response dict.
+
+    ``qualifier`` may be a version number or alias name; aliases resolve to
+    their target version via ``_get_func_record_for_qualifier`` so aliased
+    integration URIs (arn:...:function:<name>:<alias>) invoke correctly (#407)."""
+    from ministack.core.lambda_runtime import get_or_create_worker
+    from ministack.services import lambda_svc
+
+    func_data, func_config = lambda_svc._get_func_record_for_qualifier(func_name, qualifier)
+    if func_data is None:
+        label = f"{func_name}:{qualifier}" if qualifier else func_name
+        return None, f"Lambda function '{label}' not found"
+
+    code_zip = func_data.get("code_zip")
+    runtime = func_config.get("Runtime", "")
+    if code_zip and runtime.startswith(("python", "nodejs")):
+        worker_key = f"{func_name}:{qualifier}" if qualifier else func_name
+        worker = get_or_create_worker(worker_key, func_config, code_zip)
+        result = await asyncio.to_thread(worker.invoke, event, new_uuid())
+        if result.get("status") == "error":
+            return None, result.get("error", "Lambda invocation error")
+        return result.get("result", {}), None
+    else:
+        return {"statusCode": 200, "body": "Mock response"}, None
+
+
+SUPPORTED_ACTIONS = [
+    "CreateRestApi", "GetRestApis", "GetRestApi", "UpdateRestApi",
+    "DeleteRestApi", "GetResources", "GetResource", "CreateResource",
+    "UpdateResource", "DeleteResource", "PutMethod", "GetMethod",
+    "DeleteMethod", "PutMethodResponse", "GetMethodResponse",
+    "DeleteMethodResponse", "PutIntegration", "GetIntegration",
+    "DeleteIntegration", "PutIntegrationResponse", "GetIntegrationResponse",
+    "DeleteIntegrationResponse", "CreateDeployment", "GetDeployments",
+    "GetDeployment", "UpdateDeployment", "DeleteDeployment", "CreateStage",
+    "GetStages", "GetStage", "UpdateStage", "DeleteStage",
+    "CreateAuthorizer", "GetAuthorizers", "GetAuthorizer",
+    "UpdateAuthorizer", "DeleteAuthorizer", "CreateModel", "GetModels",
+    "GetModel", "DeleteModel", "GetApiKeys", "CreateApiKey", "GetApiKey",
+    "DeleteApiKey", "GetUsagePlans", "CreateUsagePlan", "GetUsagePlan",
+    "DeleteUsagePlan", "GetUsagePlanKeys", "CreateUsagePlanKey",
+    "DeleteUsagePlanKey", "GetDomainNames", "CreateDomainName",
+    "GetDomainName", "DeleteDomainName", "GetTags", "TagResource",
+    "UntagResource",
+]
+
+
+# ---- Persistence hooks ----
+
+def get_state():
+    """Return full module state for persistence."""
+    return {
+        "rest_apis": _rest_apis,
+        "resources": _resources,
+        "stages_v1": _stages_v1,
+        "deployments_v1": _deployments_v1,
+        "authorizers_v1": _authorizers_v1,
+        "models": _models,
+        "api_keys": _api_keys,
+        "usage_plans": _usage_plans,
+        "usage_plan_keys": _usage_plan_keys,
+        "domain_names": _domain_names,
+        "base_path_mappings": _base_path_mappings,
+        "v1_tags": _v1_tags,
+    }
+
+
+def load_persisted_state(data):
+    """Restore module state from a previously persisted snapshot."""
+    _rest_apis.update(data.get("rest_apis", {}))
+    _resources.update(data.get("resources", {}))
+    _stages_v1.update(data.get("stages_v1", {}))
+    _deployments_v1.update(data.get("deployments_v1", {}))
+    _authorizers_v1.update(data.get("authorizers_v1", {}))
+    _models.update(data.get("models", {}))
+    _api_keys.update(data.get("api_keys", {}))
+    _usage_plans.update(data.get("usage_plans", {}))
+    _usage_plan_keys.update(data.get("usage_plan_keys", {}))
+    _domain_names.update(data.get("domain_names", {}))
+    _base_path_mappings.update(data.get("base_path_mappings", {}))
+    _v1_tags.update(data.get("v1_tags", {}))
+
+
+def reset():
+    """Clear all module state."""
+    _rest_apis.clear()
+    _resources.clear()
+    _stages_v1.clear()
+    _deployments_v1.clear()
+    _authorizers_v1.clear()
+    _models.clear()
+    _api_keys.clear()
+    _usage_plans.clear()
+    _usage_plan_keys.clear()
+    _domain_names.clear()
+    _base_path_mappings.clear()
+    _v1_tags.clear()
+
+
+# ---- Control plane router ----
+
+async def handle_request(method, path, headers, body, query_params):
+    """Route API Gateway v1 REST API control plane requests."""
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError:
+        data = {}
+
+    parts = [p for p in path.strip("/").split("/") if p]
+
+    if not parts:
+        return _v1_error("NotFoundException", f"Unknown path: {path}", 404)
+
+    top = parts[0]
+
+    if top == "tags":
+        # /tags/{resourceArn} — ARN may contain slashes
+        resource_arn = "/".join(parts[1:]) if len(parts) > 1 else ""
+        if method == "GET":
+            return _get_v1_tags(resource_arn)
+        if method in ("PUT", "POST"):
+            return _tag_v1_resource(resource_arn, data)
+        if method == "DELETE":
+            tag_keys = query_params.get("tagKeys", [])
+            if isinstance(tag_keys, str):
+                tag_keys = [tag_keys]
+            return _untag_v1_resource(resource_arn, tag_keys)
+
+    if top == "apikeys":
+        key_id = parts[1] if len(parts) > 1 else None
+        if not key_id:
+            if method == "GET":
+                return _get_api_keys()
+            if method == "POST":
+                return _create_api_key(data)
+        else:
+            if method == "GET":
+                return _get_api_key(key_id)
+            if method == "DELETE":
+                return _delete_api_key(key_id)
+            if method == "PATCH":
+                return _update_api_key(key_id, data)
+
+    if top == "usageplans":
+        plan_id = parts[1] if len(parts) > 1 else None
+        sub = parts[2] if len(parts) > 2 else None
+        sub_id = parts[3] if len(parts) > 3 else None
+        if not plan_id:
+            if method == "GET":
+                return _get_usage_plans()
+            if method == "POST":
+                return _create_usage_plan(data)
+        elif sub == "keys":
+            if not sub_id:
+                if method == "GET":
+                    return _get_usage_plan_keys(plan_id)
+                if method == "POST":
+                    return _create_usage_plan_key(plan_id, data)
+            else:
+                if method == "DELETE":
+                    return _delete_usage_plan_key(plan_id, sub_id)
+        else:
+            if method == "GET":
+                return _get_usage_plan(plan_id)
+            if method == "DELETE":
+                return _delete_usage_plan(plan_id)
+            if method == "PATCH":
+                return _update_usage_plan(plan_id, data)
+
+    if top == "domainnames":
+        domain_name = parts[1] if len(parts) > 1 else None
+        sub = parts[2] if len(parts) > 2 else None
+        sub_id = parts[3] if len(parts) > 3 else None
+        if not domain_name:
+            if method == "GET":
+                return _get_domain_names()
+            if method == "POST":
+                return _create_domain_name(data)
+        elif sub == "basepathmappings":
+            base_path = sub_id
+            if not base_path:
+                if method == "GET":
+                    return _get_base_path_mappings(domain_name)
+                if method == "POST":
+                    return _create_base_path_mapping(domain_name, data)
+            else:
+                if method == "GET":
+                    return _get_base_path_mapping(domain_name, base_path)
+                if method == "DELETE":
+                    return _delete_base_path_mapping(domain_name, base_path)
+        else:
+            if method == "GET":
+                return _get_domain_name(domain_name)
+            if method == "DELETE":
+                return _delete_domain_name(domain_name)
+
+    if top == "restapis":
+        # /restapis
+        if len(parts) == 1:
+            if method == "POST":
+                return _create_rest_api(data)
+            if method == "GET":
+                return _get_rest_apis()
+
+        api_id = parts[1]
+
+        # /restapis/{id}
+        if len(parts) == 2:
+            if method == "GET":
+                return _get_rest_api(api_id)
+            if method == "DELETE":
+                return _delete_rest_api(api_id)
+            if method == "PATCH":
+                return _update_rest_api(api_id, data)
+
+        sub = parts[2] if len(parts) > 2 else None
+
+        # /restapis/{id}/resources[/{resourceId}[/...]]
+        if sub == "resources":
+            resource_id = parts[3] if len(parts) > 3 else None
+            method_part = parts[4] if len(parts) > 4 else None
+            http_method = parts[5] if len(parts) > 5 else None
+            after_method = parts[6] if len(parts) > 6 else None
+            after_method_id = parts[7] if len(parts) > 7 else None
+
+            if not resource_id:
+                # GET /restapis/{id}/resources
+                if method == "GET":
+                    return _get_resources(api_id)
+
+            elif method_part is None:
+                # /restapis/{id}/resources/{resourceId}
+                if method == "GET":
+                    return _get_resource(api_id, resource_id)
+                if method == "POST":
+                    # CreateResource: POST /restapis/{id}/resources/{parentId}
+                    return _create_resource(api_id, resource_id, data)
+                if method == "PATCH":
+                    return _update_resource(api_id, resource_id, data)
+                if method == "DELETE":
+                    return _delete_resource(api_id, resource_id)
+
+            elif method_part == "methods":
+                if http_method is None:
+                    return _v1_error("NotFoundException", "Method not specified", 404)
+
+                if after_method is None:
+                    # /restapis/{id}/resources/{resourceId}/methods/{httpMethod}
+                    if method == "PUT":
+                        return _put_method(api_id, resource_id, http_method, data)
+                    if method == "GET":
+                        return _get_method(api_id, resource_id, http_method)
+                    if method == "DELETE":
+                        return _delete_method(api_id, resource_id, http_method)
+                    if method == "PATCH":
+                        return _update_method(api_id, resource_id, http_method, data)
+
+                elif after_method == "responses":
+                    status_code = after_method_id
+                    if not status_code:
+                        return _v1_error("NotFoundException", "Status code not specified", 404)
+                    if method == "PUT":
+                        return _put_method_response(api_id, resource_id, http_method, status_code, data)
+                    if method == "GET":
+                        return _get_method_response(api_id, resource_id, http_method, status_code)
+                    if method == "DELETE":
+                        return _delete_method_response(api_id, resource_id, http_method, status_code)
+
+                elif after_method == "integration":
+                    # Check for integration/responses/{statusCode}
+                    int_sub = parts[7] if len(parts) > 7 else None
+                    int_sub_id = parts[8] if len(parts) > 8 else None
+
+                    if after_method_id is None and int_sub is None:
+                        # /.../{httpMethod}/integration
+                        if method == "PUT":
+                            return _put_integration(api_id, resource_id, http_method, data)
+                        if method == "GET":
+                            return _get_integration(api_id, resource_id, http_method)
+                        if method == "DELETE":
+                            return _delete_integration(api_id, resource_id, http_method)
+                        if method == "PATCH":
+                            return _update_integration(api_id, resource_id, http_method, data)
+                    elif after_method_id == "responses":
+                        status_code = int_sub_id
+                        if not status_code:
+                            return _v1_error("NotFoundException", "Status code not specified", 404)
+                        if method == "PUT":
+                            return _put_integration_response(api_id, resource_id, http_method, status_code, data)
+                        if method == "GET":
+                            return _get_integration_response(api_id, resource_id, http_method, status_code)
+                        if method == "DELETE":
+                            return _delete_integration_response(api_id, resource_id, http_method, status_code)
+
+        # /restapis/{id}/deployments[/{deploymentId}]
+        elif sub == "deployments":
+            deployment_id = parts[3] if len(parts) > 3 else None
+            if not deployment_id:
+                if method == "POST":
+                    return _create_deployment(api_id, data)
+                if method == "GET":
+                    return _get_deployments(api_id)
+            else:
+                if method == "GET":
+                    return _get_deployment(api_id, deployment_id)
+                if method == "PATCH":
+                    return _update_deployment(api_id, deployment_id, data)
+                if method == "DELETE":
+                    return _delete_deployment(api_id, deployment_id)
+
+        # /restapis/{id}/stages[/{stageName}]
+        elif sub == "stages":
+            stage_name = parts[3] if len(parts) > 3 else None
+            if not stage_name:
+                if method == "POST":
+                    return _create_stage(api_id, data)
+                if method == "GET":
+                    return _get_stages(api_id)
+            else:
+                if method == "GET":
+                    return _get_stage(api_id, stage_name)
+                if method == "PATCH":
+                    return _update_stage(api_id, stage_name, data)
+                if method == "DELETE":
+                    return _delete_stage(api_id, stage_name)
+
+        # /restapis/{id}/authorizers[/{authorizerId}]
+        elif sub == "authorizers":
+            auth_id = parts[3] if len(parts) > 3 else None
+            if not auth_id:
+                if method == "POST":
+                    return _create_authorizer(api_id, data)
+                if method == "GET":
+                    return _get_authorizers(api_id)
+            else:
+                if method == "GET":
+                    return _get_authorizer(api_id, auth_id)
+                if method == "PATCH":
+                    return _update_authorizer(api_id, auth_id, data)
+                if method == "DELETE":
+                    return _delete_authorizer(api_id, auth_id)
+
+        # /restapis/{id}/models[/{modelName}]
+        elif sub == "models":
+            model_name = parts[3] if len(parts) > 3 else None
+            if not model_name:
+                if method == "POST":
+                    return _create_model(api_id, data)
+                if method == "GET":
+                    return _get_models(api_id)
+            else:
+                if method == "GET":
+                    return _get_model(api_id, model_name)
+                if method == "DELETE":
+                    return _delete_model(api_id, model_name)
+
+    return _v1_error("NotFoundException", f"Unknown API Gateway v1 path: {path}", 404)
+
+
+# ---- Data plane ----
+
+async def handle_execute(api_id, stage_name, method, path, headers, body, query_params):
+    """Execute a v1 REST API request through a deployed stage (data plane)."""
+    api = _rest_apis.get(api_id)
+    if not api:
+        return 404, {"Content-Type": "application/json"}, json.dumps({"message": "Not Found"}).encode()
+
+    stage = _stages_v1.get(api_id, {}).get(stage_name)
+    if not stage:
+        return 404, {"Content-Type": "application/json"}, json.dumps({"message": f"Stage '{stage_name}' not found"}).encode()
+
+    # Match path against resource tree
+    segments = [s for s in path.strip("/").split("/") if s]
+    resource, path_params = _match_resource_tree(api_id, segments)
+
+    if not resource:
+        return 404, {"Content-Type": "application/json"}, json.dumps({"message": "Missing Authentication Token"}).encode()
+
+    # Look up method
+    resource_methods = resource.get("resourceMethods", {})
+    method_obj = resource_methods.get(method) or resource_methods.get("ANY")
+    if not method_obj:
+        return 405, {"Content-Type": "application/json"}, json.dumps({"message": "Method Not Allowed"}).encode()
+
+    integration = method_obj.get("methodIntegration")
+    if not integration:
+        return 500, {"Content-Type": "application/json"}, json.dumps({"message": "No integration configured"}).encode()
+
+    int_type = integration.get("type", "")
+
+    if int_type in ("AWS_PROXY", "AWS"):
+        return await _invoke_lambda_proxy_v1(
+            integration, api_id, stage_name, stage, resource, path, method,
+            headers, body, query_params, path_params
+        )
+    elif int_type in ("HTTP_PROXY", "HTTP"):
+        return await _invoke_http_proxy_v1(integration, path, method, headers, body, query_params)
+    elif int_type == "MOCK":
+        return _invoke_mock_v1(integration)
+    else:
+        return 500, {"Content-Type": "application/json"}, json.dumps({"message": f"Unsupported integration type: {int_type}"}).encode()
+
+
+async def _invoke_lambda_proxy_v1(integration, api_id, stage_name, stage, resource, request_path, method, headers, body, query_params, path_params):
+    """Invoke Lambda with API Gateway v1 payload format 1.0."""
+    uri = integration.get("uri", "")
+    # Supported URI formats:
+    #   1. arn:aws:apigateway:{region}:lambda:path/2015-03-31/functions/arn:aws:lambda:{region}:{acct}:function:{name}[:{qualifier}]/invocations
+    #   2. arn:aws:lambda:{region}:{acct}:function:{name}[:{qualifier}]
+    #   3. plain function name: MyFunction[:{qualifier}]
+    from ministack.services import lambda_svc as _lambda_svc
+    if "function:" in uri:
+        # Strip wrapper up through 'function:' and any trailing /invocations.
+        tail = uri.split("function:")[-1].split("/")[0]
+        # tail is now "<name>" or "<name>:<qualifier>".
+        func_name, qualifier = _lambda_svc._resolve_name_and_qualifier(tail)
+    else:
+        func_name, qualifier = _lambda_svc._resolve_name_and_qualifier(uri)
+
+    qs_params = {k: v[0] for k, v in query_params.items()} if query_params else None
+    mv_qs_params = {k: list(v) for k, v in query_params.items()} if query_params else None
+
+    # Build single and multi-value header dicts
+    single_headers = {k: v if isinstance(v, str) else v[-1] for k, v in headers.items()}
+    multi_headers = {k: [v] if isinstance(v, str) else list(v) for k, v in headers.items()}
+
+    now_epoch_ms = int(time.time() * 1000)
+    request_time = datetime.datetime.utcnow().strftime("%d/%b/%Y:%H:%M:%S +0000")
+    request_id = new_uuid()
+
+    event = {
+        "version": "1.0",
+        "resource": resource["path"],
+        "path": request_path,
+        "httpMethod": method,
+        "headers": single_headers,
+        "multiValueHeaders": multi_headers,
+        "queryStringParameters": qs_params or None,
+        "multiValueQueryStringParameters": mv_qs_params or None,
+        "pathParameters": path_params or None,
+        "stageVariables": stage.get("variables") or None,
+        "requestContext": {
+            "accountId": get_account_id(),
+            "resourceId": resource["id"],
+            "stage": stage_name,
+            "requestId": request_id,
+            "extendedRequestId": request_id,
+            "requestTime": request_time,
+            "requestTimeEpoch": now_epoch_ms,
+            "path": f"/{stage_name}{request_path}",
+            "protocol": "HTTP/1.1",
+            "identity": {
+                "sourceIp": headers.get("x-forwarded-for", "127.0.0.1").split(",")[0].strip()
+                if isinstance(headers.get("x-forwarded-for", ""), str)
+                else "127.0.0.1",
+                "userAgent": headers.get("user-agent", ""),
+            },
+            "resourcePath": resource["path"],
+            "httpMethod": method,
+            "apiId": api_id,
+        },
+        "body": body.decode("utf-8", errors="replace") if body else None,
+        "isBase64Encoded": False,
+    }
+
+    lambda_response, err = await _call_lambda(func_name, event, qualifier=qualifier)
+    if err:
+        return 502, {"Content-Type": "application/json"}, json.dumps({"message": err}).encode()
+
+    status = lambda_response.get("statusCode", 200)
+    resp_headers = {"Content-Type": "application/json"}
+    resp_headers.update(lambda_response.get("headers", {}))
+    resp_body = lambda_response.get("body", "")
+    if isinstance(resp_body, str):
+        resp_body = resp_body.encode("utf-8")
+    elif isinstance(resp_body, dict):
+        resp_body = json.dumps(resp_body, ensure_ascii=False).encode("utf-8")
+
+    return status, resp_headers, resp_body
+
+
+async def _invoke_http_proxy_v1(integration, path, method, headers, body, query_params):
+    """Forward a request to an HTTP backend."""
+    uri = integration.get("uri", "")
+    url = uri.rstrip("/") + path
+
+    req = urllib.request.Request(url, data=body or None, method=method)
+    for k, v in headers.items():
+        if k.lower() not in ("host", "content-length"):
+            req.add_header(k, v)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            resp_body = resp.read()
+            resp_headers = {"Content-Type": resp.headers.get("Content-Type", "application/json")}
+            return resp.status, resp_headers, resp_body
+    except urllib.error.HTTPError as e:
+        return e.code, {"Content-Type": "application/json"}, e.read()
+    except Exception as ex:
+        return 502, {"Content-Type": "application/json"}, json.dumps({"message": str(ex)}).encode()
+
+
+def _invoke_mock_v1(integration):
+    """Return a MOCK integration response.
+
+    Selection: iterate integrationResponses in status-code order; the first
+    entry whose selectionPattern is empty (default) or matches "200" is used,
+    matching AWS behaviour for MOCK where the input is always treated as
+    successful (statusCode 200).
+    """
+    int_responses = integration.get("integrationResponses", {})
+    if not int_responses:
+        return 200, {"Content-Type": "application/json"}, b"{}"
+
+    # AWS selects the response whose selectionPattern matches the integration
+    # status code.  For MOCK the "status" is always 200 (success path).
+    selected = None
+    # Prefer an explicit "200" entry first
+    if "200" in int_responses:
+        selected = int_responses["200"]
+    else:
+        # Fall back to the entry with an empty / catch-all selectionPattern
+        for resp in int_responses.values():
+            pattern = resp.get("selectionPattern", "")
+            if not pattern:
+                selected = resp
+                break
+        if not selected:
+            selected = next(iter(int_responses.values()))
+
+    status = int(selected.get("statusCode", 200))
+    resp_headers = {"Content-Type": "application/json"}
+
+    # Apply responseParameters: map integration values to method response headers
+    for dest, src in selected.get("responseParameters", {}).items():
+        # dest: "method.response.header.X-Custom-Header"
+        if dest.startswith("method.response.header."):
+            header_name = dest[len("method.response.header."):]
+            # src is a static string value (quoted) or integration reference
+            value = src.strip("'") if src.startswith("'") else src
+            resp_headers[header_name] = value
+
+    body_template = selected.get("responseTemplates", {}).get("application/json", "")
+    if body_template:
+        return status, resp_headers, body_template.encode()
+    return status, resp_headers, b"{}"
+
+
+# ---- Control plane: REST APIs ----
+
+def _resolve_custom_rest_api_id(tags: dict) -> tuple[str | None, tuple | None]:
+    """Return (api_id_or_None, error_response_or_None).
+
+    Reads the ministack-native ``ms-custom-id`` tag (issue #400). If the
+    LocalStack ``ls-custom-id`` tag is set (and ``ms-custom-id`` is not), the
+    caller gets a clear ``BadRequestException`` so the ministack-native key is
+    the only supported contract."""
+    if not isinstance(tags, dict):
+        return None, None
+    if "ls-custom-id" in tags and "ms-custom-id" not in tags:
+        return None, _v1_error(
+            "BadRequestException",
+            "ls-custom-id tag is not supported; use 'ms-custom-id' instead",
+            400,
+        )
+    custom = tags.get("ms-custom-id")
+    if not custom:
+        return None, None
+    if custom in _rest_apis:
+        return None, _v1_error(
+            "ConflictException",
+            f"REST API id '{custom}' (from ms-custom-id tag) is already in use",
+            409,
+        )
+    return str(custom), None
+
+
+def _create_rest_api(data):
+    tags = data.get("tags", {})
+    custom_id, err = _resolve_custom_rest_api_id(tags)
+    if err is not None:
+        return err
+    api_id = custom_id or _new_id()[:8]
+    api = {
+        "id": api_id,
+        "name": data.get("name", "unnamed"),
+        "description": data.get("description", ""),
+        "createdDate": _now_unix(),
+        "version": data.get("version", ""),
+        "binaryMediaTypes": data.get("binaryMediaTypes", []),
+        "minimumCompressionSize": data.get("minimumCompressionSize"),
+        "apiKeySource": data.get("apiKeySource", "HEADER"),
+        "endpointConfiguration": data.get("endpointConfiguration", {"types": ["REGIONAL"]}),
+        "policy": data.get("policy"),
+        "tags": data.get("tags", {}),
+        "disableExecuteApiEndpoint": data.get("disableExecuteApiEndpoint", False),
+    }
+    _rest_apis[api_id] = api
+    _resources[api_id] = {}
+    _stages_v1[api_id] = {}
+    _deployments_v1[api_id] = {}
+    _authorizers_v1[api_id] = {}
+    _models[api_id] = {}
+
+    # Create root resource "/"
+    root_id = _new_id()[:8]
+    root_resource = {
+        "id": root_id,
+        "parentId": None,
+        "pathPart": "",
+        "path": "/",
+        "resourceMethods": {},
+    }
+    _resources[api_id][root_id] = root_resource
+
+    _v1_tags[_rest_api_arn(api_id)] = dict(data.get("tags", {}))
+    return _v1_response(api, 201)
+
+
+def _get_rest_api(api_id):
+    api = _rest_apis.get(api_id)
+    if not api:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    return _v1_response(api)
+
+
+def _get_rest_apis():
+    return _v1_response({"item": list(_rest_apis.values()), "nextToken": None})
+
+
+def _update_rest_api(api_id, data):
+    api = _rest_apis.get(api_id)
+    if not api:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(api, patch_ops)
+    return _v1_response(api)
+
+
+def _delete_rest_api(api_id):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    _rest_apis.pop(api_id, None)
+    _resources.pop(api_id, None)
+    _stages_v1.pop(api_id, None)
+    _deployments_v1.pop(api_id, None)
+    _authorizers_v1.pop(api_id, None)
+    _models.pop(api_id, None)
+    _v1_tags.pop(_rest_api_arn(api_id), None)
+    return 202, {}, b""
+
+
+# ---- Control plane: Resources ----
+
+def _get_resources(api_id):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    return _v1_response({"item": list(_resources.get(api_id, {}).values())})
+
+
+def _get_resource(api_id, resource_id):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    return _v1_response(resource)
+
+
+def _create_resource(api_id, parent_id, data):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    if parent_id not in _resources.get(api_id, {}):
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    path_part = data.get("pathPart", "")
+    # Check for duplicate pathPart under same parent
+    for r in _resources.get(api_id, {}).values():
+        if r.get("parentId") == parent_id and r.get("pathPart") == path_part:
+            return _v1_error("ConflictException",
+                             f"Another resource with the same parent already has this name: {path_part}", 409)
+    resource_id = _new_id()[:8]
+    resource = {
+        "id": resource_id,
+        "parentId": parent_id,
+        "pathPart": path_part,
+        "path": "",
+        "resourceMethods": {},
+    }
+    _resources[api_id][resource_id] = resource
+    # Compute the full path
+    resource["path"] = _compute_path(api_id, resource_id)
+    return _v1_response(resource, 201)
+
+
+def _update_resource(api_id, resource_id, data):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(resource, patch_ops)
+    # Recompute path if pathPart changed
+    resource["path"] = _compute_path(api_id, resource_id)
+    return _v1_response(resource)
+
+
+def _delete_resource(api_id, resource_id):
+    if resource_id not in _resources.get(api_id, {}):
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    _resources[api_id].pop(resource_id, None)
+    return 202, {}, b""
+
+
+# ---- Control plane: Methods ----
+
+def _put_method(api_id, resource_id, http_method, data):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = {
+        "httpMethod": http_method,
+        "authorizationType": data.get("authorizationType", "NONE"),
+        "authorizerId": data.get("authorizerId"),
+        "apiKeyRequired": data.get("apiKeyRequired", False),
+        "operationName": data.get("operationName", ""),
+        "requestParameters": data.get("requestParameters", {}),
+        "requestModels": data.get("requestModels", {}),
+        "methodResponses": {},
+        "methodIntegration": None,
+    }
+    resource["resourceMethods"][http_method] = method_obj
+    return _v1_response(method_obj, 201)
+
+
+def _get_method(api_id, resource_id, http_method):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    return _v1_response(method_obj)
+
+
+def _delete_method(api_id, resource_id, http_method):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    resource["resourceMethods"].pop(http_method, None)
+    return 204, {}, b""
+
+
+def _update_method(api_id, resource_id, http_method, data):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(method_obj, patch_ops)
+    return _v1_response(method_obj)
+
+
+# ---- Control plane: Method Responses ----
+
+def _put_method_response(api_id, resource_id, http_method, status_code, data):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    method_response = {
+        "statusCode": status_code,
+        "responseParameters": data.get("responseParameters", {}),
+        "responseModels": data.get("responseModels", {}),
+    }
+    method_obj["methodResponses"][status_code] = method_response
+    return _v1_response(method_response)
+
+
+def _get_method_response(api_id, resource_id, http_method, status_code):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    resp = method_obj["methodResponses"].get(status_code)
+    if not resp:
+        return _v1_error("NotFoundException", "Invalid Response status code specified", 404)
+    return _v1_response(resp)
+
+
+def _delete_method_response(api_id, resource_id, http_method, status_code):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if method_obj:
+        method_obj["methodResponses"].pop(status_code, None)
+    return 204, {}, b""
+
+
+# ---- Control plane: Integration ----
+
+def _put_integration(api_id, resource_id, http_method, data):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    integration = {
+        "type": data.get("type", "AWS_PROXY"),
+        "httpMethod": data.get("httpMethod", "POST"),
+        "uri": data.get("uri", ""),
+        "connectionType": data.get("connectionType", "INTERNET"),
+        "credentials": data.get("credentials"),
+        "requestParameters": data.get("requestParameters", {}),
+        "requestTemplates": data.get("requestTemplates", {}),
+        "passthroughBehavior": data.get("passthroughBehavior", "WHEN_NO_MATCH"),
+        "timeoutInMillis": data.get("timeoutInMillis", 29000),
+        "cacheNamespace": resource_id,
+        "cacheKeyParameters": data.get("cacheKeyParameters", []),
+        "integrationResponses": {},
+    }
+    method_obj["methodIntegration"] = integration
+    return _v1_response(integration)
+
+
+def _get_integration(api_id, resource_id, http_method):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    integration = method_obj.get("methodIntegration")
+    if not integration:
+        return _v1_error("NotFoundException", "Invalid Integration identifier specified", 404)
+    return _v1_response(integration)
+
+
+def _delete_integration(api_id, resource_id, http_method):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if method_obj:
+        method_obj["methodIntegration"] = None
+    return 204, {}, b""
+
+
+def _update_integration(api_id, resource_id, http_method, data):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    integration = method_obj.get("methodIntegration")
+    if not integration:
+        return _v1_error("NotFoundException", "Invalid Integration identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(integration, patch_ops)
+    return _v1_response(integration)
+
+
+# ---- Control plane: Integration Responses ----
+
+def _put_integration_response(api_id, resource_id, http_method, status_code, data):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    integration = method_obj.get("methodIntegration")
+    if not integration:
+        return _v1_error("NotFoundException", "Invalid Integration identifier specified", 404)
+    int_response = {
+        "statusCode": status_code,
+        "selectionPattern": data.get("selectionPattern", ""),
+        "responseParameters": data.get("responseParameters", {}),
+        "responseTemplates": data.get("responseTemplates", {}),
+        "contentHandling": data.get("contentHandling"),
+    }
+    integration["integrationResponses"][status_code] = int_response
+    return _v1_response(int_response)
+
+
+def _get_integration_response(api_id, resource_id, http_method, status_code):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if not method_obj:
+        return _v1_error("NotFoundException", "Invalid Method identifier specified", 404)
+    integration = method_obj.get("methodIntegration")
+    if not integration:
+        return _v1_error("NotFoundException", "Invalid Integration identifier specified", 404)
+    resp = integration["integrationResponses"].get(status_code)
+    if not resp:
+        return _v1_error("NotFoundException", "Invalid Response status code specified", 404)
+    return _v1_response(resp)
+
+
+def _delete_integration_response(api_id, resource_id, http_method, status_code):
+    resource = _resources.get(api_id, {}).get(resource_id)
+    if not resource:
+        return _v1_error("NotFoundException", "Invalid Resource identifier specified", 404)
+    method_obj = resource["resourceMethods"].get(http_method)
+    if method_obj and method_obj.get("methodIntegration"):
+        method_obj["methodIntegration"]["integrationResponses"].pop(status_code, None)
+    return 204, {}, b""
+
+
+# ---- Helpers ----
+
+def _build_api_summary(api_id):
+    """Build the apiSummary structure: {path: {httpMethod: {authorizationScopes, apiKeyRequired}}}."""
+    summary = {}
+    for resource in _resources.get(api_id, {}).values():
+        path = resource.get("path", "/")
+        for http_method, method_obj in resource.get("resourceMethods", {}).items():
+            if path not in summary:
+                summary[path] = {}
+            summary[path][http_method] = {
+                "authorizationScopes": [],
+                "apiKeyRequired": method_obj.get("apiKeyRequired", False),
+            }
+    return summary
+
+
+# ---- Control plane: Deployments ----
+
+def _create_deployment(api_id, data):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    deployment_id = _new_id()[:8]
+    deployment = {
+        "id": deployment_id,
+        "description": data.get("description", ""),
+        "createdDate": _now_unix(),
+        "apiSummary": _build_api_summary(api_id),
+    }
+    _deployments_v1.setdefault(api_id, {})[deployment_id] = deployment
+
+    # If stageName is provided, create/update the stage automatically
+    stage_name = data.get("stageName")
+    if stage_name:
+        existing_stage = _stages_v1.get(api_id, {}).get(stage_name)
+        if existing_stage:
+            existing_stage["deploymentId"] = deployment_id
+            existing_stage["lastUpdatedDate"] = _now_unix()
+        else:
+            stage = {
+                "stageName": stage_name,
+                "deploymentId": deployment_id,
+                "description": data.get("stageDescription", ""),
+                "createdDate": _now_unix(),
+                "lastUpdatedDate": _now_unix(),
+                "variables": data.get("variables", {}),
+                "methodSettings": {},
+                "accessLogSettings": {},
+                "cacheClusterEnabled": False,
+                "cacheClusterSize": None,
+                "tracingEnabled": False,
+                "tags": {},
+                "documentationVersion": None,
+            }
+            _stages_v1.setdefault(api_id, {})[stage_name] = stage
+
+    return _v1_response(deployment, 201)
+
+
+def _get_deployments(api_id):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    return _v1_response({"item": list(_deployments_v1.get(api_id, {}).values())})
+
+
+def _get_deployment(api_id, deployment_id):
+    deployment = _deployments_v1.get(api_id, {}).get(deployment_id)
+    if not deployment:
+        return _v1_error("NotFoundException", "Invalid Deployment identifier specified", 404)
+    return _v1_response(deployment)
+
+
+def _update_deployment(api_id, deployment_id, data):
+    deployment = _deployments_v1.get(api_id, {}).get(deployment_id)
+    if not deployment:
+        return _v1_error("NotFoundException", "Invalid Deployment identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(deployment, patch_ops)
+    return _v1_response(deployment)
+
+
+def _delete_deployment(api_id, deployment_id):
+    if deployment_id not in _deployments_v1.get(api_id, {}):
+        return _v1_error("NotFoundException", "Invalid Deployment identifier specified", 404)
+    _deployments_v1[api_id].pop(deployment_id, None)
+    return 202, {}, b""
+
+
+# ---- Control plane: Stages ----
+
+def _create_stage(api_id, data):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    stage_name = data.get("stageName", "")
+    if not stage_name:
+        return _v1_error("BadRequestException", "Stage name is required", 400)
+    stage = {
+        "stageName": stage_name,
+        "deploymentId": data.get("deploymentId", ""),
+        "description": data.get("description", ""),
+        "createdDate": _now_unix(),
+        "lastUpdatedDate": _now_unix(),
+        "variables": data.get("variables", {}),
+        "methodSettings": data.get("methodSettings", {}),
+        "accessLogSettings": data.get("accessLogSettings", {}),
+        "cacheClusterEnabled": data.get("cacheClusterEnabled", False),
+        "cacheClusterSize": data.get("cacheClusterSize"),
+        "tracingEnabled": data.get("tracingEnabled", False),
+        "tags": data.get("tags", {}),
+        "documentationVersion": data.get("documentationVersion"),
+    }
+    _stages_v1.setdefault(api_id, {})[stage_name] = stage
+    return _v1_response(stage, 201)
+
+
+def _get_stages(api_id):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    return _v1_response({"item": list(_stages_v1.get(api_id, {}).values())})
+
+
+def _get_stage(api_id, stage_name):
+    stage = _stages_v1.get(api_id, {}).get(stage_name)
+    if not stage:
+        return _v1_error("NotFoundException", "Invalid Stage identifier specified", 404)
+    return _v1_response(stage)
+
+
+def _update_stage(api_id, stage_name, data):
+    stage = _stages_v1.get(api_id, {}).get(stage_name)
+    if not stage:
+        return _v1_error("NotFoundException", "Invalid Stage identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(stage, patch_ops)
+    stage["lastUpdatedDate"] = _now_unix()
+    return _v1_response(stage)
+
+
+def _delete_stage(api_id, stage_name):
+    if stage_name not in _stages_v1.get(api_id, {}):
+        return _v1_error("NotFoundException", "Invalid Stage identifier specified", 404)
+    _stages_v1[api_id].pop(stage_name, None)
+    return 202, {}, b""
+
+
+# ---- Control plane: Authorizers ----
+
+def _create_authorizer(api_id, data):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    auth_id = _new_id()[:8]
+    authorizer = {
+        "id": auth_id,
+        "name": data.get("name", ""),
+        "type": data.get("type", "TOKEN"),
+        "authorizerUri": data.get("authorizerUri", ""),
+        "authorizerCredentials": data.get("authorizerCredentials"),
+        "identitySource": data.get("identitySource", "method.request.header.Authorization"),
+        "identityValidationExpression": data.get("identityValidationExpression", ""),
+        "authorizerResultTtlInSeconds": data.get("authorizerResultTtlInSeconds", 300),
+        "providerARNs": data.get("providerARNs", []),
+    }
+    _authorizers_v1.setdefault(api_id, {})[auth_id] = authorizer
+    return _v1_response(authorizer, 201)
+
+
+def _get_authorizers(api_id):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    return _v1_response({"item": list(_authorizers_v1.get(api_id, {}).values())})
+
+
+def _get_authorizer(api_id, auth_id):
+    authorizer = _authorizers_v1.get(api_id, {}).get(auth_id)
+    if not authorizer:
+        return _v1_error("NotFoundException", "Invalid Authorizer identifier specified", 404)
+    return _v1_response(authorizer)
+
+
+def _update_authorizer(api_id, auth_id, data):
+    authorizer = _authorizers_v1.get(api_id, {}).get(auth_id)
+    if not authorizer:
+        return _v1_error("NotFoundException", "Invalid Authorizer identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(authorizer, patch_ops)
+    return _v1_response(authorizer)
+
+
+def _delete_authorizer(api_id, auth_id):
+    if auth_id not in _authorizers_v1.get(api_id, {}):
+        return _v1_error("NotFoundException", "Invalid Authorizer identifier specified", 404)
+    _authorizers_v1[api_id].pop(auth_id, None)
+    return 202, {}, b""
+
+
+# ---- Control plane: Models ----
+
+def _create_model(api_id, data):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    model_name = data.get("name", "")
+    if not model_name:
+        return _v1_error("BadRequestException", "Model name is required", 400)
+    model = {
+        "id": _new_id()[:8],
+        "name": model_name,
+        "description": data.get("description", ""),
+        "schema": data.get("schema", ""),
+        "contentType": data.get("contentType", "application/json"),
+    }
+    _models.setdefault(api_id, {})[model_name] = model
+    return _v1_response(model, 201)
+
+
+def _get_models(api_id):
+    if api_id not in _rest_apis:
+        return _v1_error("NotFoundException", "Invalid API identifier specified", 404)
+    return _v1_response({"item": list(_models.get(api_id, {}).values())})
+
+
+def _get_model(api_id, model_name):
+    model = _models.get(api_id, {}).get(model_name)
+    if not model:
+        return _v1_error("NotFoundException", "Invalid Model identifier specified", 404)
+    return _v1_response(model)
+
+
+def _delete_model(api_id, model_name):
+    if model_name not in _models.get(api_id, {}):
+        return _v1_error("NotFoundException", "Invalid Model identifier specified", 404)
+    _models[api_id].pop(model_name, None)
+    return 202, {}, b""
+
+
+# ---- Control plane: API Keys ----
+
+def _create_api_key(data):
+    key_id = _new_id()[:8]
+    key_value = new_uuid().replace("-", "")
+    api_key = {
+        "id": key_id,
+        "name": data.get("name", ""),
+        "description": data.get("description", ""),
+        "enabled": data.get("enabled", True),
+        "createdDate": _now_unix(),
+        "lastUpdatedDate": _now_unix(),
+        "value": key_value,
+        "stageKeys": data.get("stageKeys", []),
+        "tags": data.get("tags", {}),
+    }
+    _api_keys[key_id] = api_key
+    return _v1_response(api_key, 201)
+
+
+def _get_api_keys():
+    return _v1_response({"item": list(_api_keys.values())})
+
+
+def _get_api_key(key_id):
+    key = _api_keys.get(key_id)
+    if not key:
+        return _v1_error("NotFoundException", "Invalid API Key identifier specified", 404)
+    return _v1_response(key)
+
+
+def _update_api_key(key_id, data):
+    key = _api_keys.get(key_id)
+    if not key:
+        return _v1_error("NotFoundException", "Invalid API Key identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(key, patch_ops)
+    key["lastUpdatedDate"] = _now_unix()
+    return _v1_response(key)
+
+
+def _delete_api_key(key_id):
+    if key_id not in _api_keys:
+        return _v1_error("NotFoundException", "Invalid API Key identifier specified", 404)
+    _api_keys.pop(key_id, None)
+    return 202, {}, b""
+
+
+# ---- Control plane: Usage Plans ----
+
+def _create_usage_plan(data):
+    plan_id = _new_id()[:8]
+    plan = {
+        "id": plan_id,
+        "name": data.get("name", ""),
+        "description": data.get("description", ""),
+        "apiStages": data.get("apiStages", []),
+        "throttle": data.get("throttle", {}),
+        "quota": data.get("quota", {}),
+        "tags": data.get("tags", {}),
+    }
+    _usage_plans[plan_id] = plan
+    _usage_plan_keys[plan_id] = {}
+    return _v1_response(plan, 201)
+
+
+def _get_usage_plans():
+    return _v1_response({"item": list(_usage_plans.values())})
+
+
+def _get_usage_plan(plan_id):
+    plan = _usage_plans.get(plan_id)
+    if not plan:
+        return _v1_error("NotFoundException", "Invalid Usage Plan identifier specified", 404)
+    return _v1_response(plan)
+
+
+def _update_usage_plan(plan_id, data):
+    plan = _usage_plans.get(plan_id)
+    if not plan:
+        return _v1_error("NotFoundException", "Invalid Usage Plan identifier specified", 404)
+    patch_ops = data.get("patchOperations", [])
+    _apply_patch(plan, patch_ops)
+    return _v1_response(plan)
+
+
+def _delete_usage_plan(plan_id):
+    if plan_id not in _usage_plans:
+        return _v1_error("NotFoundException", "Invalid Usage Plan identifier specified", 404)
+    _usage_plans.pop(plan_id, None)
+    _usage_plan_keys.pop(plan_id, None)
+    return 202, {}, b""
+
+
+def _create_usage_plan_key(plan_id, data):
+    if plan_id not in _usage_plans:
+        return _v1_error("NotFoundException", "Invalid Usage Plan identifier specified", 404)
+    key_id = data.get("keyId", "")
+    key_type = data.get("keyType", "API_KEY")
+    plan_key = {
+        "id": key_id,
+        "type": key_type,
+        "name": _api_keys.get(key_id, {}).get("name", ""),
+        "value": _api_keys.get(key_id, {}).get("value", ""),
+    }
+    _usage_plan_keys.setdefault(plan_id, {})[key_id] = plan_key
+    return _v1_response(plan_key, 201)
+
+
+def _get_usage_plan_keys(plan_id):
+    if plan_id not in _usage_plans:
+        return _v1_error("NotFoundException", "Invalid Usage Plan identifier specified", 404)
+    return _v1_response({"item": list(_usage_plan_keys.get(plan_id, {}).values())})
+
+
+def _delete_usage_plan_key(plan_id, key_id):
+    if plan_id not in _usage_plans:
+        return _v1_error("NotFoundException", "Invalid Usage Plan identifier specified", 404)
+    _usage_plan_keys.get(plan_id, {}).pop(key_id, None)
+    return 202, {}, b""
+
+
+# ---- Control plane: Domain Names ----
+
+def _create_domain_name(data):
+    domain_name = data.get("domainName", "")
+    if not domain_name:
+        return _v1_error("BadRequestException", "Domain name is required", 400)
+    dn = {
+        "domainName": domain_name,
+        "certificateName": data.get("certificateName", ""),
+        "certificateArn": data.get("certificateArn", ""),
+        "distributionDomainName": f"{domain_name}.cloudfront.net",
+        "regionalDomainName": f"{domain_name}.execute-api.{get_region()}.amazonaws.com",
+        "regionalHostedZoneId": "Z1UJRXOUMOOFQ8",
+        "endpointConfiguration": data.get("endpointConfiguration", {"types": ["REGIONAL"]}),
+        "tags": data.get("tags", {}),
+    }
+    _domain_names[domain_name] = dn
+    _base_path_mappings[domain_name] = {}
+    return _v1_response(dn, 201)
+
+
+def _get_domain_names():
+    return _v1_response({"item": list(_domain_names.values())})
+
+
+def _get_domain_name(domain_name):
+    dn = _domain_names.get(domain_name)
+    if not dn:
+        return _v1_error("NotFoundException", "Invalid domain name identifier specified", 404)
+    return _v1_response(dn)
+
+
+def _delete_domain_name(domain_name):
+    if domain_name not in _domain_names:
+        return _v1_error("NotFoundException", "Invalid domain name identifier specified", 404)
+    _domain_names.pop(domain_name, None)
+    _base_path_mappings.pop(domain_name, None)
+    return 202, {}, b""
+
+
+def _create_base_path_mapping(domain_name, data):
+    if domain_name not in _domain_names:
+        return _v1_error("NotFoundException", "Invalid domain name identifier specified", 404)
+    base_path = data.get("basePath", "(none)")
+    mapping = {
+        "basePath": base_path,
+        "restApiId": data.get("restApiId", ""),
+        "stage": data.get("stage", ""),
+    }
+    _base_path_mappings.setdefault(domain_name, {})[base_path] = mapping
+    return _v1_response(mapping, 201)
+
+
+def _get_base_path_mappings(domain_name):
+    if domain_name not in _domain_names:
+        return _v1_error("NotFoundException", "Invalid domain name identifier specified", 404)
+    return _v1_response({"item": list(_base_path_mappings.get(domain_name, {}).values())})
+
+
+def _get_base_path_mapping(domain_name, base_path):
+    mapping = _base_path_mappings.get(domain_name, {}).get(base_path)
+    if not mapping:
+        return _v1_error("NotFoundException", "Invalid base path mapping identifier specified", 404)
+    return _v1_response(mapping)
+
+
+def _delete_base_path_mapping(domain_name, base_path):
+    _base_path_mappings.get(domain_name, {}).pop(base_path, None)
+    return 202, {}, b""
+
+
+# ---- Control plane: Tags ----
+
+def _get_v1_tags(resource_arn):
+    tags = _v1_tags.get(resource_arn, {})
+    return _v1_response({"tags": tags})
+
+
+def _tag_v1_resource(resource_arn, data):
+    tags = data.get("tags", {})
+    _v1_tags.setdefault(resource_arn, {}).update(tags)
+    return 204, {}, b""
+
+
+def _untag_v1_resource(resource_arn, tag_keys):
+    existing = _v1_tags.get(resource_arn, {})
+    for key in tag_keys:
+        existing.pop(key, None)
+    return 204, {}, b""
+
+def get_state_summary() -> dict:
+    return {
+        "rest_apis": {"count": len(_rest_apis), "ids": list(_rest_apis.keys())},
+        "resources": {"count": sum(len(r) for r in _resources.values()) if _resources else 0},
+        "api_keys": {"count": len(_api_keys), "ids": list(_api_keys.keys())},
+        "usage_plans": {"count": len(_usage_plans), "ids": list(_usage_plans.keys())},
+        "domain_names": {"count": len(_domain_names), "names": list(_domain_names.keys())},
+    }

aws_infra/ministack/services/appconfig.py

@@ -0,0 +1,852 @@
+"""
+AppConfig Service Emulator.
+REST/JSON protocol — path-based routing.
+
+Control Plane (appconfig):
+  Applications:              CreateApplication, GetApplication, ListApplications,
+                             UpdateApplication, DeleteApplication
+  Environments:              CreateEnvironment, GetEnvironment, ListEnvironments,
+                             UpdateEnvironment, DeleteEnvironment
+  Configuration Profiles:    CreateConfigurationProfile, GetConfigurationProfile,
+                             ListConfigurationProfiles, UpdateConfigurationProfile,
+                             DeleteConfigurationProfile
+  Hosted Configuration Versions: CreateHostedConfigurationVersion,
+                             GetHostedConfigurationVersion,
+                             ListHostedConfigurationVersions,
+                             DeleteHostedConfigurationVersion
+  Deployment Strategies:     CreateDeploymentStrategy, GetDeploymentStrategy,
+                             ListDeploymentStrategies, UpdateDeploymentStrategy,
+                             DeleteDeploymentStrategy
+  Deployments:               StartDeployment, GetDeployment, ListDeployments,
+                             StopDeployment
+  Tags:                      TagResource, UntagResource, ListTagsForResource
+
+Data Plane (appconfigdata):
+  StartConfigurationSession, GetLatestConfiguration
+"""
+
+import copy
+import json
+import logging
+import os
+import re
+import time
+import uuid
+
+from ministack.core.persistence import PERSIST_STATE, load_state
+from ministack.core.responses import AccountScopedDict, get_account_id, get_region
+
+logger = logging.getLogger("appconfig")
+
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+_applications = AccountScopedDict()
+_environments = AccountScopedDict()          # "{app_id}/{env_id}" -> record
+_config_profiles = AccountScopedDict()       # "{app_id}/{profile_id}" -> record
+_hosted_versions = AccountScopedDict()       # "{app_id}/{profile_id}/{version}" -> record
+_deployment_strategies = AccountScopedDict()
+_deployments = AccountScopedDict()           # "{app_id}/{env_id}/{deploy_num}" -> record
+_tags = AccountScopedDict()                  # arn -> {key: value}
+_sessions = AccountScopedDict()              # token -> session record
+
+# ---------------------------------------------------------------------------
+# Persistence
+# ---------------------------------------------------------------------------
+
+
+def get_state():
+    return copy.deepcopy({
+        "applications": _applications,
+        "environments": _environments,
+        "config_profiles": _config_profiles,
+        "hosted_versions": _hosted_versions,
+        "deployment_strategies": _deployment_strategies,
+        "deployments": _deployments,
+        "tags": _tags,
+    })
+
+
+def restore_state(data):
+    _applications.update(data.get("applications", {}))
+    _environments.update(data.get("environments", {}))
+    _config_profiles.update(data.get("config_profiles", {}))
+    _hosted_versions.update(data.get("hosted_versions", {}))
+    _deployment_strategies.update(data.get("deployment_strategies", {}))
+    _deployments.update(data.get("deployments", {}))
+    _tags.update(data.get("tags", {}))
+
+
+_restored = load_state("appconfig")
+if _restored:
+    restore_state(_restored)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _gen_id():
+    return uuid.uuid4().hex[:7]
+
+
+def _now_iso():
+    return time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
+
+
+def _app_arn(app_id):
+    return f"arn:aws:appconfig:{get_region()}:{get_account_id()}:application/{app_id}"
+
+
+def _env_arn(app_id, env_id):
+    return f"arn:aws:appconfig:{get_region()}:{get_account_id()}:application/{app_id}/environment/{env_id}"
+
+
+def _profile_arn(app_id, profile_id):
+    return f"arn:aws:appconfig:{get_region()}:{get_account_id()}:application/{app_id}/configurationprofile/{profile_id}"
+
+
+def _strategy_arn(strategy_id):
+    return f"arn:aws:appconfig:{get_region()}:{get_account_id()}:deploymentstrategy/{strategy_id}"
+
+
+def _deployment_arn(app_id, env_id, deploy_num):
+    return (
+        f"arn:aws:appconfig:{get_region()}:{get_account_id()}:"
+        f"application/{app_id}/environment/{env_id}/deployment/{deploy_num}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Applications
+# ---------------------------------------------------------------------------
+
+
+def _create_application(body):
+    name = body.get("Name")
+    if not name:
+        return _error(400, "BadRequestException", "Name is required")
+    app_id = _gen_id()
+    record = {
+        "Id": app_id,
+        "Name": name,
+        "Description": body.get("Description", ""),
+    }
+    _applications[app_id] = record
+    _apply_tags(_app_arn(app_id), body.get("Tags", {}))
+    logger.info("CreateApplication: %s (%s)", name, app_id)
+    return _json(201, record)
+
+
+def _get_application(app_id):
+    app = _applications.get(app_id)
+    if not app:
+        return _error(404, "ResourceNotFoundException", f"Application {app_id} not found")
+    return _json(200, app)
+
+
+def _list_applications(query):
+    max_results = int(query.get("max_results", 50))
+    items = list(_applications.values())
+    return _json(200, {"Items": items[:max_results]})
+
+
+def _update_application(app_id, body):
+    app = _applications.get(app_id)
+    if not app:
+        return _error(404, "ResourceNotFoundException", f"Application {app_id} not found")
+    if "Name" in body:
+        app["Name"] = body["Name"]
+    if "Description" in body:
+        app["Description"] = body["Description"]
+    return _json(200, app)
+
+
+def _delete_application(app_id):
+    if app_id not in _applications:
+        return _error(404, "ResourceNotFoundException", f"Application {app_id} not found")
+    del _applications[app_id]
+    _tags.pop(_app_arn(app_id), None)
+    keys_to_remove = [k for k in _environments if k.startswith(f"{app_id}/")]
+    for k in keys_to_remove:
+        _environments.pop(k, None)
+    keys_to_remove = [k for k in _config_profiles if k.startswith(f"{app_id}/")]
+    for k in keys_to_remove:
+        _config_profiles.pop(k, None)
+    keys_to_remove = [k for k in _hosted_versions if k.startswith(f"{app_id}/")]
+    for k in keys_to_remove:
+        _hosted_versions.pop(k, None)
+    keys_to_remove = [k for k in _deployments if k.startswith(f"{app_id}/")]
+    for k in keys_to_remove:
+        _deployments.pop(k, None)
+    return _json(204, {})
+
+
+# ---------------------------------------------------------------------------
+# Environments
+# ---------------------------------------------------------------------------
+
+
+def _create_environment(app_id, body):
+    if app_id not in _applications:
+        return _error(404, "ResourceNotFoundException", f"Application {app_id} not found")
+    name = body.get("Name")
+    if not name:
+        return _error(400, "BadRequestException", "Name is required")
+    env_id = _gen_id()
+    record = {
+        "ApplicationId": app_id,
+        "Id": env_id,
+        "Name": name,
+        "Description": body.get("Description", ""),
+        "State": "READY_FOR_DEPLOYMENT",
+        "Monitors": body.get("Monitors", []),
+    }
+    _environments[f"{app_id}/{env_id}"] = record
+    _apply_tags(_env_arn(app_id, env_id), body.get("Tags", {}))
+    logger.info("CreateEnvironment: %s/%s (%s)", app_id, name, env_id)
+    return _json(201, record)
+
+
+def _get_environment(app_id, env_id):
+    env = _environments.get(f"{app_id}/{env_id}")
+    if not env:
+        return _error(404, "ResourceNotFoundException", f"Environment {env_id} not found")
+    return _json(200, env)
+
+
+def _list_environments(app_id, query):
+    if app_id not in _applications:
+        return _error(404, "ResourceNotFoundException", f"Application {app_id} not found")
+    max_results = int(query.get("max_results", 50))
+    items = [e for e in _environments.values() if e["ApplicationId"] == app_id]
+    return _json(200, {"Items": items[:max_results]})
+
+
+def _update_environment(app_id, env_id, body):
+    env = _environments.get(f"{app_id}/{env_id}")
+    if not env:
+        return _error(404, "ResourceNotFoundException", f"Environment {env_id} not found")
+    if "Name" in body:
+        env["Name"] = body["Name"]
+    if "Description" in body:
+        env["Description"] = body["Description"]
+    if "Monitors" in body:
+        env["Monitors"] = body["Monitors"]
+    return _json(200, env)
+
+
+def _delete_environment(app_id, env_id):
+    key = f"{app_id}/{env_id}"
+    if key not in _environments:
+        return _error(404, "ResourceNotFoundException", f"Environment {env_id} not found")
+    del _environments[key]
+    _tags.pop(_env_arn(app_id, env_id), None)
+    return _json(204, {})
+
+
+# ---------------------------------------------------------------------------
+# Configuration Profiles
+# ---------------------------------------------------------------------------
+
+
+def _create_configuration_profile(app_id, body):
+    if app_id not in _applications:
+        return _error(404, "ResourceNotFoundException", f"Application {app_id} not found")
+    name = body.get("Name")
+    if not name:
+        return _error(400, "BadRequestException", "Name is required")
+    location_uri = body.get("LocationUri", "hosted")
+    profile_id = _gen_id()
+    record = {
+        "ApplicationId": app_id,
+        "Id": profile_id,
+        "Name": name,
+        "Description": body.get("Description", ""),
+        "LocationUri": location_uri,
+        "RetrievalRoleArn": body.get("RetrievalRoleArn", ""),
+        "Validators": body.get("Validators", []),
+        "Type": body.get("Type", "AWS.Freeform"),
+    }
+    _config_profiles[f"{app_id}/{profile_id}"] = record
+    _apply_tags(_profile_arn(app_id, profile_id), body.get("Tags", {}))
+    logger.info("CreateConfigurationProfile: %s/%s (%s)", app_id, name, profile_id)
+    return _json(201, record)
+
+
+def _get_configuration_profile(app_id, profile_id):
+    profile = _config_profiles.get(f"{app_id}/{profile_id}")
+    if not profile:
+        return _error(404, "ResourceNotFoundException", f"Configuration profile {profile_id} not found")
+    return _json(200, profile)
+
+
+def _list_configuration_profiles(app_id, query):
+    if app_id not in _applications:
+        return _error(404, "ResourceNotFoundException", f"Application {app_id} not found")
+    max_results = int(query.get("max_results", 50))
+    items = [p for p in _config_profiles.values() if p["ApplicationId"] == app_id]
+    return _json(200, {"Items": items[:max_results]})
+
+
+def _update_configuration_profile(app_id, profile_id, body):
+    profile = _config_profiles.get(f"{app_id}/{profile_id}")
+    if not profile:
+        return _error(404, "ResourceNotFoundException", f"Configuration profile {profile_id} not found")
+    for field in ("Name", "Description", "RetrievalRoleArn", "Validators"):
+        if field in body:
+            profile[field] = body[field]
+    return _json(200, profile)
+
+
+def _delete_configuration_profile(app_id, profile_id):
+    key = f"{app_id}/{profile_id}"
+    if key not in _config_profiles:
+        return _error(404, "ResourceNotFoundException", f"Configuration profile {profile_id} not found")
+    del _config_profiles[key]
+    _tags.pop(_profile_arn(app_id, profile_id), None)
+    keys_to_remove = [k for k in _hosted_versions if k.startswith(f"{app_id}/{profile_id}/")]
+    for k in keys_to_remove:
+        _hosted_versions.pop(k, None)
+    return _json(204, {})
+
+
+# ---------------------------------------------------------------------------
+# Hosted Configuration Versions
+# ---------------------------------------------------------------------------
+
+
+def _create_hosted_configuration_version(app_id, profile_id, body, content_type):
+    if f"{app_id}/{profile_id}" not in _config_profiles:
+        return _error(404, "ResourceNotFoundException", f"Configuration profile {profile_id} not found")
+
+    existing = [
+        v for k, v in _hosted_versions.items()
+        if k.startswith(f"{app_id}/{profile_id}/")
+    ]
+    version_number = len(existing) + 1
+
+    record = {
+        "ApplicationId": app_id,
+        "ConfigurationProfileId": profile_id,
+        "VersionNumber": version_number,
+        "ContentType": content_type,
+        "Content": body,
+        "Description": "",
+    }
+    _hosted_versions[f"{app_id}/{profile_id}/{version_number}"] = record
+    logger.info("CreateHostedConfigurationVersion: %s/%s v%d", app_id, profile_id, version_number)
+
+    resp_headers = {
+        "Content-Type": content_type,
+        "Application-Id": app_id,
+        "Configuration-Profile-Id": profile_id,
+        "Version-Number": str(version_number),
+    }
+    return 201, resp_headers, body if isinstance(body, bytes) else body.encode("utf-8")
+
+
+def _get_hosted_configuration_version(app_id, profile_id, version_number):
+    key = f"{app_id}/{profile_id}/{version_number}"
+    record = _hosted_versions.get(key)
+    if not record:
+        return _error(404, "ResourceNotFoundException",
+                      f"Hosted configuration version {version_number} not found")
+    content = record["Content"]
+    resp_headers = {
+        "Content-Type": record["ContentType"],
+        "Application-Id": app_id,
+        "Configuration-Profile-Id": profile_id,
+        "Version-Number": str(version_number),
+    }
+    return 200, resp_headers, content if isinstance(content, bytes) else content.encode("utf-8")
+
+
+def _list_hosted_configuration_versions(app_id, profile_id, query):
+    if f"{app_id}/{profile_id}" not in _config_profiles:
+        return _error(404, "ResourceNotFoundException", f"Configuration profile {profile_id} not found")
+    max_results = int(query.get("max_results", 50))
+    items = []
+    for k, v in _hosted_versions.items():
+        if k.startswith(f"{app_id}/{profile_id}/"):
+            items.append({
+                "ApplicationId": app_id,
+                "ConfigurationProfileId": profile_id,
+                "VersionNumber": v["VersionNumber"],
+                "ContentType": v["ContentType"],
+                "Description": v.get("Description", ""),
+            })
+    return _json(200, {"Items": items[:max_results]})
+
+
+def _delete_hosted_configuration_version(app_id, profile_id, version_number):
+    key = f"{app_id}/{profile_id}/{version_number}"
+    if key not in _hosted_versions:
+        return _error(404, "ResourceNotFoundException",
+                      f"Hosted configuration version {version_number} not found")
+    del _hosted_versions[key]
+    return _json(204, {})
+
+
+# ---------------------------------------------------------------------------
+# Deployment Strategies
+# ---------------------------------------------------------------------------
+
+
+def _create_deployment_strategy(body):
+    name = body.get("Name")
+    if not name:
+        return _error(400, "BadRequestException", "Name is required")
+    strategy_id = _gen_id()
+    record = {
+        "Id": strategy_id,
+        "Name": name,
+        "Description": body.get("Description", ""),
+        "DeploymentDurationInMinutes": body.get("DeploymentDurationInMinutes", 0),
+        "GrowthType": body.get("GrowthType", "LINEAR"),
+        "GrowthFactor": body.get("GrowthFactor", 100.0),
+        "FinalBakeTimeInMinutes": body.get("FinalBakeTimeInMinutes", 0),
+        "ReplicateTo": body.get("ReplicateTo", "NONE"),
+    }
+    _deployment_strategies[strategy_id] = record
+    _apply_tags(_strategy_arn(strategy_id), body.get("Tags", {}))
+    logger.info("CreateDeploymentStrategy: %s (%s)", name, strategy_id)
+    return _json(201, record)
+
+
+def _get_deployment_strategy(strategy_id):
+    strategy = _deployment_strategies.get(strategy_id)
+    if not strategy:
+        return _error(404, "ResourceNotFoundException", f"Deployment strategy {strategy_id} not found")
+    return _json(200, strategy)
+
+
+def _list_deployment_strategies(query):
+    max_results = int(query.get("max_results", 50))
+    items = list(_deployment_strategies.values())
+    return _json(200, {"Items": items[:max_results]})
+
+
+def _update_deployment_strategy(strategy_id, body):
+    strategy = _deployment_strategies.get(strategy_id)
+    if not strategy:
+        return _error(404, "ResourceNotFoundException", f"Deployment strategy {strategy_id} not found")
+    for field in ("Description", "DeploymentDurationInMinutes", "GrowthType",
+                  "GrowthFactor", "FinalBakeTimeInMinutes"):
+        if field in body:
+            strategy[field] = body[field]
+    return _json(200, strategy)
+
+
+def _delete_deployment_strategy(strategy_id):
+    if strategy_id not in _deployment_strategies:
+        return _error(404, "ResourceNotFoundException", f"Deployment strategy {strategy_id} not found")
+    del _deployment_strategies[strategy_id]
+    _tags.pop(_strategy_arn(strategy_id), None)
+    return _json(204, {})
+
+
+# ---------------------------------------------------------------------------
+# Deployments
+# ---------------------------------------------------------------------------
+
+
+def _start_deployment(app_id, env_id, body):
+    if app_id not in _applications:
+        return _error(404, "ResourceNotFoundException", f"Application {app_id} not found")
+    if f"{app_id}/{env_id}" not in _environments:
+        return _error(404, "ResourceNotFoundException", f"Environment {env_id} not found")
+
+    strategy_id = body.get("DeploymentStrategyId", "")
+    profile_id = body.get("ConfigurationProfileId", "")
+    version = body.get("ConfigurationVersion", "")
+
+    if profile_id and f"{app_id}/{profile_id}" not in _config_profiles:
+        return _error(404, "ResourceNotFoundException", f"Configuration profile {profile_id} not found")
+
+    existing = [
+        v for k, v in _deployments.items()
+        if k.startswith(f"{app_id}/{env_id}/")
+    ]
+    deploy_num = len(existing) + 1
+
+    now = _now_iso()
+    record = {
+        "ApplicationId": app_id,
+        "EnvironmentId": env_id,
+        "DeploymentStrategyId": strategy_id,
+        "ConfigurationProfileId": profile_id,
+        "DeploymentNumber": deploy_num,
+        "ConfigurationName": _config_profiles.get(f"{app_id}/{profile_id}", {}).get("Name", ""),
+        "ConfigurationLocationUri": "hosted",
+        "ConfigurationVersion": version,
+        "Description": body.get("Description", ""),
+        "DeploymentDurationInMinutes": 0,
+        "GrowthType": "LINEAR",
+        "GrowthFactor": 100.0,
+        "FinalBakeTimeInMinutes": 0,
+        "State": "COMPLETE",
+        "PercentageComplete": 100.0,
+        "StartedAt": now,
+        "CompletedAt": now,
+    }
+    _deployments[f"{app_id}/{env_id}/{deploy_num}"] = record
+    logger.info("StartDeployment: %s/%s #%d (profile=%s, version=%s)",
+                app_id, env_id, deploy_num, profile_id, version)
+    return _json(201, record)
+
+
+def _get_deployment(app_id, env_id, deploy_num):
+    record = _deployments.get(f"{app_id}/{env_id}/{deploy_num}")
+    if not record:
+        return _error(404, "ResourceNotFoundException", f"Deployment {deploy_num} not found")
+    return _json(200, record)
+
+
+def _list_deployments(app_id, env_id, query):
+    if f"{app_id}/{env_id}" not in _environments:
+        return _error(404, "ResourceNotFoundException", f"Environment {env_id} not found")
+    max_results = int(query.get("max_results", 50))
+    items = []
+    for k, v in _deployments.items():
+        if k.startswith(f"{app_id}/{env_id}/"):
+            items.append({
+                "DeploymentNumber": v["DeploymentNumber"],
+                "ConfigurationName": v.get("ConfigurationName", ""),
+                "ConfigurationVersion": v.get("ConfigurationVersion", ""),
+                "DeploymentDurationInMinutes": v.get("DeploymentDurationInMinutes", 0),
+                "GrowthType": v.get("GrowthType", "LINEAR"),
+                "GrowthFactor": v.get("GrowthFactor", 100.0),
+                "FinalBakeTimeInMinutes": v.get("FinalBakeTimeInMinutes", 0),
+                "State": v.get("State", "COMPLETE"),
+                "PercentageComplete": v.get("PercentageComplete", 100.0),
+                "StartedAt": v.get("StartedAt", ""),
+                "CompletedAt": v.get("CompletedAt", ""),
+            })
+    return _json(200, {"Items": items[:max_results]})
+
+
+def _stop_deployment(app_id, env_id, deploy_num):
+    record = _deployments.get(f"{app_id}/{env_id}/{deploy_num}")
+    if not record:
+        return _error(404, "ResourceNotFoundException", f"Deployment {deploy_num} not found")
+    record["State"] = "ROLLED_BACK"
+    return _json(202, record)
+
+
+# ---------------------------------------------------------------------------
+# Tags
+# ---------------------------------------------------------------------------
+
+
+def _apply_tags(arn, tags_dict):
+    if tags_dict:
+        if arn not in _tags:
+            _tags[arn] = {}
+        _tags[arn].update(tags_dict)
+
+
+def _tag_resource(resource_arn, body):
+    tags_dict = body.get("Tags", {})
+    _apply_tags(resource_arn, tags_dict)
+    return _json(204, {})
+
+
+def _untag_resource(resource_arn, tag_keys):
+    if resource_arn in _tags:
+        for key in tag_keys:
+            _tags[resource_arn].pop(key, None)
+    return _json(204, {})
+
+
+def _list_tags_for_resource(resource_arn):
+    return _json(200, {"Tags": _tags.get(resource_arn, {})})
+
+
+# ---------------------------------------------------------------------------
+# Data Plane — StartConfigurationSession / GetLatestConfiguration
+# ---------------------------------------------------------------------------
+
+
+def _start_configuration_session(body):
+    app_id = body.get("ApplicationIdentifier", "")
+    env_id = body.get("EnvironmentIdentifier", "")
+    profile_id = body.get("ConfigurationProfileIdentifier", "")
+
+    if not app_id or not env_id or not profile_id:
+        return _error(400, "BadRequestException",
+                      "ApplicationIdentifier, EnvironmentIdentifier, and "
+                      "ConfigurationProfileIdentifier are required")
+
+    token = uuid.uuid4().hex
+    _sessions[token] = {
+        "ApplicationIdentifier": app_id,
+        "EnvironmentIdentifier": env_id,
+        "ConfigurationProfileIdentifier": profile_id,
+    }
+    logger.info("StartConfigurationSession: app=%s env=%s profile=%s", app_id, env_id, profile_id)
+    return _json(201, {"InitialConfigurationToken": token})
+
+
+def _get_latest_configuration(token):
+    session = _sessions.get(token)
+    if not session:
+        return _error(400, "BadRequestException", "Invalid or expired configuration token")
+
+    # Remove the used token
+    del _sessions[token]
+
+    app_id = session["ApplicationIdentifier"]
+    env_id = session["EnvironmentIdentifier"]
+    profile_id = session["ConfigurationProfileIdentifier"]
+
+    # Find the latest completed deployment for this app/env
+    latest_deploy = None
+    for k, v in _deployments.items():
+        if (k.startswith(f"{app_id}/{env_id}/")
+                and v.get("State") == "COMPLETE"
+                and v.get("ConfigurationProfileId") == profile_id):
+            if latest_deploy is None or v["DeploymentNumber"] > latest_deploy["DeploymentNumber"]:
+                latest_deploy = v
+
+    content = b""
+    content_type = "application/octet-stream"
+    if latest_deploy:
+        cfg_version = latest_deploy.get("ConfigurationVersion", "")
+        version_key = f"{app_id}/{profile_id}/{cfg_version}"
+        version_record = _hosted_versions.get(version_key)
+        if version_record:
+            raw = version_record["Content"]
+            content = raw if isinstance(raw, bytes) else raw.encode("utf-8")
+            content_type = version_record.get("ContentType", "application/octet-stream")
+
+    next_token = uuid.uuid4().hex
+    _sessions[next_token] = session.copy()
+
+    resp_headers = {
+        "Content-Type": content_type,
+        "Next-Poll-Configuration-Token": next_token,
+        "Next-Poll-Interval-In-Seconds": "30",
+    }
+    return 200, resp_headers, content
+
+
+# ---------------------------------------------------------------------------
+# Request router
+# ---------------------------------------------------------------------------
+
+
+async def handle_request(method, path, headers, body_bytes, query_params):
+    query = {k: (v[0] if isinstance(v, list) else v) for k, v in query_params.items()}
+
+    # --- Data plane paths ---
+    if path == "/configurationsessions" and method == "POST":
+        try:
+            data = json.loads(body_bytes) if body_bytes else {}
+        except json.JSONDecodeError:
+            return _error(400, "BadRequestException", "Invalid JSON")
+        return await _a(_start_configuration_session(data))
+
+    if path == "/configuration" and method == "GET":
+        token = query.get("configuration_token", "")
+        if not token:
+            return _error(400, "BadRequestException", "configuration_token is required")
+        return await _a(_get_latest_configuration(token))
+
+    # --- Control plane: tags ---
+    m = re.fullmatch(r"/tags/(.+)", path)
+    if m:
+        resource_arn = m.group(1)
+        if method == "POST":
+            try:
+                data = json.loads(body_bytes) if body_bytes else {}
+            except json.JSONDecodeError:
+                return _error(400, "BadRequestException", "Invalid JSON")
+            return await _a(_tag_resource(resource_arn, data))
+        if method == "GET":
+            return await _a(_list_tags_for_resource(resource_arn))
+        if method == "DELETE":
+            tag_keys = query.get("tagKeys", "")
+            keys = [k.strip() for k in tag_keys.split(",") if k.strip()] if tag_keys else []
+            return await _a(_untag_resource(resource_arn, keys))
+
+    # --- Control plane: parse JSON body for non-hosted-version routes ---
+    content_type = headers.get("content-type", "")
+
+    # Hosted configuration versions — body is raw content, not JSON
+    m = re.fullmatch(
+        r"/applications/([^/]+)/configurationprofiles/([^/]+)/hostedconfigurationversions",
+        path,
+    )
+    if m and method == "POST":
+        app_id, profile_id = m.group(1), m.group(2)
+        ct = content_type or "application/octet-stream"
+        return await _a(_create_hosted_configuration_version(app_id, profile_id, body_bytes, ct))
+
+    m = re.fullmatch(
+        r"/applications/([^/]+)/configurationprofiles/([^/]+)/hostedconfigurationversions/(\d+)",
+        path,
+    )
+    if m:
+        app_id, profile_id, ver = m.group(1), m.group(2), int(m.group(3))
+        if method == "GET":
+            return await _a(_get_hosted_configuration_version(app_id, profile_id, ver))
+        if method == "DELETE":
+            return await _a(_delete_hosted_configuration_version(app_id, profile_id, ver))
+
+    m = re.fullmatch(
+        r"/applications/([^/]+)/configurationprofiles/([^/]+)/hostedconfigurationversions",
+        path,
+    )
+    if m and method == "GET":
+        app_id, profile_id = m.group(1), m.group(2)
+        return await _a(_list_hosted_configuration_versions(app_id, profile_id, query))
+
+    # JSON body for remaining routes
+    try:
+        body = json.loads(body_bytes) if body_bytes else {}
+    except json.JSONDecodeError:
+        body = {}
+
+    # --- Applications ---
+    if path == "/applications":
+        if method == "POST":
+            return await _a(_create_application(body))
+        if method == "GET":
+            return await _a(_list_applications(query))
+
+    m = re.fullmatch(r"/applications/([^/]+)", path)
+    if m:
+        app_id = m.group(1)
+        if method == "GET":
+            return await _a(_get_application(app_id))
+        if method == "PATCH":
+            return await _a(_update_application(app_id, body))
+        if method == "DELETE":
+            return await _a(_delete_application(app_id))
+
+    # --- Deployments (must be checked before environments) ---
+    m = re.fullmatch(r"/applications/([^/]+)/environments/([^/]+)/deployments", path)
+    if m:
+        app_id, env_id = m.group(1), m.group(2)
+        if method == "POST":
+            return await _a(_start_deployment(app_id, env_id, body))
+        if method == "GET":
+            return await _a(_list_deployments(app_id, env_id, query))
+
+    m = re.fullmatch(r"/applications/([^/]+)/environments/([^/]+)/deployments/(\d+)", path)
+    if m:
+        app_id, env_id, deploy_num = m.group(1), m.group(2), int(m.group(3))
+        if method == "GET":
+            return await _a(_get_deployment(app_id, env_id, deploy_num))
+        if method == "DELETE":
+            return await _a(_stop_deployment(app_id, env_id, deploy_num))
+
+    # --- Environments ---
+    m = re.fullmatch(r"/applications/([^/]+)/environments", path)
+    if m:
+        app_id = m.group(1)
+        if method == "POST":
+            return await _a(_create_environment(app_id, body))
+        if method == "GET":
+            return await _a(_list_environments(app_id, query))
+
+    m = re.fullmatch(r"/applications/([^/]+)/environments/([^/]+)", path)
+    if m:
+        app_id, env_id = m.group(1), m.group(2)
+        if method == "GET":
+            return await _a(_get_environment(app_id, env_id))
+        if method == "PATCH":
+            return await _a(_update_environment(app_id, env_id, body))
+        if method == "DELETE":
+            return await _a(_delete_environment(app_id, env_id))
+
+    # --- Configuration Profiles ---
+    m = re.fullmatch(r"/applications/([^/]+)/configurationprofiles", path)
+    if m:
+        app_id = m.group(1)
+        if method == "POST":
+            return await _a(_create_configuration_profile(app_id, body))
+        if method == "GET":
+            return await _a(_list_configuration_profiles(app_id, query))
+
+    m = re.fullmatch(r"/applications/([^/]+)/configurationprofiles/([^/]+)", path)
+    if m:
+        app_id, profile_id = m.group(1), m.group(2)
+        if method == "GET":
+            return await _a(_get_configuration_profile(app_id, profile_id))
+        if method == "PATCH":
+            return await _a(_update_configuration_profile(app_id, profile_id, body))
+        if method == "DELETE":
+            return await _a(_delete_configuration_profile(app_id, profile_id))
+
+    # --- Deployment Strategies ---
+    # botocore's model uses the misspelled path "/deployementstrategies" for
+    # DeleteDeploymentStrategy (and possibly others), so accept both spellings.
+    if path in ("/deploymentstrategies", "/deployementstrategies"):
+        if method == "POST":
+            return await _a(_create_deployment_strategy(body))
+        if method == "GET":
+            return await _a(_list_deployment_strategies(query))
+
+    m = re.fullmatch(r"/deploy(?:e?)mentstrategies/([^/]+)", path)
+    if m:
+        strategy_id = m.group(1)
+        if method == "GET":
+            return await _a(_get_deployment_strategy(strategy_id))
+        if method == "PATCH":
+            return await _a(_update_deployment_strategy(strategy_id, body))
+        if method == "DELETE":
+            return await _a(_delete_deployment_strategy(strategy_id))
+
+    return _error(400, "BadRequestException", f"Unknown AppConfig path: {method} {path}")
+
+
+async def _a(result):
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Response helpers
+# ---------------------------------------------------------------------------
+
+
+def _json(status, data):
+    if status == 204:
+        return status, {}, b""
+    body = json.dumps(data).encode("utf-8")
+    return status, {"Content-Type": "application/json"}, body
+
+
+def _error(status, code, message):
+    body = json.dumps({"Message": message, "Code": code}).encode("utf-8")
+    return status, {"Content-Type": "application/json", "x-amzn-errortype": code}, body
+
+
+# ---------------------------------------------------------------------------
+# Reset
+# ---------------------------------------------------------------------------
+
+
+def reset():
+    _applications.clear()
+    _environments.clear()
+    _config_profiles.clear()
+    _hosted_versions.clear()
+    _deployment_strategies.clear()
+    _deployments.clear()
+    _tags.clear()
+    _sessions.clear()
+
+def get_state_summary() -> dict:
+    return {
+        "applications": {"count": len(_applications), "names": list(_applications.keys())},
+        "environments": {"count": len(_environments), "names": list(_environments.keys())},
+        "config_profiles": {"count": len(_config_profiles), "names": list(_config_profiles.keys())},
+        "hosted_versions": {"count": len(_hosted_versions), "names": list(_hosted_versions.keys())},
+        "deployment_strategies": {"count": len(_deployment_strategies), "names": list(_deployment_strategies.keys())},
+        "deployments": {"count": len(_deployments), "names": list(_deployments.keys())},
+    }

aws_infra/ministack/services/appsync.py

@@ -0,0 +1,1001 @@
+"""
+AWS AppSync Service Emulator.
+
+GraphQL API management service — REST/JSON protocol via /v1/apis/* paths.
+
+Supports:
+  GraphQL APIs:  CreateGraphQLApi, GetGraphQLApi, ListGraphQLApis,
+                 UpdateGraphQLApi, DeleteGraphQLApi
+  API Keys:      CreateApiKey, ListApiKeys, DeleteApiKey
+  Data Sources:  CreateDataSource, GetDataSource, ListDataSources, DeleteDataSource
+  Resolvers:     CreateResolver, GetResolver, ListResolvers, DeleteResolver
+  Types:         CreateType, ListTypes, GetType
+  Tags:          TagResource, UntagResource, ListTagsForResource
+
+Wire protocol:
+  REST/JSON — path-based routing under /v1/apis.
+  Credential scope: appsync
+"""
+
+import copy
+import json
+import logging
+import os
+import re
+import time
+
+from ministack.core.persistence import PERSIST_STATE, load_state
+from ministack.core.responses import AccountScopedDict, get_account_id, error_response_json, json_response, new_uuid, get_region
+
+logger = logging.getLogger("appsync")
+
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+
+# ---------------------------------------------------------------------------
+# In-memory state
+# ---------------------------------------------------------------------------
+
+_apis = AccountScopedDict()            # apiId -> api record
+_api_keys = AccountScopedDict()        # apiId -> {keyId -> key record}
+_data_sources = AccountScopedDict()    # apiId -> {name -> data source record}
+_resolvers = AccountScopedDict()       # apiId -> {typeName -> {fieldName -> resolver record}}
+_types = AccountScopedDict()           # apiId -> {typeName -> type record}
+_tags = AccountScopedDict()            # resource_arn -> {key: value}
+
+# ---------------------------------------------------------------------------
+# Persistence
+# ---------------------------------------------------------------------------
+
+def _load_persisted():
+    if not PERSIST_STATE:
+        return
+    data = load_state("appsync")
+    if data:
+        restore_state(data)
+        logger.info("Loaded persisted state for appsync")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _now():
+    return int(time.time())
+
+
+def _api_arn(api_id):
+    return f"arn:aws:appsync:{get_region()}:{get_account_id()}:apis/{api_id}"
+
+
+def _json(status, body):
+    return json_response(body, status)
+
+
+# ---------------------------------------------------------------------------
+# GraphQL APIs
+# ---------------------------------------------------------------------------
+
+def _create_graphql_api(body):
+    api_id = new_uuid().replace("-", "")[:26]
+    name = body.get("name", "")
+    auth_type = body.get("authenticationType", "API_KEY")
+    additional_auth = body.get("additionalAuthenticationProviders", [])
+    log_config = body.get("logConfig")
+    user_pool_config = body.get("userPoolConfig")
+    openid_config = body.get("openIDConnectConfig")
+    xray = body.get("xrayEnabled", False)
+    tags = body.get("tags", {})
+    lambda_auth = body.get("lambdaAuthorizerConfig")
+
+    arn = _api_arn(api_id)
+    now = _now()
+
+    record = {
+        "apiId": api_id,
+        "name": name,
+        "authenticationType": auth_type,
+        "arn": arn,
+        "uris": {
+            "GRAPHQL": f"https://{api_id}.appsync-api.{get_region()}.amazonaws.com/graphql",
+            "REALTIME": f"wss://{api_id}.appsync-realtime-api.{get_region()}.amazonaws.com/graphql",
+        },
+        "additionalAuthenticationProviders": additional_auth,
+        "xrayEnabled": xray,
+        "wafWebAclArn": body.get("wafWebAclArn"),
+        "createdAt": now,
+        "lastUpdatedAt": now,
+    }
+    if log_config:
+        record["logConfig"] = log_config
+    if user_pool_config:
+        record["userPoolConfig"] = user_pool_config
+    if openid_config:
+        record["openIDConnectConfig"] = openid_config
+    if lambda_auth:
+        record["lambdaAuthorizerConfig"] = lambda_auth
+
+    _apis[api_id] = record
+    _api_keys[api_id] = {}
+    _data_sources[api_id] = {}
+    _resolvers[api_id] = {}
+    _types[api_id] = {}
+
+    if tags:
+        _tags[arn] = tags
+
+    return _json(200, {"graphqlApi": record})
+
+
+def _get_graphql_api(api_id):
+    api = _apis.get(api_id)
+    if not api:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+    return _json(200, {"graphqlApi": api})
+
+
+def _list_graphql_apis(query_params):
+    apis = list(_apis.values())
+    return _json(200, {"graphqlApis": apis})
+
+
+def _update_graphql_api(api_id, body):
+    api = _apis.get(api_id)
+    if not api:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    if "name" in body:
+        api["name"] = body["name"]
+    if "authenticationType" in body:
+        api["authenticationType"] = body["authenticationType"]
+    if "additionalAuthenticationProviders" in body:
+        api["additionalAuthenticationProviders"] = body["additionalAuthenticationProviders"]
+    if "logConfig" in body:
+        api["logConfig"] = body["logConfig"]
+    if "userPoolConfig" in body:
+        api["userPoolConfig"] = body["userPoolConfig"]
+    if "openIDConnectConfig" in body:
+        api["openIDConnectConfig"] = body["openIDConnectConfig"]
+    if "xrayEnabled" in body:
+        api["xrayEnabled"] = body["xrayEnabled"]
+    if "lambdaAuthorizerConfig" in body:
+        api["lambdaAuthorizerConfig"] = body["lambdaAuthorizerConfig"]
+
+    api["lastUpdatedAt"] = _now()
+    return _json(200, {"graphqlApi": api})
+
+
+def _delete_graphql_api(api_id):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    arn = _apis[api_id]["arn"]
+    del _apis[api_id]
+    _api_keys.pop(api_id, None)
+    _data_sources.pop(api_id, None)
+    _resolvers.pop(api_id, None)
+    _types.pop(api_id, None)
+    _tags.pop(arn, None)
+
+    return _json(200, {})
+
+
+# ---------------------------------------------------------------------------
+# API Keys
+# ---------------------------------------------------------------------------
+
+def _create_api_key(api_id, body):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    key_id = "da2-" + new_uuid()[:26]
+    now = _now()
+    expires = body.get("expires", now + 604800)  # default 7 days
+    description = body.get("description", "")
+
+    record = {
+        "id": key_id,
+        "description": description,
+        "expires": expires,
+        "createdAt": now,
+        "lastUpdatedAt": now,
+        "deletes": expires + 5184000,  # 60 days after expiry
+    }
+
+    _api_keys.setdefault(api_id, {})[key_id] = record
+    return _json(200, {"apiKey": record})
+
+
+def _list_api_keys(api_id):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    keys = list(_api_keys.get(api_id, {}).values())
+    return _json(200, {"apiKeys": keys})
+
+
+def _delete_api_key(api_id, key_id):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    keys = _api_keys.get(api_id, {})
+    if key_id not in keys:
+        return error_response_json("NotFoundException", f"API key {key_id} not found", 404)
+
+    del keys[key_id]
+    return _json(200, {})
+
+
+# ---------------------------------------------------------------------------
+# Data Sources
+# ---------------------------------------------------------------------------
+
+def _create_data_source(api_id, body):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    name = body.get("name", "")
+    ds_type = body.get("type", "NONE")
+    description = body.get("description", "")
+    service_role_arn = body.get("serviceRoleArn", "")
+
+    arn = f"{_apis[api_id]['arn']}/datasources/{name}"
+
+    record = {
+        "dataSourceArn": arn,
+        "name": name,
+        "type": ds_type,
+        "description": description,
+        "serviceRoleArn": service_role_arn,
+        "createdAt": _now(),
+        "lastUpdatedAt": _now(),
+    }
+
+    if ds_type == "AMAZON_DYNAMODB":
+        record["dynamodbConfig"] = body.get("dynamodbConfig", {})
+    elif ds_type == "AWS_LAMBDA":
+        record["lambdaConfig"] = body.get("lambdaConfig", {})
+    elif ds_type == "AMAZON_ELASTICSEARCH" or ds_type == "AMAZON_OPENSEARCH_SERVICE":
+        record["elasticsearchConfig"] = body.get("elasticsearchConfig", {})
+    elif ds_type == "HTTP":
+        record["httpConfig"] = body.get("httpConfig", {})
+    elif ds_type == "RELATIONAL_DATABASE":
+        record["relationalDatabaseConfig"] = body.get("relationalDatabaseConfig", {})
+
+    _data_sources.setdefault(api_id, {})[name] = record
+    return _json(200, {"dataSource": record})
+
+
+def _get_data_source(api_id, name):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    ds = _data_sources.get(api_id, {}).get(name)
+    if not ds:
+        return error_response_json("NotFoundException", f"Data source {name} not found", 404)
+
+    return _json(200, {"dataSource": ds})
+
+
+def _list_data_sources(api_id):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    sources = list(_data_sources.get(api_id, {}).values())
+    return _json(200, {"dataSources": sources})
+
+
+def _delete_data_source(api_id, name):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    sources = _data_sources.get(api_id, {})
+    if name not in sources:
+        return error_response_json("NotFoundException", f"Data source {name} not found", 404)
+
+    del sources[name]
+    return _json(200, {})
+
+
+# ---------------------------------------------------------------------------
+# Resolvers
+# ---------------------------------------------------------------------------
+
+def _create_resolver(api_id, type_name, body):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    field_name = body.get("fieldName", "")
+    data_source_name = body.get("dataSourceName")
+    request_template = body.get("requestMappingTemplate", "")
+    response_template = body.get("responseMappingTemplate", "")
+    kind = body.get("kind", "UNIT")
+    pipeline_config = body.get("pipelineConfig")
+    caching_config = body.get("cachingConfig")
+    runtime = body.get("runtime")
+    code = body.get("code")
+
+    arn = f"{_apis[api_id]['arn']}/types/{type_name}/resolvers/{field_name}"
+
+    record = {
+        "typeName": type_name,
+        "fieldName": field_name,
+        "dataSourceName": data_source_name,
+        "resolverArn": arn,
+        "requestMappingTemplate": request_template,
+        "responseMappingTemplate": response_template,
+        "kind": kind,
+        "createdAt": _now(),
+        "lastUpdatedAt": _now(),
+    }
+    if pipeline_config:
+        record["pipelineConfig"] = pipeline_config
+    if caching_config:
+        record["cachingConfig"] = caching_config
+    if runtime:
+        record["runtime"] = runtime
+    if code:
+        record["code"] = code
+
+    _resolvers.setdefault(api_id, {}).setdefault(type_name, {})[field_name] = record
+    return _json(200, {"resolver": record})
+
+
+def _get_resolver(api_id, type_name, field_name):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    resolver = _resolvers.get(api_id, {}).get(type_name, {}).get(field_name)
+    if not resolver:
+        return error_response_json("NotFoundException",
+                                   f"Resolver {type_name}.{field_name} not found", 404)
+
+    return _json(200, {"resolver": resolver})
+
+
+def _list_resolvers(api_id, type_name):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    resolvers = list(_resolvers.get(api_id, {}).get(type_name, {}).values())
+    return _json(200, {"resolvers": resolvers})
+
+
+def _delete_resolver(api_id, type_name, field_name):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    type_resolvers = _resolvers.get(api_id, {}).get(type_name, {})
+    if field_name not in type_resolvers:
+        return error_response_json("NotFoundException",
+                                   f"Resolver {type_name}.{field_name} not found", 404)
+
+    del type_resolvers[field_name]
+    return _json(200, {})
+
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+def _create_type(api_id, body):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    definition = body.get("definition", "")
+    fmt = body.get("format", "SDL")
+
+    # Extract type name from SDL definition (e.g. "type Query { ... }" -> "Query")
+    name_match = re.search(r"(?:type|input|enum|interface|union|scalar)\s+(\w+)", definition)
+    type_name = name_match.group(1) if name_match else "Unknown"
+
+    arn = f"{_apis[api_id]['arn']}/types/{type_name}"
+
+    record = {
+        "name": type_name,
+        "description": body.get("description", ""),
+        "arn": arn,
+        "definition": definition,
+        "format": fmt,
+        "createdAt": _now(),
+        "lastUpdatedAt": _now(),
+    }
+
+    _types.setdefault(api_id, {})[type_name] = record
+    return _json(200, {"type": record})
+
+
+def _get_type(api_id, type_name, query_params):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    fmt = "SDL"
+    if query_params.get("format"):
+        fmt_val = query_params["format"]
+        fmt = fmt_val[0] if isinstance(fmt_val, list) else fmt_val
+
+    t = _types.get(api_id, {}).get(type_name)
+    if not t:
+        return error_response_json("NotFoundException", f"Type {type_name} not found", 404)
+
+    return _json(200, {"type": t})
+
+
+def _list_types(api_id, query_params):
+    if api_id not in _apis:
+        return error_response_json("NotFoundException", f"GraphQL API {api_id} not found", 404)
+
+    types = list(_types.get(api_id, {}).values())
+    return _json(200, {"types": types})
+
+
+# ---------------------------------------------------------------------------
+# Tags
+# ---------------------------------------------------------------------------
+
+def _tag_resource(body):
+    arn = body.get("resourceArn", "")
+    tags = body.get("tags", {})
+    _tags.setdefault(arn, {}).update(tags)
+    return _json(200, {})
+
+
+def _untag_resource(arn, query_params):
+    tag_keys = query_params.get("tagKeys", [])
+    if isinstance(tag_keys, str):
+        tag_keys = [tag_keys]
+    existing = _tags.get(arn, {})
+    for k in tag_keys:
+        existing.pop(k, None)
+    return _json(200, {})
+
+
+def _list_tags_for_resource(arn):
+    tags = _tags.get(arn, {})
+    return _json(200, {"tags": tags})
+
+
+# ---------------------------------------------------------------------------
+# Request router
+# ---------------------------------------------------------------------------
+
+# Path patterns for routing
+_PATH_RE = re.compile(r"^/v1/apis(?:/([^/]+))?(?:/([^/]+))?(?:/([^/]+))?(?:/([^/]+))?(?:/([^/]+))?")
+# /v1/apis                          -> groups: (None, None, None, None, None)
+# /v1/apis/{apiId}                  -> groups: (apiId, None, None, None, None)
+# /v1/apis/{apiId}/apikeys          -> groups: (apiId, "apikeys", None, None, None)
+# /v1/apis/{apiId}/apikeys/{id}     -> groups: (apiId, "apikeys", id, None, None)
+# /v1/apis/{apiId}/datasources      -> groups: (apiId, "datasources", None, None, None)
+# /v1/apis/{apiId}/datasources/{n}  -> groups: (apiId, "datasources", name, None, None)
+# /v1/apis/{apiId}/types            -> groups: (apiId, "types", None, None, None)
+# /v1/apis/{apiId}/types/{t}/resolvers          -> (apiId, "types", t, "resolvers", None)
+# /v1/apis/{apiId}/types/{t}/resolvers/{field}  -> (apiId, "types", t, "resolvers", field)
+
+
+async def handle_request(method, path, headers, body, query_params):
+    """Main entry point — route AppSync REST requests."""
+
+    # Tags endpoint: /v1/tags/{resourceArn}
+    if path.startswith("/v1/tags/"):
+        from urllib.parse import unquote
+        arn = unquote(path[len("/v1/tags/"):])
+        if method == "POST":
+            data = json.loads(body) if body else {}
+            data["resourceArn"] = arn
+            return _tag_resource(data)
+        elif method == "DELETE":
+            return _untag_resource(arn, query_params)
+        else:  # GET
+            return _list_tags_for_resource(arn)
+
+    # GraphQL data plane: POST /graphql or POST /v1/apis/{apiId}/graphql
+    if path == "/graphql" and method == "POST":
+        api_key = headers.get("x-api-key", "")
+        api_id = _resolve_api_by_key(api_key)
+        if not api_id:
+            return error_response_json("UnauthorizedException", "Valid API key required", 401)
+        data = json.loads(body) if body else {}
+        return _execute_graphql(api_id, data)
+
+    if path.startswith("/v1/apis/") and path.endswith("/graphql") and method == "POST":
+        parts = path.split("/")
+        if len(parts) >= 5:
+            api_id = parts[3]
+            data = json.loads(body) if body else {}
+            return _execute_graphql(api_id, data)
+
+    m = _PATH_RE.match(path)
+    if not m:
+        return error_response_json("NotFoundException", f"Unknown path: {path}", 404)
+
+    api_id, sub1, sub2, sub3, sub4 = m.groups()
+
+    data = {}
+    if body:
+        try:
+            data = json.loads(body)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            data = {}
+
+    # POST /v1/apis — CreateGraphQLApi
+    if api_id is None and sub1 is None:
+        if method == "POST":
+            return _create_graphql_api(data)
+        elif method == "GET":
+            return _list_graphql_apis(query_params)
+
+    # /v1/apis/{apiId}
+    if api_id and sub1 is None:
+        if method == "GET":
+            return _get_graphql_api(api_id)
+        elif method == "POST":
+            return _update_graphql_api(api_id, data)
+        elif method == "DELETE":
+            return _delete_graphql_api(api_id)
+
+    # /v1/apis/{apiId}/apikeys
+    if sub1 == "apikeys":
+        if sub2 is None:
+            if method == "POST":
+                return _create_api_key(api_id, data)
+            elif method == "GET":
+                return _list_api_keys(api_id)
+        else:
+            # /v1/apis/{apiId}/apikeys/{keyId}
+            if method == "DELETE":
+                return _delete_api_key(api_id, sub2)
+
+    # /v1/apis/{apiId}/datasources
+    if sub1 == "datasources":
+        if sub2 is None:
+            if method == "POST":
+                return _create_data_source(api_id, data)
+            elif method == "GET":
+                return _list_data_sources(api_id)
+        else:
+            # /v1/apis/{apiId}/datasources/{name}
+            if method == "GET":
+                return _get_data_source(api_id, sub2)
+            elif method == "DELETE":
+                return _delete_data_source(api_id, sub2)
+
+    # /v1/apis/{apiId}/types
+    if sub1 == "types":
+        if sub2 is None:
+            if method == "POST":
+                return _create_type(api_id, data)
+            elif method == "GET":
+                return _list_types(api_id, query_params)
+        elif sub3 == "resolvers":
+            # /v1/apis/{apiId}/types/{typeName}/resolvers
+            type_name = sub2
+            if sub4 is None:
+                if method == "POST":
+                    return _create_resolver(api_id, type_name, data)
+                elif method == "GET":
+                    return _list_resolvers(api_id, type_name)
+            else:
+                # /v1/apis/{apiId}/types/{typeName}/resolvers/{fieldName}
+                field_name = sub4
+                if method == "GET":
+                    return _get_resolver(api_id, type_name, field_name)
+                elif method == "DELETE":
+                    return _delete_resolver(api_id, type_name, field_name)
+        else:
+            # /v1/apis/{apiId}/types/{typeName} — GetType
+            if sub3 is None and method == "GET":
+                return _get_type(api_id, sub2, query_params)
+
+    return error_response_json("BadRequestException", f"Unsupported route: {method} {path}")
+
+
+# ---------------------------------------------------------------------------
+# State management
+# ---------------------------------------------------------------------------
+
+def reset():
+    """Clear all in-memory state."""
+    _apis.clear()
+    _api_keys.clear()
+    _data_sources.clear()
+    _resolvers.clear()
+    _types.clear()
+    _tags.clear()
+
+
+def get_state():
+    """Return a deep copy of all state for persistence."""
+    return copy.deepcopy({
+        "apis": _apis,
+        "api_keys": _api_keys,
+        "data_sources": _data_sources,
+        "resolvers": _resolvers,
+        "types": _types,
+        "tags": _tags,
+    })
+
+
+def restore_state(data):
+    """Restore state from persisted data."""
+    _apis.update(data.get("apis", {}))
+    _api_keys.update(data.get("api_keys", {}))
+    _data_sources.update(data.get("data_sources", {}))
+    _resolvers.update(data.get("resolvers", {}))
+    _types.update(data.get("types", {}))
+    _tags.update(data.get("tags", {}))
+
+
+# ---------------------------------------------------------------------------
+# GraphQL Data Plane — parse and execute queries against DynamoDB
+# ---------------------------------------------------------------------------
+
+import re as _re
+
+# Simple GraphQL parser — handles queries/mutations that Amplify generates
+_GQL_OP_RE = _re.compile(
+    r'(?:query|mutation|subscription)\s+(\w+)?\s*(?:\(([^)]*)\))?\s*\{(.*)\}',
+    _re.DOTALL,
+)
+_GQL_FIELD_RE = _re.compile(r'(\w+)\s*(?:\(([^)]*)\))?\s*(?:\{([^}]*)\})?')
+
+
+def _resolve_api_by_key(api_key_value):
+    """Find the API ID that owns this API key."""
+    for api_id, keys in _api_keys.items():
+        for kid, key in keys.items():
+            if kid == api_key_value or key.get("id") == api_key_value:
+                return api_id
+    # Fallback: if only one API exists, use it
+    if len(_apis) == 1:
+        return next(iter(_apis))
+    return None
+
+
+def _execute_graphql(api_id, data):
+    """Execute a GraphQL query/mutation against the configured resolvers."""
+    query = data.get("query", "")
+    variables = data.get("variables", {})
+    operation_name = data.get("operationName")
+
+    if not query.strip():
+        return _json(400, {"errors": [{"message": "Query is required"}]})
+
+    if api_id not in _apis:
+        return _json(404, {"errors": [{"message": f"API {api_id} not found"}]})
+
+    # Parse the top-level operation
+    # Strip __typename fields — Amplify adds these everywhere
+    query_clean = _re.sub(r'__typename\s*', '', query)
+
+    m = _GQL_OP_RE.search(query_clean)
+    if not m:
+        # Try bare field query: { getUser(id: "1") { name } }
+        inner = query_clean.strip().strip("{}")
+        fields = _parse_fields(inner, variables)
+    else:
+        op_name, op_args, body = m.groups()
+        fields = _parse_fields(body, variables)
+
+    # Determine operation type
+    is_mutation = query_clean.strip().startswith("mutation")
+
+    results = {}
+    errors = []
+    for field_name, args, sub_fields in fields:
+        resolver = _find_resolver(api_id, "Mutation" if is_mutation else "Query", field_name)
+        if resolver:
+            try:
+                result = _resolve_field(api_id, resolver, args, sub_fields, variables)
+                results[field_name] = result
+            except Exception as e:
+                errors.append({"message": str(e), "path": [field_name]})
+                results[field_name] = None
+        else:
+            # No resolver — return mock empty result
+            results[field_name] = None
+
+    response = {"data": results}
+    if errors:
+        response["errors"] = errors
+    return _json(200, response)
+
+
+def _parse_fields(body, variables):
+    """Parse GraphQL field selections into (name, args_dict, sub_fields) tuples."""
+    fields = []
+    for m in _GQL_FIELD_RE.finditer(body.strip()):
+        name = m.group(1)
+        args_str = m.group(2) or ""
+        sub = m.group(3) or ""
+        args = _parse_args(args_str, variables)
+        sub_fields = [s.strip() for s in sub.split() if s.strip() and s.strip() != "__typename"]
+        fields.append((name, args, sub_fields))
+    return fields
+
+
+def _parse_args(args_str, variables):
+    """Parse GraphQL arguments like (id: "1") or (id: $id) into a dict."""
+    args = {}
+    if not args_str.strip():
+        return args
+    # Match key: value pairs
+    for pair in _re.finditer(r'(\w+)\s*:\s*("(?:[^"\\]|\\.)*"|\$\w+|\d+(?:\.\d+)?|true|false|null|\{[^}]*\}|\[[^\]]*\])', args_str):
+        key = pair.group(1)
+        val = pair.group(2)
+        if val.startswith("$"):
+            val = variables.get(val[1:], val)
+        elif val.startswith('"') and val.endswith('"'):
+            val = val[1:-1]
+        elif val == "true":
+            val = True
+        elif val == "false":
+            val = False
+        elif val == "null":
+            val = None
+        elif val.startswith("{") and val.endswith("}"):
+            val = _parse_args(val[1:-1], variables)
+        elif val.startswith("[") and val.endswith("]"):
+            val = val  # Keep as string for now
+        elif val.replace(".", "").isdigit():
+            val = float(val) if "." in val else int(val)
+        args[key] = val
+    return args
+
+
+def _find_resolver(api_id, type_name, field_name):
+    """Find a resolver for Query.fieldName or Mutation.fieldName."""
+    resolvers = _resolvers.get(api_id, {})
+    # Try exact match
+    if type_name in resolvers and field_name in resolvers[type_name]:
+        return resolvers[type_name][field_name]
+    # Try generic match (some setups use "Query" or "Mutation" type)
+    for tn in resolvers:
+        if field_name in resolvers[tn]:
+            return resolvers[tn][field_name]
+    return None
+
+
+def _resolve_field(api_id, resolver, args, sub_fields, variables):
+    """Execute a resolver against its data source (DynamoDB)."""
+    ds_name = resolver.get("dataSourceName", "")
+    data_source = _data_sources.get(api_id, {}).get(ds_name)
+
+    if not data_source:
+        # No data source — return args as mock
+        return args or {}
+
+    ds_type = data_source.get("type", "NONE")
+
+    if ds_type == "AMAZON_DYNAMODB":
+        return _resolve_dynamodb(data_source, resolver, args, sub_fields)
+    elif ds_type == "AWS_LAMBDA":
+        return _resolve_lambda(data_source, args)
+    else:
+        return args or {}
+
+
+def _resolve_dynamodb(data_source, resolver, args, sub_fields):
+    """Execute a DynamoDB resolver — auto-detect operation from field name and args."""
+    import ministack.services.dynamodb as _ddb
+
+    config = data_source.get("dynamodbConfig", {})
+    table_name = config.get("tableName", "")
+    if not table_name:
+        return None
+
+    table = _ddb._tables.get(table_name)
+    if not table:
+        return None
+
+    field_name = resolver.get("fieldName", "")
+
+    # Auto-detect: get* → GetItem, list* → Scan, create*/update*/put* → PutItem, delete* ��� DeleteItem
+    if field_name.startswith("get") or "id" in args:
+        return _ddb_get_item(table, table_name, args, sub_fields)
+    elif field_name.startswith("list"):
+        return _ddb_scan(table, table_name, args, sub_fields)
+    elif field_name.startswith("create") or field_name.startswith("put"):
+        return _ddb_put_item(table, table_name, args)
+    elif field_name.startswith("update"):
+        return _ddb_update_item(table, table_name, args)
+    elif field_name.startswith("delete"):
+        return _ddb_delete_item(table, table_name, args)
+    else:
+        # Default: try scan
+        return _ddb_scan(table, table_name, args, sub_fields)
+
+
+def _ddb_get_item(table, table_name, args, sub_fields):
+    """Get a single item by primary key."""
+    pk_name = table["pk_name"]
+    sk_name = table.get("sk_name")
+
+    pk_val = args.get("id") or args.get(pk_name) or next(iter(args.values()), None)
+    if pk_val is None:
+        return None
+
+    items = table["items"]
+    pk_bucket = items.get(str(pk_val), {})
+
+    if sk_name:
+        sk_val = args.get(sk_name, "")
+        item = pk_bucket.get(str(sk_val))
+    else:
+        # No sort key — get the single item
+        item = next(iter(pk_bucket.values()), None) if pk_bucket else None
+
+    if not item:
+        return None
+
+    return _strip_ddb_types(item, sub_fields)
+
+
+def _ddb_scan(table, table_name, args, sub_fields):
+    """Scan/list items, optionally with filters and pagination."""
+    items = []
+    limit = args.get("limit", 100)
+    next_token = args.get("nextToken")
+
+    count = 0
+    for pk in sorted(table["items"].keys()):
+        for sk in sorted(table["items"][pk].keys()):
+            if count >= limit:
+                break
+            items.append(_strip_ddb_types(table["items"][pk][sk], sub_fields))
+            count += 1
+
+    # Filter if filter arg provided
+    filter_arg = args.get("filter", {})
+    if filter_arg and isinstance(filter_arg, dict):
+        filtered = []
+        for item in items:
+            match = True
+            for fk, fv in filter_arg.items():
+                if isinstance(fv, dict) and "eq" in fv:
+                    if item.get(fk) != fv["eq"]:
+                        match = False
+                elif item.get(fk) != fv:
+                    match = False
+            if match:
+                filtered.append(item)
+        items = filtered
+
+    return {"items": items, "nextToken": None}
+
+
+def _ddb_put_item(table, table_name, args):
+    """Create/put an item."""
+    import ministack.services.dynamodb as _ddb
+    from collections import defaultdict
+
+    input_data = args.get("input", args)
+    pk_name = table["pk_name"]
+    sk_name = table.get("sk_name")
+
+    # Build DynamoDB-typed item
+    ddb_item = {}
+    for k, v in input_data.items():
+        if isinstance(v, str):
+            ddb_item[k] = {"S": v}
+        elif isinstance(v, (int, float)):
+            ddb_item[k] = {"N": str(v)}
+        elif isinstance(v, bool):
+            ddb_item[k] = {"BOOL": v}
+        elif isinstance(v, list):
+            ddb_item[k] = {"L": [{"S": str(i)} for i in v]}
+        elif v is None:
+            ddb_item[k] = {"NULL": True}
+        else:
+            ddb_item[k] = {"S": str(v)}
+
+    # Auto-generate ID if not provided
+    if pk_name not in ddb_item and "id" not in ddb_item:
+        ddb_item["id" if pk_name == "id" else pk_name] = {"S": new_uuid()}
+
+    pk_val = _ddb._extract_key_val(ddb_item.get(pk_name, {}))
+    sk_val = _ddb._extract_key_val(ddb_item.get(sk_name, {})) if sk_name else ""
+
+    if not isinstance(table["items"], defaultdict):
+        table["items"] = defaultdict(dict, table["items"])
+
+    table["items"][pk_val][sk_val] = ddb_item
+    table["ItemCount"] = sum(len(v) for v in table["items"].values())
+
+    return _strip_ddb_types(ddb_item, [])
+
+
+def _ddb_update_item(table, table_name, args):
+    """Update an existing item — merge input fields."""
+    input_data = args.get("input", args)
+    pk_name = table["pk_name"]
+    pk_val = str(input_data.get("id") or input_data.get(pk_name, ""))
+
+    if pk_val in table["items"]:
+        sk = next(iter(table["items"][pk_val]), "")
+        existing = table["items"][pk_val].get(sk, {})
+        for k, v in input_data.items():
+            if isinstance(v, str):
+                existing[k] = {"S": v}
+            elif isinstance(v, (int, float)):
+                existing[k] = {"N": str(v)}
+            elif isinstance(v, bool):
+                existing[k] = {"BOOL": v}
+        return _strip_ddb_types(existing, [])
+    return None
+
+
+def _ddb_delete_item(table, table_name, args):
+    """Delete an item and return it."""
+    input_data = args.get("input", args)
+    pk_name = table["pk_name"]
+    pk_val = str(input_data.get("id") or input_data.get(pk_name, ""))
+
+    if pk_val in table["items"]:
+        sk = next(iter(table["items"][pk_val]), "")
+        item = table["items"][pk_val].pop(sk, None)
+        if not table["items"][pk_val]:
+            table["items"].pop(pk_val, None)
+        if item:
+            return _strip_ddb_types(item, [])
+    return None
+
+
+def _strip_ddb_types(item, sub_fields):
+    """Convert DynamoDB typed attributes to plain values for GraphQL response."""
+    if not item:
+        return None
+    result = {}
+    for k, v in item.items():
+        if isinstance(v, dict):
+            if "S" in v:
+                result[k] = v["S"]
+            elif "N" in v:
+                val = v["N"]
+                result[k] = int(val) if "." not in val else float(val)
+            elif "BOOL" in v:
+                result[k] = v["BOOL"]
+            elif "NULL" in v:
+                result[k] = None
+            elif "L" in v:
+                result[k] = [_strip_ddb_types(i, []) if isinstance(i, dict) and not any(t in i for t in ("S", "N", "BOOL")) else (i.get("S") or i.get("N") or i.get("BOOL")) for i in v["L"]]
+            elif "M" in v:
+                result[k] = _strip_ddb_types(v["M"], [])
+            else:
+                result[k] = v
+        else:
+            result[k] = v
+    if sub_fields:
+        result = {k: v for k, v in result.items() if k in sub_fields or k == "id" or k == "__typename"}
+    return result
+
+
+def _resolve_lambda(data_source, args):
+    """Execute a Lambda resolver."""
+    config = data_source.get("lambdaConfig", {})
+    func_arn = config.get("lambdaFunctionArn", "")
+    if not func_arn:
+        return args
+
+    import ministack.services.lambda_svc as _lambda_svc
+    func_name = func_arn.rsplit(":", 1)[-1]
+    func = _lambda_svc._functions.get(func_name)
+    if not func:
+        return args
+
+    result = _lambda_svc._execute_function(func, args)
+    body = result.get("body")
+    if isinstance(body, dict):
+        return body
+    if isinstance(body, (str, bytes)):
+        try:
+            return json.loads(body)
+        except Exception:
+            return {"result": body}
+    return args
+
+# Load persisted state (must be after restore_state is defined)
+_load_persisted()
+
+def get_state_summary() -> dict:
+    return {
+        "apis": {"count": len(_apis), "ids": list(_apis.keys())},
+    }

aws_infra/ministack/services/athena.py

@@ -0,0 +1,938 @@
+"""
+Athena Service Emulator.
+JSON-based API via X-Amz-Target (AmazonAthena).
+Uses DuckDB to actually execute SQL queries against S3 data (CSV/JSON/Parquet).
+Supports: StartQueryExecution, GetQueryExecution, GetQueryResults,
+          StopQueryExecution, ListQueryExecutions,
+          CreateWorkGroup, DeleteWorkGroup, GetWorkGroup, ListWorkGroups, UpdateWorkGroup,
+          CreateNamedQuery, DeleteNamedQuery, GetNamedQuery, ListNamedQueries,
+          BatchGetNamedQuery, BatchGetQueryExecution,
+          CreateDataCatalog, GetDataCatalog, ListDataCatalogs, DeleteDataCatalog, UpdateDataCatalog,
+          CreatePreparedStatement, GetPreparedStatement, DeletePreparedStatement, ListPreparedStatements,
+          GetTableMetadata, ListTableMetadata,
+          TagResource, UntagResource, ListTagsForResource.
+"""
+
+import copy
+import json
+import logging
+import os
+import re
+import threading
+import time
+
+from ministack.core.persistence import PERSIST_STATE, load_state
+from ministack.core.responses import AccountScopedDict, get_account_id, error_response_json, json_response, new_uuid, get_region
+
+logger = logging.getLogger("athena")
+
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+S3_DATA_DIR = os.environ.get("S3_DATA_DIR", "/tmp/ministack-data/s3")
+ATHENA_ENGINE = os.environ.get("ATHENA_ENGINE", "auto")  # "auto" | "duckdb" | "mock"
+
+
+def get_athena_engine():
+    """Resolve the effective SQL engine. Reads module-level ATHENA_ENGINE which
+    can be overridden at runtime via POST /_ministack/config."""
+    engine = ATHENA_ENGINE
+    if engine == "auto":
+        engine = "duckdb" if _duckdb_available else "mock"
+    logger.debug("Athena engine: %s (ATHENA_ENGINE=%s)", engine, ATHENA_ENGINE)
+    return engine
+
+
+_executions = AccountScopedDict()
+# Per-account workgroups / data catalogs. AWS's "primary" workgroup and
+# "AwsDataCatalog" exist in every account — we lazily seed them per-tenant
+# on first access so two accounts never share the same workgroup or catalog
+# state (creation times, configs, etc.).
+_workgroups = AccountScopedDict()
+_named_queries = AccountScopedDict()
+_data_catalogs = AccountScopedDict()
+
+
+def _ensure_default_workgroup():
+    if "primary" not in _workgroups:
+        _workgroups["primary"] = {
+            "Name": "primary",
+            "State": "ENABLED",
+            "Description": "Primary workgroup",
+            "CreationTime": int(time.time()),
+            "Configuration": {
+                "ResultConfiguration": {"OutputLocation": "s3://athena-results/"}
+            },
+        }
+
+
+def _ensure_default_data_catalog():
+    if "AwsDataCatalog" not in _data_catalogs:
+        _data_catalogs["AwsDataCatalog"] = {
+            "Name": "AwsDataCatalog",
+            "Description": "AWS Glue Data Catalog",
+            "Type": "GLUE",
+            "Parameters": {},
+        }
+_prepared_statements = AccountScopedDict()  # "workgroup/name" -> statement dict
+_tags = AccountScopedDict()  # arn -> {key: value, ...}
+
+
+def get_state():
+    return copy.deepcopy(
+        {
+            "_executions": _executions,
+            "_workgroups": _workgroups,
+            "_named_queries": _named_queries,
+            "_data_catalogs": _data_catalogs,
+            "_prepared_statements": _prepared_statements,
+            "_tags": _tags,
+        }
+    )
+
+
+def restore_state(data):
+    # AccountScopedDicts are mutated in-place — no module-level reassignment.
+    _executions.clear()
+    _executions.update(data.get("_executions", {}))
+    _workgroups.clear()
+    _workgroups.update(data.get("_workgroups", {}))
+    _named_queries.clear()
+    _named_queries.update(data.get("_named_queries", {}))
+    _data_catalogs.clear()
+    _data_catalogs.update(data.get("_data_catalogs", {}))
+    _prepared_statements.clear()
+    _prepared_statements.update(data.get("_prepared_statements", {}))
+    _tags.clear()
+    _tags.update(data.get("_tags", {}))
+
+
+_restored = load_state("athena")
+if _restored:
+    restore_state(_restored)
+
+try:
+    import duckdb
+
+    _duckdb_available = True
+except ImportError:
+    _duckdb_available = False
+
+
+
+_DUCKDB_TYPE_MAP = {
+    "BOOLEAN": "boolean",
+    "TINYINT": "tinyint",
+    "SMALLINT": "smallint",
+    "INTEGER": "integer",
+    "INT": "integer",
+    "BIGINT": "bigint",
+    "HUGEINT": "bigint",
+    "FLOAT": "float",
+    "REAL": "float",
+    "DOUBLE": "double",
+    "DECIMAL": "decimal",
+    "VARCHAR": "varchar",
+    "BLOB": "varbinary",
+    "DATE": "date",
+    "TIME": "time",
+    "TIMESTAMP": "timestamp",
+    "TIMESTAMP WITH TIME ZONE": "timestamp",
+    "INTERVAL": "varchar",
+    "LIST": "array",
+    "STRUCT": "row",
+    "MAP": "map",
+}
+
+
+def _arn_workgroup(name):
+    return f"arn:aws:athena:{get_region()}:{get_account_id()}:workgroup/{name}"
+
+
+def _arn_datacatalog(name):
+    return f"arn:aws:athena:{get_region()}:{get_account_id()}:datacatalog/{name}"
+
+
+async def handle_request(method, path, headers, body, query_params):
+    # AWS pre-provisions "primary" workgroup + "AwsDataCatalog" in every
+    # account. Seed them lazily per-tenant on first access.
+    _ensure_default_workgroup()
+    _ensure_default_data_catalog()
+
+    target = headers.get("x-amz-target", "")
+    action = target.split(".")[-1] if "." in target else ""
+
+    try:
+        data = json.loads(body) if body else {}
+    except json.JSONDecodeError:
+        return error_response_json("SerializationException", "Invalid JSON", 400)
+
+    handlers = {
+        "StartQueryExecution": _start_query_execution,
+        "GetQueryExecution": _get_query_execution,
+        "GetQueryResults": _get_query_results,
+        "StopQueryExecution": _stop_query_execution,
+        "ListQueryExecutions": _list_query_executions,
+        "CreateWorkGroup": _create_workgroup,
+        "DeleteWorkGroup": _delete_workgroup,
+        "GetWorkGroup": _get_workgroup,
+        "ListWorkGroups": _list_workgroups,
+        "UpdateWorkGroup": _update_workgroup,
+        "CreateNamedQuery": _create_named_query,
+        "DeleteNamedQuery": _delete_named_query,
+        "GetNamedQuery": _get_named_query,
+        "ListNamedQueries": _list_named_queries,
+        "BatchGetNamedQuery": _batch_get_named_query,
+        "BatchGetQueryExecution": _batch_get_query_execution,
+        # Data Catalogs
+        "CreateDataCatalog": _create_data_catalog,
+        "GetDataCatalog": _get_data_catalog,
+        "ListDataCatalogs": _list_data_catalogs,
+        "DeleteDataCatalog": _delete_data_catalog,
+        "UpdateDataCatalog": _update_data_catalog,
+        # Prepared Statements
+        "CreatePreparedStatement": _create_prepared_statement,
+        "GetPreparedStatement": _get_prepared_statement,
+        "DeletePreparedStatement": _delete_prepared_statement,
+        "ListPreparedStatements": _list_prepared_statements,
+        # Table Metadata
+        "GetTableMetadata": _get_table_metadata,
+        "ListTableMetadata": _list_table_metadata,
+        # Tags
+        "TagResource": _tag_resource,
+        "UntagResource": _untag_resource,
+        "ListTagsForResource": _list_tags_for_resource,
+    }
+
+    handler = handlers.get(action)
+    if not handler:
+        return error_response_json(
+            "InvalidAction", f"Unknown Athena action: {action}", 400
+        )
+    return handler(data)
+
+
+# ---- Query Execution ----
+
+
+def _start_query_execution(data):
+    query = data.get("QueryString", "")
+    query_id = new_uuid()
+    workgroup = data.get("WorkGroup", "primary")
+    output_location = data.get("ResultConfiguration", {}).get(
+        "OutputLocation"
+    ) or _workgroups.get(workgroup, {}).get("Configuration", {}).get(
+        "ResultConfiguration", {}
+    ).get("OutputLocation", "s3://athena-results/")
+    db = data.get("QueryExecutionContext", {}).get("Database", "default")
+    catalog = data.get("QueryExecutionContext", {}).get("Catalog", "AwsDataCatalog")
+
+    execution = {
+        "QueryExecutionId": query_id,
+        "Query": query,
+        "StatementType": _detect_statement_type(query),
+        "ResultConfiguration": {"OutputLocation": f"{output_location}{query_id}.csv"},
+        "QueryExecutionContext": {"Database": db, "Catalog": catalog},
+        "Status": {
+            "State": "QUEUED",
+            "SubmissionDateTime": int(time.time()),
+            "CompletionDateTime": None,
+            "StateChangeReason": "",
+        },
+        "Statistics": {
+            "EngineExecutionTimeInMillis": 0,
+            "DataScannedInBytes": 0,
+            "DataManifestLocation": "",
+            "TotalExecutionTimeInMillis": 0,
+            "QueryQueueTimeInMillis": 0,
+            "QueryPlanningTimeInMillis": 0,
+            "ServiceProcessingTimeInMillis": 0,
+        },
+        "WorkGroup": workgroup,
+        "EngineVersion": {
+            "SelectedEngineVersion": "Athena engine version 3",
+            "EffectiveEngineVersion": "Athena engine version 3",
+        },
+        "_results": None,
+        "_column_types": None,
+        "_error": None,
+    }
+    _executions[query_id] = execution
+
+    thread = threading.Thread(
+        target=_execute_query, args=(query_id, query, db), daemon=True
+    )
+    thread.start()
+
+    return json_response({"QueryExecutionId": query_id})
+
+
+def _execute_query(query_id, query, database):
+    execution = _executions.get(query_id)
+    if not execution:
+        return
+
+    execution["Status"]["State"] = "RUNNING"
+    start = time.time()
+
+    try:
+        engine = get_athena_engine()
+
+        if engine == "duckdb":
+            results = _run_duckdb(query, database)
+        else:
+            results = _mock_query_results(query)
+
+        execution["_results"] = {"columns": results["columns"], "rows": results["rows"]}
+        execution["_column_types"] = results.get(
+            "column_types", ["varchar"] * len(results["columns"])
+        )
+        execution["Status"]["State"] = "SUCCEEDED"
+        elapsed_ms = int((time.time() - start) * 1000)
+        execution["Statistics"]["EngineExecutionTimeInMillis"] = elapsed_ms
+        execution["Statistics"]["TotalExecutionTimeInMillis"] = elapsed_ms + 50
+        execution["Statistics"]["QueryPlanningTimeInMillis"] = min(20, elapsed_ms)
+        execution["Statistics"]["ServiceProcessingTimeInMillis"] = 30
+        execution["Statistics"]["DataScannedInBytes"] = sum(
+            len(str(row)) for row in results.get("rows", [])
+        )
+    except Exception as e:
+        logger.error("Athena query %s failed: %s", query_id, e)
+        execution["Status"]["State"] = "FAILED"
+        execution["Status"]["StateChangeReason"] = str(e)[:2000]
+        execution["_error"] = str(e)
+
+    execution["Status"]["CompletionDateTime"] = int(time.time())
+
+
+def _run_duckdb(query, database):
+    import duckdb
+
+    conn = duckdb.connect(":memory:")
+    rewritten = _rewrite_s3_paths(query)
+
+    try:
+        result = conn.execute(rewritten)
+        columns = []
+        column_types = []
+        if result.description:
+            for desc in result.description:
+                columns.append(desc[0])
+                raw_type = desc[1] if len(desc) > 1 else "VARCHAR"
+                if isinstance(raw_type, str):
+                    type_key = raw_type.upper().split("(")[0].strip()
+                else:
+                    type_key = str(raw_type).upper().split("(")[0].strip()
+                athena_type = _DUCKDB_TYPE_MAP.get(type_key, "varchar")
+                column_types.append(athena_type)
+        rows = result.fetchall()
+        conn.close()
+        return {
+            "columns": columns,
+            "column_types": column_types,
+            "rows": [list(r) for r in rows],
+        }
+    except Exception as e:
+        conn.close()
+        raise e
+
+
+def _rewrite_s3_paths(query):
+    """Replace s3://bucket/key references with local file paths.
+    Handles: quoted strings, read_csv/read_parquet/read_json function args,
+    and FROM clauses with s3 paths.
+    """
+
+    def replace_s3(match):
+        prefix = match.group(1)
+        s3_uri = match.group(2)
+        suffix = match.group(3)
+        stripped = s3_uri
+        if stripped.startswith("s3://"):
+            stripped = stripped[5:]
+        elif stripped.startswith("s3a://"):
+            stripped = stripped[6:]
+        parts = stripped.split("/", 1)
+        bucket = parts[0]
+        key = parts[1] if len(parts) > 1 else ""
+        local_path = os.path.join(S3_DATA_DIR, bucket, key)
+        return f"{prefix}{local_path}{suffix}"
+
+    result = re.sub(
+        r"""(["'])(s3a?://[^"']+)(["'])""",
+        replace_s3,
+        query,
+    )
+    result = re.sub(
+        r"(FROM\s+)(s3a?://\S+)(\s|;|$)",
+        replace_s3,
+        result,
+        flags=re.IGNORECASE,
+    )
+    return result
+
+
+def _mock_query_results(query):
+    query_upper = query.strip().upper()
+    if query_upper.startswith("SELECT"):
+        match = re.match(r"SELECT\s+'([^']*)'", query.strip(), re.IGNORECASE)
+        if match:
+            val = match.group(1)
+            return {"columns": [val], "column_types": ["varchar"], "rows": [[val]]}
+        alias_pattern = re.findall(
+            r"""(?:(\d+(?:\.\d+)?)|'([^']*)')\s+AS\s+(\w+)""",
+            query.strip(),
+            re.IGNORECASE,
+        )
+        if alias_pattern:
+            cols = [m[2] for m in alias_pattern]
+            types = ["integer" if m[0] else "varchar" for m in alias_pattern]
+            vals = [m[0] if m[0] else m[1] for m in alias_pattern]
+            return {"columns": cols, "column_types": types, "rows": [vals]}
+        return {
+            "columns": ["result"],
+            "column_types": ["varchar"],
+            "rows": [["mock_value"]],
+        }
+    return {"columns": [], "column_types": [], "rows": []}
+
+
+def _detect_statement_type(query):
+    q = query.strip().upper()
+    if q.startswith("SELECT") or q.startswith("WITH"):
+        return "DML"
+    if q.startswith(("CREATE", "DROP", "ALTER")):
+        return "DDL"
+    if q.startswith(("INSERT", "DELETE", "UPDATE", "MERGE")):
+        return "DML"
+    return "UTILITY"
+
+
+def _get_query_execution(data):
+    query_id = data.get("QueryExecutionId")
+    execution = _executions.get(query_id)
+    if not execution:
+        return error_response_json(
+            "InvalidRequestException", f"Query {query_id} not found", 400
+        )
+    return json_response({"QueryExecution": _execution_out(execution)})
+
+
+def _get_query_results(data):
+    query_id = data.get("QueryExecutionId")
+    max_results = data.get("MaxResults", 1000)
+    next_token = data.get("NextToken")
+    execution = _executions.get(query_id)
+    if not execution:
+        return error_response_json(
+            "InvalidRequestException", f"Query {query_id} not found", 400
+        )
+
+    state = execution["Status"]["State"]
+    if state == "FAILED":
+        return error_response_json(
+            "InvalidRequestException",
+            f"Query has failed: {execution['Status'].get('StateChangeReason', 'Unknown')}",
+            400,
+        )
+    if state != "SUCCEEDED":
+        return error_response_json(
+            "InvalidRequestException", f"Query is in state {state}", 400
+        )
+
+    results = execution.get("_results") or {"columns": [], "rows": []}
+    columns = results.get("columns", [])
+    rows = results.get("rows", [])
+    column_types = execution.get("_column_types") or ["varchar"] * len(columns)
+
+    start_idx = 0
+    if next_token:
+        try:
+            start_idx = int(next_token)
+        except ValueError:
+            pass
+
+    page_rows = rows[start_idx : start_idx + max_results]
+
+    result_rows = []
+    result_rows.append({"Data": [{"VarCharValue": col} for col in columns]})
+    for row in page_rows:
+        result_rows.append(
+            {"Data": [{"VarCharValue": str(v) if v is not None else ""} for v in row]}
+        )
+
+    column_info = []
+    for i, col in enumerate(columns):
+        ctype = column_types[i] if i < len(column_types) else "varchar"
+        precision, scale = _type_precision_scale(ctype)
+        column_info.append(
+            {
+                "CatalogName": "hive",
+                "SchemaName": "",
+                "TableName": "",
+                "Name": col,
+                "Label": col,
+                "Type": ctype,
+                "Precision": precision,
+                "Scale": scale,
+                "Nullable": "UNKNOWN",
+                "CaseSensitive": ctype == "varchar",
+            }
+        )
+
+    response = {
+        "ResultSet": {
+            "Rows": result_rows,
+            "ResultSetMetadata": {"ColumnInfo": column_info},
+        },
+        "UpdateCount": 0,
+    }
+
+    end_idx = start_idx + max_results
+    if end_idx < len(rows):
+        response["NextToken"] = str(end_idx)
+
+    return json_response(response)
+
+
+def _type_precision_scale(athena_type):
+    if athena_type in ("integer", "int"):
+        return 10, 0
+    if athena_type == "bigint":
+        return 19, 0
+    if athena_type == "smallint":
+        return 5, 0
+    if athena_type == "tinyint":
+        return 3, 0
+    if athena_type == "double":
+        return 17, 0
+    if athena_type == "float":
+        return 7, 0
+    if athena_type == "boolean":
+        return 0, 0
+    if athena_type == "decimal":
+        return 38, 0
+    return 0, 0
+
+
+def _stop_query_execution(data):
+    query_id = data.get("QueryExecutionId")
+    execution = _executions.get(query_id)
+    if execution and execution["Status"]["State"] in ("QUEUED", "RUNNING"):
+        execution["Status"]["State"] = "CANCELLED"
+        execution["Status"]["StateChangeReason"] = "Query was cancelled by user"
+        execution["Status"]["CompletionDateTime"] = int(time.time())
+    return json_response({})
+
+
+def _list_query_executions(data):
+    workgroup = data.get("WorkGroup", "primary")
+    ids = [qid for qid, ex in _executions.items() if ex.get("WorkGroup") == workgroup]
+    return json_response({"QueryExecutionIds": ids})
+
+
+# ---- WorkGroups ----
+
+
+def _create_workgroup(data):
+    name = data.get("Name")
+    if name in _workgroups:
+        return error_response_json(
+            "InvalidRequestException", f"WorkGroup {name} already exists", 400
+        )
+    _workgroups[name] = {
+        "Name": name,
+        "State": "ENABLED",
+        "Description": data.get("Description", ""),
+        "CreationTime": int(time.time()),
+        "Configuration": data.get("Configuration", {}),
+    }
+    tags = data.get("Tags", [])
+    if tags:
+        arn = _arn_workgroup(name)
+        _tags[arn] = {t["Key"]: t["Value"] for t in tags}
+    return json_response({})
+
+
+def _delete_workgroup(data):
+    name = data.get("WorkGroup")
+    if name == "primary":
+        return error_response_json(
+            "InvalidRequestException", "Cannot delete primary workgroup", 400
+        )
+    _workgroups.pop(name, None)
+    _tags.pop(_arn_workgroup(name), None)
+    return json_response({})
+
+
+def _get_workgroup(data):
+    name = data.get("WorkGroup")
+    wg = _workgroups.get(name)
+    if not wg:
+        return error_response_json(
+            "InvalidRequestException", f"WorkGroup {name} not found", 400
+        )
+    out = dict(wg)
+    out.setdefault("WorkGroupConfiguration", out.get("Configuration", {}))
+    return json_response({"WorkGroup": out})
+
+
+def _list_workgroups(data):
+    return json_response(
+        {
+            "WorkGroups": [
+                {
+                    "Name": wg["Name"],
+                    "State": wg["State"],
+                    "Description": wg.get("Description", ""),
+                    "CreationTime": wg.get("CreationTime", 0),
+                }
+                for wg in _workgroups.values()
+            ]
+        }
+    )
+
+
+def _update_workgroup(data):
+    name = data.get("WorkGroup")
+    wg = _workgroups.get(name)
+    if not wg:
+        return error_response_json(
+            "InvalidRequestException", f"WorkGroup {name} not found", 400
+        )
+    if "ConfigurationUpdates" in data:
+        updates = data["ConfigurationUpdates"]
+        config = wg.setdefault("Configuration", {})
+        if "ResultConfigurationUpdates" in updates:
+            rc = config.setdefault("ResultConfiguration", {})
+            rcu = updates["ResultConfigurationUpdates"]
+            if "OutputLocation" in rcu:
+                rc["OutputLocation"] = rcu["OutputLocation"]
+            if "EncryptionConfiguration" in rcu:
+                rc["EncryptionConfiguration"] = rcu["EncryptionConfiguration"]
+            if rcu.get("RemoveOutputLocation"):
+                rc.pop("OutputLocation", None)
+            if rcu.get("RemoveEncryptionConfiguration"):
+                rc.pop("EncryptionConfiguration", None)
+        for ck in (
+            "EnforceWorkGroupConfiguration",
+            "PublishCloudWatchMetricsEnabled",
+            "BytesScannedCutoffPerQuery",
+            "RequesterPaysEnabled",
+            "EngineVersion",
+        ):
+            if ck in updates:
+                config[ck] = updates[ck]
+    if "Description" in data:
+        wg["Description"] = data["Description"]
+    if "State" in data:
+        wg["State"] = data["State"]
+    return json_response({})
+
+
+# ---- Named Queries ----
+
+
+def _create_named_query(data):
+    query_id = new_uuid()
+    _named_queries[query_id] = {
+        "NamedQueryId": query_id,
+        "Name": data.get("Name", ""),
+        "Description": data.get("Description", ""),
+        "Database": data.get("Database", "default"),
+        "QueryString": data.get("QueryString", ""),
+        "WorkGroup": data.get("WorkGroup", "primary"),
+    }
+    return json_response({"NamedQueryId": query_id})
+
+
+def _delete_named_query(data):
+    _named_queries.pop(data.get("NamedQueryId"), None)
+    return json_response({})
+
+
+def _get_named_query(data):
+    query_id = data.get("NamedQueryId")
+    nq = _named_queries.get(query_id)
+    if not nq:
+        return error_response_json(
+            "InvalidRequestException", f"Named query {query_id} not found", 400
+        )
+    return json_response({"NamedQuery": nq})
+
+
+def _list_named_queries(data):
+    workgroup = data.get("WorkGroup")
+    if workgroup:
+        ids = [qid for qid, nq in _named_queries.items() if nq.get("WorkGroup") == workgroup]
+    else:
+        ids = list(_named_queries.keys())
+    return json_response({"NamedQueryIds": ids})
+
+
+def _batch_get_named_query(data):
+    ids = data.get("NamedQueryIds", [])
+    queries = [_named_queries[qid] for qid in ids if qid in _named_queries]
+    unprocessed = [
+        {
+            "NamedQueryId": qid,
+            "ErrorCode": "INTERNAL_FAILURE",
+            "ErrorMessage": "Not found",
+        }
+        for qid in ids
+        if qid not in _named_queries
+    ]
+    return json_response(
+        {"NamedQueries": queries, "UnprocessedNamedQueryIds": unprocessed}
+    )
+
+
+def _batch_get_query_execution(data):
+    ids = data.get("QueryExecutionIds", [])
+    execs = [_execution_out(_executions[qid]) for qid in ids if qid in _executions]
+    unprocessed = [
+        {
+            "QueryExecutionId": qid,
+            "ErrorCode": "INTERNAL_FAILURE",
+            "ErrorMessage": "Not found",
+        }
+        for qid in ids
+        if qid not in _executions
+    ]
+    return json_response(
+        {"QueryExecutions": execs, "UnprocessedQueryExecutionIds": unprocessed}
+    )
+
+
+# ---- Data Catalogs ----
+
+
+def _create_data_catalog(data):
+    name = data.get("Name")
+    if not name:
+        return error_response_json("InvalidRequestException", "Name is required", 400)
+    if name in _data_catalogs:
+        return error_response_json(
+            "InvalidRequestException", f"Data catalog {name} already exists", 400
+        )
+    catalog_type = data.get("Type", "HIVE")
+    if catalog_type not in ("HIVE", "LAMBDA", "GLUE"):
+        return error_response_json(
+            "InvalidRequestException", f"Invalid catalog type: {catalog_type}", 400
+        )
+    _data_catalogs[name] = {
+        "Name": name,
+        "Description": data.get("Description", ""),
+        "Type": catalog_type,
+        "Parameters": data.get("Parameters", {}),
+    }
+    tags = data.get("Tags", [])
+    if tags:
+        arn = _arn_datacatalog(name)
+        _tags[arn] = {t["Key"]: t["Value"] for t in tags}
+    return json_response({})
+
+
+def _get_data_catalog(data):
+    name = data.get("Name")
+    catalog = _data_catalogs.get(name)
+    if not catalog:
+        return error_response_json(
+            "InvalidRequestException", f"Data catalog {name} not found", 400
+        )
+    return json_response({"DataCatalog": catalog})
+
+
+def _list_data_catalogs(data):
+    summaries = [
+        {"CatalogName": c["Name"], "Type": c["Type"]} for c in _data_catalogs.values()
+    ]
+    return json_response({"DataCatalogsSummary": summaries})
+
+
+def _delete_data_catalog(data):
+    name = data.get("Name")
+    if name == "AwsDataCatalog":
+        return error_response_json(
+            "InvalidRequestException", "Cannot delete the default AWS data catalog", 400
+        )
+    if name not in _data_catalogs:
+        return error_response_json(
+            "InvalidRequestException", f"Data catalog {name} not found", 400
+        )
+    del _data_catalogs[name]
+    _tags.pop(_arn_datacatalog(name), None)
+    return json_response({})
+
+
+def _update_data_catalog(data):
+    name = data.get("Name")
+    catalog = _data_catalogs.get(name)
+    if not catalog:
+        return error_response_json(
+            "InvalidRequestException", f"Data catalog {name} not found", 400
+        )
+    if "Description" in data:
+        catalog["Description"] = data["Description"]
+    if "Type" in data:
+        catalog["Type"] = data["Type"]
+    if "Parameters" in data:
+        catalog["Parameters"] = data["Parameters"]
+    return json_response({})
+
+
+# ---- Prepared Statements ----
+
+
+def _create_prepared_statement(data):
+    name = data.get("StatementName")
+    workgroup = data.get("WorkGroup", "primary")
+    query = data.get("QueryStatement", "")
+    if not name:
+        return error_response_json(
+            "InvalidRequestException", "StatementName is required", 400
+        )
+    key = f"{workgroup}/{name}"
+    if key in _prepared_statements:
+        return error_response_json(
+            "InvalidRequestException",
+            f"Prepared statement {name} already exists in {workgroup}",
+            400,
+        )
+    _prepared_statements[key] = {
+        "StatementName": name,
+        "WorkGroupName": workgroup,
+        "QueryStatement": query,
+        "Description": data.get("Description", ""),
+        "LastModifiedTime": int(time.time()),
+    }
+    return json_response({})
+
+
+def _get_prepared_statement(data):
+    name = data.get("StatementName")
+    workgroup = data.get("WorkGroup") or data.get("WorkGroupName", "primary")
+    key = f"{workgroup}/{name}"
+    stmt = _prepared_statements.get(key)
+    if not stmt:
+        return error_response_json(
+            "ResourceNotFoundException",
+            f"Prepared statement {name} not found in {workgroup}",
+            400,
+        )
+    return json_response({"PreparedStatement": stmt})
+
+
+def _delete_prepared_statement(data):
+    name = data.get("StatementName")
+    workgroup = data.get("WorkGroup") or data.get("WorkGroupName", "primary")
+    key = f"{workgroup}/{name}"
+    if key not in _prepared_statements:
+        return error_response_json(
+            "ResourceNotFoundException", f"Prepared statement {name} not found", 400
+        )
+    del _prepared_statements[key]
+    return json_response({})
+
+
+def _list_prepared_statements(data):
+    workgroup = data.get("WorkGroup") or data.get("WorkGroupName", "primary")
+    stmts = [
+        {"StatementName": s["StatementName"], "LastModifiedTime": s["LastModifiedTime"]}
+        for k, s in _prepared_statements.items()
+        if s.get("WorkGroupName") == workgroup
+    ]
+    return json_response({"PreparedStatements": stmts})
+
+
+# ---- Table Metadata (stubs) ----
+
+
+def _get_table_metadata(data):
+    catalog = data.get("CatalogName", "AwsDataCatalog")
+    db = data.get("DatabaseName", "default")
+    table = data.get("TableName", "")
+    return json_response(
+        {
+            "TableMetadata": {
+                "Name": table,
+                "CreateTime": int(time.time()),
+                "LastAccessTime": int(time.time()),
+                "TableType": "EXTERNAL_TABLE",
+                "Columns": [],
+                "PartitionKeys": [],
+                "Parameters": {"classification": "csv"},
+            }
+        }
+    )
+
+
+def _list_table_metadata(data):
+    return json_response({"TableMetadataList": []})
+
+
+# ---- Tags ----
+
+
+def _tag_resource(data):
+    arn = data.get("ResourceARN", "")
+    tags = data.get("Tags", [])
+    tag_dict = _tags.setdefault(arn, {})
+    for t in tags:
+        tag_dict[t["Key"]] = t["Value"]
+    return json_response({})
+
+
+def _untag_resource(data):
+    arn = data.get("ResourceARN", "")
+    keys = data.get("TagKeys", [])
+    tag_dict = _tags.get(arn, {})
+    for k in keys:
+        tag_dict.pop(k, None)
+    return json_response({})
+
+
+def _list_tags_for_resource(data):
+    arn = data.get("ResourceARN", "")
+    tag_dict = _tags.get(arn, {})
+    tags = [{"Key": k, "Value": v} for k, v in tag_dict.items()]
+    return json_response({"Tags": tags})
+
+
+# ---- Helpers ----
+
+
+def _execution_out(ex):
+    return {k: v for k, v in ex.items() if not k.startswith("_")}
+
+
+SUPPORTED_ACTIONS = [
+    "StartQueryExecution", "GetQueryExecution", "GetQueryResults", "StopQueryExecution",
+    "ListQueryExecutions", "CreateWorkGroup", "DeleteWorkGroup", "GetWorkGroup",
+    "ListWorkGroups", "UpdateWorkGroup", "CreateNamedQuery", "DeleteNamedQuery",
+    "GetNamedQuery", "ListNamedQueries", "BatchGetNamedQuery", "BatchGetQueryExecution",
+    "CreateDataCatalog", "GetDataCatalog", "ListDataCatalogs", "DeleteDataCatalog",
+    "UpdateDataCatalog", "CreatePreparedStatement", "GetPreparedStatement",
+    "DeletePreparedStatement", "ListPreparedStatements", "GetTableMetadata",
+    "ListTableMetadata", "TagResource", "UntagResource", "ListTagsForResource",
+]
+
+
+def get_state_summary() -> dict:
+    return {
+        "workgroups": {"count": len(_workgroups), "names": list(_workgroups.keys())},
+        "named_queries": {"count": len(_named_queries), "ids": list(_named_queries.keys())},
+        "data_catalogs": {"count": len(_data_catalogs), "names": list(_data_catalogs.keys())},
+        "executions": {"count": len(_executions), "ids": list(_executions.keys())},
+        "prepared_statements": {"count": len(_prepared_statements), "keys": list(_prepared_statements.keys())},
+        "tags": {"count": len(_tags), "arns": list(_tags.keys())},
+    }
+
+
+def reset():
+    _executions.clear()
+    _named_queries.clear()
+    _prepared_statements.clear()
+    _workgroups.clear()
+    _data_catalogs.clear()
+    _tags.clear()
+    # "primary" workgroup and "AwsDataCatalog" are seeded lazily per-account
+    # on next access via _ensure_default_workgroup() / _ensure_default_data_catalog().

aws_infra/ministack/services/autoscaling.py

@@ -0,0 +1,554 @@
+"""
+AutoScaling Service Emulator.
+Query API (Action=...) — groups, launch configs, policies, hooks, scheduled actions.
+All in-memory, no actual instance scaling.
+
+Supports:
+  ASG:       CreateAutoScalingGroup, DescribeAutoScalingGroups, UpdateAutoScalingGroup,
+             DeleteAutoScalingGroup, DescribeAutoScalingInstances, DescribeScalingActivities
+  LC:        CreateLaunchConfiguration, DescribeLaunchConfigurations, DeleteLaunchConfiguration
+  Policies:  PutScalingPolicy, DescribePolicies, DeletePolicy
+  Hooks:     PutLifecycleHook, DescribeLifecycleHooks, DeleteLifecycleHook,
+             CompleteLifecycleAction, RecordLifecycleActionHeartbeat
+  Schedule:  PutScheduledUpdateGroupAction, DescribeScheduledActions, DeleteScheduledAction
+  Tags:      CreateOrUpdateTags, DescribeTags, DeleteTags
+"""
+
+import logging
+import os
+import time
+from collections import defaultdict
+
+from ministack.core.responses import AccountScopedDict, get_account_id, new_uuid, now_iso, get_region
+
+logger = logging.getLogger("autoscaling")
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+
+_asgs = AccountScopedDict()
+_launch_configs = AccountScopedDict()
+_policies = AccountScopedDict()
+_hooks = AccountScopedDict()
+_scheduled_actions = AccountScopedDict()
+_tags = AccountScopedDict()  # asg_name -> [{"Key":..., "Value":...}, ...]
+
+
+import copy
+
+
+def get_state():
+    return {
+        "asgs": copy.deepcopy(_asgs),
+        "launch_configs": copy.deepcopy(_launch_configs),
+        "policies": copy.deepcopy(_policies),
+        "hooks": copy.deepcopy(_hooks),
+        "scheduled_actions": copy.deepcopy(_scheduled_actions),
+        "tags": copy.deepcopy(_tags),
+    }
+
+
+def restore_state(data):
+    if data:
+        _asgs.update(data.get("asgs", {}))
+        _launch_configs.update(data.get("launch_configs", {}))
+        _policies.update(data.get("policies", {}))
+        _hooks.update(data.get("hooks", {}))
+        _scheduled_actions.update(data.get("scheduled_actions", {}))
+        _tags.update(data.get("tags", {}))
+
+
+def reset():
+    _asgs.clear()
+    _launch_configs.clear()
+    _policies.clear()
+    _hooks.clear()
+    _scheduled_actions.clear()
+    _tags.clear()
+
+
+def _p(params, key):
+    v = params.get(key, "")
+    return v[0] if isinstance(v, list) else v
+
+
+def _parse_member_list(params, prefix):
+    items = []
+    i = 1
+    while True:
+        key = f"{prefix}.member.{i}"
+        val = _p(params, key)
+        if not val:
+            break
+        items.append(val)
+        i += 1
+    return items
+
+
+def _xml(status, root_tag, inner):
+    body = (f'<?xml version="1.0" encoding="UTF-8"?>'
+            f'<{root_tag} xmlns="http://autoscaling.amazonaws.com/doc/2011-01-01/">'
+            f'{inner}'
+            f'<ResponseMetadata><RequestId>{new_uuid()}</RequestId></ResponseMetadata>'
+            f'</{root_tag}>').encode("utf-8")
+    return status, {"Content-Type": "application/xml"}, body
+
+
+def _error(code, message, status=400):
+    return _xml(status, "ErrorResponse",
+                f'<Error><Type>Sender</Type><Code>{code}</Code><Message>{message}</Message></Error>')
+
+
+def _asg_arn(name):
+    return f"arn:aws:autoscaling:{get_region()}:{get_account_id()}:autoScalingGroup:{new_uuid()}:autoScalingGroupName/{name}"
+
+
+# ---------------------------------------------------------------------------
+# AutoScalingGroup
+# ---------------------------------------------------------------------------
+
+def _create_asg(p):
+    name = _p(p, "AutoScalingGroupName")
+    if not name:
+        return _error("ValidationError", "AutoScalingGroupName is required")
+    if name in _asgs:
+        return _error("AlreadyExistsFault", f"AutoScalingGroup {name} already exists")
+
+    arn = _asg_arn(name)
+    _asgs[name] = {
+        "AutoScalingGroupName": name,
+        "AutoScalingGroupARN": arn,
+        "LaunchConfigurationName": _p(p, "LaunchConfigurationName"),
+        "LaunchTemplate": {},
+        "MinSize": int(_p(p, "MinSize") or 0),
+        "MaxSize": int(_p(p, "MaxSize") or 0),
+        "DesiredCapacity": int(_p(p, "DesiredCapacity") or _p(p, "MinSize") or 0),
+        "DefaultCooldown": int(_p(p, "DefaultCooldown") or 300),
+        "AvailabilityZones": _parse_member_list(p, "AvailabilityZones") or [f"{get_region()}a"],
+        "HealthCheckType": _p(p, "HealthCheckType") or "EC2",
+        "HealthCheckGracePeriod": int(_p(p, "HealthCheckGracePeriod") or 300),
+        "Instances": [],
+        "CreatedTime": now_iso(),
+        "VPCZoneIdentifier": _p(p, "VPCZoneIdentifier") or "",
+        "TerminationPolicies": _parse_member_list(p, "TerminationPolicies") or ["Default"],
+        "NewInstancesProtectedFromScaleIn": _p(p, "NewInstancesProtectedFromScaleIn") == "true",
+        "ServiceLinkedRoleARN": _p(p, "ServiceLinkedRoleARN") or "",
+        "Tags": [],
+        "Status": "",
+    }
+
+    # Parse launch template
+    lt_id = _p(p, "LaunchTemplate.LaunchTemplateId") or _p(p, "LaunchTemplate.LaunchTemplateName")
+    lt_ver = _p(p, "LaunchTemplate.Version") or "$Default"
+    if lt_id:
+        _asgs[name]["LaunchTemplate"] = {
+            "LaunchTemplateId": lt_id,
+            "LaunchTemplateName": lt_id,
+            "Version": lt_ver,
+        }
+
+    # Parse tags
+    i = 1
+    tags = []
+    while _p(p, f"Tags.member.{i}.Key"):
+        tags.append({
+            "Key": _p(p, f"Tags.member.{i}.Key"),
+            "Value": _p(p, f"Tags.member.{i}.Value"),
+            "ResourceId": name,
+            "ResourceType": "auto-scaling-group",
+            "PropagateAtLaunch": _p(p, f"Tags.member.{i}.PropagateAtLaunch") == "true",
+        })
+        i += 1
+    _asgs[name]["Tags"] = tags
+    _tags[name] = tags
+
+    logger.info("CreateAutoScalingGroup: %s", name)
+    return _xml(200, "CreateAutoScalingGroupResponse", "<CreateAutoScalingGroupResult/>")
+
+
+def _describe_asgs(p):
+    names = _parse_member_list(p, "AutoScalingGroupNames")
+    members = ""
+    for name, asg in _asgs.items():
+        if names and name not in names:
+            continue
+        azs = "".join(f"<member>{az}</member>" for az in asg["AvailabilityZones"])
+        tp = "".join(f"<member>{t}</member>" for t in asg["TerminationPolicies"])
+        tags_xml = "".join(
+            f"<member><Key>{t['Key']}</Key><Value>{t['Value']}</Value>"
+            f"<ResourceId>{t['ResourceId']}</ResourceId><ResourceType>{t['ResourceType']}</ResourceType>"
+            f"<PropagateAtLaunch>{'true' if t.get('PropagateAtLaunch') else 'false'}</PropagateAtLaunch></member>"
+            for t in asg.get("Tags", [])
+        )
+        lt = asg.get("LaunchTemplate", {})
+        lt_xml = ""
+        if lt:
+            lt_xml = (f"<LaunchTemplate>"
+                      f"<LaunchTemplateId>{lt.get('LaunchTemplateId', '')}</LaunchTemplateId>"
+                      f"<LaunchTemplateName>{lt.get('LaunchTemplateName', '')}</LaunchTemplateName>"
+                      f"<Version>{lt.get('Version', '')}</Version></LaunchTemplate>")
+        members += (f"<member>"
+                    f"<AutoScalingGroupName>{name}</AutoScalingGroupName>"
+                    f"<AutoScalingGroupARN>{asg['AutoScalingGroupARN']}</AutoScalingGroupARN>"
+                    f"<MinSize>{asg['MinSize']}</MinSize>"
+                    f"<MaxSize>{asg['MaxSize']}</MaxSize>"
+                    f"<DesiredCapacity>{asg['DesiredCapacity']}</DesiredCapacity>"
+                    f"<DefaultCooldown>{asg['DefaultCooldown']}</DefaultCooldown>"
+                    f"<AvailabilityZones>{azs}</AvailabilityZones>"
+                    f"<HealthCheckType>{asg['HealthCheckType']}</HealthCheckType>"
+                    f"<HealthCheckGracePeriod>{asg['HealthCheckGracePeriod']}</HealthCheckGracePeriod>"
+                    f"<CreatedTime>{asg['CreatedTime']}</CreatedTime>"
+                    f"<VPCZoneIdentifier>{asg['VPCZoneIdentifier']}</VPCZoneIdentifier>"
+                    f"<TerminationPolicies>{tp}</TerminationPolicies>"
+                    f"<NewInstancesProtectedFromScaleIn>{'true' if asg['NewInstancesProtectedFromScaleIn'] else 'false'}</NewInstancesProtectedFromScaleIn>"
+                    f"<Tags>{tags_xml}</Tags>"
+                    f"<Instances/>"
+                    f"{lt_xml}"
+                    f"<LaunchConfigurationName>{asg.get('LaunchConfigurationName', '')}</LaunchConfigurationName>"
+                    f"</member>")
+    return _xml(200, "DescribeAutoScalingGroupsResponse",
+                f"<DescribeAutoScalingGroupsResult><AutoScalingGroups>{members}</AutoScalingGroups></DescribeAutoScalingGroupsResult>")
+
+
+def _update_asg(p):
+    name = _p(p, "AutoScalingGroupName")
+    asg = _asgs.get(name)
+    if not asg:
+        return _error("ValidationError", f"AutoScalingGroup {name} not found")
+    for k, pk in [("MinSize", "MinSize"), ("MaxSize", "MaxSize"), ("DesiredCapacity", "DesiredCapacity"),
+                   ("DefaultCooldown", "DefaultCooldown"), ("HealthCheckGracePeriod", "HealthCheckGracePeriod")]:
+        v = _p(p, pk)
+        if v:
+            asg[k] = int(v)
+    if _p(p, "HealthCheckType"):
+        asg["HealthCheckType"] = _p(p, "HealthCheckType")
+    if _p(p, "VPCZoneIdentifier"):
+        asg["VPCZoneIdentifier"] = _p(p, "VPCZoneIdentifier")
+    return _xml(200, "UpdateAutoScalingGroupResponse", "<UpdateAutoScalingGroupResult/>")
+
+
+def _delete_asg(p):
+    name = _p(p, "AutoScalingGroupName")
+    _asgs.pop(name, None)
+    _tags.pop(name, None)
+    # Remove associated hooks
+    keys_to_del = [k for k in _hooks if k.startswith(f"{name}/")]
+    for k in keys_to_del:
+        del _hooks[k]
+    return _xml(200, "DeleteAutoScalingGroupResponse", "<DeleteAutoScalingGroupResult/>")
+
+
+def _describe_asg_instances(p):
+    return _xml(200, "DescribeAutoScalingInstancesResponse",
+                "<DescribeAutoScalingInstancesResult><AutoScalingInstances/></DescribeAutoScalingInstancesResult>")
+
+
+def _describe_scaling_activities(p):
+    return _xml(200, "DescribeScalingActivitiesResponse",
+                "<DescribeScalingActivitiesResult><Activities/></DescribeScalingActivitiesResult>")
+
+
+# ---------------------------------------------------------------------------
+# LaunchConfiguration
+# ---------------------------------------------------------------------------
+
+def _create_lc(p):
+    name = _p(p, "LaunchConfigurationName")
+    if not name:
+        return _error("ValidationError", "LaunchConfigurationName is required")
+    if name in _launch_configs:
+        return _error("AlreadyExistsFault", f"LaunchConfiguration {name} already exists")
+    arn = f"arn:aws:autoscaling:{get_region()}:{get_account_id()}:launchConfiguration:{new_uuid()}:launchConfigurationName/{name}"
+    _launch_configs[name] = {
+        "LaunchConfigurationName": name,
+        "LaunchConfigurationARN": arn,
+        "ImageId": _p(p, "ImageId") or "ami-00000000",
+        "InstanceType": _p(p, "InstanceType") or "t2.micro",
+        "KeyName": _p(p, "KeyName") or "",
+        "SecurityGroups": _parse_member_list(p, "SecurityGroups"),
+        "UserData": _p(p, "UserData") or "",
+        "CreatedTime": now_iso(),
+    }
+    return _xml(200, "CreateLaunchConfigurationResponse", "<CreateLaunchConfigurationResult/>")
+
+
+def _describe_lcs(p):
+    names = _parse_member_list(p, "LaunchConfigurationNames")
+    members = ""
+    for name, lc in _launch_configs.items():
+        if names and name not in names:
+            continue
+        sgs = "".join(f"<member>{sg}</member>" for sg in lc.get("SecurityGroups", []))
+        members += (f"<member>"
+                    f"<LaunchConfigurationName>{name}</LaunchConfigurationName>"
+                    f"<LaunchConfigurationARN>{lc['LaunchConfigurationARN']}</LaunchConfigurationARN>"
+                    f"<ImageId>{lc['ImageId']}</ImageId>"
+                    f"<InstanceType>{lc['InstanceType']}</InstanceType>"
+                    f"<CreatedTime>{lc['CreatedTime']}</CreatedTime>"
+                    f"<SecurityGroups>{sgs}</SecurityGroups>"
+                    f"</member>")
+    return _xml(200, "DescribeLaunchConfigurationsResponse",
+                f"<DescribeLaunchConfigurationsResult><LaunchConfigurations>{members}</LaunchConfigurations></DescribeLaunchConfigurationsResult>")
+
+
+def _delete_lc(p):
+    name = _p(p, "LaunchConfigurationName")
+    _launch_configs.pop(name, None)
+    return _xml(200, "DeleteLaunchConfigurationResponse", "<DeleteLaunchConfigurationResult/>")
+
+
+# ---------------------------------------------------------------------------
+# Scaling Policy
+# ---------------------------------------------------------------------------
+
+def _put_scaling_policy(p):
+    asg_name = _p(p, "AutoScalingGroupName")
+    policy_name = _p(p, "PolicyName")
+    if not policy_name:
+        return _error("ValidationError", "PolicyName is required")
+    arn = f"arn:aws:autoscaling:{get_region()}:{get_account_id()}:scalingPolicy:{new_uuid()}:autoScalingGroupName/{asg_name}:policyName/{policy_name}"
+    key = f"{asg_name}/{policy_name}"
+    _policies[key] = {
+        "PolicyARN": arn,
+        "PolicyName": policy_name,
+        "AutoScalingGroupName": asg_name,
+        "PolicyType": _p(p, "PolicyType") or "SimpleScaling",
+        "AdjustmentType": _p(p, "AdjustmentType") or "ChangeInCapacity",
+        "ScalingAdjustment": int(_p(p, "ScalingAdjustment") or 0),
+        "Cooldown": int(_p(p, "Cooldown") or 300),
+    }
+    return _xml(200, "PutScalingPolicyResponse",
+                f"<PutScalingPolicyResult><PolicyARN>{arn}</PolicyARN></PutScalingPolicyResult>")
+
+
+def _describe_policies(p):
+    asg_name = _p(p, "AutoScalingGroupName")
+    members = ""
+    for key, pol in _policies.items():
+        if asg_name and pol["AutoScalingGroupName"] != asg_name:
+            continue
+        members += (f"<member>"
+                    f"<PolicyARN>{pol['PolicyARN']}</PolicyARN>"
+                    f"<PolicyName>{pol['PolicyName']}</PolicyName>"
+                    f"<AutoScalingGroupName>{pol['AutoScalingGroupName']}</AutoScalingGroupName>"
+                    f"<PolicyType>{pol['PolicyType']}</PolicyType>"
+                    f"<AdjustmentType>{pol.get('AdjustmentType', '')}</AdjustmentType>"
+                    f"<ScalingAdjustment>{pol.get('ScalingAdjustment', 0)}</ScalingAdjustment>"
+                    f"<Cooldown>{pol.get('Cooldown', 300)}</Cooldown>"
+                    f"</member>")
+    return _xml(200, "DescribePoliciesResponse",
+                f"<DescribePoliciesResult><ScalingPolicies>{members}</ScalingPolicies></DescribePoliciesResult>")
+
+
+def _delete_policy(p):
+    policy_name = _p(p, "PolicyName")
+    asg_name = _p(p, "AutoScalingGroupName")
+    key = f"{asg_name}/{policy_name}"
+    _policies.pop(key, None)
+    return _xml(200, "DeletePolicyResponse", "<DeletePolicyResult/>")
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle Hook
+# ---------------------------------------------------------------------------
+
+def _put_lifecycle_hook(p):
+    asg_name = _p(p, "AutoScalingGroupName")
+    hook_name = _p(p, "LifecycleHookName")
+    key = f"{asg_name}/{hook_name}"
+    _hooks[key] = {
+        "LifecycleHookName": hook_name,
+        "AutoScalingGroupName": asg_name,
+        "LifecycleTransition": _p(p, "LifecycleTransition") or "autoscaling:EC2_INSTANCE_LAUNCHING",
+        "HeartbeatTimeout": int(_p(p, "HeartbeatTimeout") or 3600),
+        "DefaultResult": _p(p, "DefaultResult") or "ABANDON",
+        "NotificationTargetARN": _p(p, "NotificationTargetARN") or "",
+        "RoleARN": _p(p, "RoleARN") or "",
+    }
+    return _xml(200, "PutLifecycleHookResponse", "<PutLifecycleHookResult/>")
+
+
+def _describe_lifecycle_hooks(p):
+    asg_name = _p(p, "AutoScalingGroupName")
+    members = ""
+    for key, hook in _hooks.items():
+        if hook["AutoScalingGroupName"] != asg_name:
+            continue
+        members += (f"<member>"
+                    f"<LifecycleHookName>{hook['LifecycleHookName']}</LifecycleHookName>"
+                    f"<AutoScalingGroupName>{hook['AutoScalingGroupName']}</AutoScalingGroupName>"
+                    f"<LifecycleTransition>{hook['LifecycleTransition']}</LifecycleTransition>"
+                    f"<HeartbeatTimeout>{hook['HeartbeatTimeout']}</HeartbeatTimeout>"
+                    f"<DefaultResult>{hook['DefaultResult']}</DefaultResult>"
+                    f"</member>")
+    return _xml(200, "DescribeLifecycleHooksResponse",
+                f"<DescribeLifecycleHooksResult><LifecycleHooks>{members}</LifecycleHooks></DescribeLifecycleHooksResult>")
+
+
+def _delete_lifecycle_hook(p):
+    asg_name = _p(p, "AutoScalingGroupName")
+    hook_name = _p(p, "LifecycleHookName")
+    _hooks.pop(f"{asg_name}/{hook_name}", None)
+    return _xml(200, "DeleteLifecycleHookResponse", "<DeleteLifecycleHookResult/>")
+
+
+def _complete_lifecycle_action(p):
+    return _xml(200, "CompleteLifecycleActionResponse", "<CompleteLifecycleActionResult/>")
+
+
+def _record_lifecycle_heartbeat(p):
+    return _xml(200, "RecordLifecycleActionHeartbeatResponse", "<RecordLifecycleActionHeartbeatResult/>")
+
+
+# ---------------------------------------------------------------------------
+# Scheduled Action
+# ---------------------------------------------------------------------------
+
+def _put_scheduled_action(p):
+    asg_name = _p(p, "AutoScalingGroupName")
+    action_name = _p(p, "ScheduledActionName")
+    key = f"{asg_name}/{action_name}"
+    arn = f"arn:aws:autoscaling:{get_region()}:{get_account_id()}:scheduledUpdateGroupAction:{new_uuid()}:autoScalingGroupName/{asg_name}:scheduledActionName/{action_name}"
+    _scheduled_actions[key] = {
+        "ScheduledActionARN": arn,
+        "ScheduledActionName": action_name,
+        "AutoScalingGroupName": asg_name,
+        "Recurrence": _p(p, "Recurrence") or "",
+        "MinSize": int(_p(p, "MinSize") or -1),
+        "MaxSize": int(_p(p, "MaxSize") or -1),
+        "DesiredCapacity": int(_p(p, "DesiredCapacity") or -1),
+    }
+    return _xml(200, "PutScheduledUpdateGroupActionResponse", "<PutScheduledUpdateGroupActionResult/>")
+
+
+def _describe_scheduled_actions(p):
+    asg_name = _p(p, "AutoScalingGroupName")
+    members = ""
+    for key, sa in _scheduled_actions.items():
+        if asg_name and sa["AutoScalingGroupName"] != asg_name:
+            continue
+        members += (f"<member>"
+                    f"<ScheduledActionARN>{sa['ScheduledActionARN']}</ScheduledActionARN>"
+                    f"<ScheduledActionName>{sa['ScheduledActionName']}</ScheduledActionName>"
+                    f"<AutoScalingGroupName>{sa['AutoScalingGroupName']}</AutoScalingGroupName>"
+                    f"</member>")
+    return _xml(200, "DescribeScheduledActionsResponse",
+                f"<DescribeScheduledActionsResult><ScheduledUpdateGroupActions>{members}</ScheduledUpdateGroupActions></DescribeScheduledActionsResult>")
+
+
+def _delete_scheduled_action(p):
+    asg_name = _p(p, "AutoScalingGroupName")
+    action_name = _p(p, "ScheduledActionName")
+    _scheduled_actions.pop(f"{asg_name}/{action_name}", None)
+    return _xml(200, "DeleteScheduledActionResponse", "<DeleteScheduledActionResult/>")
+
+
+# ---------------------------------------------------------------------------
+# Tags
+# ---------------------------------------------------------------------------
+
+def _create_or_update_tags(p):
+    i = 1
+    while _p(p, f"Tags.member.{i}.Key"):
+        asg_name = _p(p, f"Tags.member.{i}.ResourceId")
+        tag = {
+            "Key": _p(p, f"Tags.member.{i}.Key"),
+            "Value": _p(p, f"Tags.member.{i}.Value"),
+            "ResourceId": asg_name,
+            "ResourceType": "auto-scaling-group",
+            "PropagateAtLaunch": _p(p, f"Tags.member.{i}.PropagateAtLaunch") == "true",
+        }
+        existing = _tags.setdefault(asg_name, [])
+        existing = [t for t in existing if t["Key"] != tag["Key"]]
+        existing.append(tag)
+        _tags[asg_name] = existing
+        if asg_name in _asgs:
+            _asgs[asg_name]["Tags"] = existing
+        i += 1
+    return _xml(200, "CreateOrUpdateTagsResponse", "<CreateOrUpdateTagsResult/>")
+
+
+def _describe_tags(p):
+    members = ""
+    for asg_name, tag_list in _tags.items():
+        for t in tag_list:
+            members += (f"<member>"
+                        f"<Key>{t['Key']}</Key><Value>{t['Value']}</Value>"
+                        f"<ResourceId>{t['ResourceId']}</ResourceId>"
+                        f"<ResourceType>{t['ResourceType']}</ResourceType>"
+                        f"<PropagateAtLaunch>{'true' if t.get('PropagateAtLaunch') else 'false'}</PropagateAtLaunch>"
+                        f"</member>")
+    return _xml(200, "DescribeTagsResponse",
+                f"<DescribeTagsResult><Tags>{members}</Tags></DescribeTagsResult>")
+
+
+def _delete_tags(p):
+    i = 1
+    while _p(p, f"Tags.member.{i}.Key"):
+        asg_name = _p(p, f"Tags.member.{i}.ResourceId")
+        key = _p(p, f"Tags.member.{i}.Key")
+        existing = _tags.get(asg_name, [])
+        _tags[asg_name] = [t for t in existing if t["Key"] != key]
+        if asg_name in _asgs:
+            _asgs[asg_name]["Tags"] = _tags[asg_name]
+        i += 1
+    return _xml(200, "DeleteTagsResponse", "<DeleteTagsResult/>")
+
+
+# ---------------------------------------------------------------------------
+# Request handler
+# ---------------------------------------------------------------------------
+
+_ACTION_MAP = {
+    "CreateAutoScalingGroup": _create_asg,
+    "DescribeAutoScalingGroups": _describe_asgs,
+    "UpdateAutoScalingGroup": _update_asg,
+    "DeleteAutoScalingGroup": _delete_asg,
+    "DescribeAutoScalingInstances": _describe_asg_instances,
+    "DescribeScalingActivities": _describe_scaling_activities,
+    "CreateLaunchConfiguration": _create_lc,
+    "DescribeLaunchConfigurations": _describe_lcs,
+    "DeleteLaunchConfiguration": _delete_lc,
+    "PutScalingPolicy": _put_scaling_policy,
+    "DescribePolicies": _describe_policies,
+    "DeletePolicy": _delete_policy,
+    "PutLifecycleHook": _put_lifecycle_hook,
+    "DescribeLifecycleHooks": _describe_lifecycle_hooks,
+    "DeleteLifecycleHook": _delete_lifecycle_hook,
+    "CompleteLifecycleAction": _complete_lifecycle_action,
+    "RecordLifecycleActionHeartbeat": _record_lifecycle_heartbeat,
+    "PutScheduledUpdateGroupAction": _put_scheduled_action,
+    "DescribeScheduledActions": _describe_scheduled_actions,
+    "DeleteScheduledAction": _delete_scheduled_action,
+    "CreateOrUpdateTags": _create_or_update_tags,
+    "DescribeTags": _describe_tags,
+    "DeleteTags": _delete_tags,
+}
+
+
+async def handle_request(method, path, headers, body, query_params):
+    from urllib.parse import parse_qs
+    if body:
+        params = parse_qs(body.decode("utf-8", errors="replace"), keep_blank_values=True)
+        params = {k: v[0] if len(v) == 1 else v for k, v in params.items()}
+    else:
+        params = dict(query_params) if query_params else {}
+
+    action = params.get("Action", "")
+    if isinstance(action, list):
+        action = action[0]
+
+    handler = _ACTION_MAP.get(action)
+    if not handler:
+        s, h, b = _error("InvalidAction", f"Unknown AutoScaling action: {action}")
+        return s, h, b
+
+    s, h, b = handler(params)
+    return s, h, b
+
+def get_state_summary() -> dict:
+    return {
+        "asgs": {"count": len(_asgs), "names": list(_asgs.keys())},
+        "launch_configs": {"count": len(_launch_configs), "names": list(_launch_configs.keys())},
+        "policies": {"count": len(_policies), "names": list(_policies.keys())},
+        "hooks": {"count": len(_hooks), "names": list(_hooks.keys())},
+        "scheduled_actions": {"count": len(_scheduled_actions), "names": list(_scheduled_actions.keys())},
+    }

aws_infra/ministack/services/cloudformation/__init__.py

@@ -0,0 +1,109 @@
+"""
+CloudFormation Service Emulator -- AWS-compatible.
+Supports: CreateStack, UpdateStack, DeleteStack, DescribeStacks, ListStacks,
+          DescribeStackEvents, DescribeStackResource, DescribeStackResources,
+          ListStackResources, GetTemplate, ValidateTemplate, ListExports,
+          CreateChangeSet, DescribeChangeSet, ExecuteChangeSet,
+          DeleteChangeSet, ListChangeSets,
+          GetTemplateSummary.
+Uses Query API (Action=...) with form-encoded body.
+"""
+
+import json
+import logging
+import os
+from urllib.parse import parse_qs
+
+from ministack.core.responses import AccountScopedDict
+
+logger = logging.getLogger("cloudformation")
+
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+
+# In-memory state (shared across all submodules)
+_stacks = AccountScopedDict()          # stack_name -> stack dict
+_stack_events = AccountScopedDict()    # stack_id -> [event list]
+_exports = AccountScopedDict()         # export_name -> {StackId, Name, Value}
+_change_sets = AccountScopedDict()     # cs_id -> change set dict
+
+# Re-exports for compatibility
+from .engine import (  # noqa: E402
+    _parse_template,
+    _resolve_parameters,
+    _evaluate_conditions,
+    _resolve_refs,
+    _extract_deps,
+    _topological_sort,
+    _NO_VALUE,
+)
+
+from .helpers import _p  # noqa: E402
+
+
+async def handle_request(method: str, path: str, headers: dict,
+                         body: bytes, query_params: dict) -> tuple:
+    params = dict(query_params)
+    content_type = headers.get("content-type", "")
+    target = headers.get("x-amz-target", "")
+
+    # JSON protocol (newer SDKs): X-Amz-Target: CloudFormation_20100515.ActionName
+    if "amz-json" in content_type and target.startswith("CloudFormation_20100515."):
+        action_name = target.split(".")[-1]
+        params["Action"] = [action_name]
+        if body:
+            try:
+                json_body = json.loads(body)
+                for k, v in json_body.items():
+                    params[k] = [str(v)] if not isinstance(v, list) else v
+            except (json.JSONDecodeError, TypeError):
+                pass
+    elif method == "POST" and body:
+        form_params = parse_qs(body.decode("utf-8", errors="replace"))
+        for k, v in form_params.items():
+            params[k] = v
+
+    action = _p(params, "Action")
+    handler = _ACTION_HANDLERS.get(action)
+    if not handler:
+        from .helpers import _error
+        return _error("InvalidAction", f"Unknown action: {action}", 400)
+    return handler(params)
+
+
+# ---------------------------------------------------------------------------
+# Supported Actions
+# ---------------------------------------------------------------------------
+
+SUPPORTED_ACTIONS = [
+    "CreateStack", "UpdateStack", "DeleteStack", "DescribeStacks",
+    "ListStacks", "DescribeStackEvents", "DescribeStackResource",
+    "DescribeStackResources", "GetTemplate", "ValidateTemplate",
+    "ListExports", "CreateChangeSet", "DescribeChangeSet",
+    "ExecuteChangeSet", "DeleteChangeSet", "ListChangeSets",
+    "GetTemplateSummary",
+]
+
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+def get_state_summary() -> dict:
+    return {
+        "stacks": {"count": len(_stacks), "names": list(_stacks.keys())},
+        "change_sets": {"count": len(_change_sets), "ids": list(_change_sets.keys())},
+        "stack_events": {"count": len(_stack_events), "ids": list(_stack_events.keys())},
+        "exports": {"count": len(_exports), "names": list(_exports.keys())},
+    }
+
+
+def reset():
+    _stacks.clear()
+    _stack_events.clear()
+    _exports.clear()
+    _change_sets.clear()
+
+
+# Must be last — handlers imports from this module
+from .handlers import _ACTION_HANDLERS, _validate_template  # noqa: E402
+from ministack.core.responses import AccountScopedDict, get_account_id

aws_infra/ministack/services/cloudformation/changesets.py

@@ -0,0 +1,323 @@
+"""
+CloudFormation change set handlers — Create, Describe, Execute, Delete, List change sets.
+"""
+
+import asyncio
+import copy
+import json
+import logging
+
+from ministack.core.responses import get_account_id, new_uuid, now_iso
+
+from .engine import (
+    _evaluate_conditions, _parse_template, _resolve_parameters,
+    _resolve_refs, _NO_VALUE,
+)
+from .stacks import _add_event, _deploy_stack_async, _diff_resources
+from .provisioners import REGION
+from .helpers import _xml, _error, _p, _esc, _extract_members, _resolve_template, CFN_NS
+
+logger = logging.getLogger("cloudformation")
+
+
+def _find_change_set(cs_name, stack_name=""):
+    """Look up a change set by ID or by name+stack. Returns (cs_id, cs_dict) or (None, None)."""
+    from ministack.services.cloudformation import _change_sets
+    if cs_name in _change_sets:
+        return cs_name, _change_sets[cs_name]
+    for cid, c in _change_sets.items():
+        if c["ChangeSetName"] == cs_name:
+            if not stack_name or c["StackName"] == stack_name:
+                return cid, c
+    return None, None
+
+
+# --- CreateChangeSet ---
+
+def _create_change_set(params):
+    from ministack.services.cloudformation import _stacks, _stack_events, _change_sets
+    stack_name = _p(params, "StackName")
+    cs_name = _p(params, "ChangeSetName")
+    cs_type = _p(params, "ChangeSetType", "UPDATE")
+
+    if not stack_name:
+        return _error("ValidationError", "StackName is required")
+    if not cs_name:
+        return _error("ValidationError", "ChangeSetName is required")
+
+    template_body, resolve_err = _resolve_template(params)
+    if resolve_err:
+        return resolve_err
+
+    provided_params = _extract_members(params, "Parameters")
+    tags = _extract_members(params, "Tags")
+
+    stack = _stacks.get(stack_name)
+
+    if cs_type == "CREATE":
+        if stack and stack.get("StackStatus") not in (
+            "DELETE_COMPLETE", "ROLLBACK_COMPLETE", "REVIEW_IN_PROGRESS"
+        ):
+            return _error("AlreadyExistsException",
+                          f"Stack [{stack_name}] already exists")
+        if not template_body:
+            return _error("ValidationError", "TemplateBody or TemplateURL is required")
+
+        # Create a placeholder stack in REVIEW_IN_PROGRESS
+        stack_id = (
+            f"arn:aws:cloudformation:{REGION}:{get_account_id()}:"
+            f"stack/{stack_name}/{new_uuid()}"
+        )
+        stack = {
+            "StackName": stack_name,
+            "StackId": stack_id,
+            "StackStatus": "REVIEW_IN_PROGRESS",
+            "StackStatusReason": "",
+            "CreationTime": now_iso(),
+            "LastUpdatedTime": now_iso(),
+            "Description": "",
+            "Parameters": [],
+            "Tags": tags,
+            "Outputs": [],
+            "DisableRollback": False,
+            "_resources": {},
+            "_template": {},
+            "_template_body": "",
+            "_resolved_params": {},
+            "_conditions": {},
+        }
+        _stacks[stack_name] = stack
+        _stack_events[stack_id] = []
+    else:
+        if not stack:
+            return _error("ValidationError",
+                          f"Stack [{stack_name}] does not exist")
+        stack_id = stack["StackId"]
+        if not template_body:
+            template_body = stack.get("_template_body", "{}")
+
+    try:
+        template = _parse_template(template_body)
+    except Exception as e:
+        return _error("ValidationError", f"Template format error: {e}")
+
+    try:
+        param_values = _resolve_parameters(template, provided_params)
+    except ValueError as exc:
+        return _error("ValidationError", str(exc))
+
+    # Compute changes
+    old_template = stack.get("_template", {}) if cs_type == "UPDATE" else {}
+    changes = _diff_resources(old_template, template)
+
+    cs_id = (
+        f"arn:aws:cloudformation:{REGION}:{get_account_id()}:"
+        f"changeSet/{cs_name}/{new_uuid()}"
+    )
+
+    change_set = {
+        "ChangeSetId": cs_id,
+        "ChangeSetName": cs_name,
+        "StackId": stack_id,
+        "StackName": stack_name,
+        "Status": "CREATE_COMPLETE",
+        "ExecutionStatus": "AVAILABLE",
+        "CreationTime": now_iso(),
+        "Description": _p(params, "Description", ""),
+        "ChangeSetType": cs_type,
+        "Changes": changes,
+        "Parameters": [
+            {"ParameterKey": k, "ParameterValue": v["Value"]}
+            for k, v in param_values.items()
+        ],
+        "Tags": tags,
+        "_template": template,
+        "_template_body": template_body,
+        "_resolved_params": param_values,
+    }
+    _change_sets[cs_id] = change_set
+
+    return _xml(200, "CreateChangeSetResponse",
+                f"<CreateChangeSetResult>"
+                f"<Id>{cs_id}</Id>"
+                f"<StackId>{stack_id}</StackId>"
+                f"</CreateChangeSetResult>")
+
+
+# --- DescribeChangeSet ---
+
+def _describe_change_set(params):
+    cs_name = _p(params, "ChangeSetName")
+    stack_name = _p(params, "StackName")
+    _, cs = _find_change_set(cs_name, stack_name)
+    if not cs:
+        return _error("ChangeSetNotFoundException",
+                      f"ChangeSet [{cs_name}] does not exist")
+
+    params_xml = ""
+    for p in cs.get("Parameters", []):
+        params_xml += (
+            "<member>"
+            f"<ParameterKey>{_esc(p['ParameterKey'])}</ParameterKey>"
+            f"<ParameterValue>{_esc(str(p['ParameterValue']))}</ParameterValue>"
+            "</member>"
+        )
+
+    changes_xml = ""
+    for ch in cs.get("Changes", []):
+        rc = ch.get("ResourceChange", {})
+        changes_xml += (
+            "<member><ResourceChange>"
+            f"<Action>{rc.get('Action', '')}</Action>"
+            f"<LogicalResourceId>{_esc(rc.get('LogicalResourceId', ''))}</LogicalResourceId>"
+            f"<ResourceType>{_esc(rc.get('ResourceType', ''))}</ResourceType>"
+            f"<Replacement>{rc.get('Replacement', '')}</Replacement>"
+            "</ResourceChange></member>"
+        )
+
+    tags_xml = ""
+    for t in cs.get("Tags", []):
+        tags_xml += (
+            "<member>"
+            f"<Key>{_esc(t.get('Key', ''))}</Key>"
+            f"<Value>{_esc(t.get('Value', ''))}</Value>"
+            "</member>"
+        )
+
+    inner = (
+        f"<ChangeSetId>{_esc(cs['ChangeSetId'])}</ChangeSetId>"
+        f"<ChangeSetName>{_esc(cs['ChangeSetName'])}</ChangeSetName>"
+        f"<StackId>{_esc(cs['StackId'])}</StackId>"
+        f"<StackName>{_esc(cs['StackName'])}</StackName>"
+        f"<Status>{cs['Status']}</Status>"
+        f"<ExecutionStatus>{cs['ExecutionStatus']}</ExecutionStatus>"
+        f"<CreationTime>{cs['CreationTime']}</CreationTime>"
+        f"<Description>{_esc(cs.get('Description', ''))}</Description>"
+        f"<ChangeSetType>{cs.get('ChangeSetType', '')}</ChangeSetType>"
+        f"<Parameters>{params_xml}</Parameters>"
+        f"<Changes>{changes_xml}</Changes>"
+        f"<Tags>{tags_xml}</Tags>"
+    )
+
+    return _xml(200, "DescribeChangeSetResponse",
+                f"<DescribeChangeSetResult>{inner}</DescribeChangeSetResult>")
+
+
+# --- ExecuteChangeSet ---
+
+def _execute_change_set(params):
+    from ministack.services.cloudformation import _stacks
+    cs_name = _p(params, "ChangeSetName")
+    stack_name = _p(params, "StackName")
+    _, cs = _find_change_set(cs_name, stack_name)
+    if not cs:
+        return _error("ChangeSetNotFoundException",
+                      f"ChangeSet [{cs_name}] does not exist")
+
+    if cs["ExecutionStatus"] != "AVAILABLE":
+        return _error("InvalidChangeSetStatusException",
+                      f"ChangeSet [{cs_name}] is in {cs['ExecutionStatus']} status")
+
+    cs["ExecutionStatus"] = "EXECUTE_IN_PROGRESS"
+    real_stack_name = cs["StackName"]
+    stack = _stacks.get(real_stack_name)
+    if not stack:
+        return _error("ValidationError",
+                      f"Stack [{real_stack_name}] does not exist")
+
+    stack_id = stack["StackId"]
+    template = cs["_template"]
+    template_body = cs["_template_body"]
+    param_values = cs["_resolved_params"]
+    tags = cs.get("Tags", [])
+    cs_type = cs.get("ChangeSetType", "UPDATE")
+    is_update = cs_type == "UPDATE"
+
+    if is_update:
+        previous_stack = {
+            "_resources": copy.deepcopy(stack.get("_resources", {})),
+            "_template": copy.deepcopy(stack.get("_template", {})),
+            "_template_body": stack.get("_template_body", ""),
+            "_resolved_params": copy.deepcopy(stack.get("_resolved_params", {})),
+            "Outputs": copy.deepcopy(stack.get("Outputs", [])),
+        }
+    else:
+        previous_stack = None
+
+    status_prefix = "UPDATE" if is_update else "CREATE"
+    stack["StackStatus"] = f"{status_prefix}_IN_PROGRESS"
+    stack["LastUpdatedTime"] = now_iso()
+    stack["_template_body"] = template_body
+    if tags:
+        stack["Tags"] = tags
+    stack["Parameters"] = [
+        {"ParameterKey": k, "ParameterValue": v["Value"], "NoEcho": v["NoEcho"]}
+        for k, v in param_values.items()
+    ]
+    stack["_conditions"] = _evaluate_conditions(template, param_values)
+
+    _add_event(stack_id, real_stack_name, real_stack_name,
+               "AWS::CloudFormation::Stack", f"{status_prefix}_IN_PROGRESS",
+               physical_id=stack_id)
+
+    asyncio.get_event_loop().create_task(
+        _deploy_stack_async(real_stack_name, stack_id, template,
+                            param_values, False, tags,
+                            is_update=is_update,
+                            previous_stack=previous_stack)
+    )
+
+    cs["ExecutionStatus"] = "EXECUTE_COMPLETE"
+    cs["Status"] = "EXECUTE_COMPLETE"
+
+    return _xml(200, "ExecuteChangeSetResponse",
+                "<ExecuteChangeSetResult></ExecuteChangeSetResult>")
+
+
+# --- DeleteChangeSet ---
+
+def _delete_change_set(params):
+    from ministack.services.cloudformation import _change_sets
+    cs_name = _p(params, "ChangeSetName")
+    stack_name = _p(params, "StackName")
+    cs_id, cs = _find_change_set(cs_name, stack_name)
+    if not cs_id:
+        return _error("ChangeSetNotFoundException",
+                      f"ChangeSet [{cs_name}] does not exist")
+    _change_sets.pop(cs_id, None)
+    return _xml(200, "DeleteChangeSetResponse", "")
+
+
+# --- ListChangeSets ---
+
+def _list_change_sets(params):
+    from ministack.services.cloudformation import _stacks, _change_sets
+    stack_name = _p(params, "StackName")
+    if not stack_name:
+        return _error("ValidationError", "StackName is required")
+
+    members = ""
+    for cs in _change_sets.values():
+        if cs["StackName"] != stack_name:
+            continue
+        members += (
+            "<member>"
+            f"<ChangeSetId>{_esc(cs['ChangeSetId'])}</ChangeSetId>"
+            f"<ChangeSetName>{_esc(cs['ChangeSetName'])}</ChangeSetName>"
+            f"<StackId>{_esc(cs['StackId'])}</StackId>"
+            f"<StackName>{_esc(cs['StackName'])}</StackName>"
+            f"<Status>{cs['Status']}</Status>"
+            f"<ExecutionStatus>{cs['ExecutionStatus']}</ExecutionStatus>"
+            f"<CreationTime>{cs['CreationTime']}</CreationTime>"
+            f"<Description>{_esc(cs.get('Description', ''))}</Description>"
+            "</member>"
+        )
+
+    return _xml(200, "ListChangeSetsResponse",
+                f"<ListChangeSetsResult>"
+                f"<Summaries>{members}</Summaries>"
+                f"</ListChangeSetsResult>")
+
+
+# --- GetTemplateSummary ---
+

aws_infra/ministack/services/cloudformation/engine.py

@@ -0,0 +1,545 @@
+"""
+CloudFormation engine — pure functions for template parsing, parameter resolution,
+condition evaluation, intrinsic function resolution, and topological sorting.
+"""
+
+import base64
+import os
+import heapq
+import json
+import re
+from collections import defaultdict
+
+import yaml
+
+from ministack.core.responses import get_account_id, get_region, new_uuid
+
+# Sentinel for AWS::NoValue
+_NO_VALUE = object()
+
+# REGION kept for backwards compat with old imports; new code must prefer
+# get_region() so AWS::Region reflects the caller's request region (#398).
+REGION = os.environ.get("MINISTACK_REGION", "us-east-1")
+
+
+# ===========================================================================
+# YAML Parser -- CloudFormation tag support
+# ===========================================================================
+
+class CfnLoader(yaml.SafeLoader):
+    """YAML loader that handles CloudFormation intrinsic function tags."""
+    pass
+
+
+def _construct_cfn_tag(tag_name):
+    """Build a constructor that wraps the value in {tag_name: value}."""
+    def constructor(loader, node):
+        if isinstance(node, yaml.ScalarNode):
+            val = loader.construct_scalar(node)
+        elif isinstance(node, yaml.SequenceNode):
+            val = loader.construct_sequence(node, deep=True)
+        elif isinstance(node, yaml.MappingNode):
+            val = loader.construct_mapping(node, deep=True)
+        else:
+            val = loader.construct_scalar(node)
+        return {tag_name: val}
+    return constructor
+
+
+def _construct_getatt(loader, node):
+    """!GetAtt -- scalar 'A.B' splits on first dot; sequence passes through."""
+    if isinstance(node, yaml.ScalarNode):
+        val = loader.construct_scalar(node)
+        parts = val.split(".", 1)
+        if len(parts) == 2:
+            return {"Fn::GetAtt": [parts[0], parts[1]]}
+        return {"Fn::GetAtt": [val, ""]}
+    if isinstance(node, yaml.SequenceNode):
+        val = loader.construct_sequence(node, deep=True)
+        return {"Fn::GetAtt": val}
+    val = loader.construct_scalar(node)
+    return {"Fn::GetAtt": [val, ""]}
+
+
+def _construct_timestamp(loader, node):
+    """Override timestamp to preserve date strings as plain strings."""
+    return loader.construct_scalar(node)
+
+
+# Register all CFN tags
+_SIMPLE_TAGS = {
+    "!Ref": "Ref",
+    "!Sub": "Fn::Sub",
+    "!Join": "Fn::Join",
+    "!Split": "Fn::Split",
+    "!Select": "Fn::Select",
+    "!If": "Fn::If",
+    "!Equals": "Fn::Equals",
+    "!And": "Fn::And",
+    "!Or": "Fn::Or",
+    "!Not": "Fn::Not",
+    "!Base64": "Fn::Base64",
+    "!FindInMap": "Fn::FindInMap",
+    "!ImportValue": "Fn::ImportValue",
+    "!GetAZs": "Fn::GetAZs",
+    "!Condition": "Condition",
+    "!Cidr": "Fn::Cidr",
+}
+
+for _tag, _fn_name in _SIMPLE_TAGS.items():
+    CfnLoader.add_constructor(_tag, _construct_cfn_tag(_fn_name))
+
+CfnLoader.add_constructor("!GetAtt", _construct_getatt)
+# Preserve date strings -- override the implicit timestamp resolver
+CfnLoader.add_constructor("tag:yaml.org,2002:timestamp", _construct_timestamp)
+
+
+def _parse_template(template_body: str) -> dict:
+    """Parse a CFN template from JSON or YAML."""
+    template_body = template_body.strip()
+    if template_body.startswith("{"):
+        result = json.loads(template_body)
+    else:
+        result = yaml.load(template_body, Loader=CfnLoader)
+    if not isinstance(result, dict):
+        raise ValueError("Template must be a JSON or YAML mapping")
+    return result
+
+
+# ===========================================================================
+# Parameter Resolver
+# ===========================================================================
+
+_AWS_SPECIFIC_TYPES = {
+    "AWS::SSM::Parameter::Type",
+    "AWS::SSM::Parameter::Value<String>",
+    "AWS::SSM::Parameter::Value<List<String>>",
+    "AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>",
+    "AWS::EC2::AvailabilityZone::Name",
+    "AWS::EC2::Image::Id",
+    "AWS::EC2::Instance::Id",
+    "AWS::EC2::KeyPair::KeyName",
+    "AWS::EC2::SecurityGroup::GroupName",
+    "AWS::EC2::SecurityGroup::Id",
+    "AWS::EC2::Subnet::Id",
+    "AWS::EC2::Volume::Id",
+    "AWS::EC2::VPC::Id",
+    "AWS::Route53::HostedZone::Id",
+}
+
+
+def _resolve_parameters(template: dict, provided_params: list[dict]) -> dict:
+    """Resolve template parameters with provided values and defaults.
+
+    Returns dict of param_name -> {Value, NoEcho}.
+    """
+    param_defs = template.get("Parameters", {})
+    provided_map = {p["Key"]: p["Value"] for p in provided_params if "Key" in p}
+    resolved = {}
+
+    for name, defn in param_defs.items():
+        ptype = defn.get("Type", "String")
+        no_echo = str(defn.get("NoEcho", "false")).lower() == "true"
+
+        if name in provided_map:
+            value = provided_map[name]
+        elif "Default" in defn:
+            value = defn["Default"]
+        else:
+            raise ValueError(f"Parameter '{name}' has no Default and was not provided")
+
+        value = str(value) if value is not None else ""
+
+        # Validate AllowedValues
+        allowed = defn.get("AllowedValues")
+        if allowed and value not in [str(a) for a in allowed]:
+            raise ValueError(
+                f"Parameter '{name}' value '{value}' is not in AllowedValues: {allowed}"
+            )
+
+        # Type coercion
+        if ptype == "Number":
+            # Validate it's numeric but keep as string for consistency
+            try:
+                float(value)
+            except ValueError:
+                raise ValueError(f"Parameter '{name}' value '{value}' is not a valid Number")
+        elif ptype == "CommaDelimitedList":
+            # Keep as string; Fn::Select will split
+            pass
+        # AWS-specific types treated as String -- no extra validation
+
+        resolved[name] = {"Value": value, "NoEcho": no_echo}
+
+    return resolved
+
+
+# ===========================================================================
+# Condition Evaluator
+# ===========================================================================
+
+def _evaluate_conditions(template: dict, params: dict) -> dict:
+    """Evaluate all conditions in the template. Returns {name: bool}."""
+    cond_defs = template.get("Conditions", {})
+    evaluated: dict[str, bool] = {}
+
+    def _eval(expr):
+        if isinstance(expr, dict):
+            if "Fn::Equals" in expr:
+                args = expr["Fn::Equals"]
+                left = _resolve_cond_value(args[0])
+                right = _resolve_cond_value(args[1])
+                return str(left) == str(right)
+            if "Fn::And" in expr:
+                return all(_eval(c) for c in expr["Fn::And"])
+            if "Fn::Or" in expr:
+                return any(_eval(c) for c in expr["Fn::Or"])
+            if "Fn::Not" in expr:
+                return not _eval(expr["Fn::Not"][0])
+            if "Condition" in expr:
+                cname = expr["Condition"]
+                if cname not in evaluated:
+                    evaluated[cname] = _eval(cond_defs[cname])
+                return evaluated[cname]
+            if "Ref" in expr:
+                return _resolve_cond_value(expr)
+        return bool(expr)
+
+    def _resolve_cond_value(val):
+        if isinstance(val, dict):
+            if "Ref" in val:
+                pname = val["Ref"]
+                if pname in params:
+                    return params[pname]["Value"]
+                return pname
+            if "Fn::Equals" in val:
+                return _eval(val)
+            if "Condition" in val:
+                return _eval(val)
+        return val
+
+    for name, defn in cond_defs.items():
+        if name not in evaluated:
+            evaluated[name] = _eval(defn)
+
+    return evaluated
+
+
+# ===========================================================================
+# Intrinsic Function Resolver
+# ===========================================================================
+
+def _resolve_refs(value, resources, params, conditions, mappings,
+                  stack_name, stack_id):
+    """Recursively resolve CloudFormation intrinsic functions."""
+    if isinstance(value, str):
+        return value
+
+    if isinstance(value, list):
+        resolved = [
+            _resolve_refs(item, resources, params, conditions, mappings,
+                          stack_name, stack_id)
+            for item in value
+        ]
+        return [r for r in resolved if r is not _NO_VALUE]
+
+    if not isinstance(value, dict):
+        return value
+
+    # --- Ref ---
+    if "Ref" in value:
+        ref = value["Ref"]
+        # Pseudo-parameters
+        pseudo = {
+            "AWS::StackName": stack_name,
+            "AWS::StackId": stack_id,
+            "AWS::Region": get_region(),
+            "AWS::AccountId": get_account_id(),
+            "AWS::NoValue": _NO_VALUE,
+            "AWS::URLSuffix": "amazonaws.com",
+            "AWS::Partition": "aws",
+            "AWS::NotificationARNs": [],
+        }
+        if ref in pseudo:
+            return pseudo[ref]
+        if ref in params:
+            return params[ref]["Value"]
+        # Resource physical ID
+        if ref in resources and "PhysicalResourceId" in resources[ref]:
+            return resources[ref]["PhysicalResourceId"]
+        return ref
+
+    # --- Fn::GetAtt ---
+    if "Fn::GetAtt" in value:
+        args = value["Fn::GetAtt"]
+        if isinstance(args, str):
+            parts = args.split(".", 1)
+            logical_id = parts[0]
+            attr = parts[1] if len(parts) > 1 else ""
+        else:
+            logical_id = args[0]
+            attr = args[1] if len(args) > 1 else ""
+        res = resources.get(logical_id, {})
+        attrs = res.get("Attributes", {})
+        if attr in attrs:
+            return attrs[attr]
+        # Fallback: try PhysicalResourceId
+        return res.get("PhysicalResourceId", "")
+
+    # --- Fn::Join ---
+    if "Fn::Join" in value:
+        args = value["Fn::Join"]
+        delimiter = args[0]
+        items = _resolve_refs(args[1], resources, params, conditions,
+                              mappings, stack_name, stack_id)
+        return delimiter.join(str(i) for i in items if i is not _NO_VALUE)
+
+    # --- Fn::Sub ---
+    if "Fn::Sub" in value:
+        sub_val = value["Fn::Sub"]
+        if isinstance(sub_val, list):
+            template_str = sub_val[0]
+            var_map = sub_val[1] if len(sub_val) > 1 else {}
+            # Resolve values in the var_map first
+            resolved_map = {}
+            for k, v in var_map.items():
+                resolved_map[k] = _resolve_refs(v, resources, params,
+                                                conditions, mappings,
+                                                stack_name, stack_id)
+        else:
+            template_str = sub_val
+            resolved_map = {}
+
+        def _sub_replace(match):
+            var = match.group(1)
+            # Check explicit var map first
+            if var in resolved_map:
+                return str(resolved_map[var])
+            # Pseudo-params
+            pseudo = {
+                "AWS::StackName": stack_name,
+                "AWS::StackId": stack_id,
+                "AWS::Region": get_region(),
+                "AWS::AccountId": get_account_id(),
+                "AWS::URLSuffix": "amazonaws.com",
+                "AWS::Partition": "aws",
+            }
+            if var in pseudo:
+                return str(pseudo[var])
+            # Param
+            if var in params:
+                return str(params[var]["Value"])
+            # Resource.Attr
+            if "." in var:
+                parts = var.split(".", 1)
+                res = resources.get(parts[0], {})
+                attrs = res.get("Attributes", {})
+                if parts[1] in attrs:
+                    return str(attrs[parts[1]])
+                return str(res.get("PhysicalResourceId", var))
+            # Resource physical ID
+            if var in resources and "PhysicalResourceId" in resources[var]:
+                return str(resources[var]["PhysicalResourceId"])
+            return var
+
+        return re.sub(r"\$\{([^}]+)\}", _sub_replace, str(template_str))
+
+    # --- Fn::Select ---
+    if "Fn::Select" in value:
+        args = value["Fn::Select"]
+        index = int(_resolve_refs(args[0], resources, params, conditions,
+                                  mappings, stack_name, stack_id))
+        items = _resolve_refs(args[1], resources, params, conditions,
+                              mappings, stack_name, stack_id)
+        if isinstance(items, str):
+            items = [s.strip() for s in items.split(",")]
+        if 0 <= index < len(items):
+            return items[index]
+        return ""
+
+    # --- Fn::Split ---
+    if "Fn::Split" in value:
+        args = value["Fn::Split"]
+        delimiter = args[0]
+        source = _resolve_refs(args[1], resources, params, conditions,
+                               mappings, stack_name, stack_id)
+        return str(source).split(delimiter)
+
+    # --- Fn::If ---
+    if "Fn::If" in value:
+        args = value["Fn::If"]
+        cond_name = args[0]
+        cond_val = conditions.get(cond_name, False)
+        branch = args[1] if cond_val else args[2]
+        result = _resolve_refs(branch, resources, params, conditions,
+                               mappings, stack_name, stack_id)
+        return result
+
+    # --- Fn::Base64 ---
+    if "Fn::Base64" in value:
+        inner = _resolve_refs(value["Fn::Base64"], resources, params,
+                              conditions, mappings, stack_name, stack_id)
+        return base64.b64encode(str(inner).encode("utf-8")).decode("utf-8")
+
+    # --- Fn::FindInMap ---
+    if "Fn::FindInMap" in value:
+        args = value["Fn::FindInMap"]
+        map_name = _resolve_refs(args[0], resources, params, conditions,
+                                 mappings, stack_name, stack_id)
+        key1 = _resolve_refs(args[1], resources, params, conditions,
+                             mappings, stack_name, stack_id)
+        key2 = _resolve_refs(args[2], resources, params, conditions,
+                             mappings, stack_name, stack_id)
+        return mappings.get(str(map_name), {}).get(str(key1), {}).get(str(key2), "")
+
+    # --- Fn::ImportValue ---
+    if "Fn::ImportValue" in value:
+        from ministack.services.cloudformation import _exports
+        export_name = _resolve_refs(value["Fn::ImportValue"], resources,
+                                    params, conditions, mappings,
+                                    stack_name, stack_id)
+        export = _exports.get(str(export_name))
+        if export:
+            return export["Value"]
+        raise ValueError(f"Export '{export_name}' not found")
+
+    # --- Fn::GetAZs ---
+    if "Fn::GetAZs" in value:
+        region = _resolve_refs(value["Fn::GetAZs"], resources, params,
+                               conditions, mappings, stack_name, stack_id)
+        if not region:
+            region = get_region()
+        return [f"{region}a", f"{region}b", f"{region}c"]
+
+    # --- Fn::Cidr ---
+    if "Fn::Cidr" in value:
+        args = value["Fn::Cidr"]
+        ip_block = _resolve_refs(args[0], resources, params, conditions,
+                                 mappings, stack_name, stack_id)
+        count = int(_resolve_refs(args[1], resources, params, conditions,
+                                  mappings, stack_name, stack_id))
+        cidr_bits = int(_resolve_refs(args[2], resources, params, conditions,
+                                      mappings, stack_name, stack_id))
+        # Simplified CIDR generation
+        return [f"10.0.{i}.0/{32 - cidr_bits}" for i in range(count)]
+
+    # --- Fn::Equals (condition-like in non-condition context) ---
+    if "Fn::Equals" in value:
+        args = value["Fn::Equals"]
+        left = _resolve_refs(args[0], resources, params, conditions,
+                             mappings, stack_name, stack_id)
+        right = _resolve_refs(args[1], resources, params, conditions,
+                              mappings, stack_name, stack_id)
+        return str(left) == str(right)
+
+    # --- Condition (reference) ---
+    if "Condition" in value and len(value) == 1:
+        return conditions.get(value["Condition"], False)
+
+    # Recurse into plain dicts
+    result = {}
+    for k, v in value.items():
+        resolved = _resolve_refs(v, resources, params, conditions,
+                                 mappings, stack_name, stack_id)
+        if resolved is not _NO_VALUE:
+            result[k] = resolved
+    return result
+
+
+# ===========================================================================
+# Dependency Extractor + Topological Sort
+# ===========================================================================
+
+def _extract_deps(resource_def: dict, all_resource_names: set) -> set:
+    """Walk a resource definition and extract dependency logical IDs."""
+    deps = set()
+
+    def _walk(obj):
+        if isinstance(obj, dict):
+            if "Ref" in obj:
+                ref = obj["Ref"]
+                if ref in all_resource_names:
+                    deps.add(ref)
+            if "Fn::GetAtt" in obj:
+                args = obj["Fn::GetAtt"]
+                if isinstance(args, list) and args:
+                    if args[0] in all_resource_names:
+                        deps.add(args[0])
+                elif isinstance(args, str):
+                    logical = args.split(".")[0]
+                    if logical in all_resource_names:
+                        deps.add(logical)
+            if "Fn::Sub" in obj:
+                sub_val = obj["Fn::Sub"]
+                template_str = sub_val[0] if isinstance(sub_val, list) else sub_val
+                for match in re.finditer(r"\$\{([^}]+)\}", str(template_str)):
+                    var = match.group(1)
+                    base = var.split(".")[0]
+                    if base in all_resource_names:
+                        deps.add(base)
+            # Walk ALL branches of Fn::If
+            if "Fn::If" in obj:
+                args = obj["Fn::If"]
+                for branch in args[1:]:
+                    _walk(branch)
+            for k, v in obj.items():
+                if k not in ("Ref", "Fn::GetAtt", "Fn::Sub", "Fn::If"):
+                    _walk(v)
+        elif isinstance(obj, list):
+            for item in obj:
+                _walk(item)
+
+    # DependsOn
+    depends_on = resource_def.get("DependsOn", [])
+    if isinstance(depends_on, str):
+        depends_on = [depends_on]
+    for d in depends_on:
+        if d in all_resource_names:
+            deps.add(d)
+
+    # Walk Properties
+    _walk(resource_def.get("Properties", {}))
+
+    return deps
+
+
+def _topological_sort(resources: dict, conditions: dict) -> list:
+    """Kahn's algorithm for topological sort of resources."""
+    all_names = set(resources.keys())
+    # Filter out resources whose condition evaluates to false
+    active = set()
+    for name, defn in resources.items():
+        cond = defn.get("Condition")
+        if cond and not conditions.get(cond, True):
+            continue
+        active.add(name)
+
+    in_degree = {name: 0 for name in active}
+    adj: dict[str, list[str]] = {name: [] for name in active}
+
+    for name in active:
+        deps = _extract_deps(resources[name], active)
+        for dep in deps:
+            if dep in active and dep != name:
+                adj[dep].append(name)
+                in_degree[name] += 1
+
+    queue = sorted(n for n in active if in_degree[n] == 0)
+    heapq.heapify(queue)
+    result = []
+
+    while queue:
+        node = heapq.heappop(queue)
+        result.append(node)
+        for neighbor in adj[node]:
+            in_degree[neighbor] -= 1
+            if in_degree[neighbor] == 0:
+                heapq.heappush(queue, neighbor)
+
+    if len(result) != len(active):
+        remaining = active - set(result)
+        raise ValueError(
+            f"Circular dependency detected among resources: {', '.join(sorted(remaining))}"
+        )
+
+    return result

aws_infra/ministack/services/cloudformation/handlers.py

@@ -0,0 +1,646 @@
+"""
+CloudFormation handlers — API action handlers for all supported CloudFormation actions.
+"""
+
+import asyncio
+import copy
+import json
+import logging
+
+from ministack.core.responses import get_account_id, new_uuid, now_iso
+
+from .engine import (
+    _evaluate_conditions, _parse_template, _resolve_parameters,
+    _resolve_refs, _NO_VALUE,
+)
+from .stacks import _add_event, _deploy_stack_async, _delete_stack_async, _diff_resources
+from .provisioners import _provision_resource
+from ministack.core.responses import get_region
+from .helpers import _xml, _error, _p, _esc, _extract_members, _extract_stack_status_filters, _resolve_template, CFN_NS
+from .changesets import (
+    _create_change_set, _describe_change_set, _execute_change_set,
+    _delete_change_set, _list_change_sets,
+)
+
+logger = logging.getLogger("cloudformation")
+
+
+# --- CreateStack ---
+
+def _create_stack(params):
+    from ministack.services.cloudformation import _stacks, _stack_events, _exports, _change_sets
+    stack_name = _p(params, "StackName")
+    if not stack_name:
+        return _error("ValidationError", "StackName is required")
+
+    template_body, resolve_err = _resolve_template(params)
+    if resolve_err:
+        return resolve_err
+    if not template_body:
+        return _error("ValidationError", "TemplateBody or TemplateURL is required")
+
+    # Check stack name uniqueness (active stacks)
+    existing = _stacks.get(stack_name)
+    if existing and existing.get("StackStatus", "") not in (
+        "DELETE_COMPLETE", "ROLLBACK_COMPLETE"
+    ):
+        return _error("AlreadyExistsException",
+                      f"Stack [{stack_name}] already exists")
+
+    try:
+        template = _parse_template(template_body)
+    except Exception as e:
+        return _error("ValidationError", f"Template format error: {e}")
+    provided_params = _extract_members(params, "Parameters")
+    tags = _extract_members(params, "Tags")
+    disable_rollback = _p(params, "DisableRollback", "false").lower() == "true"
+
+    # Resolve parameters
+    try:
+        param_values = _resolve_parameters(template, provided_params)
+    except ValueError as exc:
+        return _error("ValidationError", str(exc))
+
+    stack_id = (
+        f"arn:aws:cloudformation:{get_region()}:{get_account_id()}:"
+        f"stack/{stack_name}/{new_uuid()}"
+    )
+
+    stack = {
+        "StackName": stack_name,
+        "StackId": stack_id,
+        "StackStatus": "CREATE_IN_PROGRESS",
+        "StackStatusReason": "",
+        "CreationTime": now_iso(),
+        "LastUpdatedTime": now_iso(),
+        "Description": template.get("Description", ""),
+        "Parameters": [
+            {
+                "ParameterKey": k,
+                "ParameterValue": v["Value"],
+                "NoEcho": v["NoEcho"],
+            }
+            for k, v in param_values.items()
+        ],
+        "Tags": tags,
+        "Outputs": [],
+        "DisableRollback": disable_rollback,
+        "_resources": {},
+        "_template": template,
+        "_template_body": template_body,
+        "_resolved_params": param_values,
+        "_conditions": _evaluate_conditions(template, param_values),
+    }
+    _stacks[stack_name] = stack
+    _stack_events[stack_id] = []
+
+    _add_event(stack_id, stack_name, stack_name,
+               "AWS::CloudFormation::Stack", "CREATE_IN_PROGRESS",
+               physical_id=stack_id)
+
+    asyncio.get_event_loop().create_task(
+        _deploy_stack_async(stack_name, stack_id, template,
+                            param_values, disable_rollback, tags)
+    )
+
+    return _xml(200, "CreateStackResponse",
+                f"<CreateStackResult><StackId>{stack_id}</StackId></CreateStackResult>")
+
+
+# --- DescribeStacks ---
+
+def _describe_stacks(params):
+    from ministack.services.cloudformation import _stacks
+    stack_name = _p(params, "StackName")
+
+    if stack_name:
+        stack = _stacks.get(stack_name)
+        # Also try matching by stack ID
+        if not stack:
+            for s in _stacks.values():
+                if s.get("StackId") == stack_name:
+                    stack = s
+                    break
+        if not stack:
+            return _error("ValidationError",
+                          f"Stack with id {stack_name} does not exist")
+        stacks_to_describe = [stack]
+    else:
+        # Return all stacks except DELETE_COMPLETE
+        stacks_to_describe = [
+            s for s in _stacks.values()
+            if s.get("StackStatus") != "DELETE_COMPLETE"
+        ]
+
+    members = ""
+    for s in stacks_to_describe:
+        params_xml = ""
+        for p in s.get("Parameters", []):
+            val = "****" if p.get("NoEcho") else _esc(str(p.get("ParameterValue", "")))
+            params_xml += (
+                "<member>"
+                f"<ParameterKey>{_esc(p['ParameterKey'])}</ParameterKey>"
+                f"<ParameterValue>{val}</ParameterValue>"
+                "</member>"
+            )
+
+        outputs_xml = ""
+        for o in s.get("Outputs", []):
+            export_xml = ""
+            if o.get("ExportName"):
+                export_xml = f"<ExportName>{_esc(o['ExportName'])}</ExportName>"
+            outputs_xml += (
+                "<member>"
+                f"<OutputKey>{_esc(o['OutputKey'])}</OutputKey>"
+                f"<OutputValue>{_esc(str(o['OutputValue']))}</OutputValue>"
+                f"<Description>{_esc(o.get('Description', ''))}</Description>"
+                f"{export_xml}"
+                "</member>"
+            )
+
+        tags_xml = ""
+        for t in s.get("Tags", []):
+            tags_xml += (
+                "<member>"
+                f"<Key>{_esc(t.get('Key', ''))}</Key>"
+                f"<Value>{_esc(t.get('Value', ''))}</Value>"
+                "</member>"
+            )
+
+        members += (
+            "<member>"
+            f"<StackName>{_esc(s['StackName'])}</StackName>"
+            f"<StackId>{_esc(s['StackId'])}</StackId>"
+            f"<StackStatus>{s['StackStatus']}</StackStatus>"
+            f"<StackStatusReason>{_esc(s.get('StackStatusReason', ''))}</StackStatusReason>"
+            f"<CreationTime>{s.get('CreationTime', '')}</CreationTime>"
+            f"<LastUpdatedTime>{s.get('LastUpdatedTime', '')}</LastUpdatedTime>"
+            f"<Description>{_esc(s.get('Description', ''))}</Description>"
+            f"<DisableRollback>{str(s.get('DisableRollback', False)).lower()}</DisableRollback>"
+            f"<Parameters>{params_xml}</Parameters>"
+            f"<Outputs>{outputs_xml}</Outputs>"
+            f"<Tags>{tags_xml}</Tags>"
+            "</member>"
+        )
+
+    return _xml(200, "DescribeStacksResponse",
+                f"<DescribeStacksResult><Stacks>{members}</Stacks></DescribeStacksResult>")
+
+
+# --- ListStacks ---
+
+def _list_stacks(params):
+    from ministack.services.cloudformation import _stacks
+    status_filters = _extract_stack_status_filters(params)
+
+    summaries = ""
+    for s in _stacks.values():
+        status = s.get("StackStatus", "")
+        if status_filters and status not in status_filters:
+            continue
+        entry = (
+            "<member>"
+            f"<StackName>{_esc(s['StackName'])}</StackName>"
+            f"<StackId>{_esc(s['StackId'])}</StackId>"
+            f"<StackStatus>{status}</StackStatus>"
+            f"<CreationTime>{s.get('CreationTime', '')}</CreationTime>"
+        )
+        if s.get("LastUpdatedTime"):
+            entry += f"<LastUpdatedTime>{s['LastUpdatedTime']}</LastUpdatedTime>"
+        if s.get("StackStatusReason"):
+            entry += f"<StackStatusReason>{_esc(s['StackStatusReason'])}</StackStatusReason>"
+        if s.get("DeletionTime"):
+            entry += f"<DeletionTime>{s['DeletionTime']}</DeletionTime>"
+        entry += "</member>"
+        summaries += entry
+
+    return _xml(200, "ListStacksResponse",
+                f"<ListStacksResult><StackSummaries>{summaries}</StackSummaries></ListStacksResult>")
+
+
+# --- DescribeStackEvents ---
+
+def _describe_stack_events(params):
+    from ministack.services.cloudformation import _stacks, _stack_events
+    stack_name = _p(params, "StackName")
+    if not stack_name:
+        return _error("ValidationError", "StackName is required")
+
+    stack = _stacks.get(stack_name)
+    if not stack:
+        # Try by stack ID
+        for s in _stacks.values():
+            if s.get("StackId") == stack_name:
+                stack = s
+                break
+    if not stack:
+        return _error("ValidationError",
+                      f"Stack [{stack_name}] does not exist")
+
+    stack_id = stack["StackId"]
+    events = _stack_events.get(stack_id, [])
+    # Newest first
+    events_sorted = sorted(events, key=lambda e: e.get("Timestamp", ""),
+                           reverse=True)
+
+    members = ""
+    for e in events_sorted:
+        members += (
+            "<member>"
+            f"<StackId>{_esc(e.get('StackId', ''))}</StackId>"
+            f"<StackName>{_esc(e.get('StackName', ''))}</StackName>"
+            f"<EventId>{_esc(e.get('EventId', ''))}</EventId>"
+            f"<LogicalResourceId>{_esc(e.get('LogicalResourceId', ''))}</LogicalResourceId>"
+            f"<PhysicalResourceId>{_esc(e.get('PhysicalResourceId', ''))}</PhysicalResourceId>"
+            f"<ResourceType>{_esc(e.get('ResourceType', ''))}</ResourceType>"
+            f"<ResourceStatus>{e.get('ResourceStatus', '')}</ResourceStatus>"
+            f"<ResourceStatusReason>{_esc(e.get('ResourceStatusReason', ''))}</ResourceStatusReason>"
+            f"<Timestamp>{e.get('Timestamp', '')}</Timestamp>"
+            "</member>"
+        )
+
+    return _xml(200, "DescribeStackEventsResponse",
+                f"<DescribeStackEventsResult><StackEvents>{members}</StackEvents></DescribeStackEventsResult>")
+
+
+# --- DescribeStackResource ---
+
+def _describe_stack_resource(params):
+    from ministack.services.cloudformation import _stacks
+    stack_name = _p(params, "StackName")
+    logical_id = _p(params, "LogicalResourceId")
+
+    stack = _stacks.get(stack_name)
+    if not stack:
+        return _error("ValidationError",
+                      f"Stack [{stack_name}] does not exist")
+
+    resources = stack.get("_resources", {})
+    res = resources.get(logical_id)
+    if not res:
+        return _error("ValidationError",
+                      f"Resource [{logical_id}] does not exist in stack [{stack_name}]")
+
+    detail = (
+        f"<LogicalResourceId>{_esc(logical_id)}</LogicalResourceId>"
+        f"<PhysicalResourceId>{_esc(res.get('PhysicalResourceId', ''))}</PhysicalResourceId>"
+        f"<ResourceType>{_esc(res.get('ResourceType', ''))}</ResourceType>"
+        f"<ResourceStatus>{res.get('ResourceStatus', '')}</ResourceStatus>"
+        f"<Timestamp>{res.get('Timestamp', '')}</Timestamp>"
+        f"<StackName>{_esc(stack_name)}</StackName>"
+        f"<StackId>{_esc(stack['StackId'])}</StackId>"
+    )
+
+    return _xml(200, "DescribeStackResourceResponse",
+                f"<DescribeStackResourceResult>"
+                f"<StackResourceDetail>{detail}</StackResourceDetail>"
+                f"</DescribeStackResourceResult>")
+
+
+# --- DescribeStackResources ---
+
+def _describe_stack_resources(params):
+    from ministack.services.cloudformation import _stacks
+    stack_name = _p(params, "StackName")
+
+    stack = _stacks.get(stack_name)
+    if not stack:
+        return _error("ValidationError",
+                      f"Stack [{stack_name}] does not exist")
+
+    resources = stack.get("_resources", {})
+    members = ""
+    for logical_id, res in resources.items():
+        members += (
+            "<member>"
+            f"<LogicalResourceId>{_esc(logical_id)}</LogicalResourceId>"
+            f"<PhysicalResourceId>{_esc(res.get('PhysicalResourceId', ''))}</PhysicalResourceId>"
+            f"<ResourceType>{_esc(res.get('ResourceType', ''))}</ResourceType>"
+            f"<ResourceStatus>{res.get('ResourceStatus', '')}</ResourceStatus>"
+            f"<Timestamp>{res.get('Timestamp', '')}</Timestamp>"
+            f"<StackName>{_esc(stack_name)}</StackName>"
+            f"<StackId>{_esc(stack['StackId'])}</StackId>"
+            "</member>"
+        )
+
+    return _xml(200, "DescribeStackResourcesResponse",
+                f"<DescribeStackResourcesResult>"
+                f"<StackResources>{members}</StackResources>"
+                f"</DescribeStackResourcesResult>")
+
+
+# --- ListStackResources ---
+
+def _list_stack_resources(params):
+    from ministack.services.cloudformation import _stacks
+    stack_name = _p(params, "StackName")
+    if not stack_name:
+        return _error("ValidationError", "StackName is required")
+
+    stack = _stacks.get(stack_name)
+    if not stack:
+        for s in _stacks.values():
+            if s.get("StackId") == stack_name:
+                stack = s
+                break
+    if not stack:
+        return _error("ValidationError",
+                      f"Stack [{stack_name}] does not exist")
+
+    resources = stack.get("_resources", {})
+    members = ""
+    for logical_id, res in resources.items():
+        members += (
+            "<member>"
+            f"<LogicalResourceId>{_esc(logical_id)}</LogicalResourceId>"
+            f"<PhysicalResourceId>{_esc(res.get('PhysicalResourceId', ''))}</PhysicalResourceId>"
+            f"<ResourceType>{_esc(res.get('ResourceType', ''))}</ResourceType>"
+            f"<ResourceStatus>{res.get('ResourceStatus', '')}</ResourceStatus>"
+            f"<LastUpdatedTimestamp>{res.get('Timestamp', '')}</LastUpdatedTimestamp>"
+            "</member>"
+        )
+
+    return _xml(200, "ListStackResourcesResponse",
+                f"<ListStackResourcesResult>"
+                f"<StackResourceSummaries>{members}</StackResourceSummaries>"
+                f"</ListStackResourcesResult>")
+
+
+# --- GetTemplate ---
+
+def _get_template(params):
+    from ministack.services.cloudformation import _stacks
+    stack_name = _p(params, "StackName")
+
+    stack = _stacks.get(stack_name)
+    if not stack:
+        for s in _stacks.values():
+            if s.get("StackId") == stack_name:
+                stack = s
+                break
+    if not stack:
+        return _error("ValidationError",
+                      f"Stack [{stack_name}] does not exist")
+
+    template_body = stack.get("_template_body", "{}")
+    return _xml(200, "GetTemplateResponse",
+                f"<GetTemplateResult>"
+                f"<TemplateBody>{_esc(template_body)}</TemplateBody>"
+                f"</GetTemplateResult>")
+
+
+# --- DeleteStack ---
+
+def _delete_stack(params):
+    from ministack.services.cloudformation import _stacks
+    stack_name = _p(params, "StackName")
+    if not stack_name:
+        return _error("ValidationError", "StackName is required")
+
+    stack = _stacks.get(stack_name)
+    if not stack:
+        # AWS returns success for deleting non-existent stacks
+        return _xml(200, "DeleteStackResponse", "")
+
+    if stack.get("StackStatus") == "DELETE_COMPLETE":
+        return _xml(200, "DeleteStackResponse", "")
+
+    # Check for active imports before deleting
+    stack_exports = [
+        out.get("ExportName") for out in stack.get("Outputs", [])
+        if out.get("ExportName")
+    ]
+    for export_name in stack_exports:
+        for other_name, other_stack in _stacks.items():
+            if other_name == stack_name:
+                continue
+            other_status = other_stack.get("StackStatus", "")
+            if other_status.endswith("_COMPLETE") and "DELETE" not in other_status:
+                other_template = other_stack.get("_template", {})
+                if export_name in json.dumps(other_template):
+                    return _error("ValidationError",
+                                  f"Export {export_name} is imported by stack {other_name}")
+
+    stack_id = stack["StackId"]
+    asyncio.get_event_loop().create_task(_delete_stack_async(stack_name, stack_id))
+
+    return _xml(200, "DeleteStackResponse", "")
+
+
+# --- UpdateStack ---
+
+def _update_stack(params):
+    from ministack.services.cloudformation import _stacks
+    stack_name = _p(params, "StackName")
+    if not stack_name:
+        return _error("ValidationError", "StackName is required")
+
+    stack = _stacks.get(stack_name)
+    if not stack:
+        return _error("ValidationError",
+                      f"Stack [{stack_name}] does not exist")
+
+    current_status = stack.get("StackStatus", "")
+    if current_status not in ("CREATE_COMPLETE", "UPDATE_COMPLETE",
+                               "UPDATE_ROLLBACK_COMPLETE"):
+        return _error("ValidationError",
+                      f"Stack [{stack_name}] is in {current_status} state "
+                      f"and cannot be updated")
+
+    template_body, resolve_err = _resolve_template(params)
+    if resolve_err:
+        return resolve_err
+    if not template_body:
+        # Use previous template if UsePreviousTemplate
+        if _p(params, "UsePreviousTemplate", "false").lower() == "true":
+            template_body = stack.get("_template_body", "{}")
+        else:
+            return _error("ValidationError", "TemplateBody or TemplateURL is required")
+
+    try:
+        template = _parse_template(template_body)
+    except Exception as e:
+        return _error("ValidationError", f"Template format error: {e}")
+    provided_params = _extract_members(params, "Parameters")
+    tags = _extract_members(params, "Tags")
+    disable_rollback = _p(params, "DisableRollback", "false").lower() == "true"
+
+    try:
+        param_values = _resolve_parameters(template, provided_params)
+    except ValueError as exc:
+        return _error("ValidationError", str(exc))
+
+    # Save previous state for rollback
+    previous_stack = {
+        "_resources": copy.deepcopy(stack.get("_resources", {})),
+        "_template": copy.deepcopy(stack.get("_template", {})),
+        "_template_body": stack.get("_template_body", ""),
+        "_resolved_params": copy.deepcopy(stack.get("_resolved_params", {})),
+        "Outputs": copy.deepcopy(stack.get("Outputs", [])),
+    }
+
+    stack_id = stack["StackId"]
+    stack["StackStatus"] = "UPDATE_IN_PROGRESS"
+    stack["LastUpdatedTime"] = now_iso()
+    stack["_template_body"] = template_body
+    if tags:
+        stack["Tags"] = tags
+    stack["Parameters"] = [
+        {"ParameterKey": k, "ParameterValue": v["Value"], "NoEcho": v["NoEcho"]}
+        for k, v in param_values.items()
+    ]
+    stack["_conditions"] = _evaluate_conditions(template, param_values)
+
+    _add_event(stack_id, stack_name, stack_name,
+               "AWS::CloudFormation::Stack", "UPDATE_IN_PROGRESS",
+               physical_id=stack_id)
+
+    asyncio.get_event_loop().create_task(
+        _deploy_stack_async(stack_name, stack_id, template,
+                            param_values, disable_rollback, tags,
+                            is_update=True, previous_stack=previous_stack)
+    )
+
+    return _xml(200, "UpdateStackResponse",
+                f"<UpdateStackResult><StackId>{stack_id}</StackId></UpdateStackResult>")
+
+
+# --- ValidateTemplate ---
+
+def _validate_template(params):
+    template_body = _p(params, "TemplateBody")
+    if not template_body:
+        return _error("ValidationError", "TemplateBody is required")
+
+    try:
+        template = _parse_template(template_body)
+    except Exception as e:
+        return _error("ValidationError", f"Template format error: {e}")
+    if "Resources" not in template:
+        return _error("ValidationError",
+                      "Template format error: At least one Resources member must be defined.")
+    description = template.get("Description", "")
+    param_defs = template.get("Parameters", {})
+
+    params_xml = ""
+    for name, defn in param_defs.items():
+        default = defn.get("Default", "")
+        no_echo = str(defn.get("NoEcho", "false")).lower()
+        ptype = defn.get("Type", "String")
+        desc = defn.get("Description", "")
+        params_xml += (
+            "<member>"
+            f"<ParameterKey>{_esc(name)}</ParameterKey>"
+            f"<DefaultValue>{_esc(str(default))}</DefaultValue>"
+            f"<NoEcho>{no_echo}</NoEcho>"
+            f"<ParameterType>{_esc(ptype)}</ParameterType>"
+            f"<Description>{_esc(desc)}</Description>"
+            "</member>"
+        )
+
+    return _xml(200, "ValidateTemplateResponse",
+                f"<ValidateTemplateResult>"
+                f"<Description>{_esc(description)}</Description>"
+                f"<Parameters>{params_xml}</Parameters>"
+                f"</ValidateTemplateResult>")
+
+
+# --- ListExports ---
+
+def _list_exports(params):
+    from ministack.services.cloudformation import _exports
+    members = ""
+    for name, exp in _exports.items():
+        members += (
+            "<member>"
+            f"<ExportingStackId>{_esc(exp.get('StackId', ''))}</ExportingStackId>"
+            f"<Name>{_esc(name)}</Name>"
+            f"<Value>{_esc(str(exp.get('Value', '')))}</Value>"
+            "</member>"
+        )
+
+    return _xml(200, "ListExportsResponse",
+                f"<ListExportsResult><Exports>{members}</Exports></ListExportsResult>")
+# --- GetTemplateSummary ---
+
+def _get_template_summary(params):
+    from ministack.services.cloudformation import _stacks
+    template_body, resolve_err = _resolve_template(params)
+    if resolve_err:
+        return resolve_err
+    stack_name = _p(params, "StackName")
+
+    if stack_name and not template_body:
+        stack = _stacks.get(stack_name)
+        if not stack:
+            return _error("ValidationError",
+                          f"Stack [{stack_name}] does not exist")
+        template_body = stack.get("_template_body", "{}")
+
+    if not template_body:
+        return _error("ValidationError",
+                      "Either TemplateBody, TemplateURL, or StackName must be provided")
+
+    try:
+        template = _parse_template(template_body)
+    except Exception as e:
+        return _error("ValidationError", f"Template format error: {e}")
+    description = template.get("Description", "")
+    resources = template.get("Resources", {})
+    param_defs = template.get("Parameters", {})
+
+    # Resource types
+    resource_types = sorted(set(
+        r.get("Type", "") for r in resources.values()
+    ))
+    types_xml = "".join(f"<member>{_esc(t)}</member>" for t in resource_types)
+
+    # Parameters
+    params_xml = ""
+    for name, defn in param_defs.items():
+        default = defn.get("Default", "")
+        no_echo = str(defn.get("NoEcho", "false")).lower()
+        ptype = defn.get("Type", "String")
+        desc = defn.get("Description", "")
+        params_xml += (
+            "<member>"
+            f"<ParameterKey>{_esc(name)}</ParameterKey>"
+            f"<DefaultValue>{_esc(str(default))}</DefaultValue>"
+            f"<NoEcho>{no_echo}</NoEcho>"
+            f"<ParameterType>{_esc(ptype)}</ParameterType>"
+            f"<Description>{_esc(desc)}</Description>"
+            "</member>"
+        )
+
+    return _xml(200, "GetTemplateSummaryResponse",
+                f"<GetTemplateSummaryResult>"
+                f"<Description>{_esc(description)}</Description>"
+                f"<ResourceTypes>{types_xml}</ResourceTypes>"
+                f"<Parameters>{params_xml}</Parameters>"
+                f"</GetTemplateSummaryResult>")
+
+
+# ===========================================================================
+# Action Handler Registry
+# ===========================================================================
+
+_ACTION_HANDLERS = {
+    "CreateStack": _create_stack,
+    "DescribeStacks": _describe_stacks,
+    "ListStacks": _list_stacks,
+    "DeleteStack": _delete_stack,
+    "UpdateStack": _update_stack,
+    "DescribeStackEvents": _describe_stack_events,
+    "DescribeStackResource": _describe_stack_resource,
+    "DescribeStackResources": _describe_stack_resources,
+    "ListStackResources": _list_stack_resources,
+    "GetTemplate": _get_template,
+    "ValidateTemplate": _validate_template,
+    "ListExports": _list_exports,
+    "CreateChangeSet": _create_change_set,
+    "DescribeChangeSet": _describe_change_set,
+    "ExecuteChangeSet": _execute_change_set,
+    "DeleteChangeSet": _delete_change_set,
+    "ListChangeSets": _list_change_sets,
+    "GetTemplateSummary": _get_template_summary,
+}

aws_infra/ministack/services/cloudformation/helpers.py

@@ -0,0 +1,109 @@
+"""
+CloudFormation helpers — XML response formatting and parameter extraction utilities.
+"""
+
+import logging
+from html import escape as _esc
+from urllib.parse import urlparse
+
+from ministack.core.responses import new_uuid
+
+logger = logging.getLogger("cloudformation")
+
+CFN_NS = "http://cloudformation.amazonaws.com/doc/2010-05-08/"
+
+
+def _p(params, key, default=""):
+    """Extract a single value from parsed query-string params."""
+    val = params.get(key, [default])
+    return val[0] if isinstance(val, list) else val
+
+
+def _xml(status, root_tag, inner):
+    body = (
+        f'<?xml version="1.0" encoding="UTF-8"?>'
+        f'<{root_tag} xmlns="{CFN_NS}">'
+        f'{inner}'
+        f'<ResponseMetadata><RequestId>{new_uuid()}</RequestId></ResponseMetadata>'
+        f'</{root_tag}>'
+    ).encode("utf-8")
+    return status, {"Content-Type": "application/xml"}, body
+
+
+def _error(code, message, status=400):
+    t = "Sender" if status < 500 else "Receiver"
+    body = (
+        f'<?xml version="1.0" encoding="UTF-8"?>'
+        f'<ErrorResponse xmlns="{CFN_NS}">'
+        f'<Error><Type>{t}</Type><Code>{code}</Code>'
+        f'<Message>{_esc(message)}</Message></Error>'
+        f'<RequestId>{new_uuid()}</RequestId>'
+        f'</ErrorResponse>'
+    ).encode("utf-8")
+    return status, {"Content-Type": "application/xml"}, body
+
+
+def _extract_members(params, prefix):
+    """Extract Parameters.member.N.Key/Value or Tags.member.N.Key/Value."""
+    result = []
+    i = 1
+    while True:
+        key = (_p(params, f"{prefix}.member.{i}.ParameterKey")
+               or _p(params, f"{prefix}.member.{i}.Key"))
+        if not key:
+            break
+        value = (_p(params, f"{prefix}.member.{i}.ParameterValue")
+                 or _p(params, f"{prefix}.member.{i}.Value"))
+        result.append({"Key": key, "Value": value or ""})
+        i += 1
+    return result
+
+
+def _resolve_template(params):
+    """Resolve TemplateBody or TemplateURL to a template string.
+    If TemplateURL is provided, fetch the template from S3.
+    Returns (template_body, error_tuple) — error_tuple is None on success."""
+    template_body = _p(params, "TemplateBody")
+    template_url = _p(params, "TemplateURL")
+
+    if template_body:
+        return template_body, None
+
+    if template_url:
+        try:
+            from ministack.services import s3 as _s3
+            parsed = urlparse(template_url)
+            # Support formats:
+            #   http://localhost:4566/bucket/key
+            #   https://s3.amazonaws.com/bucket/key
+            #   https://bucket.s3.amazonaws.com/key
+            path = parsed.path.lstrip("/")
+            parts = path.split("/", 1)
+            if len(parts) < 2:
+                return None, _error("ValidationError",
+                                    f"Invalid TemplateURL: {template_url}")
+            bucket_name, key = parts[0], parts[1]
+            obj_data = _s3._get_object_data(bucket_name, key)
+            if obj_data is None:
+                return None, _error("ValidationError",
+                                    f"Template not found at {template_url}")
+            return obj_data.decode("utf-8"), None
+        except Exception as e:
+            logger.warning("Failed to fetch TemplateURL %s: %s", template_url, e)
+            return None, _error("ValidationError",
+                                f"Error fetching TemplateURL: {e}")
+
+    return None, None  # neither provided
+
+
+def _extract_stack_status_filters(params):
+    """Extract StackStatusFilter.member.N values."""
+    filters = []
+    i = 1
+    while True:
+        val = _p(params, f"StackStatusFilter.member.{i}")
+        if not val:
+            break
+        filters.append(val)
+        i += 1
+    return filters

aws_infra/ministack/services/cloudformation/stacks.py

@@ -0,0 +1,343 @@
+"""
+CloudFormation stacks — async stack lifecycle (deploy, delete, update, diff).
+"""
+
+import asyncio
+import copy
+import json
+import logging
+import time
+
+from ministack.core.responses import get_account_id, new_uuid, now_iso
+
+from .engine import (
+    _evaluate_conditions, _parse_template, _resolve_parameters,
+    _resolve_refs, _topological_sort, _NO_VALUE,
+)
+from .provisioners import _provision_resource, _delete_resource, REGION
+
+logger = logging.getLogger("cloudformation")
+
+
+# ===========================================================================
+# Stack Events helper
+# ===========================================================================
+
+def _add_event(stack_id, stack_name, logical_id, resource_type, status,
+               reason="", physical_id=""):
+    """Record a stack event."""
+    from ministack.services.cloudformation import _stack_events
+    event = {
+        "StackId": stack_id,
+        "StackName": stack_name,
+        "EventId": new_uuid(),
+        "LogicalResourceId": logical_id,
+        "PhysicalResourceId": physical_id,
+        "ResourceType": resource_type,
+        "ResourceStatus": status,
+        "ResourceStatusReason": reason,
+        "Timestamp": now_iso(),
+    }
+    if stack_id not in _stack_events:
+        _stack_events[stack_id] = []
+    _stack_events[stack_id].append(event)
+
+
+# ===========================================================================
+# Stack Deploy / Delete / Update Logic
+# ===========================================================================
+
+async def _deploy_stack_async(stack_name: str, stack_id: str, template: dict,
+                              param_values: dict, disable_rollback: bool,
+                              tags: list, is_update: bool = False,
+                              previous_stack: dict | None = None):
+    """Background task: provision resources and set final stack status."""
+    from ministack.services.cloudformation import _stacks, _exports
+    status_prefix = "UPDATE" if is_update else "CREATE"
+    stack = _stacks[stack_name]
+
+    mappings = template.get("Mappings", {})
+    conditions = _evaluate_conditions(template, param_values)
+    resources_defs = template.get("Resources", {})
+    outputs_defs = template.get("Outputs", {})
+
+    # Topological sort
+    try:
+        ordered = _topological_sort(resources_defs, conditions)
+    except ValueError as exc:
+        stack["StackStatus"] = f"{status_prefix}_FAILED"
+        stack["StackStatusReason"] = str(exc)
+        _add_event(stack_id, stack_name, stack_name,
+                   "AWS::CloudFormation::Stack", f"{status_prefix}_FAILED",
+                   str(exc), stack_id)
+        return
+
+    provisioned_resources: dict = stack.get("_resources", {})
+    created_in_this_run = []
+
+    # If update: figure out what to add/modify/remove
+    if is_update and previous_stack:
+        old_resource_names = set(previous_stack.get("_resources", {}).keys())
+        new_resource_names = set(ordered)
+        to_remove = old_resource_names - new_resource_names
+    else:
+        to_remove = set()
+
+    failed = False
+    fail_reason = ""
+
+    for logical_id in ordered:
+        res_def = resources_defs[logical_id]
+        cond = res_def.get("Condition")
+        if cond and not conditions.get(cond, True):
+            continue
+
+        resource_type = res_def.get("Type", "AWS::CloudFormation::CustomResource")
+        raw_props = res_def.get("Properties", {})
+
+        try:
+            # Resolve properties
+            resolved_props = _resolve_refs(
+                copy.deepcopy(raw_props), provisioned_resources, param_values,
+                conditions, mappings, stack_name, stack_id
+            )
+            # Filter out _NO_VALUE properties at top level
+            if isinstance(resolved_props, dict):
+                resolved_props = {
+                    k: v for k, v in resolved_props.items() if v is not _NO_VALUE
+                }
+
+            _add_event(stack_id, stack_name, logical_id, resource_type,
+                       f"{status_prefix}_IN_PROGRESS")
+
+            physical_id, attrs = _provision_resource(
+                resource_type, logical_id, resolved_props, stack_name
+            )
+        except Exception as exc:
+            logger.error("Failed to provision %s (%s): %s",
+                         logical_id, resource_type, exc)
+            _add_event(stack_id, stack_name, logical_id, resource_type,
+                       f"{status_prefix}_FAILED", str(exc))
+            failed = True
+            fail_reason = f"Resource {logical_id} failed: {exc}"
+            break
+
+        provisioned_resources[logical_id] = {
+            "PhysicalResourceId": physical_id,
+            "ResourceType": resource_type,
+            "ResourceStatus": f"{status_prefix}_COMPLETE",
+            "LogicalResourceId": logical_id,
+            "Properties": resolved_props,
+            "Attributes": attrs,
+            "Timestamp": now_iso(),
+        }
+        created_in_this_run.append(logical_id)
+
+        _add_event(stack_id, stack_name, logical_id, resource_type,
+                   f"{status_prefix}_COMPLETE", physical_id=physical_id)
+
+    # Delete removed resources (update case)
+    if not failed and to_remove:
+        old_resources = previous_stack.get("_resources", {})
+        for logical_id in to_remove:
+            old_res = old_resources.get(logical_id, {})
+            rtype = old_res.get("ResourceType", "")
+            pid = old_res.get("PhysicalResourceId", "")
+            old_props = old_res.get("Properties", {})
+            try:
+                _delete_resource(rtype, pid, old_props)
+            except Exception as exc:
+                logger.warning("Failed to delete old resource %s: %s",
+                               logical_id, exc)
+            provisioned_resources.pop(logical_id, None)
+
+    await asyncio.sleep(0)
+
+    if failed:
+        if disable_rollback:
+            stack["StackStatus"] = f"{status_prefix}_FAILED"
+            stack["StackStatusReason"] = fail_reason
+            _add_event(stack_id, stack_name, stack_name,
+                       "AWS::CloudFormation::Stack", f"{status_prefix}_FAILED",
+                       fail_reason, stack_id)
+        else:
+            # Rollback: delete resources created in this run in reverse order
+            stack["StackStatus"] = "ROLLBACK_IN_PROGRESS" if not is_update else "UPDATE_ROLLBACK_IN_PROGRESS"
+            _add_event(stack_id, stack_name, stack_name,
+                       "AWS::CloudFormation::Stack", stack["StackStatus"],
+                       "Rollback requested", stack_id)
+
+            for logical_id in reversed(created_in_this_run):
+                res = provisioned_resources.get(logical_id, {})
+                rtype = res.get("ResourceType", "")
+                pid = res.get("PhysicalResourceId", "")
+                res_props = res.get("Properties", {})
+                try:
+                    _delete_resource(rtype, pid, res_props)
+                    _add_event(stack_id, stack_name, logical_id, rtype,
+                               "DELETE_COMPLETE", physical_id=pid)
+                except Exception as del_exc:
+                    logger.warning("Rollback delete of %s failed: %s",
+                                   logical_id, del_exc)
+                    _add_event(stack_id, stack_name, logical_id, rtype,
+                               "DELETE_FAILED", str(del_exc), pid)
+                provisioned_resources.pop(logical_id, None)
+
+            if is_update and previous_stack:
+                # Restore previous resources
+                stack["_resources"] = previous_stack.get("_resources", {})
+                stack["_template"] = previous_stack.get("_template", {})
+                stack["_resolved_params"] = previous_stack.get("_resolved_params", {})
+                stack["Outputs"] = previous_stack.get("Outputs", [])
+                stack["StackStatus"] = "UPDATE_ROLLBACK_COMPLETE"
+            else:
+                stack["StackStatus"] = "ROLLBACK_COMPLETE"
+            _add_event(stack_id, stack_name, stack_name,
+                       "AWS::CloudFormation::Stack", stack["StackStatus"],
+                       "Rollback complete", stack_id)
+        return
+
+    # Success: resolve outputs
+    stack["_resources"] = provisioned_resources
+    stack["_template"] = template
+    stack["_resolved_params"] = param_values
+
+    resolved_outputs = []
+    for out_name, out_def in outputs_defs.items():
+        cond = out_def.get("Condition")
+        if cond and not conditions.get(cond, True):
+            continue
+        out_value = _resolve_refs(
+            copy.deepcopy(out_def.get("Value", "")),
+            provisioned_resources, param_values, conditions,
+            mappings, stack_name, stack_id
+        )
+        output = {
+            "OutputKey": out_name,
+            "OutputValue": str(out_value),
+            "Description": out_def.get("Description", ""),
+        }
+        export_def = out_def.get("Export", {})
+        if export_def:
+            export_name = _resolve_refs(
+                copy.deepcopy(export_def.get("Name", "")),
+                provisioned_resources, param_values, conditions,
+                mappings, stack_name, stack_id
+            )
+            output["ExportName"] = str(export_name)
+            _exports[str(export_name)] = {
+                "StackId": stack_id,
+                "Name": str(export_name),
+                "Value": str(out_value),
+            }
+        resolved_outputs.append(output)
+
+    stack["Outputs"] = resolved_outputs
+    stack["StackStatus"] = f"{status_prefix}_COMPLETE"
+    _add_event(stack_id, stack_name, stack_name,
+               "AWS::CloudFormation::Stack", f"{status_prefix}_COMPLETE",
+               physical_id=stack_id)
+
+
+async def _delete_stack_async(stack_name: str, stack_id: str):
+    """Background task: delete all resources and mark stack DELETE_COMPLETE."""
+    from ministack.services.cloudformation import _stacks, _exports
+    stack = _stacks.get(stack_name)
+    if not stack:
+        return
+
+    stack["StackStatus"] = "DELETE_IN_PROGRESS"
+    _add_event(stack_id, stack_name, stack_name,
+               "AWS::CloudFormation::Stack", "DELETE_IN_PROGRESS",
+               physical_id=stack_id)
+
+    # Export-in-use check already done synchronously in _delete_stack
+
+    resources = stack.get("_resources", {})
+    template = stack.get("_template", {})
+    res_defs = template.get("Resources", {}) if template else {}
+    conditions = stack.get("_conditions", {})
+
+    # Delete in reverse dependency order
+    try:
+        ordered = _topological_sort(res_defs, conditions) if res_defs else list(resources.keys())
+    except ValueError:
+        ordered = list(resources.keys())
+
+    for logical_id in reversed(ordered):
+        res = resources.get(logical_id)
+        if not res:
+            continue
+        rtype = res.get("ResourceType", "")
+        pid = res.get("PhysicalResourceId", "")
+        res_props = res.get("Properties", {})
+
+        _add_event(stack_id, stack_name, logical_id, rtype,
+                   "DELETE_IN_PROGRESS", physical_id=pid)
+        try:
+            _delete_resource(rtype, pid, res_props)
+            _add_event(stack_id, stack_name, logical_id, rtype,
+                       "DELETE_COMPLETE", physical_id=pid)
+        except Exception as exc:
+            logger.warning("Delete of %s (%s) failed: %s", logical_id, pid, exc)
+            _add_event(stack_id, stack_name, logical_id, rtype,
+                       "DELETE_FAILED", str(exc), pid)
+
+    # Remove exports
+    for out in stack.get("Outputs", []):
+        export_name = out.get("ExportName")
+        if export_name:
+            _exports.pop(export_name, None)
+
+    await asyncio.sleep(0)
+
+    stack["StackStatus"] = "DELETE_COMPLETE"
+    _add_event(stack_id, stack_name, stack_name,
+               "AWS::CloudFormation::Stack", "DELETE_COMPLETE",
+               physical_id=stack_id)
+
+
+# ===========================================================================
+# Change Set Helpers
+# ===========================================================================
+
+def _diff_resources(old_template: dict, new_template: dict) -> list:
+    """Diff two templates and return a list of change dicts."""
+    old_res = old_template.get("Resources", {})
+    new_res = new_template.get("Resources", {})
+    changes = []
+
+    all_keys = old_res.keys() | new_res.keys()
+    for key in sorted(all_keys):
+        if key not in old_res:
+            changes.append({
+                "ResourceChange": {
+                    "Action": "Add",
+                    "LogicalResourceId": key,
+                    "ResourceType": new_res[key].get("Type", ""),
+                    "Replacement": "False",
+                }
+            })
+        elif key not in new_res:
+            changes.append({
+                "ResourceChange": {
+                    "Action": "Remove",
+                    "LogicalResourceId": key,
+                    "ResourceType": old_res[key].get("Type", ""),
+                    "PhysicalResourceId": "",
+                    "Replacement": "False",
+                }
+            })
+        else:
+            old_props = old_res[key].get("Properties", {})
+            new_props = new_res[key].get("Properties", {})
+            if old_props != new_props:
+                changes.append({
+                    "ResourceChange": {
+                        "Action": "Modify",
+                        "LogicalResourceId": key,
+                        "ResourceType": new_res[key].get("Type", ""),
+                        "Replacement": "Conditional",
+                    }
+                })
+    return changes