--- name: alchemy-provider description: Bring up a new Alchemy cloud provider (its own `@alchemy.run/` package under packages/) 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 provider", "create an alchemy provider for ", "port to alchemy", "add to the provider", "bring the provider up to par", or any work that needs a distilled SDK plus Alchemy resources tested against a live API. --- # 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/ && 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. If the provider supports OIDC or workload identity federation for deploys (GitHub Actions, a cloud's identity pool), ask for that setup and wire it through `alchemy/Auth/OidcToken`; a long-lived API key is the fallback, not the default; - 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 ` (use the profile name the user asks for). Tests select it with `--profile `. 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/` in `submodules/distilled/packages/`). 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//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.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 ` 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//src/services`) before writing resources; for a large SDK, fan the catalog out as a workflow (see Orchestration). Each service gets `processes//catalog/.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` + `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//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: `, 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/` in `packages/`, 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, `Auth` layer | | `src/Credentials.ts` | `fromAuthProvider()` = `lazyCredentials()(...)` → the distilled `Credentials` layer | | `src/Providers.ts` | `ProviderCollection` + `providers()` layer (provider layers, credentials, `FetchHttpClient`, auth, profile and credential stores) | | `src/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 from ".//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//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/` 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/` 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//src/globals.d.ts`; - `stacks/nuke.ts` — `.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//` (`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//src//.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 `

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 `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 `Http.ts` layer wraps `.` from `@distilled.cloud/`. 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("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/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`. It picks the host's identity in the order of "Federated identity over keys" in `AGENTS.md`: - On a host that runs as the cloud's own identity (`runsAsRole`, `runsAsServiceAccount`; an Azure managed identity) the grants go on that identity. - On a host whose platform signs identity tokens (`runsAsGoogleServiceAccount` and `runsOnFlyMachines` in `AWSBindings`; `runsAsAwsRole` and `runsOnFlyMachines` in `GCPBindings`) it creates a trust scoped to that one workload (a Role that trusts the token's subject, a workload identity pool member for one role or App), and the grants go on it. No key exists. - Only a host with no platform identity (a Cloudflare Worker) gets an identity built from the provider's own resources (IAM `User` + `AccessKey` + a Role that user alone may assume on AWS, `ServiceAccount` + `ServiceAccountKey` on GCP), 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. When you add a provider, or a new kind of runtime, check whether its platform issues OIDC tokens or signs requests before reaching for the key path, and add a federated branch to every cloud's `

Bindings` that can trust it. A runtime that has tokens implements `BaseRuntimeContext.oidcToken(audience)` and sets `__ALCHEMY_HOST_IDENTITY__` in its bundler. - `withCredentials(operation)` — resolves a distilled operation once when the layer is built: the host's ambient identity, a token exchange (`AssumeRoleWithWebIdentity`, Google STS) for a federated host, the bound key read back from `RuntimeContext`, or the deployer's credentials. - `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 (`

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 `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", { 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 `.InferEnv` 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; ``` ```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** (`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///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 `.WorkflowFunction`-style host that lists its workflows, and a `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/-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//` (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///.test.ts --profile testing --retry 0 ``` What a test must prove: - **Every resource has its own test file** (`test///.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//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("")` 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/ --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 `.Website.` 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 CDN. Putting the whole build in a container or an always-on VM, with no CDN, is the lazy default. It is not done, even though it works for every framework on the first try. Azure's first pass did exactly that. All 14 frameworks, the static-only ones included, became a Docker image on Container Apps. A follow-up moved static builds to a Storage static website and server builds to an always-on App Service plan, with Front Door optional. That is still a VM instead of functions, and no CDN by default. GCP's composites still deploy a Node image to Cloud Run for every framework, `StaticSite` included. Copy neither. Pick the hosting per cloud before writing code, and record the choice and its reason in the catalog: | Kind of provider | Static assets | Server rendering | Reference | | --- | --- | --- | --- | | Hyperscaler with a CDN and functions | object storage behind the CDN | serverless functions as the CDN's dynamic origin | `packages/aws/src/Website/` (S3 + CloudFront + Lambda, `SsrSite.ts`) | | Edge platform | the platform's asset hosting | the platform's functions | `packages/cloudflare/src/Website/` (Workers + static assets) | | Platform with its own function runtime | the platform's asset hosting | its functions, through a framework target | `packages/neon/src/Website/` (`frontend-frameworks//neon.ts`) | | Containers or VMs only | served by the same Node server, behind the platform's CDN when it has one | the Node server | `packages/fly/src/Website/`, `packages/hetzner/src/Website/`, `packages/railway/src/Website/` (`Cdn.ts`) | What that means for the clouds still to be built: - **Azure:** Static Web Apps, or Blob static website behind Front Door, with server rendering on Azure Functions (Flex Consumption). Not Container Apps, not an App Service plan. - **GCP:** a Cloud Storage bucket behind Cloud CDN on an external HTTPS load balancer, with Cloud Run or Cloud Functions as the serverless origin for server rendering. Assets-only sites never run a container. Rules: - An assets-only build (Vite, StaticSite, SPA output) never runs compute. - The CDN is on by default, not behind a `cdn: true` flag. Assets are uploaded with content hashes and cache headers, and a deploy invalidates or purges what changed (`AssetDeployment.ts` + `CloudFront.Invalidation` on AWS). - Server rendering runs on functions that scale to zero. A container or VM is acceptable only when the cloud has no function runtime, or when a framework needs a long-lived process. Document that framework's reason in its JSDoc. - Functions need a framework target: a new `packages/frontend-frameworks/src//.ts` next to `aws.ts`, `cloudflare.ts`, and `neon.ts`, producing a handler for the cloud's function runtime. Only container/VM providers use the Node target (`@alchemy.run/frontend-frameworks//node`) through core's `alchemy/Website/Server`. - Before choosing a container, check whether the cloud's docs have a hosting page for the framework (Azure Static Web Apps has one for Next.js, Nuxt, Astro, and SvelteKit). If they do, use what it uses. ### Layout Ship the same framework set as the existing providers (`ls packages/aws/src/Website` and `packages/hetzner/src/Website`: Astro, Foldkit, Nextjs, Nuxt, Octane, ReactRouter, SolidStart, StaticSite, SvelteKit, TanStackStart, Vinext, Vite, Vocs, Waku): - `FrameworkSite.ts` owns `makeFrameworkSite`, which builds through the framework integration (`@alchemy.run/frontend-frameworks/`) and deploys the output onto the hosting above. Its shared props (`rootDir`, `memo`, `dev`, `env`, `assets`, `domain`, `tags`) keep the names and meaning the sibling providers use. - One small file per framework that only sets the framework specifier, the deploy target, and the framework's own option block. - `StaticSite.ts` for assets-only sites, and `index.ts` exported from the provider barrel as `export * as Website from "./Website/index.ts"`. Each framework gets a live `packages/integration-tests/test//Website/.test.ts` that asserts the response comes through the CDN (a cache header, or the CDN hostname) and that a server-rendered route hits the function; a `.local.test.ts` for `alchemy dev`; and a shared `PropSurface.test.ts`. It also gets an `examples/-website-` example listed in `scripts/test-examples.ts`, and a page under `website/src/content/docs//frontend/`. ## Step 8 — close the loop Every failure the live run exposes is classified before it is fixed, in this order: **provider bug > distilled patch > test fix**. | Symptom | Fix | | --- | --- | | `UnknownError`, or a status/message you want to branch on | typed error patch (`distilled-sdk-patch`) | | decode failure, field null or missing on the wire | nullable/optional patch | | secret returned as a plain string | sensitive patch | | resource leaks, returns before ready, wrong replace | provider fix in alchemy | | test asserts something the API does not promise | test fix | After a patch, regenerate only that package (`pnpm generate ` in the submodule) and rerun the test immediately — the test runner reads distilled from `src/`, so there is nothing to build. Collect the patches, prove each with `pnpm patches:audit`, and ship them as a distilled PR, then bump the pin (step 1). After a full run, list what is still alive in the test account (`pnpm nuke --dry-run --profile testing --include .*` or the provider's list calls). A green test that leaves resources behind is a provider bug. ## Step 9 — review gate Run every check in [review.md](review.md) with a fresh reviewer subagent and fix what it finds. Report the result table to the user with the counts, so they can see what was checked without re-reviewing by hand. ## Step 10 — docs, examples, and the PR - JSDoc on every resource, prop, attribute, and binding, to the bar in [docs.md](docs.md#api-reference-jsdoc): runtimes as complete as `AWS.Lambda.Function`, fat-head resources as complete as S3 Bucket or R2 Bucket, and a creation example plus replacement cautions for the long tail. Then run `pnpm docs:check-jsdoc` and `pnpm docs:gen`. - The hand-written hub at `website/src/content/docs//`, built to [docs.md](docs.md): the AWS hub's structure (Overview, Setup, a five-part tutorial, sections by concern), code taken from tested examples, and the voice rules there. A hub of loose "guides" that walk the examples is not done; GCP's had to be rebuilt. - The example set described under **Examples** below. - Type-check with `pnpm exec tsrs -b`, run `pnpm exports:check` and `pnpm lint:providers`, and format with `pnpm exec oxfmt`. - Open the alchemy PR per **Pull Request Conventions**, linking the distilled PRs it depends on. The description shows the provider's DX, not a list of what was built: - One or two lines on what the package is, then a few bullets of counts (services, resources, live test files, gated tests). - A `###` section for every runtime (each form), the event sources, and the websites. - A `###` section for each **fat-head** resource: the 10–20 that most apps on this cloud use (resource groups or projects, identity and roles, object storage, the main SQL and document databases, queues and topics, secrets, the container registry, networking and DNS, logs). Pick them from the cloud's own quickstarts, not from the catalog's order. Group a resource with the ones it's always used with (a namespace and its queue) and its bindings. - Each section is one or two sentences, then one snippet copied from that resource's JSDoc example, so the code is already checked. - One closing line names the long tail and points to the generated reference. Don't list it. Don't show a binding running in a host unless a test deploys it that way. On Azure, the description was going to show bindings inside `Azure.Functions.Function`, which isn't a registered binding host, so those bindings did nothing. ### Examples Examples are how users learn the provider, and the docs hub copies its code from them. Ship a comprehensive set, not one or two. Azure's first pass shipped `azure-storage` (a Stack with no runtime) and one website; AWS, Cloudflare, Fly, and Hetzner ship one example per framework plus one per workload. **Every web framework gets its own example**, for every provider that hosts websites: `examples/-website-`, one per `.Website.` composite (Astro, Foldkit, Nextjs, Nuxt, Octane, ReactRouter, SolidStart, SvelteKit, TanStackStart, Vinext, Vite, Vocs, Waku, plus `-static-site`). `ls examples | grep hetzner-website-` is the complete set to match. **Then one example per workload the cloud supports.** Go down this list and add an example for every row the provider has, and skip the rest: | Workload | Shows | AWS / GCP / Cloudflare reference | | --- | --- | --- | | Serverless function, effectful | an HTTP handler with a binding to storage or a database | `aws-lambda`, `gcp-cloud-function`, `cloudflare-worker` | | Serverless function, async | the same with a plain handler and `InferEnv` | `cloudflare-worker-async` | | HTTP API | Effect HTTP API or RPC on the default runtime | `aws-lambda-httpapi`, `aws-lambda-rpc`, `gcp-cloud-run-api` | | Queue | a producer and a consumer through an event source | `gcp-pubsub-worker`, `gcp-pubsub-fanout` | | Scheduled job | a cron trigger | `gcp-cron`, `gcp-scheduled-job` | | Storage events | a function triggered by an upload | `gcp-storage-uploads`, `gcp-eventarc-firestore` | | Durable workflows | `alchemy/Workflows` on the provider's engine (Step 5): start, signal, read a run | no example yet; copy the conformance fixtures in `packages/integration-tests/test/Cloudflare/Workers/fixtures/durable-workflow/` | | Containers | a container service | `aws-ecs`, `fly-service` | | Kubernetes | a Deployment on the cloud's managed cluster | `aws-eks`, `gcp-gke` | | VMs | a VM running a program | `aws-ec2`, `hetzner-server` | | SQL database | a database with migrations, from a runtime | `aws-rds`, `gcp-cloud-sql-drizzle` | | Cache | Redis from a runtime | `gcp-memorystore-redis`, `fly-redis` | | Secrets | a secret read by a runtime | `gcp-secrets-kms` | | AI | the cloud's model service | `aws-bedrock-ai`, `gcp-vertex-ai` | | Service to service | two runtimes calling each other | `gcp-service-to-service` | | Local dev | the same app under `alchemy dev` | `aws-dev`, `cloudflare-dev` | Name examples `-` in kebab case. Each one is a workspace project with the layout of `examples/gcp-pubsub-worker`: - `package.json` (private, `deploy` / `dev` / `destroy` / `test` scripts, `workspace:*` dependencies), `tsconfig.json` referencing `packages/alchemy` and the provider package, and a `README.md`. - `alchemy.run.ts`, with the runtime and resources in `src/`. - `test/integ.test.ts` with `@alchemy.run/test/Bun`: deploy in `beforeAll`, call the deployed app over HTTP, verify cloud state through distilled, destroy in `afterAll`. Websites and `dev`-capable apps also get `test/dev.test.ts`. Register every example in the root `tsconfig.json` references and in `scripts/test-examples.ts`, and run its test against the testing profile before you call it done. Track examples as rows in `INDEX.md` like any other deliverable. A draft PR for an early wave is fine; its description states the index counts and that the provider is incomplete. A provider is done when: - every SDK service is cataloged and every operation is classified; - every in-scope resource has its own passing live test (or is `blocked: cost` / `blocked: skipped` and the user has the list); - every `binding` operation is a least-privilege binding over distilled, goes through `Bindings.Bind`, reaches foreign hosts, and is called from a deployed host in a test; - no alchemy code makes a hand-written API call (review.md's "Hand-written HTTP" check is clean); - every runtime ships both forms with `InferEnv`, its event sources, and tests for each form; - the cloud's durable engine has an Effect workflow engine that passes the conformance cases, or is out of scope with a reason; - the framework websites (if the cloud hosts websites) deploy to its CDN and functions; - the example set (one per framework, one per workload) deploys and passes; - JSDoc meets the bar in [docs.md](docs.md), the reference docs are generated, and the hub matches [docs.md](docs.md); - the PR description shows the runtimes and the fat head; - the review gate is clean, the test account is clean after a full run, and every SDK mismatch found along the way is a merged distilled patch.