# Alchemy Provider

> Bring up a new Alchemy cloud provider (its own `@alchemy.run/<provider>` package under packages/<provider>) end to end — credentials, a distilled SDK, resources, bindings, live tests, and the patch loop that feeds live-test failures back into distilled — or extend an existing provider with a new service, or bring an existing provider up to the bar (gap audit, then waves). Use for "add a <X> provider", "create an alchemy provider for <X>", "port <X> to alchemy", "add <service> to the <X> provider", "bring the <X> provider up to par", or any work that needs a distilled SDK plus Alchemy resources tested against a live API.

- Skill: `tuyv/alchemy-provider` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add tuyv/alchemy-provider`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tuyv/alchemy-provider/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tuyv (https://skillmd.com/u/tuyv)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/tuyv/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](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.

## Bringing an existing provider up to the bar

When the provider already exists (a PR in progress, or a package on
`main`), start with a gap audit instead of step 0:

1. Merge `origin/main` into the branch and type-check the package (see
   **Branch, checkpoints, and PRs**).
2. Run every check in [review.md](review.md) against the code as it is,
   and port `scripts/audit-service.ts` (step 2) to get per-service
   operation coverage.
3. Rebuild `INDEX.md` from the results: one row per missing resource,
   binding, runtime form, event source, workflow engine, website
   rework, example, docs page, and JSDoc gap, plus one per review hit
   that needs a fix (hand-written HTTP, `host.bind`, a container
   website). Existing rows keep their status only when review.md passes
   them.
4. Do the distilled work first. Missing data-plane modules, credentials
   providers, and manual specs block the bindings that depend on them.
5. Then run the waves from step 4 onward, with the same contracts as a
   new provider.

Report the audit to the user before the first wave: counts per category
and the planned waves.

## Orchestration

Fan-out work (the gap audit, the catalog in step 2, implementation waves,
fix rounds in step 8, the review gate in step 9) runs as a **workflow**
when the harness has one: Claude Code's `Workflow` tool (load its
`workflow-authoring` skill before writing the script), Grok's `workflow`
tool (its `create-workflow` skill), or the equivalent elsewhere. Run a
workflow only when the user asked for one, since it spends many agents. A workflow runs the whole wave as one
script with bounded parallelism, enforces an agent budget, and journals
every finished agent's result, so a crash costs only the agents still
running. When no workflow tool exists, launch each agent as a detached
top-level thread (`t3_thread_launch` with `workspaceStrategy: "worktree"`
in T3 Code), never a `delegate_task` subagent thread; the coordinator reads
each thread's result with `t3_thread_read`. Either way,
each agent gets the task contract from **What every agent task prompt must
include** in `AGENTS.md`, owns one distilled service, and returns the
structured result the coordinator turns into index statuses.

Coordinator duties during a long run:

- **Size agents to finish within an hour.** A service with more than about
  25 resources runs as a chain of agents over resource batches. Agents that
  run for hours hit the model's idle timeout and lose their context.
- **Read the workflow state, not only file activity.** Each status check
  counts agents by state and reads the error of every failed or cancelled
  one. A model-API outage (`auth_unavailable`, idle timeouts) looks like a
  quiet period from the file system; on Azure it went unnoticed for three
  hours. Relaunch only the rows still `missing`, with an assess-first
  contract, once the cause is gone.
- **Offer periodic status updates** when the run will take more than an
  hour, and include the index counts in each.

## Branch, checkpoints, and PRs

- Work in a fresh worktree on a branch from `origin/main`, with
  `submodules/distilled` at the commit alchemy pins plus your distilled
  branch. Never start from whatever branch the worktree happens to be on.
- Open **draft** PRs in alchemy and distilled after the first wave that
  passes live, and push a checkpoint at every wave boundary. The
  description carries the current index counts.
- Each checkpoint: rebase onto `origin/main` (distilled onto the pin
  `main` uses), type-check, push, and confirm the PR's checks actually ran.
  A PR with merge conflicts runs no `pull_request` workflows, so a stale
  green check means nothing. Dependency bumps on `main` (Effect, Node
  types) break new code; catch them at the checkpoint.
- When a rebase or pull brings in a newer version of this skill, re-read
  the whole skill and review.md before the next wave. Add an index row for
  every new deliverable, then build those rows and run review.md with a
  fresh reviewer.
- `pnpm exec tsrs -b` reads distilled's built declarations (`lib/`), while
  the test runner reads its `src/`. After distilled patches or a pin bump,
  rebuild that package before the type check, or new error types show up
  as false type errors.
- After merging `main`, type-check the provider package on its own first
  (`cd packages/<provider> && pnpm exec tsrs -b`), then the workspace. A
  newer distilled pin is the usual break: a shape that became open
  (`[key: string]: unknown`) or a renamed error tag.
- Commit with the repo's hooks. If signing or a hook hangs, ask the user;
  if they approve skipping it, run `pnpm exec oxfmt` yourself and say the
  commits are unsigned.

## Step 0 — get credentials first

**Always ask the user for credentials for the upstream provider before
anything else**, even when the request does not mention testing. Live tests
are the whole point of the loop, and a provider built without them is
unverified. Ask in one message, and name exactly what is needed:

- the auth method the provider supports (API token, service account key,
  OAuth app, access key pair) and the minimum scopes or roles the test
  resources need;
- a dedicated test account, project, or organization — never a production
  one, because tests create and nuke resources;
- account identifiers the API needs (org id, project id, default region);
- known limits of that account (plan tier, quotas, features that need an
  upgrade), so gated tests can be planned up front.

Store what the user gives you in an Alchemy profile, never in the repo:
`alchemy profile edit --profile testing --add <Provider>` (use the profile
name the user asks for). Tests select it with `--profile <name>`. Never
print a secret, write it to a tracked file, or put it in a PR, commit, or
log. If the user has no credentials, give them the exact steps to create
them (console path or CLI commands, roles to grant), offer to do it in the
browser if they allow it, and keep working on the catalog and code
meanwhile. Until credentials arrive, mark every live test as blocked in
your report; do not claim anything is tested.

## Step 1 — the distilled SDK

Every provider talks to its API through a distilled SDK
(`@distilled.cloud/<pkg>` in `submodules/distilled/packages/<pkg>`). Alchemy
never calls the API with a hand-written HTTP client.

- **No SDK yet:** follow the `distilled-sdk` skill in the submodule
  (`submodules/distilled/.agents/skills/distilled-sdk/SKILL.md`). It covers
  sourcing the spec, the mirror, convert/generate, the README, and the
  distilled PR.
- **SDK exists but is wrong** (missing typed error, nullable field, wrong
  response schema, unmarked secret): follow the `distilled-sdk-patch`
  skill (`submodules/distilled/.agents/skills/distilled-sdk-patch/SKILL.md`).
- **SDK is behind its spec:** follow `distilled-sdk-update`.

**That includes the data plane.** Bindings call the cloud's data APIs
(put a blob, send a message, read a secret), and those go through
distilled exactly like the management API that creates the resources.
AWS is the model: `sqs.sendMessage`, `s3.putObject` and
`dynamodb.getItem` are distilled operations, and AWS bindings hold no
HTTP code. Check data-plane coverage when you check the SDK. If the SDK
covers only the management API, extend it before writing a binding:

- **The spec has a data-plane model** (Azure's
  `specification/<service>/data-plane/`, GCP's data APIs in discovery
  docs): extend the converter to include it, as its own service module
  (`storage-queue`, `keyvault-secrets`).
- **The API has no published spec** (Kudu zip deploy, a CLI-only
  endpoint): write the model by hand in the package's `manual-specs/`.
- **The protocol isn't HTTP-shaped** (XML bodies, SAS signing, a token
  audience per data plane): add it to the distilled protocol, not to
  alchemy.
- **Credentials from the runtime's identity endpoint** (managed identity,
  metadata server, container credentials) are a distilled credentials
  provider, like AWS's `fromContainerMetadata`. A binding never fetches
  its own token.

On Azure, the converter skips `data-plane/` (`scripts/convert.ts`), so
the agent hand-wrote XML request builders for Storage queues and blobs,
Key Vault secrets, Service Bus, Event Hubs, a static-website uploader, and
a managed-identity token cache: 22 raw request sites, with no typed
errors and no tests against a spec. Don't repeat it. Stop and extend
distilled.

Raw `HttpClient` calls are allowed only for:

- URLs the API hands back to you to use as-is (a presigned or SAS upload
  URL, a signed download URL);
- the user's own deployed endpoints (calling a Worker, Function, or
  service the stack deployed).

Each one carries a comment saying which case it is.

If a skill file is missing at the pinned submodule commit, read it from
distilled `main`: `git -C submodules/distilled fetch origin main && git -C
submodules/distilled show origin/main:.agents/skills/<skill>/SKILL.md`.

Distilled changes land as their own PR in `alchemy-run/distilled`. After
it merges, move the submodule pin in alchemy to the merged commit
(`git -C submodules/distilled checkout <sha>` then commit the gitlink) and
run `pnpm install` so the workspace links the package.

## Step 2 — catalog and scope

Catalog **every** service module in the SDK
(`ls submodules/distilled/packages/<pkg>/src/services`) before writing
resources; for a large SDK, fan the catalog out as a workflow (see Orchestration). Each service gets
`processes/<Provider>/catalog/<service>.md` in that section's format:
resources, props with replacement rules, attributes,
lifecycle-to-operation mapping, bindings, testability, and priority.
`processes/` is gitignored, so the catalog is the local order book; the
committed record of scope is the overview page below.

Each catalog file also lists **every operation** in the service module,
classified the way `scripts/audit-service.ts` classifies AWS:

| Category | Meaning | Becomes |
| --- | --- | --- |
| `resource-lifecycle` | create/get/update/delete/list of the resource itself | a resource's `reconcile`/`read`/`delete`/`list` |
| `binding` | data-plane work on or inside a resource (put an object, send a message, query a table, read a secret, invoke a function) | a `Binding.Service` + `<Op>Http.ts` |
| `event-source` | the resource triggers runtimes (notifications, streams, subscriptions) | an event source |
| `internal` | not useful from user code (long-running-operation polling, deprecated aliases) | nothing, with a reason |

Read operations a user calls at runtime (get an item, list objects,
describe a queue's depth) are bindings even when a lifecycle uses them
too. Port `scripts/audit-service.ts` to the provider before the first
wave (it reads the distilled module and the package and prints the gaps),
and run it per service at every wave boundary.

`processes/<Provider>/catalog/INDEX.md` has one row per resource and one per binding with a
status of `missing`, `implemented`, `tested`, `blocked` (with the exact
error), or `out-of-scope` (with the reason). Build waves from it and repeat
until no row is `missing` or `implemented`. Every progress report and the
final report quote its counts per status; "done" while any in-scope row is
`missing` is a false claim.

The first line of `INDEX.md` records the skill version it was built
against: `Skill: <sha>`, from `git log -1 --format=%H --
.agents/skills/alchemy-provider`. Update it after re-reading a newer skill.

Decide scope per resource and record the out-of-scope list in the
provider's website overview under an "Out of scope" section:

- **In scope:** infrastructure the user configures and owns (databases,
  buckets, queues, networks, keys, functions, DNS).
- **Out of scope** (the only valid reasons): end-user data APIs (mail, calendar, documents, videos),
  APIs that need end-user OAuth scopes, deprecated or retired APIs,
  billing/subscription objects, closed-beta endpoints, and duplicates of
  another service.

Fix public names now; renaming after release is a breaking change.
Service namespaces are PascalCase (`AccessContextManager`), and resource
names are correct English singulars (`Index`, not `Indexe`; `Process`, not
`Processe`). Audit generated names by eye before the first PR.

## Step 3 — the provider package

A provider is its own workspace package, `@alchemy.run/<provider>` in
`packages/<provider>`, following **Package boundaries** in `AGENTS.md`.
Copy the closest small package: `packages/axiom` (token auth, flat
resources) or `packages/hetzner` (labels, `list`, nuke ordering, bindings,
a hosted runtime, websites). A package holds:

| File | Purpose |
| --- | --- |
| `package.json` | name, shared alchemy version, publish metadata, `exports`/`publishConfig` (generated, below), `alchemy.contributes`, dependencies |
| `tsconfig.json` | composite project; references the distilled package, `distilled/core`, and `../alchemy` |
| `scripts/build.ts` | copied verbatim from a sibling package |
| `src/Contributions.ts` | `Contributions.make({ name, auth, … })` — what the CLI, the Alchemist API, and the test harness load without the user's stack |
| `src/AuthProvider.ts` | `makeStoredAuthProvider` fields, CI env vars, `<Provider>Auth` layer |
| `src/Credentials.ts` | `fromAuthProvider()` = `lazyCredentials<Resolved, ConfigError>()(...)` → the distilled `Credentials` layer |
| `src/Providers.ts` | `ProviderCollection` + `providers()` layer (provider layers, credentials, `FetchHttpClient`, auth, profile and credential stores) |
| `src/<Provider>Bindings.ts` | how bindings reach the cloud from any host (step 5) |
| `src/globals.d.ts` | `import type {} from "alchemy/Phase";` so `globalThis.__ALCHEMY_RUNTIME__` type-checks |
| `src/index.ts` | re-exports every resource, binding, and layer; `export * as <Service> from "./<Service>/index.ts"` |
| `src/Labels.ts` / tags helper | ownership labels, if the API supports labels or tags |
| `src/Bootstrap.ts` | process entry for a hosted runtime, if the cloud runs code (source-only export) |
| `README.md` | npm readme: short intro, install line, one complete type-checked example, absolute `https://alchemy.run` links |

