/.repos/alchemy-effect/AGENTS.md at HEAD | the-knife

1	# alchemy
2
3	Alchemy Effect is an Infrastructure-as-Effects (IaE) framework that extends Infrastructure-as-Code (IaC) by combining business logic and infrastructure config into a single, type-safe program expressed as Effects.
4
5	It includes a core IaC engine built with Effect. Effect provides the foundation for type-safe, composable, and testable infrastructure programs. It brings errors into the type-system and provides declarative/composable retry logic that ensure proper and reliable handling of failures.
6
7	# Concepts
8
9	- Cloud Provider - a cloud provider that offers a set of Services, e.g. AWS, Azure, GCP, Cloudflare, Stripe, Planetscale, Neon, etc.
10	- Service - a collection of Resources, Functions, and Bindings offered by a Cloud Provider.
11	- Resource - a named entity that is configuted with "Input Properties" and produces "Output Attributes". May or may not have Binding Contract.
12	- Input Properties - the properties passed as input to configure a Resource. Otherwise known as the "desired state" of the Resource.
13	- Output Attributes - the attributes produced by a Resource. Otherwise known as the "current state" of the Resource.
14	- Stable Properties - properties that are not affected by an Update, e.g. the ID or ARN of a Resource.
15	- Function (aka. Runtime) - a special kind of Resource that includes a runtime implementation expressed as a Function producing an `Effect<A, Err, Req>`. The `Req` type captures runtime dependencies, from which Infrastructure Dependencies are inferred.
16	- Resource Provider (see [Provider](./packages/alchemy/src/Provider.ts))
17
18	A Resource Provider implements the following Lifecycle Operations:
19
20	- Diff - compares new props with old props and determines if the Resource needs to be updated or replaced. For updates, it can also specify a list of Stable Properties that will not be changed by the update.
21	- Read - reads the current state of a Resource and returns the current Output Attributes. May return `Unowned(attrs)` to signal an existing-but-foreign resource that the engine should refuse to take over unless `--adopt` is set.
22	- Pre-Create - an optional operation that creates a stub of a Resource before reconcile runs. Used to resolve circular dependencies — e.g. Function A and B depend on each other, so we create a stub of Function A first and then `reconcile` later wires up the real dependency.
23	- Reconcile - converges a Resource's actual cloud state to the desired state described by the new Input Properties. Called for both first-time provisioning and subsequent updates. The provider receives `output` (current Attributes) and `olds` (previous Props) which may both be `undefined` on a greenfield create, both defined on an update, or `output !== undefined && olds === undefined` on an adoption. See the Reconciler doctrine section below for the required shape.
24	- Delete - deletes an existing Resource. It must be designed as idempotent because it is always possible for state persistence to fail after the delete operation is called. If the resource doesn't exist during deletion, it should not be considered an error.
25	- Capability - a runtime requirement of a Function (e.g. require read access to an `R2Bucket`, or `SQS.SendMessage` on a `SQS.Queue`). A Capability is modeled as one or more `Binding.Service`s. Where the underlying API distinguishes access levels, split it into `Read` / `Write` / `ReadWrite` services (see the Read/Write/ReadWrite binding convention below); otherwise a single service suffices. Each service typically ships two interchangeable implementations: a native binding (`Binding`) and a token-scoped HTTP* client (`*Http`).
26	- Binding.Service - an Effect Service that exposes a `.bind(resource)` method returning a typed runtime client. Its outer (init) Effect resolves the host Function/Worker and its environment, then registers the deploy-time binding — environment variables, IAM policy statements (AWS), or a native Cloudflare binding — by calling ``host.bind`${resource}`(data)``, guarded by `!globalThis.__ALCHEMY_RUNTIME__` so it is a no-op once running inside the deployed Function/Worker. Provided as a Layer on the Function/Worker Effect so it gets bundled into the Lambda/Worker. See [Binding](./packages/alchemy/src/Binding.ts).
27	- Binding - data attached to a target Function/Worker via ``host.bind`${resource}`(data)`` from inside a `Binding.Service`. The binding data is collected on the Stack during plan/deploy. Bindings enable circular references between Resources — e.g. a capability binds `{ policyStatements: [...] }` (AWS) or `{ bindings: [...] }` (Cloudflare) onto the host. The Resource Provider then receives the resolved binding data in its `reconcile` lifecycle operation via the `bindings` parameter.
28	- Binding Contract - the shape of data a Resource accepts from Bindings. For example, a Lambda Function accepts `{ env?: Record<string, any>, policyStatements?: PolicyStatement[] }` because it needs environment variables and IAM policies. A Cloudflare Worker accepts `{ bindings: Worker.Binding[] }` for its native binding system. The Binding Contract is declared as the fourth type parameter on the `Resource` interface. See [Lambda Function](./packages/alchemy/src/AWS/Lambda/Function.ts) and [Cloudflare Worker](./packages/alchemy/src/Cloudflare/Workers/Worker.ts).
29	- Dependency - Resources depend on other Resources through two mechanisms:
30	- Output Properties of one Resource passed as Input Properties to another Resource (non-circular, directed acyclic graph)
31	- Bindings that attach data (IAM policies, env vars, Cloudflare bindings) from one Resource to another, enabling circular references between Resources.
32	- Output - a reference to (or derived from) a Resource's "Output Attributes". E.g. Bucket.bucketArn
33	- Stack - a collection of Resources, Functions, and Bindings that are deployed together.
34	- Stack Name - the name of a Stack, e.g. `my-stack`
35	- Stage - the stage of a Stack, e.g. `dev`, `prod`, `dev-sam`
36	- Stack Instance - a deployed instance of a Stack+Stage
37	- Resource Type - the type of a Resource, e.g. `Bucket`, `Instance`
38	- Physical Name - a unique name for a Resource, e.g. `my-bucket-1234567890`. It is usually best to generate them using the built-in createPhysicalName utility function which generates
39	- Logical ID - the logical ID identifying a resource within a Stack, e.g. `my-bucket`. It is stable across creates, updates, deletes and replaces.
40	- Instance ID - a unique identifier for an instance of a Resource. It is stable across creates, updates and deletes. It changes when a resource is replaced. It is truncated and used as the suffix of the Physical Name.
41	- Event Source - a special kind of Binding between a Function and a Resource that produces events that invoke the Function, e.g. `SQS.QueueEventSource`. Implemented as a `Binding.Service` whose init Effect both registers the runtime event listener on the host and, at deploy time, yields the event-source mapping resource (or calls the cloud provider API to create/update it).
42	- Replacement - the process of replacing a Resource with a new one. A new one is created, downstream dependencies are updated with the new reference, and then the old one is deleted. Or, the old one is deleted first and then the new one is created.
43	- Dependency Violation - an error that some APIs call when an operation cannot be performed because a dependency is not met. E.g. you cannot delete an EIP until the NAT Gateway it is attached to is deleted. Lifecycle operations typically retry Dependency Violations.
44	- Eventual Consistency - create/update/delete operations can be eventually consistent leading to a variety of failure modes. For example, a Resource may be created but not yet available for use, or a Resource may be deleted but still appear in the console. Errors caused by eventual consistency should be retried, and lifecycle operations/tests should be carefully designed to wait for consistency before proceeding.
45	- Retryable Error - an error that can be retried. E.g. a Dependency Violation, Eventual Consistency Error, Transient Failure, etc.
46	- Non-Retryable Error - an error that cannot be retried. E.g. a Validation Error, Authorization Error, etc.
47	- Retry Policy - a policy for retrying errors. E.g. a fixed delay, exponential backoff, max retries, while some condition is true, or until some condition is true/false, etc.
48
49	# File System Conventions
50
51	First-class sibling repositories we maintain live in `submodules/`:
52
53	- `submodules/distilled` — generated Effect SDKs (workspace packages). Initialized by `git submodule update --init`.
54	- `submodules/floci` — our fork of the local AWS emulator. Skipped by default; fetch with `git submodule update --init --checkout -- submodules/floci`.
55
56	Each Service's Resources follow the same pattern. Resource contract and provider are co-located in the same file. Each Capability lives in its own file(s) named after the capability and access level (`Binding.Service` contract + the `Binding` / `Http` implementations).
57
58	```sh
59	# source files
60	packages/alchemy/src/{Cloud}/{Service}/index.ts # re-exports resources, capability contracts, and impl layers
61	packages/alchemy/src/{Cloud}/{Service}/{Resource}.ts # resource contract + resource provider
62	packages/alchemy/src/{Cloud}/{Service}/{Capability}.ts # Binding.Service contract + runtime client interface
63	# test files
64	packages/alchemy/test/{Cloud}/{Service}/{Resource}.test.ts
65	# docs (auto-generated from source-code JSDoc - DO NOT manually edit)
66	website/src/content/docs/providers/{Cloud}/{Resource}.md # API reference, generated by `pnpm docs:gen`
67	```
68
69	A capability that exposes distinct access levels is split into a contract per level plus interchangeable native-binding and HTTP implementations, with shared scaffolding kept in un-exported helper files (see the Read/Write/ReadWrite binding convention below). For example, the Cloudflare R2 bucket capability:
70
71	```sh
72	packages/alchemy/src/Cloudflare/R2/BucketTypes.ts # shared types + error (exported)
73	packages/alchemy/src/Cloudflare/R2/BucketRead.ts # BucketRead Binding.Service + ReadBucketClient (exported)
74	packages/alchemy/src/Cloudflare/R2/BucketWrite.ts # BucketWrite Binding.Service + WriteBucketClient (exported)
75	packages/alchemy/src/Cloudflare/R2/BucketReadWrite.ts # BucketReadWrite Binding.Service + ReadWriteBucketClient (exported)
76	packages/alchemy/src/Cloudflare/R2/BucketBinding.ts # shared worker-binding scaffolding (NOT exported from index)
77	packages/alchemy/src/Cloudflare/R2/BucketReadBinding.ts # ReadBucketBinding layer + makeRead (exported)
78	packages/alchemy/src/Cloudflare/R2/BucketWriteBinding.ts # WriteBucketBinding layer + makeWrite (exported)
79	packages/alchemy/src/Cloudflare/R2/BucketReadWriteBinding.ts # ReadWriteBucketBinding layer (exported)
80	packages/alchemy/src/Cloudflare/R2/BucketHttp.ts # shared HTTP/token scaffolding (NOT exported from index)
81	packages/alchemy/src/Cloudflare/R2/BucketReadHttp.ts # ReadBucketHttp layer (exported)
82	packages/alchemy/src/Cloudflare/R2/BucketWriteHttp.ts # WriteBucketHttp layer (exported)
83	packages/alchemy/src/Cloudflare/R2/BucketReadWriteHttp.ts # ReadWriteBucketHttp layer (exported)
84	```
85
86	Examples of actual paths:
87
88	```sh
89	packages/alchemy/src/AWS/S3/Bucket.ts # S3 Bucket resource + provider
90	packages/alchemy/src/AWS/S3/GetObject.ts # S3 GetObject capability (Binding.Service)
91	packages/alchemy/src/AWS/S3/PutObject.ts # S3 PutObject capability (Binding.Service)
92	packages/alchemy/src/AWS/SQS/Queue.ts # SQS Queue resource + provider
93	packages/alchemy/src/AWS/SQS/SendMessage.ts # SQS SendMessage capability
94	packages/alchemy/src/AWS/Kinesis/Stream.ts # Kinesis Stream resource + provider
95	packages/alchemy/src/AWS/Kinesis/PutRecord.ts # Kinesis PutRecord capability
96	packages/alchemy/src/AWS/Lambda/Function.ts # Lambda Function resource + provider
97	packages/alchemy/src/AWS/DynamoDB/Table.ts # DynamoDB Table resource + provider
98	packages/alchemy/src/AWS/DynamoDB/GetItem.ts # DynamoDB GetItem capability
99	packages/alchemy/src/AWS/EC2/Vpc.ts # VPC resource + provider
100	packages/alchemy/src/AWS/EC2/Subnet.ts # Subnet resource + provider
101	```
102
103	# The Resource Factory Process
104
105	Alchemy resource coverage is produced as a software factory: fleets of agents implement and live-test IaC resources in waves, and every API mismatch the tests surface is fed back as a patch to distilled. The factory was used to take Cloudflare from 36 to 239 cataloged resources (250 test files / 600+ test cases, 1000+ patched operations) and is the template for every future provider.
106
107	## The flywheel
108
109	```
110	catalog ──> implement ──> live test ──> unmatched error / wrong schema?
111	^ │
112	│ v
113	update statuses <── regenerate service <── patch distilled
114	```
115
116	1. Catalog — fan out research agents over the provider's distilled service modules (one batch per thematic group). Each agent reads the generated SDK (`submodules/distilled/packages/{cloud}/src/services/{service}.ts`), cross-references the vendor API docs, and writes a self-contained design spec to `processes/{Cloud}/catalog/{service}.md`: resources, namespaces, props/attrs with replacement rules, lifecycle-to-operation mapping, scope (account/zone), testability, priority. The coordinator aggregates a machine-readable `summary.json` + human `INDEX.md` that tracks `implemented \| partial \| missing` per resource — this is the factory's order book.
117	2. Implement + test in waves (below). Tests run against the real cloud (`pnpm test --profile testing`); zone-scoped tests use the standing test zone (`alchemy-test-2.us` via `findZoneByName`).
118	3. Patch the SDK, never the consumer — every `UnknownCloudflareError`, out-of-union status error, or wrong request/response schema found by a test becomes an RFC 6902 JSON Patch against the service's Smithy model, under `submodules/distilled/packages/{cloud}/patches/{service}/{op}.json` (see the Typed Error Doctrine section). Regenerate only that service. The typed union improves for every future consumer of the SDK — that is the flywheel's output.
119	4. Update the catalog statuses after each wave and pick the next batch from the order book. Repeat until everything left is documented as out of scope (deprecated APIs, billing/data-only endpoints, closed-beta, needs-external-systems).
120
121	## Orchestration rules (the coordinator)
122
123	- One workflow at a time, ~12 concurrent agents (cap ≈ CPU cores − 2). Two parallel workflows double throughput but also double crash blast-radius — only do it when the machine and budget clearly allow.
124	- One agent per distilled service. Service ownership is the unit of isolation: only the owner may touch `patches/{service}/` and regenerate `src/services/{service}.ts`, so generator runs never race. An agent may own several resources of its service; a very large same-service backlog (e.g. zero-trust) runs as a sequential chain of agents inside the workflow, in parallel with all other services.
125	- Shared-file discipline. `Providers.ts` and the provider barrel `index.ts` are edited by every agent: single minimal insertions only, re-read and retry on edit conflict, never rewrite wholesale.
126	- `Layer.mergeAll` ceiling. Keep `Providers.ts`'s provider layers in nested `Layer.mergeAll` groups (~90 entries each). A flat ~200-argument call exceeds tsc's variadic inference and silently drops the tail layers from the inferred union, producing baffling `Provider<X> is not assignable to StackServices` cascades across every test file.
127	- Crash resilience. Word every task as assess-first: "partial work may exist from an interrupted run — list your dirs, read existing files, check registration, FINISH rather than rewrite." Completed agent results are banked in the workflow journal even if the workflow dies; the coordinator recovers them from `journal.jsonl` and re-dispatches only the lost tasks.
128	- The coordinator (not agents) does: the authoritative type-check, distilled lib rebuilds, combined verification runs, catalog/index updates, cross-cutting fixes (shared-file restructures, Effect-version API migrations), and deterministic mass transforms (mechanical codemods are scripted centrally, not fanned out).
129	- Monitor for stalls: an agent transcript that hasn't been written for ~5 minutes with no child test process is stalled — kill and re-dispatch; don't wait.
130
131	## Resource budget: one type-checker for the whole factory
132
133	`tsc -b` over the workspace is expensive; dozens of agents running it concurrently thrashes the machine (and concurrent `tsbuildinfo` writes race). Instead:
134
135	- Agents are banned from running `tsc` or `pnpm build` (root or distilled) in any form. The coordinator owns type-checking and runs a one-shot `pnpm exec tsc -b` at wave boundaries.
136	- *The test runner resolves distilled from `src/.ts` directly, NOT the built `lib/` (`alchemy-test` runs in plain bun, which resolves the `bun` export condition natively). So a regenerated service is immediately test-visible the moment `bun scripts/generate.ts --resource {service}` (+ oxfmt) finishes — there is nothing to rebuild and nothing to wait for**. Do NOT sleep and do NOT gate a test re-run on a build after regenerating. This applies to response-schema patches as well as error-tag-only patches.
137
138	## Speed doctrine: never wait on a hang
139
140	- Run tests with `pnpm test` (works from the repo root or `packages/alchemy`; suite paths are relative to `packages/alchemy`, e.g. `test/Cloudflare/...`). Wrap every test invocation in a hard kill: `timeout 240 pnpm test <suite> --profile testing`. Hitting the wall is the failure — read the partial output (and the run's log under `.alchemy/log/test/`), find the hang (unbounded retry, infinite pagination, the engine deadlock below), fix the root cause. Never just re-run hoping. The runner also prints the currently-running tests whenever nothing finishes for 10s — use that list to identify the hang.
141	- Per-test timeout ≤ 90–120s (`{ timeout: ... }` on the test, or `--timeout` for the whole run). A suite needing more than ~3–5 minutes total is a bug.
142	- Every `Effect.retry`/`Effect.repeat` is bounded: `times ≤ 8–10`, total backoff under ~45–60s. Never poll for asynchronous provisioning slower than ~90s — skipIf-gate instead.
143	- Known engine bug: a deploy that replaces a resource while simultaneously removing its old dependency deadlocks. Keep both dependencies deployed across replacement steps in tests (see `test/Cloudflare/R2/BucketEventNotification.test.ts`).
144	- Three-iteration budget: if a suite is not green after ~3 fix iterations and the blocker is platform behavior (entitlement, slow async provisioning, beta API), implement fully, skipIf-gate with the typed tag and exact error, verify a skip-clean run, and report honestly. Do not burn an hour on one resource.
145
146	## Entitlement gating pattern
147
148	Most enterprise/plan-gated resources are still fully implementable; only the live lifecycle is gated:
149
150	1. Probe once against the real API to capture the exact rejection (code + message). If it surfaces as an untyped catch-all, patch distilled first so the entitlement error is a typed tag (e.g. `MagicTransitNotOnboarded` code 1012, `SaasQuotaNotAllocated` code 1404, `AdvancedCertificateManagerRequired` code 1450).
151	2. Keep an ungated probe test that asserts the typed tag is returned — this proves both the patch and the gating are correct, forever, at near-zero cost.
152	3. skipIf-gate the full lifecycle behind an env var (`CLOUDFLARE_TEST_MAGIC_TRANSIT=1`, `CLOUDFLARE_TEST_DLP=1`, …) so an entitled account can run it unchanged.
153	4. Record the testability verdict (`yes \| limited \| no`) and the exact error in the catalog notes.
154
155	Deprecated APIs (superseded by Rulesets etc.), billing/subscription objects, pure data-APIs, and closed-beta endpoints are documented as out of scope in `INDEX.md` rather than implemented.
156
157	## What every agent task prompt must include
158
159	A wave task prompt is a contract. Include, every time:
160
161	1. The distilled service the agent owns and the resources to build (with namespace + directory).
162	2. Assess-first instruction (finish partial work, don't rewrite).
163	3. The reading list: this file's Reconciler doctrine + Typed Error Doctrine, the catalog spec, the distilled service module + existing patches, current exemplar resources/tests (account-level CRUD, zone singleton capture-and-restore, observe-before-delete), and the registration files.
164	4. The type-check/build ban (above) — agents never run `tsc`/`pnpm build`; the coordinator owns type-checking.
165	5. The speed doctrine (above) verbatim — agents rediscover unbounded waits otherwise.
166	6. The Typed Error Doctrine hard rule with the patch-regenerate command for their service only.
167	7. Registration discipline for the shared files, including the nested-mergeAll note.
168	8. Test requirements: `test.provider`, start and end with `stack.destroy()`, deterministic names (engine default or constant), out-of-band verification via distilled, typed wait-until-gone, replacement coverage where applicable.
169	9. Known footguns: `diff` receives `Input<Props>` — narrow with `isResolved(news)` before property access; never `Input<T>` in declared Props; Effect 4 APIs (`Effect.result` + `Result.isSuccess/isFailure`, not `Effect.either`/`effect/Either`); JSON Patches address the Smithy model, so shape IDs are `com.cloudflare.{service}#Name` and member names are wire names (snake_case) — the camelCase TS surface is derived at codegen; fixtures (CSRs, PEMs, JWKS) are generated once and checked in as constants, never at test time.
170	10. A structured result schema: `{ service, resources, testsPassed, testCommand, files, patches (with reasons), skippedTests (with exact errors), notes }` — the coordinator aggregates these into the catalog.
171
172	# Documentation Generation
173
174	Source of truth: The source code is the single source of truth for all API documentation. JSDoc comments in `packages/alchemy/src/*/.ts` are extracted and used to generate the public API reference markdown.
175
176	:::warning
177	Never edit the generated markdown files under `website/src/content/docs/providers/{Cloud}/`. They are overwritten on every regeneration.
178
179	To "update the docs", edit the JSDoc on the source `.ts` file (resource-level JSDoc on the exported `const`, plus field-level JSDoc on each prop/attribute) and re-run the generator. There is no separate doc file to update.
180	:::
181
182	How to generate docs:
183
184	```sh
185	pnpm docs:gen # -> website/src/content/docs/providers/{Cloud}/{Resource}.md
186	```
187
188	This is the only doc generator that produces user-facing output. ([scripts/generate-api-reference.ts](./scripts/generate-api-reference.ts)) does the following:
189
190	1. Discovers documented files across its configured source roots — `packages/alchemy/src/{Cloud}/{Service}/` plus flat single-provider packages like `packages/better-auth/src/` (mapped onto a synthetic provider directory, e.g. `BetterAuth/`)
191	2. Parses TypeScript with the native TypeScript API (`typescript-api` tooling alias)
192	3. Extracts the page-level summary plus Markdown section/example blocks from JSDoc on the export tagged `@resource`, `@binding`, or `@layer`
193	4. Writes one markdown file per page at `website/src/content/docs/providers/{Provider}/{Name}.md`
194
195	Layer pages (`@layer`) document exported Layer factories — the pluggable implementations of a Context service (e.g. better-auth's database layers). Alongside the shared tags, a Layer declares what it satisfies and needs:
196
197	```typescript
198	/**
199	* Neon database layer for Better Auth over Neon's serverless driver.
200	*
201	* ### Connecting from a Worker or Lambda
202	* Example: Worker or Lambda with Neon-backed Better Auth
203	* ```typescript
204	* // ...
205	* ```
206	*
207	* @layer
208	* @provides BetterAuth.Database
209	* @peer @neondatabase/serverless
210	* @product Neon
211	*/
212	export const Neon = (url: ConnectionSource, options?: NeonOptions): Layer.Layer<Database> => ...
213	```
214
215	- `@provides <Service.Tag>` — the Context service tag(s) the Layer satisfies (repeatable)
216	- `@peer <package>` — optional peer dependencies the Layer needs at runtime (repeatable)
217
218	Both render as a metadata line under the page's `Source:` blockquote. Every Layer implementation should carry these annotations — a Layer without them is an undocumented integration surface.
219
220	Keep all API-generator metadata tags (`@resource`, `@binding`, `@layer`,
221	`@product`, `@category`, `@provides`, and `@peer`) together at the very end of
222	the JSDoc block. Do not put prose, sections, or examples after them: TypeScript
223	treats subsequent content as part of the block tag, which breaks editor JSDoc
224	rendering. The generator also supports `@group` as an alias for `@category` and
225	`@label` as an alias for `@product`.
226
227	After editing JSDoc on a resource, run `pnpm docs:gen` to refresh the website
228	docs. Run `pnpm docs:check-jsdoc` to validate the source layout, or
229	`pnpm docs:fix-jsdoc` to normalize it automatically.
230
231	Writing good documentation: When adding or updating a resource, ensure all Props and Attrs have JSDoc comments:
232
233	```typescript
234	export interface BucketProps {
235	/**
236	* Name of the bucket. If omitted, a unique name will be generated.
237	* Must be lowercase and between 3-63 characters.
238	*/
239	bucketName?: string;
240
241	/**
242	* Whether to delete all objects when the bucket is destroyed.
243	* @default false
244	*/
245	forceDestroy?: boolean;
246	}
247	```
248
249	The `@default` tag is used to document default values and will appear in the generated documentation.
250
251	### Examples and Sections (IMPORTANT)
252
253	Examples are critical for documentation. Every resource should have examples demonstrating common use cases. Use Markdown headings and labels on the main Resource export to organize examples into a navigable table of contents.
254
255	Format:
256
257	- `### <Section Title>` - Creates a heading in the Examples section and adds an entry to the Quick Reference table of contents
258	- `Example: <Example Title>` - Creates a labeled code example (must follow a section heading)
259	- A level-three heading that is ordinary page prose rather than an example section must end with `<!-- api-prose -->`; the generator removes the marker and preserves it as `###` in the output
260	- Code blocks inside examples use standard markdown fenced code blocks (` `)
261	- Put the API-generator metadata tags after all sections and examples
262
263	Example:
264
265	````typescript
266	/**
267	* An S3 bucket for storing objects.
268	*
269	* ### Creating a Bucket
270	* Example: Basic Bucket
271	* ```typescript
272	* const bucket = yield* Bucket("my-bucket", {});
273	* ```
274	*
275	* Example: Bucket with Force Destroy
276	* ```typescript
277	* const bucket = yield* Bucket("my-bucket", {
278	* forceDestroy: true,
279	* });
280	* ```
281	*
282	* ### Reading Objects
283	* Example: Get Object from Bucket
284	* ```typescript
285	* const response = yield* getObject(bucket, { key: "my-key" });
286	* const body = yield* Effect.tryPromise(() => response.Body?.transformToString());
287	* ```
288	*
289	* ### Writing Objects
290	* Example: Put Object to Bucket
291	* ```typescript
292	* yield* putObject(bucket, {
293	* key: "hello.txt",
294	* body: "Hello, World!",
295	* contentType: "text/plain",
296	* });
297	* ```
298	*
299	* @resource
300	*/
301	export const Bucket = Resource<...>("AWS.S3.Bucket");
302	````
303
304	This generates:
305
306	1. A "Quick Reference" section with links to each `###` section
307	2. An "Examples" section with organized code examples under each section heading
308
309	Best practices for examples:
310
311	- Start with the simplest use case and progress to more complex ones
312	- Include examples for all major capabilities (GetObject, PutObject, etc.)
313	- Show real-world patterns like error handling, combining with other resources
314	- Use descriptive titles that explain what the example demonstrates
315
316	# Workflow (per-service inner loop)
317
318	This is the inner loop that each factory agent (see The Resource Factory Process above) executes for the service it owns — it applies equally when a single engineer brings up one service by hand.
319
320	Development of Alchemy-Effect Resources is heavily pattern based. Each Service has many Resources that each have 0 or more Capabilities and Event Sources. When working on a new Service, the following steps should be followed.
321
322	1. Research the AWS Service and identify its Resources, Identifier Types, Structs, Capabilities, and Event Sources. Refer to the corresponding Terraform Provider, Pulumi Provider, and CloudFormation docs for that service (use the provided tools specifically for searching these docs for services and resources).
323
324	Example (abbreviated):
325
326	Service: S3
327
328	Resources:
329
330	- Bucket
331	- BucketPolicy
332	- etc.
333
334	Bucket Capabilities:
335
336	- GetObject
337	- PutObject
338	- DeleteObject
339
340	Identifier Types:
341
342	- Bucket Name
343	- Bucket ARN
344
345	Structs:
346
347	- CorsRule
348	- LifecycleConfiguration
349
350	2. Document each of the Resource interfaces
351
352	Include the following information:
353
354	- ResourceName, e.g. Bucket, Instance, Queue
355	- Input Properties (for each property: Name, Type, Description, Default Value, Required, Constraints, Replaces: true/false)
356	- Output Attributes (for each attribute: Name, Type, Description)
357
358	3. Document each of the Capabilities and Bindings
359
360	Include the following information:
361
362	- Capability Name, e.g. `GetObject`, `PutObject` (it maps 1:1 with an AWS API)
363	- Constraints (e.g. `Key`)
364	- IAM Policies (how the capability maps to an IAM Policy, e.g. Effect: Allow, Action: s3:GetObject, Resource: `arn:aws:s3:::${bucketName}/${Key}`)
365	- Environment Variables (what environment variables should be added to a Lambda Function so that it can access the capability, e.g. `BUCKET_NAME`, `BUCKET_ARN`, `QUEUE_URL`, `QUEUE_ARN`, etc.)
366
367	4. Research and design each of the Lifecycle Operations
368
369	- Diff - identify which properties are always stable across any update, which properties change conditionally depending on new and old values, which properties trigger a replacement. This is usually just a distinct list, but can sometimes require if-this-then-that logic. Document it explicitly and exhaustively. Cross-reference with AWS CloudFormation, Terraform Provider and Pulumi Provider docs.
370
371	:::warning
372	You should almost never use `no-op` in the Diff. No-op should be explicitly designed as a way to say "i know this property changed, but i don't want it to trigger an update". This is an edge-case and not the norm. Usually you want diff to return `undefined` or `void` to let the engine apply the default update logic. Diff is usually just use as an optimization or to identify replacement instead of update.
373	:::
374
375	- Read - determine which API calls are required to read the Output Attributes of a Resource from the Cloud Provider state (otherwise known as refresh or synchronize resource state). This is usually a single Get{Resource} API call, but can be a complex set of calls depending on the Service. Read can also be called without the current Output Attributes because of past state persistence failures. These cases are handled by computing the deterministic Physical Name and looking it up or by searching for Resources using tags (if the Cloud Provider supports it). Read may return `Unowned(attrs)` when the resource exists but lacks our ownership tags, signalling the engine to gate adoption behind `--adopt` or `adopt(true)`.
376	- Pre-Create - determine if the Resource needs a pre-create operation. This is usually only the case for the special Function/Runtime Resources like AWS Lambda Functions. If it is required, then document which API call(s) should be called and what the empty (unit) input properties are. E.g. a Lambda Function takes a simple script that exports a no-op handler function.
377	- Reconcile - determine the API calls needed to converge the cloud's actual state to the desired state described by the new Input Properties. Reconcile must be a single flow that works whether the resource is missing (greenfield create), pre-existing under our ownership (update), or freshly adopted (`output` defined but `olds` absent). See the Reconciler doctrine section below.
378	- Delete - determine which APIs should be called and in what order to delete an existing Resource. Delete should be idempotent so that if the resource has already been deleted, it is not considered an error. It is common for deletions to fail because of Dependency Violations or Eventual Consistency Errors. These are not always called Dependency Violations in the API docs, so attention should be paid to investigating each API's possible error codes and how they should be handled by the Delete operation. Should we retry for a period of time, indefinitely, or fail immediately?
379
380	# Reconciler doctrine
381
382	The provider's `reconcile` function replaces the legacy `create` + `update` pair. It runs every time the engine wants to make the cloud match the desired state — whether that's the first time the resource is being provisioned, a routine update, or a takeover after `read` returned an existing cloud resource.
383
384	It receives `output: Attributes \| undefined` and `olds: Props \| undefined`:
385
386	\| `output` \| `olds` \| Meaning \|
387	\| ------------ \| ------------ \| ------------------------------------------------- \|
388	\| `undefined` \| `undefined` \| Greenfield — no prior physical resource \|
389	\| defined \| defined \| Routine update — engine-owned resource \|
390	\| defined \| `undefined` \| Adoption — engine adopted via `read` \|
391
392	A reconciler MUST work correctly for all three combinations. It MUST NOT branch the body on `output === undefined` and run different code paths for "create" vs "update". That pattern is just rename-and-branch and re-introduces every assumption the old `create`/`update` split made. Instead, write one flow:
393
394	```
395	1. Observe — derive the physical identifier; read live cloud state via getX/describeX
396	2. Ensure — if the resource is missing, call createX. Catch AlreadyExists/ConflictException
397	as a race and continue. Wait for active state if applicable.
398	3. Sync — for each mutable aspect (settings, sub-resources, tags, policy):
399	- read OBSERVED cloud state (not olds)
400	- compute desired state from news + bindings
401	- diff observed against desired
402	- apply only the delta API call (skip the API entirely on no-op)
403	4. Return — re-read final state if needed; return the fresh Attributes shape
404	```
405
406	Key invariants:
407
408	- Observation > assumption. Cloud state is authoritative. `olds` is at most a hint to skip a no-op API call; it is never the source of truth for what's actually deployed.
409	- Each sync step is independently idempotent. Crash mid-reconcile, re-run, you converge.
410	- `output` is treated as a cache for stable identifiers (physical name, ARN, immutable id). It is NOT a guarantee that the resource still exists. If it doesn't, observation falls through to "missing" and ensure recreates.
411	- `AlreadyExists`/`NotFoundException`/`ResourceInUseException`-style errors are caught, not propagated — they're races or eventual-consistency, not failures.
412	- Tags use observed cloud tags as the diff baseline, not `olds.tags` or `output.tags`. Adoption may bring you a resource with foreign tags that need to be reconciled.
413
414	:::warning
415	*Do not write `if (output === undefined) { / create body / } else { / update body / }`.* That is rename-and-branch, not reconciliation. The reconciler's body is one observe-ensure-sync flow that produces correct cloud state regardless of starting point.
416	:::
417
418	The canonical reference reconcilers cover the common shapes:
419
420	- [S3 Bucket](./packages/alchemy/src/AWS/S3/Bucket.ts) — uses `ensureBucketExists` + `syncBucketTags` + `syncBucketPolicy` helpers; each helper is itself a tiny reconciler.
421	- [SQS Queue](./packages/alchemy/src/AWS/SQS/Queue.ts) — observe via `getQueueUrl`, ensure via `createQueue` (tolerates `QueueNameExists` race), sync attributes by diffing `getQueueAttributes` against desired, sync tags.
422	- [Kinesis Stream](./packages/alchemy/src/AWS/Kinesis/Stream.ts) — many mutable aspects (mode, shards, retention, encryption, metrics), each its own observed-vs-desired sync block.
423	- [DynamoDB Table](./packages/alchemy/src/AWS/DynamoDB/Table.ts) — multi-API observation (table + tags + PITR + TTL), per-aspect diffing, GSI delta application.
424	- [EC2 Vpc](./packages/alchemy/src/AWS/EC2/Vpc.ts) — auto-assigned id, observe via `describeVpcs([output.vpcId])` with NotFound fallback to create, sync DNS attrs by reading `describeVpcAttribute`, sync tags from observed `vpc.Tags`.
425	- [Lambda Function](./packages/alchemy/src/AWS/Lambda/Function.ts) — uses `createOrUpdateFunction` / `createOrUpdateFunctionUrl` / `attachBindings` helpers, each idempotent.
426	- [Cloudflare Worker](./packages/alchemy/src/Cloudflare/Workers/Worker.ts) — non-AWS API; the underlying `putWorker` is a true upsert, so reconcile observes existing settings and delegates.
427
428	Existence-only resources (Lambda Permission, EC2 Route, EC2 RouteTableAssociation, IAM AccessKey, etc.) have nothing mutable beyond their identity. Their reconciler is just observe → if missing, create. There is no sync step.
429
430	5. Research and design the test cases for each resource. Test cases can be single or multi-step. Single-step test cases are just testing a single create success or failure mode. Multi-step cases are testing a sequence of operations, starting with create and then updating or replacing the resource multiple times. Test cases should be designed to be exhaustive and cover all possible success and failure modes, starting from simple happy paths to long, complicated aggregate (including other resources) smoke tests.
431	6. Implement the Resource contract and Provider in `packages/alchemy/src/{Cloud}/{Service}/{Resource}.ts`.
432
433	The Resource contract (Props, Attributes, Binding Contract) and the Resource Provider (lifecycle operations) are co-located in the same file.
434
435	Read through the established examples to understand the pattern:
436
437	- [S3 Bucket](./packages/alchemy/src/AWS/S3/Bucket.ts)
438	- [SQS Queue](./packages/alchemy/src/AWS/SQS/Queue.ts)
439	- [DynamoDB Table](./packages/alchemy/src/AWS/DynamoDB/Table.ts)
440	- [Kinesis Stream](./packages/alchemy/src/AWS/Kinesis/Stream.ts)
441	- [Lambda Function](./packages/alchemy/src/AWS/Lambda/Function.ts)
442	- [VPC](./packages/alchemy/src/AWS/EC2/Vpc.ts)
443	- [Subnet](./packages/alchemy/src/AWS/EC2/Subnet.ts)
444
445	The Resource interface takes four type parameters: `Resource<Type, Props, Attributes, BindingContract>`.
446
447	```ts
448	export interface Stream extends Resource<
449	"AWS.Kinesis.Stream",
450	StreamProps,
451	{
452	streamName: string;
453	streamArn: string;
454	streamStatus: StreamStatus;
455	}
456	> {}
457
458	export const Stream = Resource<Stream>("AWS.Kinesis.Stream");
459	```
460
461	For Resources that accept Bindings (like Lambda Function), include a fourth type parameter for the Binding Contract:
462
463	```ts
464	export interface Function extends Resource<
465	"AWS.Lambda.Function",
466	FunctionProps,
467	{
468	functionArn: string;
469	functionName: string;
470	functionUrl: string \| undefined;
471	roleName: string;
472	roleArn: string;
473	},
474	{
475	env?: Record<string, any>;
476	policyStatements?: PolicyStatement[];
477	}
478	> {}
479	```
480
481	:::warning
482	Never use `Input<T>` in declared Props interfaces. Declare plain types (`zoneId: string`, `ips?: string[]`, nested structs with plain fields). The `Resource` machinery applies `Input` automatically — and `Input<T>` is deep (it recursively distributes over arrays and object fields), so even nested references like `memberships: [{ identifier: zone.zoneId }]` accept `Output<string>` without any explicit annotation. Writing `Input<string>` in a Props interface produces a redundant double-wrap.
483
484	```ts
485	// ❌ wrong
486	export interface LoadBalancerProps {
487	zoneId: Input<string>;
488	}
489
490	// ✅ right — the engine wraps automatically and deeply
491	export interface LoadBalancerProps {
492	zoneId: string;
493	}
494	```
495
496	`Input<T>` in a function signature is still legitimate when the function genuinely receives unresolved values at runtime (e.g. helpers that resolve tag maps, or `DurableObjectNamespace.from(scriptName: Input<string>)`).
497	:::
498
499	7. Implement each Capability as a `Binding.Service` in `packages/alchemy/src/{Cloud}/{Service}/{Capability}.ts`.
500
501	A single `Binding.Service` does both halves of a capability in one Effect:
502
503	- Init (outer) Effect — resolves the host Function/Worker and its environment, then registers the deploy-time binding by calling ``host.bind`${resource}`(data)`` (environment variables + IAM policy statements for AWS, native bindings for Cloudflare), guarded by `!globalThis.__ALCHEMY_RUNTIME__` so it becomes a no-op once running inside the deployed Function/Worker.
504	- Runtime (inner) callable — the typed client returned to the caller; its methods require `Alchemy.RuntimeContext` (see below).
505
506	There is no separate deploy-time policy object and nothing to register in `providers()` — the implementation layer is provided directly on the Function/Worker Effect.
507
508	Read through the established capabilities to understand the pattern:
509
510	- [S3 GetObject](./packages/alchemy/src/AWS/S3/GetObject.ts), [S3 PutObject](./packages/alchemy/src/AWS/S3/PutObject.ts)
511	- [SQS SendMessage](./packages/alchemy/src/AWS/SQS/SendMessage.ts), [DynamoDB GetItem](./packages/alchemy/src/AWS/DynamoDB/GetItem.ts)
512	- [Kinesis PutRecord](./packages/alchemy/src/AWS/Kinesis/PutRecord.ts), [Lambda InvokeFunction](./packages/alchemy/src/AWS/Lambda/InvokeFunction.ts)
513	- Access-split Cloudflare capabilities: [R2 Bucket](./packages/alchemy/src/Cloudflare/R2/), [KV Namespace](./packages/alchemy/src/Cloudflare/KV/), [Queue](./packages/alchemy/src/Cloudflare/Queue/)
514
515	For Event Sources, see:
516
517	- [SQS QueueEventSource](./packages/alchemy/src/AWS/SQS/QueueEventSource.ts)
518	- [S3 BucketEventSource](./packages/alchemy/src/AWS/S3/BucketEventSource.ts)
519
520	Each capability exports its contract plus one or more implementation layers:
521
522	```ts
523	// 1. The Binding.Service class (the contract) + a bind alias for ergonomic use
524	export class PutRecord extends Binding.Service<...>()("AWS.Kinesis.PutRecord") {}
525	export const putRecord = PutRecord.bind;
526
527	// 2. The implementation layer — resolves the host + environment, registers the
528	// binding inline (guarded by __ALCHEMY_RUNTIME__), and returns the runtime client.
529	export const PutRecordLive = Layer.effect(
530	PutRecord,
531	Effect.gen(function* () {
532	const host = yield* Worker; // or the AWS Function host
533	const env = yield* WorkerEnvironment; // or Lambda.FunctionEnvironment
534	return Effect.fn(function* (stream: Stream) {
535	if (!globalThis.__ALCHEMY_RUNTIME__) {
536	// AWS: { policyStatements: [...] } Cloudflare: { bindings: [...] }
537	yield* host.bind`${stream}`({ policyStatements: [...] });
538	}
539	return /* typed runtime client closing over `env` */;
540	});
541	}),
542	);
543	```
544
545	Provide the implementation layer on the Function/Worker Effect (`Effect.provide(PutRecordLive)`).
546
547	### Read/Write/ReadWrite binding convention
548
549	When a capability's API distinguishes access levels (R2 `head`/`get`/`list` vs `put`/`delete`; KV `get`/`getWithMetadata`/`list` vs `put`/`delete`), split it into three `Binding.Service`s so consumers can request least privilege, each with two interchangeable implementations:
550
551	- `{Cap}Read.ts` / `{Cap}Write.ts` / `{Cap}ReadWrite.ts` — the `Binding.Service` class + runtime client interface + a `bind` alias (e.g. `ReadBucket = BucketRead.bind`). `ReadWrite`'s client interface `extends` both the `Read` and `Write` client interfaces.
552	- `{Cap}Binding.ts` — shared worker-binding scaffolding: a `make{Cap}Binding({ makeClient })` that resolves `WorkerEnvironment` + host `Worker`, registers the native binding via ``host.bind`${resource}`(...)`` (guarded by `__ALCHEMY_RUNTIME__`), plus a `make{Cap}Helpers` returning the low-level `raw`/`use`/`tryPromise` primitives. Do NOT export this file from `index.ts`.
553	- `{Cap}ReadBinding.ts` / `{Cap}WriteBinding.ts` / `{Cap}ReadWriteBinding.ts` — `Layer.effect` implementations over the native binding (`ReadBucketBinding`, …) plus the `makeRead`/`makeWrite` client builders. `ReadWrite` composes the read + write builders.
554	- `{Cap}Http.ts` — shared HTTP/token scaffolding: a `makeHttp{Cap}Binding({ permissionGroups, makeClient })` that mints a scoped `AccountApiToken` with the right permission groups, binds the token's `value`/`accountId` into the Worker, and resolves the per-operation scope. Do NOT export this file from `index.ts`.
555	- `{Cap}ReadHttp.ts` / `{Cap}WriteHttp.ts` / `{Cap}ReadWriteHttp.ts` — `Layer.effect` implementations over the cloud's HTTP API (`ReadBucketHttp`, …). Operations the HTTP API can't support `Effect.die` with a typed error.
556
557	Rules:
558
559	- Keep shared scaffolding internal. Re-export only the contracts, the per-level layers, and the client builders from `index.ts`. Exporting `{Cap}Binding.ts`/`{Cap}Http.ts` leaks generic helper names into the flat `Cloudflare`/`AWS` namespace and collides across services.
560	- Use service-unique helper names. Avoid generic `makeHelpers`/`makeWrite`; prefix with the capability (`makeQueueHelpers`, `makeWriteQueueClient`) so re-exported builders never clash.
561	- Namespace the public surface. Export the service both flatly and as a namespace (`export * as KV from "./KV/index.ts"`) so callers write `Cloudflare.KV.ReadWriteNamespace(ns)`. The bind-alias callables drop the redundant service prefix (`ReadWriteNamespace`, not `ReadWriteKVNamespace`); the underlying classes/interfaces keep it (`KVNamespaceReadWrite`, `ReadWriteKVNamespaceClient`).
562	- No resource-level `bind`. The Resource is plain `Resource<T>("Cloud.Type")` with no `bind:` field; callers bind via the namespaced capability, not `resource.bind`.
563	- Single-mode capabilities stay single. A producer-only capability (e.g. Cloudflare Queue's send-only producer, which has no runtime read) ships just the `Write` service — don't invent a `Read` the runtime can't satisfy. The HTTP impl can still cover both directions where the API does.
564
565	Reference: [Cloudflare R2 Bucket](./packages/alchemy/src/Cloudflare/R2/), [KV Namespace](./packages/alchemy/src/Cloudflare/KV/), [Queue](./packages/alchemy/src/Cloudflare/Queue/).
566
567	### Runtime-only methods: color with `Alchemy.RuntimeContext`
568
569	The runtime callable returned by a `Binding.Service` (the inner Effect inside `.bind(resource)`'s return) must declare `Alchemy.RuntimeContext` as a requirement. This is how Alchemy models "this code can only run inside a deployed Function/Worker" at the type level — analogous to a colored function.
570
571	```ts
572	import type { RuntimeContext } from "../../RuntimeContext.ts";
573
574	export class GetItem extends Binding.Service<
575	GetItem,
576	<T extends Table>(
577	table: T,
578	) => Effect.Effect<
579	(
580	request: GetItemRequest,
581	) => Effect.Effect<
582	DynamoDB.GetItemOutput,
583	DynamoDB.GetItemError,
584	RuntimeContext // ← runtime-only
585	>
586	>
587	>()("AWS.DynamoDB.GetItem") {}
588	```
589
590	Rules:
591
592	- Outer Effect (the `bind(resource)` setup) runs at the Function's init phase. It does NOT require `RuntimeContext`.
593	- Inner Effect (the actual SDK invocation) only makes sense inside a running Function. It MUST require `RuntimeContext`.
594	- Resolve cloud-environment services (`WorkerEnvironment`, AWS SDK clients, etc.) once during Layer construction and close over them. Do NOT leak `WorkerEnvironment` / `Lambda.FunctionEnvironment` onto the runtime callable — that couples downstream service code to a specific cloud and breaks Layer encapsulation. The Function/Worker runtime satisfies `RuntimeContext` automatically.
595	- The implementation can return `Effect.Effect<A, E>` without explicitly providing `RuntimeContext` (it's contravariant in `R`); just declare it on the interface.
596
597	Why this matters: consumers can build cloud-agnostic services on top of bindings using `Layer.effect(Tag, ...)` without polluting their service interface with `WorkerEnvironment`. See [Layers concept](./website/src/content/docs/concepts/layers.mdx).
598
599	After implementing, re-export the contract and implementation layers from the service's `index.ts` (but keep the shared `{Cap}Binding.ts`/`{Cap}Http.ts` scaffolding un-exported).
600
601	### Isolate scope vs request scope (runtime bridges)
602
603	Layer construction is isolate-scoped; the effects built services expose are request-scoped.
604
605	- At layer build / Worker init (instance scope) a layer MAY resolve services and env/config, register listeners and `bind` declarations, assemble `Effect.fn` clients, and perform one-shot I/O that produces a plain cached value (e.g. fetch a secret and cache it for a client). It MUST NOT acquire disposable resources — connections, pools, streams, anything with a finalizer (`Layer.scoped` / `Effect.acquireRelease` / init-level `Effect.addFinalizer`) — or retain I/O-backed objects or promises across events (workerd pins them to the creating request's IoContext). The runtime bridges (Worker event, Durable Object call, Workflow run, Lambda invoke) build the layer stack once per instance on the first event. Instance finalizers run at instance shutdown at best: never on workerd (no teardown hook), and in a best-effort 500 ms SIGTERM window on Lambda (the generated entry registers an internal extension to obtain it and closes the instance scope on SIGTERM; not delivered on hard failures). Server processes (Containers, ECS Tasks) close their root scope on graceful exit.
606	- At request scope, anything needing I/O or cleanup is an effect requiring `Scope.Scope`, acquired lazily per call. Every bridge provides a fresh `Scope` per event; `Effect.addFinalizer` in a handler attaches to it and runs after the response (registered with `ctx.waitUntil` on workerd; settled inline on Lambda). Per-request memoization keys on the scope object (`yield* Effect.scope`) — see [Drizzle/Postgres.ts](./packages/alchemy/src/Drizzle/Postgres.ts) for the canonical WeakMap pattern. One pool/socket per event is the law on workerd (sockets are IoContext-pinned); Hyperdrive is the cross-request pooler.
607
608	:::tip
609	If you need to know what AWS region or account ID the resource is being created/updated in, you can use this inside any of the lifecycle operations.
610
611	```ts
612	const region = yield * Region;
613	const account = yield * Account;
614	```
615
616	:::
617
618	:::warning
619	You should favor getting the region/account INSIDE the lifecycle operations instead of inside the Layer effect like this because then it's scoped to the resource isntead of the resource provider:
620
621	```ts
622	reconcile: Effect.fn(function* ({ id, news, output, session }) {
623	const { accountId, region } = yield* AWSEnvironment.current;
624	});
625	```
626
627	:::
628
629	:::warning
630	Do not use `Effect.orDie` in the lifecycle operations since this will crash the whole IaC engine.
631	:::
632
633	:::warning
634	Never use `async`/`await`, raw `Promise`, `node:fs/promises`, `node:fs`, `node:os`, or `pathe` directly in resource code. Always use the Effect platform services so that effects remain composable, traceable, retryable, and testable:
635
636	\| Don't \| Do \|
637	\| ---------------------------------------------------- \| ----------------------------------------------------------- \|
638	\| `import fs from "node:fs/promises"` \| `const fs = yield* FileSystem.FileSystem` \|
639	\| `await fs.readFile(p, "utf8")` \| `yield* fs.readFileString(p)` \|
640	\| `await fs.mkdtemp(...)` \| `yield* fs.makeTempDirectory({ prefix: ... })` \|
641	\| `import path from "pathe"` / `node:path` \| `const path = yield* Path.Path` \|
642	\| `await fetch(...)` \| `yield* HttpClient.HttpClient` + `HttpClientRequest` \|
643	\| `Effect.promise(() => listSqlFiles(dir))` \| Make `listSqlFiles` itself return `Effect` and `yield*` it \|
644	\| `new Promise((res) => setTimeout(res, ms))` \| `yield* Effect.sleep(Duration.millis(ms))` \|
645
646	Sync, CPU-only Node APIs (e.g. `crypto.createHash().update().digest()`, `process.cwd()`, `Buffer`, `TextEncoder`) must still be wrapped in `Effect.sync(() => ...)` (or `Effect.try` if they can throw) so the call participates in the Effect runtime — tracing, interruption, and error channels. Don't call them as bare expressions inside `Effect.gen`.
647
648	```ts
649	const hash = yield* Effect.sync(() =>
650	crypto.createHash("sha256").update(input).digest("hex"),
651	);
652	const cwd = yield* Effect.sync(() => process.cwd());
653	```
654
655	This applies to lifecycle operations, helpers, AND tests. Tests must use `FileSystem.FileSystem`/`Path.Path` for any file/path access (see [Database.test.ts](./packages/alchemy/test/Cloudflare/D1/Database.test.ts) for the pattern).
656	:::
657
658	:::tip
659	If a Resource supports tags, you should always include the internal Alchemy tags to brand the resource with the app, stage and logical ID so that we can "know" that we created it and are responsible for it.
660
661	```ts
662	reconcile: Effect.fn(function* ({ id, news, output, session }) {
663	const internalTags = yield* createInternalTags(id);
664	const userTags = news.tags ?? {};
665	const allTags = { ...internalTags, ...userTags };
666	});
667	```
668
669	:::
670
671	:::warning
672	Do not roll your own tag diffing logic, always use `diffTags` from [Tags.ts](./packages/alchemy/src/Tags.ts), and diff against observed cloud tags (not `olds.tags` or `output.tags`). Adoption can hand you a resource whose tags don't match what we last persisted.
673
674	```ts
675	reconcile: Effect.fn(function* ({ id, news, output, session }) {
676	const internalTags = yield* createInternalTags(id);
677	const newTags = { ...news.tags, ...internalTags };
678	// Read tags fresh from the cloud so adoption (where tags may not match
679	// what we last persisted) converges correctly.
680	const oldTags = yield* fetchObservedTags(/* … */);
681	// Option 1. use `upsert` if the API expects you to create/update tags in one call
682	const { removed, upsert } = diffTags(oldTags, newTags);
683	// Option 2. use `added` and `updated` if the API expects you to create/update tags in separate calls
684	const { removed, added, updated } = diffTags(oldTags, newTags);
685	// Option 3. use `upsert` only if the API doesn't expect you to remove tags (only PUT/UPDATe)
686	const { upsert } = diffTags(oldTags, newTags);
687	```
688
689	:::
690
691	9. Implement the test cases in `packages/alchemy/test/{Cloud}/{Service}/{Resource}.test.ts`.
692
693	Read through the established test cases before continuing so that you understand the pattern and structure of the test cases.
694
695	- [S3 Bucket Test Cases](./test/AWS/S3/Bucket.test.ts)
696	- [SQS Queue Test Cases](./test/AWS/SQS/Queue.test.ts)
697	- [Lambda Function Test Cases](./test/AWS/Lambda/Function.test.ts)
698	- [Kinesis Stream Test Cases](./test/AWS/Kinesis/Stream.test.ts)
699	- [DynamoDB Table Test Cases](./test/AWS/DynamoDB/Table.test.ts)
700	- [VPC Test Cases](./test/AWS/EC2/Vpc.test.ts)
701	- [Subnet Test Cases](./test/AWS/EC2/Subnet.test.ts)
702
703	:::warning
704	Never use `Date.now()` when constructing the physical name of a resource. You should either:
705
706	1. Do not proide a name and rely on the resource provider to generate a unique name for you from the app, stage and logical ID.
707	2. Construct a deterministic one unique to each test case. But it should be the same on each subsequent run of the test case.
708	:::
709
710	3. Consider implementing an aggregate Smoke test that brings together multiple resources that are often used together.
711
712	See the [VPC Smoke Test](./test/AWS/EC2/Vpc.smoke.test.ts) for an example.
713
714	11. Add the resource-level JSDoc (`###` section headings + `Example:` labels, with generator metadata tags last) and field-level JSDoc on each prop/attribute on the source `.ts` file. Run `pnpm docs:check-jsdoc`, then `pnpm docs:gen` to refresh `website/src/content/docs/providers/{Cloud}/{Resource}.md`. Do NOT manually edit the generated markdown.
715
716	# Typed Error Doctrine (distilled)
717
718	## How distilled is built (Smithy + JSON Patch)
719
720	Distilled is a Smithy-based SDK factory. Every provider package (`submodules/distilled/packages/{cloud}`) runs the same pipeline:
721
722	1. Convert — the provider's spec source is converted into Smithy 2.0 JSON models, one per service, in `.generated-specs/{service}.json`. Cloudflare mines them from the downloaded API docs (`scripts/spec-to-smithy.ts` over `specs/api/resources/**`); AWS consumes the official `api-models-aws` Smithy models submodule directly. Hand-authored models for APIs the spec source doesn't cover live in `manual-specs/`.
723	2. Patch — an RFC 6902 JSON Patch chain (files shaped `{ "description": ..., "patches": [ops] }`) is applied to the provider's intermediary spec before codegen. For Cloudflare, patches in `patches/{service}/.json` target the Smithy model, applied in filename order with `.manual.json` files last; `_metadata.json` carries service-level `/metadata/keyDictionary` and `/metadata/opAliases`. OpenAPI-sourced providers (Neon, PlanetScale, Stripe, …) patch the OpenAPI document upstream of the smithy conversion instead. A patch whose target path is stale (no longer in the model) warns and is skipped; a malformed patch fails the generator run.
724	3. Generate — the shared smithy→SDK compiler in `@distilled.cloud/core/codegen` compiles each patched model into an Effect SDK module at `src/services/{service}.ts` plus the barrel.
725
726	Consequences:
727
728	- *Never edit `src/services/.ts`** — regeneration overwrites it. Anything wrong in the generated SDK (missing error, wrong request/response schema, misnamed operation or member) is fixed with a JSON Patch (`add`/`remove`/`replace`/`move` on the model) in `patches/{service}/`.
729	- Patch paths address the Smithy model: shape IDs are `com.cloudflare.{service}#Name`, and member names are wire names (snake_case). The camelCase TS surface is derived at codegen; `move` ops rename shapes and members.
730
731	## The doctrine
732
733	Every error a distilled operation can produce in practice MUST be a tagged error in that operation's type-level error union. The catch-all classes (`UnknownCloudflareError`, `CloudflareHttpError`, and the status-derived classes like `NotFound`/`BadRequest` that distilled leaves out of the typed union) exist only to surface gaps — they are never something alchemy code handles.
734
735	When you hit an unmatched error (an `UnknownCloudflareError`, or you find yourself wanting to check `CloudflareHttpError.status` or an out-of-union `NotFound`), the fix is ALWAYS a distilled patch, never a catch in alchemy:
736
737	1. Note the error's code / status / message from the failure output.
738	2. Add or extend `submodules/distilled/packages/cloudflare/patches/{service}/{operation}.json` with a JSON Patch that (a) adds an error structure carrying the `smithy.api#error` trait and `com.cloudflare.protocols#errorMatchers` matchers, and (b) attaches it to the operation's `errors` list. Use a meaningful, resource-specific tag (e.g. `WidgetNotFound`, not a bare `NotFound`):
739
740	```json
741	{
742	"description": "Type the not-found error on getWidget",
743	"patches": [
744	{
745	"op": "add",
746	"path": "/shapes/com.cloudflare.widgets#WidgetNotFound",
747	"value": {
748	"type": "structure",
749	"members": {
750	"code": { "target": "smithy.api#Integer" },
751	"message": { "target": "smithy.api#String" }
752	},
753	"traits": {
754	"smithy.api#error": "client",
755	"com.cloudflare.protocols#errorMatchers": [{ "code": 1234 }]
756	}
757	}
758	},
759	{
760	"op": "add",
761	"path": "/shapes/com.cloudflare.widgets#GetWidget/errors",
762	"value": [{ "target": "com.cloudflare.widgets#WidgetNotFound" }]
763	}
764	]
765	}
766	```
767
768	If the operation already has an `errors` array (from an earlier patch), append with `"path": ".../errors/-"` instead of adding the whole array. Matchers may combine `code`, `status`, and `message` (a string, or `{ "includes": "..." }` / `{ "matches": "..." }`) — e.g. `[{ "status": 400, "message": { "includes": "snippet not found" } }]` when Cloudflare misuses 400 for a missing resource. Prefer matching the Cloudflare error `code` when one exists; fall back to `status` + `message` otherwise. The most specific matcher wins; ties break by declaration order.
769
770	3. Regenerate ONLY that service: `cd submodules/distilled/packages/cloudflare && bun scripts/generate.ts --resource {service}` (then format: `pnpm exec oxfmt src/services/{service}.ts`). A warned-stale or failed patch is a bug in your patch — fix it; never leave a red generate.
771	4. Handle the now-typed tag in alchemy code and re-run the tests.
772
773	AWS is the one exception to the JSON Patch format: it layers typed-error metadata over the official Smithy models with a per-service schema file `submodules/distilled/packages/aws/patches/{service}.json` (error categories, aliases, synthetic errors with message matchers — see `submodules/distilled/packages/aws/scripts/spec-schema.ts`), regenerated with `cd submodules/distilled/packages/aws && bun scripts/generate.ts --sdk {service}`. The doctrine is identical; only the patch dialect differs.
774
775	Forbidden patterns — these defeat the type system and must never appear in alchemy code or tests:
776
777	```ts
778	// ❌ unknown-typed structural predicates
779	const isNotFoundError = (e: unknown): boolean =>
780	Predicate.hasProperty(e, "_tag") && (e as { _tag: unknown })._tag === "NotFound";
781
782	// ❌ widening casts to duck-typed tags
783	Effect.retry({ while: (e) => (e as { _tag?: string })._tag === "Forbidden" })
784
785	// ❌ catching the catch-all HTTP error by status
786	Effect.catchIf((e) => e._tag === "CloudflareHttpError" && e.status === 404, ...)
787	```
788
789	Required patterns — fully inferred, no casts, no `unknown`:
790
791	```ts
792	// ✅ catch a typed tag
793	.pipe(Effect.catchTag("WidgetNotFound", () => Effect.void))
794
795	// ✅ retry while a typed tag is observed (e is the op's inferred error union)
796	Effect.retry({ while: (e) => e._tag === "WidgetNotFound", schedule, times })
797
798	// ✅ multiple tags
799	Effect.catchTag(["WidgetNotFound", "Gone"], () => Effect.succeed(undefined))
800	```
801
802	If `Effect.catchTag("SomeTag", ...)` fails to typecheck, that is the signal that distilled's union is missing the error — patch distilled (step 2 above); do not loosen the alchemy-side types.
803
804	# Provider Modes & Local Providers (doctrine)
805
806	Some resource types have TWO implementations: a live provider (converges real cloud state, `alchemy deploy`) and a local provider (emulates the resource on the developer's machine, `alchemy dev`). Provider mode is a first-class engine concept — see [ProviderMode.ts](./packages/alchemy/src/ProviderMode.ts), [Local/ProviderLayer.ts](./packages/alchemy/src/Local/ProviderLayer.ts), [Local/LocalProvider.ts](./packages/alchemy/src/Local/LocalProvider.ts), and the user-facing guide at [website/src/content/docs/infrastructure-as-code/local-provider.mdx](./website/src/content/docs/infrastructure-as-code/local-provider.mdx).
807
808	Engine semantics (never re-implement these per provider):
809
810	- Register both variants with `ProviderLayer.dual(cls, { live: () => ..., local: () => ... })` — never select one at layer build. The run-default variant builds eagerly; the other is lazy and memoized, so mode-specific dependency layers (workerd, Docker) MUST compose inside the `local` thunk (e.g. `LocalWorkerProvider().pipe(Layer.provide(localRuntimeServices()))`), never globally — a plain deploy must not construct local machinery unless a local-mode row needs deleting. Dep layers shared across several local providers must be module-memoized layer references so the build MemoMap dedupes them to one instance.
811	- Every state commit stamps `providerMode`. A persisted mode that differs from the resolved mode plans a REPLACEMENT (the provider diff is not consulted), and every delete — replacement old generations, GC chain draining, orphans, `destroy`, `sync`/`tail`/`logs` — resolves the provider variant of the row's stamped mode via `findProviderByType(type, mode)`. Legacy rows without a stamp are assumed live (pre-mode engines and mode-agnostic providers only ever acted on the real cloud), so a dev run replaces them like any stamped live row — assuming the run's mode instead would silently adopt a deployed live resource as a local instance and leak it untracked. The exception is an unstamped row whose attrs carry the local identity marker (`dev:`-prefixed ids, see `stampedMode` in `ProviderMode.ts`): it was reconciled by a pre-stamping `alchemy dev` run and is treated as local, so a plain destroy/deploy never hands its `dev:` identity to the live cloud API.
812	- `Alchemy.remote()` opts a resource or scope OUT of local emulation during dev (captured at registration like `adopt()`; a no-op during deploy). There is deliberately no `local()` — dev mode IS the local default; tests simulate a dev run by overriding `AlchemyContext.dev` (`inDev` in [test.resources.ts](./packages/alchemy/test/test.resources.ts)) or `Test.make({ dev: true })`. Conflicting decorations on one FQN die with `ConflictingProviderModeError`. Single-implementation providers are mode-agnostic: they satisfy any requested mode, never stamp, never replace on a switch — dev runs over constructs mixing emulatable and live-only resources (R2) just work.
813
814	## `LocalProvider.make` — long-running local providers
815
816	A local provider whose physical resource is a running process (dev server, workerd instance) MUST be built with `LocalProvider.make(cls, providersUrl, spec)` — do not hand-roll FiberMap/instance-registry/hash machinery in the provider:
817
818	- `resolveConfig(ctx)` — the restart surface. Plain, canonically-hashable data only (no closures or runtime objects: derive plain descriptors here and materialize `BindingHook`s etc. inside `start` — see the descriptor/hook split in [LocalWorkerProvider.ts](./packages/alchemy/src/Cloudflare/Workers/LocalWorkerProvider.ts)). Must be cheap and side-effect-free — it runs inside `diff` on every plan. Its canonical hash decides noop-vs-restart AND the same value is handed to `start`, so "what changed?" and "what starts?" can never drift. Deliberately EXCLUDE runtime wiring observed at start time (e.g. queue consumers read from `LocalRuntimeState`) — sibling reconciles drive those via restart hooks, not config.
819	- `start(ctx)` — boot ONE instance in the ambient `Scope` and return Attributes at readiness; the process keeps running until the runner closes the scope on restart/delete. For processes that can die on their own, fork `ctx.invalidate` after the exit so the next plan reports `update`.
820	- `stop(ctx)` — delete-only cleanup for state that intentionally survives restarts (URL proxies kept for address stability, restart hooks). NOT called on restarts.
821	- Generated for you: instance registry, per-id lock (restarts never interleave), config-hash noop/restart, instanceId-guarded delete (a create-first replacement's old-generation delete cannot kill its successor), `list`. The provider is wrapped in `RpcProvider`, so during `alchemy dev` the registry lives in the sidecar and survives user-code hot reloads.
822	- Never use `Hash.structure` to compare configs — it XOR-folds sibling fields, so a value mirrored into two subtrees (env ↔ bindings) cancels out. The helper's canonical hash (sorted-key JSON + sha256, Redacted/bytes/cycle-aware) is the law.
823
824	Registry-style local providers (the "instance" is an in-memory row, e.g. Cloudflare's local Queue mutating `LocalRuntimeState`) do NOT use `LocalProvider.make` — write a plain provider and register it via `dual`.
825
826	Reference implementations: [Command/Dev.ts](./packages/alchemy/src/Command/Dev.ts) (minimal: spawn + URL readiness), [Cloudflare Workers LocalWorkerProvider.ts](./packages/alchemy/src/Cloudflare/Workers/LocalWorkerProvider.ts) (full-size: bundler watch loop, cross-restart proxy in `stop`), [Cloudflare Queues Queue.ts](./packages/alchemy/src/Cloudflare/Queues/Queue.ts) (registry-style, no runner). Engine coverage lives in [test/provider-mode.test.ts](./packages/alchemy/test/provider-mode.test.ts) and the "provider modes" describes in [plan.test.ts](./packages/alchemy/test/plan.test.ts) / [apply.test.ts](./packages/alchemy/test/apply.test.ts).
827
828	## Local tests (`{Resource}.local.test.ts`)
829
830	Every resource with a local (dev) provider gets a `{Resource}.local.test.ts` co-located with its live test, using `Test.make({ providers, dev: true })`. Dev-mode tests run local providers behind a file-scoped RPC sidecar by default — the same `RpcProviderProxy` topology the real `alchemy dev` command uses, where `providerServicesEffect` layers (e.g. `localRuntimeServices()`) are EMPTY in the test process and RPC-backed providers run their lifecycle in the sidecar. This is what catches a plain local provider that needs those services in the main process (the class of bug behind #1007, which in-process tests masked). `Test.make({ ..., sidecar: false })` opts a file back into the in-process topology — reserve it for debugging provider code or pinning the in-process path a plain `alchemy deploy` takes when deleting `providerMode: "local"` rows.
831
832	The suite must cover, minimum:
833
834	1. The local roundtrip — deploy the resource + a worker binding it (file-based fixture `main`, never inline `script` — unsupported in dev) and drive the binding over HTTP against the local simulator. Assert the resource's identity carries the `dev:` marker (proof no cloud call ran; for the Worker itself the marker is a `http://localhost:<port>` `url`).
835	2. The `Alchemy.remote()` opt-out — the same shape with the resource piped through `Alchemy.remote()`: assert a real (non-`dev:`) identity, round-trip through the remote-proxied binding, verify out-of-band via distilled that the write landed in the real cloud resource, and after `stack.destroy()` verify the cloud resource is gone (pins the stamped-mode delete path).
836
837	Reference: [KV Namespace.local.test.ts](./packages/alchemy/test/Cloudflare/KV/Namespace.local.test.ts) (includes the mixed local + live stack), [R2 Bucket.local.test.ts](./packages/alchemy/test/Cloudflare/R2/Bucket.local.test.ts), [D1 Database.local.test.ts](./packages/alchemy/test/Cloudflare/D1/Database.local.test.ts) (includes local migrations and the #1007 regression), [Queues Queue.local.test.ts](./packages/alchemy/test/Cloudflare/Queues/Queue.local.test.ts) (produce→consume through RPC-backed providers). The harness contract itself is pinned by [TestSidecar.test.ts](./packages/alchemy/test/Local/TestSidecar.test.ts).
838
839	# Test Fixtures for Effect-Native Workers / Functions
840
841	To test runtime behavior of an Effect-native Worker, Workflow, Lambda, etc., write a fixture that defines the Worker/Function with the bindings under test and exposes one HTTP route per behavior, then write a test that deploys the fixture once via `beforeAll` and drives it over HTTP.
842
843	## File system layout
844
845	Put fixtures in a `fixtures/` directory next to the test file. Each test suite owns its own fixtures — never reach across suites:
846
847	```sh
848	packages/alchemy/test/{Cloud}/{Service}/{Resource}.test.ts
849	packages/alchemy/test/{Cloud}/{Service}/fixtures/{worker\|workflow\|handler}.ts
850	```
851
852	## Fixture shape
853
854	Resolve the bindings, expose one route per behavior, default-export the class so the test can deploy it directly:
855
856	```ts
857	// fixtures/worker.ts
858	import * as Cloudflare from "@/Cloudflare/index.ts";
859	import * as Effect from "effect/Effect";
860	import { HttpServerRequest } from "effect/http/HttpServerRequest";
861	import * as HttpServerResponse from "effect/http/HttpServerResponse";
862	import { Gateway } from "./gateway.ts";
863
864	export default class TestWorker extends Cloudflare.Worker<TestWorker>()(
865	"TestWorker",
866	{
867	main: import.meta.url,
868	},
869	Effect.gen(function* () {
870	const aiGateway = yield* Cloudflare.AI.QueryGateway(Gateway);
871
872	return {
873	fetch: Effect.gen(function* () {
874	const request = yield* HttpServerRequest;
875	if (request.url.startsWith("/url")) {
876	const url = yield* aiGateway.getUrl().pipe(Effect.orDie);
877	return yield* HttpServerResponse.json({ url });
878	}
879	return HttpServerResponse.text("ok");
880	}),
881	};
882	}).pipe(Effect.provide(Cloudflare.AI.QueryGatewayBinding)),
883	) {}
884	```
885
886	## Test shape
887
888	Compose a `Stack` that deploys the fixture, share one deploy across the file with `beforeAll`/`afterAll`, drive it via `HttpClient`, and retry the first request through edge propagation:
889
890	```ts
891	// Service.test.ts
892	import * as Alchemy from "@/index.ts";
893	import * as Cloudflare from "@/Cloudflare";
894	import * as Test from "@/Test/Alchemy";
895	import { expect } from "alchemy-test";
896	import * as Effect from "effect/Effect";
897	import * as Schedule from "effect/Schedule";
898	import * as HttpClient from "effect/http/HttpClient";
899	import TestWorker from "./fixtures/worker.ts";
900
901	const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
902	providers: Cloudflare.providers(),
903	});
904
905	const Stack = Alchemy.Stack(
906	"ServiceTestStack",
907	{ providers: Cloudflare.providers(), state: Cloudflare.state() },
908	Effect.gen(function* () {
909	const worker = yield* TestWorker;
910	return { url: worker.url.as<string>() };
911	}),
912	);
913
914	const stack = beforeAll(deploy(Stack));
915	afterAll.skipIf(!!process.env.NO_DESTROY)(destroy(Stack));
916
917	test(
918	"deployed worker exercises the binding",
919	Effect.gen(function* () {
920	const { url } = yield* stack;
921	const client = yield* HttpClient.HttpClient;
922
923	const res = yield* client.get(`${url}/url`).pipe(
924	Effect.retry({ schedule: Schedule.exponential("500 millis"), times: 10 }),
925	);
926	expect(res.status).toBe(200);
927	const body = (yield* res.json) as { url: string };
928	expect(body.url).toContain("gateway.ai.cloudflare.com");
929	}),
930	{ timeout: 180_000 },
931	);
932	```
933
934	Notes:
935
936	- `Test.make({ providers: Cloudflare.providers() })` gives you `test`, `beforeAll`, `afterAll`, `deploy`, `destroy`.
937	- `beforeAll(deploy(Stack))` returns a handle (`stack` above) that every `test` body can `yield*` to get the stack outputs.
938	- `afterAll.skipIf(!!process.env.NO_DESTROY)(destroy(Stack))` is the standard cleanup — set `NO_DESTROY=1` locally to keep the deployment around between runs while iterating.
939	- Always retry the first request (`Schedule.exponential("500 millis")`) — fresh workers.dev URLs and Lambda function URLs take a few seconds to start serving 200s.
940	- For POST: use `client.post(url)` for empty bodies, or `HttpClient.execute(HttpClientRequest.post(url).pipe(HttpClientRequest.bodyJsonUnsafe(body)))` for typed bodies.
941	- Never use `while (Date.now() < deadline)` loops to poll for an async side effect (a workflow status, a cron fire, a queue drain, eventual-consistency read, etc.). Use `Effect.repeat` with a `Schedule` and an `until` predicate so the polling participates in the Effect runtime — tracing, interruption, and error propagation work correctly, and the intent is declarative. Cap iterations with `times: N` (or a bounded schedule) so the test fails fast instead of running until the test timeout:
942
943	```ts
944	// good — declarative, bounded, interruption-safe
945	const value = yield* fetchValue.pipe(
946	Effect.repeat({
947	schedule: Schedule.spaced("5 seconds"),
948	until: (v) => v.ready,
949	times: 36,
950	}),
951	);
952
953	// bad — opaque loop, ignores interruption, leaks into the test timeout
954	let value: Value \| undefined;
955	const deadline = Date.now() + 180_000;
956	while (Date.now() < deadline) {
957	value = yield* fetchValue;
958	if (value.ready) break;
959	yield* Effect.sleep("5 seconds");
960	}
961	```
962
963	See [CronEventSource.test.ts](./packages/alchemy/test/Cloudflare/Workers/CronEventSource.test.ts) for a real-world example (polling a DO via the worker's `/times` route until the cron handler fires).
964
965	## Reference implementations
966
967	- Cloudflare.AI.Gateway — [worker fixture](./packages/alchemy/test/Cloudflare/AI/fixtures/TestWorker.ts) + [test](./packages/alchemy/test/Cloudflare/AI/Gateway.test.ts) (the deploy+fetch case lives at the bottom of the file)
968	- Cloudflare D1Connection — [worker fixture](./packages/alchemy/test/Cloudflare/D1/d1-worker.ts) + [test](./packages/alchemy/test/Cloudflare/D1/D1Binding.test.ts)
969	- Cloudflare Workflow — [workflow fixture](./packages/alchemy/test/Cloudflare/Workers/fixtures/test-workflow.ts) + [worker fixture](./packages/alchemy/test/Cloudflare/Workers/fixtures/workflow-worker.ts) + [test](./packages/alchemy/test/Cloudflare/Workers/Workflow.test.ts)
970	- Cloudflare Cron Trigger — [worker + DO fixture](./packages/alchemy/test/Cloudflare/Workers/fixtures/cron-worker.ts) + [test](./packages/alchemy/test/Cloudflare/Workers/CronEventSource.test.ts) (cron handler writes to a DO; test polls a fetch route with `Effect.repeat` until the scheduled handler fires)
971	- Cloudflare Images — [effect fixture](./packages/alchemy/test/Cloudflare/Images/fixtures/effect-worker.ts) + [async fixture](./packages/alchemy/test/Cloudflare/Images/fixtures/async-worker.ts) + [test](./packages/alchemy/test/Cloudflare/Images/Images.test.ts)
972	- AWS Lambda (DynamoDB bindings) — [Lambda fixture](./packages/alchemy/test/AWS/DynamoDB/handler.ts) + [test](./packages/alchemy/test/AWS/DynamoDB/Bindings.test.ts) (one `describe("<BindingName>")` per binding, all driving the same deployed Lambda)
973
974	# Spec-Driven Service Bring-Up
975
976	Use @processes/AWS.md as the source of truth for bringing a single AWS service from zero to full coverage.
977
978	That process covers:
979
980	- deriving resources, bindings, event sources, and helpers from distilled
981	- the audit-driven implementation loop
982	- deterministic checks for registration and binding test coverage
983	- Lambda fixture testing conventions
984	- learned conventions like no auto-marshalling and one `describe("<BindingName>")` block per binding
985
986	Keep `AGENTS.md` high-level and update @processes/AWS.md when the process evolves.
987
988	When a canonical resource needs mutable event-source configuration and there is any chance of circularity, prefer a resource binding contract over a plain input prop. DynamoDB Streams is the reference case: `Table` owns the actual stream state, while `streams(table)` injects that state via bindings and the runtime-specific layer handles the subscription mechanics. See @processes/AWS.md for the DynamoDB Streams case study.
989
990	# Build and Type Checking
991
992	Always run type checking before committing changes:
993
994	```bash
995	pnpm exec tsc -b
996	```
997
998	This runs the TypeScript compiler in build mode, which checks all projects in the workspace (including the distilled packages, which are project references). This is critical because CI will fail if there are type errors.
999
1000	## Running tests
1001
1002	`packages/alchemy/test` runs on alchemy-test (`packages/alchemy-test`), our own single-process, Effect-native test runner. The CLI is vitest/bun-test compatible: positional paths (files or directories) and `-t` work the same way.
1003
1004	There is exactly ONE entry point: `pnpm test <options>`. It works identically from the repo root and from `packages/alchemy` (the root script just cds into `packages/alchemy`); suite paths are always relative to `packages/alchemy`. Compose the flags you need — there are no per-variant package scripts. NOTE: `pnpm test`, not `bun test` — the latter invokes bun's own built-in test runner.
1005
1006	```bash
1007	# a suite, against the real cloud
1008	pnpm test test/Cloudflare/{Service}/{Resource}.test.ts --profile testing
1009
1010	# a directory, filtered by test name
1011	pnpm test test/Cloudflare/Workers -t "cron" --profile testing
1012
1013	# positional args that aren't real paths are file-name substring filters
1014	pnpm test Bucket --profile testing # every Bucket test file
1015
1016	# skip the slow tests (replaces the old FAST=1 env prefix)
1017	pnpm test --fast --profile testing
1018
1019	# interactive TUI (humans only — never in an agent shell)
1020	pnpm test --tui
1021	```
1022
1023	(`examples/` still use plain `bun test`.)
1024
1025	### Cleaning leaked test resources
1026
1027	If an interrupted live-cloud test leaves resources behind, do not add
1028	test-specific API cleanup helpers, adoption workarounds, or alternate names to
1029	make the test pass. Clean the testing account with the account-wide teardown
1030	command, then rerun the failing test:
1031
1032	```bash
1033	pnpm nuke
1034	pnpm clear:state --profile testing
1035	```
1036
1037	Lifecycle tests should continue to validate normal stack ownership and cleanup;
1038	they must not silently adopt or directly delete leaked resources from earlier
1039	runs.
1040
1041	Additional flags beyond vitest:
1042
1043	\| Flag \| Default \| Purpose \|
1044	\| ----------------- \| ------- \| ------------------------------------------------------------- \|
1045	\| `-t <regex>` \| — \| Test-name pattern (regex, like bun/vitest) tested against the full nested title (`file > describes > name`), so any fragment matches regardless of nesting. An invalid regex degrades to a literal substring instead of erroring. Remember to escape regex metacharacters when filtering literally: `-t "create $default$"` \|
1046	\| `--profile <name>` \| — \| Sets `ALCHEMY_PROFILE` before any test module is imported. Use `--profile testing` for live-cloud suites instead of an `ALCHEMY_PROFILE=testing` env prefix \|
1047	\| `--fast` \| off \| Sets `FAST=1` before imports — suites `skipIf(process.env.FAST)` their slow tests (long-provisioning resources, smoke tests). Replaces the `FAST=1` env prefix \|
1048	\| `--timeout <ms>` \| 120000 \| Default per-test timeout \|
1049	\| `--retry <n>` \| 2 \| Re-runs of a failing test body (use `--retry 0` when debugging) \|
1050	\| `--concurrency <n\\|unbounded>` \| 32 \| Files running concurrently (one bun process, no forks). Bounded by default — unbounded saturates the event loop on large suites and produces spurious 0ms `beforeAll` timeouts \|
1051	\| `--sequential` \| off \| Run tests within each file sequentially \|
1052	\| `--tui` \| off \| Opt-in interactive TUI (default is line-per-test output) \|
1053
1054	Output behavior (plain mode, the default):
1055
1056	- The collection phase (importing every test file, ~45s for the full suite) reports `collecting N/TOTAL test files (elapsed) <current file>` — repainted in place on a TTY, printed every 5s otherwise. A run that appears stuck before any test starts is almost always just collecting; if it really is stuck, the line names the file whose import hangs.
1057	- One line per test as it finishes, prefixed with a `[done/total]` progress counter so the remaining count is visible; a failing test prints its error and captured output inline immediately.
1058	- Passing tests' output is swallowed on the console — but every test's output (passes included) is streamed to a per-run log at `.alchemy/log/test/{timestamp}-pid{pid}.log` (relative to the cwd), so concurrent runs in different terminals never trample each other. The absolute path (with line/KB counts) is printed at the end of every run (`Full log: …`) — read that file when you need the complete record, e.g. a passing test's deploy output or a hang's partial log. The file is appended live, so it's readable mid-run; logs older than a week are pruned automatically (by stat mtime).
1059	- If nothing finishes for 10s, the runner prints the list of currently-running tests with elapsed times — the first place to look when a run seems hung.
1060	- Exit code is non-zero if any test failed.
1061
1062	Runner semantics to know:
1063
1064	- Everything runs in ONE bun process: files run concurrently (respecting `describe.sequential`), imports of all test files happen up-front (they must be lazy and pure — registration only, no top-level side effects beyond `Test.make`/`describe`/`test`).
1065	- Tests that mutate process-global state (e.g. `process.env.PATH`) must pass `{ exclusive: true }` in the test options to take the whole-process write lock.
1066	- The harness (`alchemy-test` package) provides `describe`, `it`/`test` (incl. `it.effect`/`it.live`), hooks, `layer`, `expect`, and `assert` — the codemod `scripts/codemod-alchemy-test.ts` migrates vitest imports and is idempotent.
1067	- The runner runs in plain bun, so distilled resolves from `src/*.ts` via the `bun` export condition — a regenerated service is test-visible immediately, no `lib/` rebuild required.
1068
1069	## The convergence loop: nuke → test → census → fix-fleet
1070
1071	Ironing out the AWS suite is an iterative loop, driven by a coordinator, that terminates only when the suite is green AND the account is clean for two consecutive rounds. "Green" alone is not the bar — a passing test that leaves cloud resources behind is a provider bug by definition.
1072
1073	Each iteration:
1074
1075	0. Clean slate — first run `aws sso login` (the alchemy `testing` profile and the raw `aws` CLI ride the same SSO session; an expired token mid-round breaks the pipeline with auth errors — only escalate to a human if the login doesn't complete automatically). Then `pnpm nuke --yes` (deletes every alchemy-tagged cloud resource; `scripts/nuke.sh` already spares state buckets, SSO roles, and AWS-managed singletons) then `pnpm alchemy state delete Nuke --config ./stacks/nuke.ts --profile testing --recursive`. Never overlap nuke with a running suite. Plain `pnpm clear:state` lacks the profile and dies on expired Cloudflare OAuth; nuke without `--yes` hangs on an interactive confirm in non-interactive shells.
1076	1. Full suite, bounded — `pnpm test test/AWS --profile testing`. The runner defaults to `--concurrency 32`; NEVER override it to `unbounded` on a full-suite run: all ~775 files' `beforeAll` deploys start at once, the event loop saturates, and hundreds of fake 0ms `beforeAll TimeoutError` failures drown the real signal (heap is ~8.5 GB regardless of N — the constraint is CPU, not memory). Target ≤10 min wall-clock, hard cap 128; measured 32 → ~21 min clean. The saturation tell is `beforeAll` failures at 0ms; real failures fail slow. If the cap can't reach 10 min, the residual is individual slow files — skipIf-gate them per the speed doctrine.
1077	2. Leak census — `pnpm nuke --dry-run` after the suite; diff against the pre-suite baseline. Worklist = failed services ∪ leaking services (a service can pass green and still leak). Leave the leaked resources LIVE as forensic evidence for the fix agents; carry-over holdouts that survive repeated nuke passes (stuck deletes) go on the worklist too — their delete path is the bug.
1078	3. Fix-fleet workflow — one agent per service on the worklist (account-singleton services — CloudTrail, Config, SecurityHub, GuardDuty, ControlTower, IdentityCenter — run as a sequential chain; everything else fans out). Each agent gets its exact failures, its leak inventory, and this root-cause priority: provider bug > distilled patch > test fix — never paper over a provider leak in the test. Each agent runs ONLY its own suite (`timeout 240 pnpm test test/AWS/{Service} --profile testing`), audits its tests for non-deterministic names (rely on PhysicalName auto-naming; random data in message payloads/idempotency tokens is fine), verifies zero orphans from its service via out-of-band distilled list/describe calls, and reports a structured result. Agents never run tsc/build and never run the account-wide nuke.
1079	4. Gate — the coordinator runs the one-shot `pnpm exec tsc -b`, fixes cross-cutting fallout, commits the iteration (+ distilled submodule bump when patches were made), and loops back to 0. Terminate on two consecutive iterations of green-suite + census reduced to documented-undeletable residue (e.g. BackupSearch terminal records, Contributor-Insights rules with no delete API, keys in scheduled deletion).
1080
1081	## Multi-agent sessions: the coordinator owns type-checking
1082
1083	When many agents work concurrently (see The Resource Factory Process), do NOT let each agent run `pnpm exec tsc -b` — concurrent runs thrash the machine and race on `tsbuildinfo`. Agents never invoke the compiler; the coordinator runs a one-shot `pnpm exec tsc -b` at wave boundaries as the authoritative type check.
1084
1085	## Build Commands
1086
1087	\| Command \| Description \|
1088	\| ----------------- \| -------------------------------------------------------------------------------------------- \|
1089	\| `pnpm exec tsc -b` \| Type check all projects (always run before committing) \|
1090	\| `pnpm build` \| Clean, type check, and build the alchemy package \|
1091	\| `pnpm build:clean` \| Full clean rebuild: cleans all artifacts, reinstalls dependencies, builds, and downloads env \|
1092
1093	Use `pnpm build:clean` when you encounter stale build artifacts or dependency issues. It runs:
1094
1095	1. `pnpm clean .` - Removes all untracked files except .env
1096	2. `pnpm install` - Reinstalls dependencies
1097	3. `pnpm build` - Builds the project
1098	4. `pnpm download:env` - Downloads environment files
1099
1100	# Tutorial Documentation Standard
1101
1102	Tutorials under `website/src/content/docs/tutorial/` are step-by-step and granular: every code snippet introduces exactly one new thing, followed by a short prose explanation of just that thing. Each step gets its own `##` heading.
1103
1104	Anti-pattern — one snippet that adds multiple distinct changes, followed by a numbered list or bullet list explaining each:
1105
1106	````md
1107	## Bind the DO to the Worker
1108
1109	```diff lang="typescript"
1110	+import Counter from "./counter.ts";
1111	+import { HttpServerRequest } from "...";
1112
1113	Effect.gen(function* () {
1114	+ const counters = yield* Counter;
1115	return {
1116	fetch: Effect.gen(function* () {
1117	+ const request = yield* HttpServerRequest;
1118	+ if (request.url.startsWith("/counter/") && ...) {
1119	+ const next = yield* counters.getByName(name).increment();
1120	+ return HttpServerResponse.text(String(next));
1121	+ }
1122	return HttpServerResponse.text("Hello!");
1123	}),
1124	};
1125	})
1126	```
1127
1128	Two things just happened:
1129	1. `yield* Counter` registers the DO ...
1130	2. `counters.getByName(name)` returns a typed stub ...
1131	````
1132
1133	Correct — split into one heading per step, each with one snippet and one explanation:
1134
1135	````md
1136	## Bind the DO to the Worker
1137
1138	```diff lang="typescript"
1139	+import Counter from "./counter.ts";
1140
1141	Effect.gen(function* () {
1142	+ const counters = yield* Counter;
1143	...
1144	})
1145	```
1146
1147	`yield* Counter` registers the DO with the Worker (binding + class-migration metadata) and hands you the namespace.
1148
1149	## Call the DO from `fetch`
1150
1151	```diff lang="typescript"
1152	+import { HttpServerRequest } from "...";
1153
1154	fetch: Effect.gen(function* () {
1155	+ const request = yield* HttpServerRequest;
1156	+ if (request.url.startsWith("/counter/") && ...) {
1157	+ const next = yield* counters.getByName(name).increment();
1158	+ return HttpServerResponse.text(String(next));
1159	+ }
1160	return HttpServerResponse.text("Hello!");
1161	})
1162	```
1163
1164	`counters.getByName(name)` returns a typed stub — `increment()` and `get()` round-trip through Cloudflare's RPC machinery.
1165	````
1166
1167	Rules of thumb:
1168
1169	- If you find yourself writing "Two/three things just happened", "A few things are happening here", or a numbered/bulleted list explaining separate parts of a single snippet — split the snippet.
1170	- One concept ⇒ one heading ⇒ one diff snippet ⇒ one explanation paragraph (no bullets).
1171	- Bullet/numbered lists are fine when they describe a recap, prerequisites, or genuinely list-shaped content (e.g. "the Worker now handles two routes: PUT and GET" at the end). They are not fine as a substitute for splitting a compound snippet.
1172	- A single API call that internally does several things (e.g. `Cloudflare.upgrade()`) doesn't need splitting — describe its behavior in prose.
1173	- Use `diff lang="typescript"` blocks so each step shows what's added on top of the previous step.
1174
1175	# Pull Request Conventions
1176
1177	When you automatically open a PR, it MUST follow this structure:
1178
1179	- Title: Use conventional commit format (e.g. `fix(website): mobile theme metas`, `feat(aws/s3): add bucket lifecycle rules`).
1180	- Description heading levels: NEVER use `#` or `##` in the PR description. The smallest heading allowed is `###`. The PR description must NOT begin with its own title heading — GitHub already renders the PR title above it.
1181	- Content: Aim for the minimal content needed to convey the idea.
1182	- Use simple sentences. If there are multiple discrete changes, use bullet points.
1183	- Prefer code snippets over prose. A short ` ```ts ` or ` ```diff ` block showing the new/changed shape is worth more than a paragraph explaining it. Reach for code first; only add prose to fill in the "why" the snippet can't show on its own.
1184	- Be direct and succinct. Cut adjectives, justifications, and anything that reads like marketing copy. If a sentence is restating what the diff already shows, delete it.
1185	- Never include a "Test plan", "Testing", or checklist of TODOs. PR descriptions document the change, not the verification process. If something needs manual verification, follow the draft-PR rule below.
1186	- Skip examples for trivial fixes, internal refactors, or doc-only changes.
1187
1188	Example PR description (good — code snippet does the talking):
1189
1190	````
1191	Track which state-store backend each project uses by emitting a `state_store.init` span tagged with `alchemy.state_store.kind`.
1192
1193	```ts
1194	// every Layer.effect(State, …) site now wraps construction:
1195	makeLocalState().pipe(recordStateStoreInit("local"))
1196	```
1197
1198	Dashboard groups projects by kind from these spans (Axiom can't APL-query metric datasets).
1199	````
1200	- Outstanding work / testing / review needed: If there are outstanding steps, manual testing required, or review items, DO NOT leave a comment on the PR and DO NOT include them in the PR description. Instead:
1201	1. Mark the PR as draft.
1202	2. Tell the user (in the chat that initiated the PR creation) what is outstanding.
1203
1204	:::warning
1205	Markdown content must reach GitHub verbatim — un-escaped backticks, fenced code blocks, etc. The reliable shape is to write the description to a file and pass `--body-file <path>` to `gh pr create` / `gh pr edit`:
1206
1207	```sh
1208	# write the body to a temp file (use Write tool, not echo/cat heredoc)
1209	gh pr edit 179 --body-file /tmp/pr-body.md
1210	```
1211
1212	Do not inline the body via `--body "$(cat <<'EOF' ... EOF)"`. Even with a single-quoted heredoc some shells / `gh` versions still mangle backticks and backslashes; the resulting PR body ends up with literal `\`` sequences instead of inline code spans. `--body-file` sidesteps shell quoting entirely.
1213
1214	If you need to update an already-created PR's body, prefer `gh pr edit --body-file ...`. If that silently no-ops (older `gh` versions), fall back to `gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -F body=@/tmp/pr-body.md`.
1215	:::
1216
1217	The summary goes at the very top of the description as plain prose — NO heading above it, no `### Summary`, nothing. The PR title already serves as the title; do not repeat or re-title it. Only add `###` subheadings further down if the description genuinely has multiple sections worth separating.
1218
1219	Example PR description (good):
1220
1221	```
1222	Persist the user's selected theme across reloads and fix a hero scroll glitch on mobile.
1223
1224	- Read theme from `localStorage` on mount before first paint
1225	- Add `<meta name="theme-color">` per theme so mobile chrome matches
1226	```
1227
1228	Example PR description (BAD — do not do this):
1229
1230	```
1231	## Theme persistence fix ← no, the PR title already exists
1232	### Summary ← no, summary needs no heading
1233	Persist the user's theme...
1234	```
1235
1236	# Blog / Release Notes Conventions
1237
1238	Release blog posts live in `website/src/content/docs/blog/` named
1239	`YYYY-MM-DD-beta-NN.md` (date = the release date).
1240
1241	Frontmatter `title` format: `<version> - <short title>`, e.g.
1242	`2.0.0-beta.45 - Config & RPC Workers`. The title renders in the
1243	blog TOC sidebar, so the descriptive suffix must be short — a few
1244	words that fit neatly on one line. Lead with the version so the
1245	list stays sorted and scannable.
1246
1247	Writing style (match the existing beta posts, e.g.
1248	[beta.41](./website/src/content/docs/blog/2026-05-20-beta-41.md),
1249	[beta.44](./website/src/content/docs/blog/2026-05-22-beta-44.md)):
1250
1251	- Lean, concise, zero-fluff. Illustrate each new
1252	feature/fix and link to the relevant docs/tutorials/guides.
1253	- Read each PR in the release's changelog to understand what
1254	actually changed before writing.
1255	- Lead with the headline features (one `##` heading each, with a
1256	short code snippet or `diff`), then fold the long tail into an
1257	`## Also in this release` bullet list.
1258	- Put breaking changes in a `:::caution` callout at the top.
1259	- Cite PRs inline as `([#NNN](…/pull/NNN))` and credit external
1260	contributors by name.
1261	- End with a `## Where to go next` list of doc links plus the
1262	CHANGELOG and compare links.