alchemy-provider

Building an Alchemy provider

A provider is built on a flywheel. Each turn of it makes both the SDK and the provider more correct:

 1. distilled SDK ──> 2. alchemy resources ──> 3. live tests
        ^                                          │
        └──── 4. distilled patches <── wrong error / wrong schema

The live API is the only authority. A resource is done when its test passes against the real provider, and every mismatch that test surfaced is fixed in distilled rather than worked around in alchemy.

The target is the whole provider. "Create a provider for X" means every resource in every service the distilled SDK covers is either implemented and live-tested, or listed as out of scope with a reason from step 2. A handful of foundation resources is the first wave, never the deliverable. Cost is not a scoping reason: expensive resources are implemented like any other (see step 6 for running their tests). The user narrows scope; the agent does not.

Coverage is 1:1 with the API, operation by operation. Every operation in every in-scope service ends up as exactly one of: part of a resource's lifecycle, a binding, an event source, or an internal row with a reason. A service with resources but no bindings is half done. AWS is the bar: 2,846 binding services across 205 of its 212 services. GCP reached 57 of 161 services and Azure 4 of 160; both were reported as done. Every call goes through distilled. When distilled is missing an operation, patch distilled (step 1); never work around it in alchemy.

The whole provider also means its non-resource deliverables: a binding for every data-plane operation (step 5), every runtime in both forms, event sources, and a workflow engine when the cloud runs code, framework websites on the cloud's CDN and functions (step 7, when the cloud hosts websites), examples, the docs hub, and generated docs (step 10). They are rows in the same index as resources, with the same statuses. Never write "a later phase" into an agent contract without adding those rows: on Azure, the contract said "bindings are a later phase — do not build them", the phase never came, and 1,193 resources shipped with zero bindings, no runtime, no examples, and docs for 4 services.

AGENTS.md owns the doctrines this skill relies on; read these sections before writing code and follow them as written:

• Package boundaries — every provider is its own workspace package; core never imports it, and it reaches core only through alchemy/*.
• Reconciler doctrine — the observe → ensure → sync shape of reconcile.
• Typed Error Doctrine (distilled) — every error alchemy handles is a typed tag in the SDK.
• Speed doctrine: never wait on a hang — bounded retries, timeout on every test run, the three-iteration budget.
• Read/Write/ReadWrite binding convention, Runtime-only methods, and Isolate scope vs request scope — bindings and runtimes.
• Documentation Generation — JSDoc is the only docs source.
• The Resource Factory Process — how to fan the work out to agents.

Those rules existed while the GCP provider was built, and its first review still found the same violations in hundreds of files. Reading the rules is not enough: review.md turns each of them into a check with a command and an expected result. Run that review at every wave boundary and before step 10; a provider with unexplained hits is not done.