`Contributions.ts` is imported on every CLI start, so it holds metadata and
`Contributions.lazy(() => import(...), pick)` fields only. Contribute `auth`
always; add `stateStores`, `cli`, `testServices`, and `devEnv` when the
provider has them (`packages/aws/src/Contributions.ts` uses all of them).
Declare it in `package.json`:

```json
"alchemy": { "contributes": ["@alchemy.run/<provider>/Contributions"] }
```

Never hand-edit `exports`. Run `pnpm exports:sync` after adding or
removing a service directory; CI runs `pnpm exports:check`. Modules other
packages must not import are named `internal.ts` or live under
`internal/`. Dependencies: `@distilled.cloud/<pkg>` and
`@distilled.cloud/core` are `dependencies`; `alchemy` and `effect` are
peer + dev dependencies; another `@alchemy.run/*` package is a dependency
only when every user needs it, otherwise an optional peer.

Register the package everywhere the repo enumerates providers. Find the
full list by grepping for an existing package (`git grep -il hetzner --
':!packages/hetzner' ':!submodules' ':!examples'`); at the time of
writing it is:

- `package.json` — the `build:pkg` filter list and a root
  `@alchemy.run/<provider>` devDependency (the CLI finds `Contributions`
  through the project's dependencies);
- `tsconfig.json` — project references to the package and its distilled
  package;
- `packages/integration-tests/package.json` and `tsconfig.json` — the
  package, its distilled package, and the project reference;
- `.github/workflows/pkg.yml` — the `@alchemy.run[Collapsed]` group;
- `.gitignore` — `!packages/<provider>/src/globals.d.ts`;
- `stacks/nuke.ts` — `<Provider>.providers()`;
- `scripts/with-fake-profiles.sh` — fake CI credentials;
- `scripts/generate-api-reference.ts` and `scripts/fix-api-jsdocs.ts` —
  the package's `src` root and provider prefix;
- `packages/integration-tests/test/Bundle/ProviderBootstraps.test.ts` —
  every `Bootstrap` the package ships;
- `website/astro.config.ts`, `website/src/components/ProviderDirectory.astro`,
  `website/scripts/generate-llms-txt.ts`, and
  `website/src/content/docs/<provider>/` (`index.mdx`, `setup.mdx`) —
  sidebar, directory card, llms.txt, overview, and setup page.

Core (`packages/alchemy`) never changes to add a provider. If a provider
seems to need a core change (a new auth registry entry, a CLI command, a
state store), it is a `Contributions` field instead.

Configuration such as region, project, or account comes from the
credential/profile or from a layer the user provides (the AWS
`AWS.Region(...)` pattern). Do not invent environment variables for it;
env vars exist only for CI credentials and for values the runtime platform
itself sets.

If `providers()` wires hundreds of resources, memoize it
(`let cached; export const providers = () => (cached ??= make())`) and keep
nested `Layer.mergeAll` groups of about 90; an unmemoized collection
rebuilds every layer per call and runs the test process out of memory.
`pnpm lint:providers` fails when a `providers()` layer leaks an `unknown`
requirement.

## Step 4 — resources

Implement each resource per **Reconciler doctrine**, co-locating the
contract and provider in `packages/<provider>/src/<Service>/<Resource>.ts`. These
are the mistakes that most often slip through review (each has a check in
[review.md](review.md)):

- **Block until ready.** `reconcile` returns only after the API reports the
  resource usable: poll the long-running operation to completion and then
  read the ready state. Use one shared operation waiter per provider with a
  per-resource time budget that matches reality (minutes for databases and
  clusters). Post-ready propagation delay is acceptable; returning early is
  not.
- **Identity changes replace.** If a user-chosen name or id is part of the
  resource's identity, `diff` returns `replace` when it changes; otherwise
  the old resource leaks.
- **Missing is not forbidden.** Only a typed not-found tag means "gone".
  A permission error treated as not-found drops the row from state and
  leaks the resource. If the API returns 403 for missing resources, patch
  distilled with a specific tag for that case.
- **Lists fail loudly and paginate.** A `list` that swallows errors reports
  "nothing here" to nuke and hides leaks. Use the SDK's paginated
  `.items(...)` stream.
- **Ownership markers go in labels or tags.** When the API has neither,
  document the fallback marker in the resource JSDoc; never put markers in
  fields users see or that change behaviour.
- **Shared helpers live once per provider** (operation waiter, not-found
  helper, label diffing). Copies per service drift apart.
- **Enable what the account needs.** Clouds that require a service to be
  switched on per account (Azure resource provider registration, GCP API
  enablement) get an idempotent enable step inside `reconcile`, so a fresh
  account deploys without manual setup.
- **Clean up after a failed create.** `read` and `delete` work when `olds`
  or parts of `output` are missing, so the next run's opening `destroy`
  removes whatever a crashed run left behind. Prove it once by interrupting
  a create.
- **SQL databases take `migrations`.** Every resource that hosts a SQL
  schema applies migrations on deploy through `@alchemy.run/sql/Migrations`;
  the provider only writes the cloud-specific call, built on its executor
  helpers (`withPgExecutor`, `makeStatementExecutor`, `splitSqlScript`). Prefer the
  cloud's HTTPS data API, then a direct or connector connection, then an
  in-network runner, and take credentials from the platform before asking
  for `migrationsUser` / `migrationsPassword`. Follow **SQL database
  migrations** in `AGENTS.md`; a SQL database shipped without migrations is
  incomplete.
- **Implement `list`** filtered to Alchemy-owned resources, and declare
  `nuke: { dependsOn: [...] }` where delete order matters, so
  `alchemy unsafe nuke` can clean the test account.

## Step 5 — bindings and runtimes

Follow the binding sections of `AGENTS.md`, then copy the AWS and GCP
packages: they are the reference for how bindings reach their host, and
most questions are answered by reading the closest existing binding. The
pattern was set by these PRs; read their descriptions when a case isn't
obvious from the code:

| PR | What it settled |
| --- | --- |
| #2260 | bindings state what they need; a `<P>Bindings` module decides how the host gets it (`packages/aws/src/AWSBindings.ts`) |
| #2347 | `Bind` / `withCredentials` effectful constructors, identity from real resources, `__ALCHEMY_HOST_IDENTITY__` bundle fold (`packages/gcp/src/GCPBindings.ts`) |
| #2267 | deploy-only services read behind the runtime guard; `*Http` bindings on local resources fail with a typed error (`packages/cloudflare/src/HttpBindingDev.ts`) |
| #2244, #2315 | no branching on another provider's host type; reach the host through `RuntimeContext` and core host services (`alchemy/WebhookHost`) |

**Cover every `binding` operation** in the catalog. Follow the AWS
shape: one `Binding.Service` per operation (`SQS.SendMessage`,
`DynamoDB.GetItem`), each with an `<Op>Http.ts` layer built on the
distilled operation, which injects the bound resource's identifier and
grants only that operation on that resource. Where the API has clear
access levels (object storage, key-value stores), also ship the
Read/Write/ReadWrite services from `AGENTS.md` on top of the per-operation ones.

Least privilege depends on the cloud's permission model:

- **Per-action permissions** (AWS IAM): grant the operation's actions on
  the resource ARN, as `scripts/audit-service.ts` checks.
- **Role-based** (GCP IAM, Azure RBAC): grant the smallest predefined
  role that covers the operation, on the resource, never the project or
  subscription. If the smallest predefined role covers much more than the
  operation, create a custom role with exactly the permissions or data
  actions it needs, and reuse it across hosts.

Every binding is a distilled call: the `<Op>Http.ts` layer wraps
`<service>.<operation>` from `@distilled.cloud/<pkg>`. If the operation
isn't in distilled (the data plane is missing, or the operation isn't
modelled), patch distilled first (step 1).

