The best way to control Claude Code, Codex and more from any computer or phone

main
md 217 lines 9.29 KB
Rendered Raw
1 # Intro design: a programming language for the cloud
2
3 The intro runs before chapter 0. It tells the story of why Alchemy exists
4 and how it works, then hands over to the demo. Like the demo chapters,
5 every numbered step is one press of →: one visual change, one caption.
6 Captions are in **bold**; the rest is what's on screen and what to say.
7
8 Code on screen is real: every Alchemy/Effect snippet lives in
9 `intro/snippets/*.ts`, type-checks against the repo, and type errors are
10 the real `tsc` messages. Pseudo-code (the imagined language) is marked as
11 such on screen.
12
13 ## Act 1: A programming language for the cloud
14
15 1. **A programming language for the cloud**
16 Title slide. Subtitle: "…without building a new language. Yet."
17
18 2. **A cloud program describes a world that outlives it**
19 Split screen. Left: an ordinary program as a timeline, entry → exit,
20 state gone. Right: a cloud program, where each run leaves behind a
21 persistent world (Functions, Databases, Buckets) that the next run must
22 start from.
23
24 3. **That world is a graph of resources**
25 The right-hand world becomes a graph: Function, Database, Bucket,
26 Queue nodes animate in, then the edges between them.
27
28 4. **Resources change over time: reconciliation**
29 Zoom into one Bucket node. Its config card steps v1 → v2 → v3
30 (versioning on, CORS added, lifecycle rule). Each change shows
31 *desired* vs *actual* and a "reconcile" arrow converging them.
32
33 5. **Connecting resources means permissions and configuration**
34 Zoom into the Function → Bucket edge. It expands into what it really
35 is: an IAM policy statement (`s3:GetObject` on the bucket ARN) and an
36 environment variable (`BUCKET_NAME`). Label the whole thing: a
37 **binding**.
38
39 6. **A cloud language could infer all of this from the code**
40 Pseudo-code: a function body calling `bucket.get(key)`. Hand-drawn
41 arrows from `bucket.get` to the inferred policy statement and to the
42 injected environment variable.
43
44 ## Act 2: Programs that run in phases
45
46 7. **Cloud programs run in two phases**
47 Two columns. *Construction*: declarative, builds the static
48 architecture: resources and bindings. *Runtime*: dynamic, imperative:
49 requests, jobs, data, API calls. A timeline underneath: construct once,
50 runtime many times.
51
52 8. **Runtime is written in terms of construction**
53 The two columns connect: runtime code points back at the resources and
54 bindings construction declared.
55
56 9. **Imagine colored functions**
57 Pseudo-code, lines tinted by phase:
58 ```
59 construct storage() {
60 const bucket = Bucket()
61 return {
62 runtime get(key) => bucket.get(key)
63 }
64 }
65 ```
66 `construct` lines in one colour, `runtime` lines in another.
67
68 10. **The colors are enforced boundaries**
69 Draw on it: a `runtime` function calling `Bucket()` gets a red
70 strike-through and "can't construct at runtime"; the reverse gets the
71 same.
72
73 11. **Inferring bindings is type checking**
74 The `get(key)` line is circled; beside it, the analysis: "over every
75 possible `key`, `get` can call `s3:GetObject` on this bucket", which
76 becomes the policy. It's the same shape of reasoning as inferring a
77 return type.
78
79 ## Act 3: How we tried before
80
81 12. **I've tried this before**
82 Timeline slide: Punchcard (2018/19, on the AWS CDK) → Functionless (2022) →
83 Alchemy.
84
85 13. **Punchcard: two phases on top of the AWS CDK**
86 A real Punchcard snippet (pulled from github.com/sam-goodwin/punchcard).
87 Then a bar grows beside it: the runtime bundle, dragging the whole CDK
88 along. **Runtime code shipped with all of the infrastructure code**
89
90 14. **Functionless: read the code's own AST at runtime**
91 A function, then its AST tree unfolding, walking into variables
92 captured from the lexical scope to find the resources it touches.
93 Annotate: bundling hacks to make the AST available.
94
95 15. **A square peg in a round hole**
96 Section slide. Both approaches bent a language into doing something it
97 was never designed to do.
98
99 ## Act 4: Effect is the missing piece
100
101 16. **Effect<A, Err, Req>**
102 The type signature, large. Each parameter lights up in turn with its
103 label: success, errors, and…
104
105 17. **Req: what a function needs from the outside world**
106 `Req` stays lit: an ordinary signature says what goes in and comes
107 out; `Req` says what the function *depends on*.
108
109 18. **Static analysis needs to see inside a function**
110 A function with a hidden call to the bucket inside its body. A
111 magnifying glass tries to peek in; annotate "breaks encapsulation".
112
113 19. **So lift it into the type instead**
114 Morph animation: the hidden dependency slides out of the body and into
115 the signature, `Effect<Buffer, NoSuchKey, GetObject>`. This is what
116 type systems are for.
117
118 20. **Context.Service and Layer separate interface from implementation**
119 Diagram: a `Context.Service` (the interface) on one side, a `Layer`
120 (the implementation) on the other, joined only at `Effect.provide`.
121 Callout back to step 13: this is exactly what Punchcard couldn't do.
122
123 21. **A resource's provider is required only by the Stack**
124 Real code: `yield* Bucket("Uploads")` inside a Worker. Its provider
125 requirement travels up the type, past the Worker, and is satisfied by
126 `Alchemy.Stack`'s `providers`. Two boxes: *Stack (deploy time only)*
127 holds the providers; *Worker bundle* contains none of them.
128
129 22. **A binding is a declaration**
130 Real code: `const getObject = yield* AWS.S3.GetObject(bucket)`.
131 Highlight: it says *what* the Worker may do, not *how*.
132
133 23. **The type system makes you provide an implementation**
134 Remove `Effect.provide(AWS.S3.GetObjectHttp)`: the real `tsc` error
135 appears as a red squiggle. Put it back: the error clears. `Http` is
136 the implementation's name: Alchemy's Distilled SDK over HTTP.
137
138 24. **The implementation wires up permissions too**
139 The `GetObjectHttp` layer forks by host. On Lambda: a least-privilege
140 statement added to the Function's IAM role. On a Cloudflare Worker (or
141 anywhere outside AWS): an IAM user that may assume a role, and its keys
142 bound to the Worker for short-lived credentials.
143
144 25. **Least privilege, by construction**
145 A Worker's policy panel beside its code. Add `GetItem`: one line of
146 code, one new statement. You can't call an API you didn't declare, so
147 permissions grow with the application, and never ahead of it.
148
149 ## Act 5: alchemy deploy is the compiler
150
151 26. **alchemy deploy is the compiler, without static analysis**
152 Pipeline: TypeScript checks the phases and requirements
153 (`Effect<A, Err, Req>`, `Layer<Out, Err, In>`) → running the program
154 builds the graph of resources and bindings → the graph is diffed into
155 a plan you review → apply.
156
157 ## Act 6: Components that include their runtime
158
159 27. **Infrastructure components have existed for years**
160 Terraform modules, CDK constructs, Pulumi components, drawn as boxes
161 full of infrastructure.
162
163 28. **But they can't include the code that uses them**
164 The runtime code sits outside each box. You can't ship an
165 application-facing component that brings its own infrastructure.
166
167 29. **In Alchemy, a component is just a Layer**
168 Real code: a `Links` `Context.Service` interface; a `Layer.effect`
169 that declares a table and its bindings in the construction phase and
170 returns the runtime interface.
171
172 30. **Swap the infrastructure, keep the business logic**
173 The Layer behind `Links` cycles S3 → R2 → DynamoDB → Neon; the
174 business logic above it doesn't change. (Chapter 6 of the demo does
175 this for real.)
176
177 ## Act 7: The colors, in the type system
178
179 31. **The phases are real, and TypeScript can check them**
180 Back to the colored-function pseudo-code, faded. Beside it, the real
181 Alchemy equivalent.
182
183 32. **Runtime calls need RuntimeContext**
184 Real code: inside a Worker's constructor, bind `GetObject` and call it
185 immediately. Red squiggle, with the real `tsc` error: the constructor
186 runs at deploy time too, and `RuntimeContext` isn't available there.
187
188 33. **An escape hatch, like ts-expect-error**
189 `Effect.provide(Alchemy.RuntimeContext.phantom)` squashes it: an
190 explicit opt-in, visible in review.
191
192 34. **Today a DSL, tomorrow a syntax**
193 Morph between the Effect code and the colored-function pseudo-code:
194 the same program. The TypeScript + Effect DSL is the foundation a
195 real syntax could sit on later.
196
197 35. **Let's build something**
198 Transition slide into chapter 0.
199
200 ## What this needs from the renderer
201
202 - **Code slides with steps**: Shiki-highlighted code where each step can
203 reveal lines, tint lines by phase, dim everything but a range, and
204 morph one snippet into another (tokens that survive glide to their new
205 place; new ones fade in).
206 - **Drawing on code**: hand-drawn circles, underlines, strike-throughs and
207 arrows to callout labels, drawn stroke by stroke (rough.js, MIT
208 licensed).
209 - **Real type errors**: a red squiggle under a range with an editor-style
210 error tooltip, text taken from `tsc` on the snippet.
211 - **Diagram slides**: the demo's node/edge style, with edges that expand
212 into their grant (policy JSON, env vars).
213 - **Timeline, split-screen, pipeline and type-signature layouts.**
214 - Authoring: `intro.ts` lists the steps with typed specs, and render
215 splits the intro into one presenter step per item, like the chapters.
216
217 Rough length: 35 steps, about 8–10 minutes of talking.