| 1 | --- |
| 2 | title: Looping the Generation of Local Emulators |
| 3 | date: 2026-08-20T16:00:00Z |
| 4 | draft: true |
| 5 | excerpt: The live test suite that generates our IaC and SDKs is also an executable spec of the cloud. Point it at an emulator and every red test is a fidelity bug with a repro. alchemy dev now emulates 219 resources across ~39 AWS services on your machine, with no AWS account. |
| 6 | --- |
| 7 | |
| 8 | In [Looping the Generation of IaC and SDKs](/blog/2026-07-02-cloudflare-resource-factory) |
| 9 | we described the loop that builds Alchemy: fleets of AI agents |
| 10 | write resources and their live tests, run them against the real |
| 11 | cloud, and every API behavior the SDK's types don't capture |
| 12 | becomes a typed patch to the generated SDK. The resource is the |
| 13 | product; the truthful SDK is the byproduct. |
| 14 | |
| 15 | The loop now has a second byproduct: a **local emulator**. What |
| 16 | makes it possible is the tests, and they cover both halves of the |
| 17 | cloud. The resource tests exercise the **control plane**: deploy |
| 18 | a resource, verify it out-of-band against the raw API, mutate it, |
| 19 | prove its destruction. The binding tests exercise the **data |
| 20 | plane**: a deployed function actually calling `putObject`, |
| 21 | `getItem`, `sendMessage` against the resources bound to it. |
| 22 | Together, thousands of them are an **executable specification of |
| 23 | the cloud**. Every consistency quirk, undocumented error code, |
| 24 | and misused HTTP status the factory ever caught is pinned as an |
| 25 | assertion. |
| 26 | |
| 27 | An emulator has to satisfy the same specification. So we |
| 28 | extended the factory: point the same suite at a local emulator, |
| 29 | and every red test is a fidelity bug that arrives with its own |
| 30 | reproduction. This is how `alchemy dev` for AWS works. Your |
| 31 | stack runs on your machine with no AWS account and no |
| 32 | credentials. It shipped in |
| 33 | [2.0.0-beta.75](/blog/2026-08-25-beta-75). |
| 34 | |
| 35 | ## We forked floci |
| 36 | |
| 37 | We [forked](https://github.com/alchemy-run/floci) |
| 38 | [floci](https://floci.io)'s AWS implementation because they've |
| 39 | already laid a great foundation for local development but don't |
| 40 | have full coverage. They're adding more every day, but we want |
| 41 | to automate the emulator's development and will push for 100% |
| 42 | next release. In this version we focused on patching services |
| 43 | floci already supported, and added MicroVMs, a new service that |
| 44 | is very important to alchemy. |
| 45 | |
| 46 | The patches span about 30 services: Lambda's streaming Function |
| 47 | URLs, ELBv2's ALB data plane, AppSync's Velocity template |
| 48 | directives, EC2, IAM, SES, Cognito, Athena, event-source |
| 49 | mappings. Every one of them exists because an alchemy test |
| 50 | failed against the emulator after passing against AWS. |
| 51 | |
| 52 | We'd like to contribute these upstream, but the factory is a |
| 53 | fully automated fan-out, with fleets of agents producing fixes |
| 54 | faster than any maintainer could reasonably review. Flooding the |
| 55 | floci team with that maintenance burden isn't fair to them. It's |
| 56 | easier to let alchemy's flywheel drive the fork directly. |
| 57 | |
| 58 | ## The flywheel |
| 59 | |
| 60 | What drives the fork is the test suite. The harness has one |
| 61 | switch that points it at the emulator instead of live AWS: |
| 62 | |
| 63 | ```sh |
| 64 | pnpm test:aws:floci |
| 65 | ``` |
| 66 | |
| 67 | It runs the same test suite that normally runs against live AWS, |
| 68 | except every call goes to floci instead. Nothing is mocked: each |
| 69 | Lambda still cold-starts in its own Docker container. |
| 70 | |
| 71 | Agents run the suite and fix every red test. The fix always goes |
| 72 | in the fork, never in alchemy: we don't loosen a test or |
| 73 | special-case lifecycle code to tolerate the emulator, so the |
| 74 | suite stays a single source of truth that both AWS and floci |
| 75 | have to satisfy. Each fix lands with a conformance test in the |
| 76 | emulator's own suite. |
| 77 | |
| 78 | For example: a live test asserts that a streaming Function URL |
| 79 | delivers its first bytes before the handler finishes. floci |
| 80 | buffered the stream, the test went red, the fix landed in the |
| 81 | fork, and streaming now behaves the same locally as in |
| 82 | `us-east-1`. |
| 83 | |
| 84 | The same goes for coverage gaps. Some operations in floci throw |
| 85 | `UnsupportedOperation`. We never work around one in alchemy; we |
| 86 | patch floci to support the operation. We're strict about this. |
| 87 | |
| 88 | ## Results |
| 89 | |
| 90 | `alchemy dev` now emulates **219 resources across ~39 AWS |
| 91 | services** locally, with **396 tests green** against the |
| 92 | emulator. Several services pass their full live suite: DynamoDB |
| 93 | (105 tests), S3 (51), Step Functions (31), Cognito (19), and |
| 94 | others. Next release we'll run the flywheel until the emulator |
| 95 | conforms to 100% of what alchemy supports. |
| 96 | |
| 97 | The result is [`alchemy dev` for AWS](/aws/local-development). |
| 98 | It also makes the factory cheaper: generation waves can now |
| 99 | iterate against floci with no rate limits, no |
| 100 | eventual-consistency stalls, and no leaked cloud resources, |
| 101 | touching the real cloud only to certify. |
| 102 | |
| 103 | ## Three artifacts per cloud |
| 104 | |
| 105 | The end state we're building toward is a flywheel that, for each |
| 106 | cloud provider, produces three artifacts from one loop: |
| 107 | |
| 108 | 1. **Infrastructure-as-Code**: typed resources and bindings in |
| 109 | Alchemy, with lifecycle logic whose error handling is |
| 110 | verified against the live API. |
| 111 | 2. **A refined spec and Effect-native SDK**: distilled, where |
| 112 | every behavior a live test observes becomes a typed patch to |
| 113 | the provider's spec, compounding for every future consumer. |
| 114 | 3. **A local emulator**: held conformant to the same test suite |
| 115 | that certifies the IaC, so `alchemy dev` is a faithful copy |
| 116 | of `alchemy deploy`. |
| 117 | |
| 118 | Each artifact makes the others cheaper. The refined SDK types |
| 119 | make lifecycle code generable. The lifecycle tests make the |
| 120 | emulator convergeable. The emulator makes the tests and your |
| 121 | dev loop free to run. And in the limit, the refined spec is |
| 122 | the substrate for all three: an emulator is just another |
| 123 | consumer of a spec, and every patch that teaches the spec what |
| 124 | the API really does is a piece of the emulator nobody has to |
| 125 | hand-write. |
| 126 | |
| 127 | Cloudflare already runs this way: its Workers simulators are |
| 128 | built on workerd itself and held to the same live suites. AWS |
| 129 | now joins it. The next provider the factory brings up will ship |
| 130 | all three artifacts together. |
| 131 | |
| 132 | - [2.0.0-beta.75 — the release AWS local dev shipped in](/blog/2026-08-25-beta-75) |
| 133 | - [AWS local development](/aws/local-development) |
| 134 | - [Looping the Generation of IaC and SDKs — the first post in this series](/blog/2026-07-02-cloudflare-resource-factory) |
| 135 | - [alchemy-run/floci — the fork](https://github.com/alchemy-run/floci) |
| 136 | - [distilled — the generated, patchable SDK](https://github.com/alchemy-run/distilled) |