**Declare** each capability as an interface plus factory:

```ts
export interface SendMessage extends Binding.Service<
  SendMessage,
  "AWS.SQS.SendMessage",
  (queue: Queue) => Effect.Effect<(request: SendMessageRequest) => Effect.Effect<…>>
> {}
export const SendMessage = Binding.Service<SendMessage>("AWS.SQS.SendMessage");
```

**Reach any host.** A binding works on the provider's own compute and on
every other cloud's: a Lambda can bind a GCP topic, a Cloudflare Worker
an SQS queue. `src/<Provider>Bindings.ts` owns the decision and exports:

- `HostBinding` — what a binding attaches: grants (IAM statements, role
  bindings, role assignments) plus `env`.
- `Bind` — yields a tagged-template `bind`. On a host that runs as the
  cloud's own identity (`runsAsRole`, `runsAsServiceAccount`; an Azure
  managed identity) the grants go on that identity. Any other host gets an
  identity built from the provider's own resources (IAM `User` +
  `AccessKey` + `Role` on AWS, `ServiceAccount` + `ServiceAccountKey` on
  GCP), the grants go on it, and its key goes into the host's env through
  `CurrentRuntimeContext`. With no host (a script, plan-time `execute`) it
  does nothing. In a host bundle it is a no-op, so the identity resources
  drop out.
- `withCredentials(operation)` — resolves a distilled operation once when
  the layer is built: the host's ambient identity, the bound key read back
  from `RuntimeContext`, or the deployer's credentials.
- `<identity>HostBundle` — the rolldown option the provider's own host
  bundlers apply (`Lambda/FunctionBundle.ts`, `CloudFunctions/FunctionSource.ts`,
  the `ImageSource.ts` files). It sets `__ALCHEMY_HOST_IDENTITY__` (declared
  in core's `Phase.ts`) so the created-key path drops out of native bundles.

A binding layer then reads:

```ts
Effect.gen(function* () {
  const publish = yield* GCPBindings.withCredentials(pubsub.publishProjectsTopics);
  const bind = yield* GCPBindings.Bind;
  return Effect.fn(function* (topic: Topic) {
    if (!globalThis.__ALCHEMY_RUNTIME__) {
      yield* bind`GCP.PubSub.WriteTopic(${topic})`({ iam: [/* scoped to topic */] });
    }
    return (message) => publish({ topic: …, body: … });
  });
});
```

Rules the reference code follows:

- Never call `host.bind(...)` from a binding, and never allowlist the
  provider's own host types; both lose foreign hosts. The exceptions are
  host-only attachments that make no sense elsewhere, and they get their
  own helper (`AWSBindings.bindVpc`, the Cloud SQL socket mount in
  `GCP.SQL.Connect`).
- Never name another provider's resource type (`host.Type ===
  "Cloudflare.Worker"`). Write env through `RuntimeContext` (`runtime.set`
  at deploy, `runtime.get` at runtime; secrets stay `Redacted`), and use
  core host services such as `WebhookHost` for anything else a host must
  provide.
- Services that only exist at deploy (`<P>Environment.current`, the
  account or project id for a grant) are read inside the
  `!globalThis.__ALCHEMY_RUNTIME__` block. Read at layer build, they crash
  a foreign host at init.
- Per-service grant helpers are constructors too (`GrantOnQueue` in
  `packages/aws/src/SQS/BindingHttp.ts`), and shared scaffolding lives in
  an unexported `BindingHttp.ts` so each `<Op>Http.ts` is a one-line
  `Layer.effect(Cap, make…({ … }))`.
- A provider with local emulation fails an HTTP binding to a locally
  emulated resource with a typed error naming the native binding and
  `Alchemy.remote()` (`HttpBindingUnsupportedInDev`).

Document any grant broader than the bound resource (a condition on a
project-level grant, say) in the binding's JSDoc, with the reason.

### Runtimes

Find every **runtime** in the catalog: a resource that runs the user's
code (functions, containers, services, workers, jobs, VMs that run a
program). Mark each one `runtime` in `INDEX.md`. Each ships in two
forms from the same resource:

**Effectful** — a class built with core's `Platform` (`alchemy/Platform`).
`main: import.meta.url` makes the file both the bundle entry and the
program. Construction binds resources, and the returned handlers run per
request:

```ts
export default class Api extends GCP.Function<Api>()(
  "Api",
  { main: import.meta.url },
  Effect.gen(function* () {
    const db = yield* GCP.Firestore.ReadWriteDatabase(Links);
    return {
      fetch: Effect.gen(function* () {
        const doc = yield* db.get("links/home");
        return yield* HttpServerResponse.json(doc?.fields ?? {});
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(GCP.Firestore.ReadWriteDatabaseHttp)),
) {}
```

**Async** — the same resource called as a plain function, with `main`
pointing at an ordinary handler file and no Effect. Alchemy bundles that
file as-is, with no Effect runtime in it. The `env` prop takes resources,
`Config` values, and literals, and `<Provider>.InferEnv<typeof Fn>`
types the handler's `env` argument:

```ts
// alchemy.run.ts
export const Ping = Railway.Function("Ping", {
  project: Site,
  main: "./src/ping.ts",
  env: { DATABASE_URL: db.connectionUri },
});
export type PingEnv = Railway.InferEnv<typeof Ping>;
```

```ts
// src/ping.ts
import type { PingEnv } from "../alchemy.run.ts";

export default {
  async fetch(_request: Request, env: PingEnv) {
    return new Response(env.DATABASE_URL ? "ok" : "missing");
  },
};
```

Copy both forms from the runtime closest to yours:

| Runtime | File | Notes |
| --- | --- | --- |
| Cloudflare Worker | `packages/cloudflare/src/Workers/Worker.ts`, `InferEnv.ts` | the full reference: `env` entries become native bindings |
| Railway Function | `packages/railway/src/Function.ts`, `InferEnv.ts` | bindings are env vars, so `InferEnv` maps to `string` |
| GCP Cloud Run, Hetzner Service | `packages/gcp/src/Run/Service.ts`, `packages/hetzner/src/Service.ts` | `Platform` over a container or process |
| AWS Lambda | `packages/aws/src/Lambda/Function.ts` | async form exists but has no `InferEnv`; don't copy that gap |

Every runtime needs:

- **Both forms**, each with its own JSDoc section (`### Effect …` and
  `### Async …`) showing the stack declaration and the handler file.
- **`InferEnv`** exported from the package, so async users get a typed
  `env` without writing the type by hand.
- **The `HostBinding` contract** on the resource, so effectful bindings
  from this and other providers can attach grants and env.
- **The host bundle option** (`<identity>HostBundle`) on the effectful
  bundle, and a source-only `Bootstrap` export for the process entry
  (`packages/hetzner/src/Bootstrap.ts`, `packages/aws/src/Bootstrap/`).
- **Event sources** for what the cloud triggers it with (queues, topics,
  storage events, schedules), shaped like AWS `SQS.QueueEventSource` and
  Cloudflare cron. Their contract lives in the source service and each
  runtime provides an implementation layer.
- **A Website target** when the runtime is how the cloud serves
  server-rendered pages (step 7).
- **Tests for both forms**: a fixture per form under
  `test/<Provider>/<Service>/fixtures/` (`effect-worker.ts` and
  `async-worker.ts` in `test/Cloudflare/Images/` are the pattern), each
  deployed and called over HTTP.

### Workflow engine

If the cloud has a durable execution engine, the provider ships an Effect
workflow engine on it, so `alchemy/Workflows` code runs there unchanged.
Follow **Effect workflow engines** in `AGENTS.md`: it covers the DX to
keep, the two engine shapes, the shared encoding module, and the eight
conformance cases.

| Cloud | Engine | Status |
| --- | --- | --- |
| Cloudflare | `Cloudflare.Workflows.NativeEngine` (Cloudflare Workflows), `DurableObjectEngine` | done, in-process |
| AWS | `AWS.Lambda.WorkflowFunction` + `DurableFunctionEngine` (Lambda durable functions) | done, host + remote |
| Azure | Durable Functions on the Durable Task Scheduler (`Azure.DurableTask.Scheduler` exists) | missing |
| GCP | no code-first durable runtime; Cloud Workflows is a YAML orchestrator | decide and record in the catalog before building |

Research the cloud's engine in step 2 and record it in the catalog: its
durable step, durable sleep, external-event or callback primitive, how a
run is interrupted, and its limits. Then decide the shape:

- **In-process** when the runtime that starts runs can also host the
  durable construct (Cloudflare). The engine is a Layer provided next to
  the workflow Layers.
- **Host + remote** when runs need a dedicated durable runtime (Lambda
  durable functions, and most likely Azure Durable Functions). Ship a
  `<Runtime>.WorkflowFunction`-style host that lists its workflows, and a
  `<Runtime>Engine(...hosts)` Layer that routes to it and grants access.

If the cloud has no durable engine, or only one that can't run code
steps, write `out-of-scope` with the reason on the engine's index row.
Don't build a database-backed engine of your own.

The engine counts as a runtime: it gets its own index row, the
conformance suite, an `examples/<provider>-effect-workflows` example, and
a `compute/effect-workflows.mdx` page in the docs hub.

## Step 6 — live tests

Tests live in `packages/integration-tests/test/<Provider>/` (paths below
are relative to `packages/integration-tests`). Write them per the test
sections of `AGENTS.md` (`test.provider`,
`stack.destroy()` at start and end, deterministic names, out-of-band
verification through distilled, typed wait-until-gone). Run with the
profile from step 0:

```sh
pnpm test:integration test/<Provider>/<Service>/<Resource>.test.ts --profile testing --retry 0
```

What a test must prove:

- **Every resource has its own test file**
  (`test/<Provider>/<Service>/<Resource>.test.ts`). Deploying a resource
  as a dependency inside another resource's test does not count, because
  its own update, replace, and delete paths never run.
- **Lifecycle runs by default.** Create, update, and (where applicable)
  replace against the real API. Slow lifecycles are gated behind one
  provider-wide flag with a realistic timeout; entitlement-bound ones keep
  an ungated probe that asserts the one specific typed tag the account
  returns.
- **Bindings run inside a deployed host** (a fixture Worker, Function, or
  container calling the binding over HTTP) so the IAM grant or native
  binding is exercised with the host's identity, not the deployer's. Test
  both paths of `Bind`: the provider's own host, and a foreign host using
  the created key in `test/<Provider>/ExternalHost/CloudflareWorker.test.ts`
  (copy `test/GCP/ExternalHost/`). If the provider hosts code, also add
  its host to the other providers' external-host suites
  (`test/Cloudflare/ExternalHost/Lambda.test.ts` is the pattern).
- **Every binding has a test.** One `describe("<BindingName>")` per
  binding, all driving the same deployed fixture host
  (`test/AWS/DynamoDB/Bindings.test.ts` + `handler.ts` is the pattern).
  A binding no test calls from a host is not done.
- **Assertions can fail.** No always-true checks, no lists of acceptable
  tags, no early `return` that skips the assertions.

**Expensive resources** (dedicated clusters, large VMs or databases,
reserved capacity, anything billed per hour at a noticeable rate) are
implemented and get full tests, but you do not run those tests on your own.
Gate them behind the provider-wide slow flag, mark them `blocked: cost` in
the index, and list them for the user with an estimate of what one run
costs. Run them only after the user says so.

Scarce account quotas (networks, clusters, IP addresses) are shared with a
semaphore in a test helper, or moved to less-used regions. The suite still
runs in one process: `pnpm test:integration test/<Provider> --profile testing`.

Unblock account prerequisites in the dedicated test account yourself as
soon as a test hits them. Request quota increases and register preview
features through the provider's API (anything that raises spend needs the
user's go-ahead from step 0 or step 6's cost rule),
and put any setup a fresh account would need again into the test helper.
Do one-time console work (free trials, free organizations, sign-ups) in the
browser with whatever browser-automation skill the harness has, and ask the user only to sign in.
A row stays `blocked` only when it needs payment, a vendor's approval,
hardware, or is skipped under the long-tail rule below; report each one
with the exact request that would unblock it.

Failure-path tests assert the typed error and finish in minutes. Give them
a short timeout and never let them wait out a slow provisioning or delete;
a single test case that runs for an hour is a bug in the test.

Stop chasing the long tail after the three-iteration budget from the
**Speed doctrine** in `AGENTS.md`, or as soon as the user says so. When the
remaining failures are slow provisioning, platform behavior, or test
infrastructure the cloud needs (a reachable endpoint, a custom image),
let the current run finish, then skip-gate each failing case with its
exact error, mark the row `blocked: skipped` in the index, and list those
rows in the next report so the user can reopen any. When the user sets a
deadline, cap test fixing at half of it and spend the rest on the other
deliverables (bindings, runtime, websites, examples, docs, PR). On Azure,
fix rounds on one-hour tests kept running after the user asked to skip
them, until the user set a one-hour deadline to wrap up.

## Step 7 — framework websites

**Skip this step when the provider can't host a website.** Most
providers can't: observability, payments, databases, and auth (Axiom,
Stripe, Turso, PlanetScale) have no web hosting, so they ship no
`Website` namespace and get no "N/A" rows in the index. This step is
for providers that serve HTTP or static files.

Those providers ship `<Provider>.Website.<Framework>` composites, so a
user deploys an Astro or Next.js app with one call:

```ts
const site = yield* AWS.Website.Astro("Site", { rootDir: "./web" });
```

### Use the cloud's web hosting, not a container

A website deploys onto the infrastructure the cloud built for websites:
static assets on a CDN, and server rendering on the cloud's serverless
functions behind that same

…(truncated)
