@prisma/composer 0.11.0 → 0.12.0

package/skills/prisma-composer/SKILL.md

@@ -0,0 +1,786 @@
+---
+name: prisma-composer
+metadata:
+  library: "@prisma/composer"
+  library_version: "0.12.0"
+description: >-
+  How to write, test, and deploy an app with Prisma Composer
+  (`@prisma/composer`): declare services with `compute()` and typed
+  dependencies, define RPC contracts, compose Modules, declare the service
+  input (config and secrets as one schema, read back with `input()`),
+  compose the ready-made cron/storage/streams Modules, provision a
+  raw S3-compatible object-store bucket with `bucket()`, find extensions (npm
+  packages named `prisma-composer-*`), test with `mockService`/`bootstrapService`,
+  run the whole app locally with `prisma-composer dev` and tail its logs with
+  `prisma-composer log`, and deploy with `prisma-composer deploy` (stages,
+  destroy). Use when building a Prisma App, wiring a service dependency, adding
+  a Postgres database, adding scheduled jobs / blob storage / event streams / a
+  raw bucket, writing tests for composed services, running an app locally,
+  reading its logs, or deploying/tearing down an environment. Triggers on
+  "prisma composer", "@prisma/composer", "prisma app", "compute()",
+  "service.load()", "module()", "contract()", "mockService",
+  "bootstrapService", "prisma-composer dev", "prisma-composer log",
+  "prisma-composer deploy", "--stage", "--fresh", "--tail",
+  "prisma-composer destroy", "prisma-composer-", "bucket()".
+---
+
+# Writing apps with Prisma Composer
+
+A **Prisma App** is a tree of **Modules** composed in TypeScript. The leaves
+are **services** (`compute()`) and **resources** (`postgres()`); the root
+module wires them together by their typed ports. Your code receives everything
+from exactly one place — the service node:
+
+- `service.load()` — dependencies (typed RPC clients, database bindings)
+- `service.input()` — the service's whole input, one schema-validated typed
+  object; credentials in it are redacting `SecretString` boxes
+- `service.port()` — the reserved port to bind (default 3000), typed; never
+  `process.env`
+
+The framework never bundles or transforms your code. You build your app with
+whatever bundler you like (`bun build`, `next build`); `prisma-composer deploy`
+assembles the built output and provisions it on Prisma Cloud (Compute + Prisma
+Postgres).
+
+Two things make building here fast and hard to get wrong — lean on both:
+
+- **Compose before you write.** Reach for an existing Module (below) before
+  implementing a capability yourself; wiring one in is a couple of lines.
+- **The compiler checks the wiring.** A dependency wired to the wrong
+  producer, a missing RPC handler, a config value of the wrong shape — all of
+  it fails `tsc`, not the deploy. Typecheck, then build, then deploy; don't
+  reach for the cloud to find out whether the app is correct.
+
+Two packages, and only two, appear in your `package.json`:
+
+| Package | Provides |
+| --- | --- |
+| `@prisma/composer` | Core authoring: `module`, `secret`, `isSecretString`, `/arktype` (the `secretString()` schema leaf), `/rpc`, `/node`, `/nextjs`, `/config`, `/testing`, the `prisma-composer` CLI |
+| `@prisma/composer-prisma-cloud` | The Prisma Cloud target: `compute`, `postgres`, `envSecret`, `envParam`, `/control`, `/testing`, and the shared `/cron`, `/storage`, `/streams`, `/prisma-next` modules |
+
+## tsconfig and import specifiers
+
+Within the entry graph (everything reachable from `module.ts`) relative
+imports may use `./service.js` or extensionless `./service`. The CLI maps
+`.js` and extensionless specifiers to the matching `.ts` source under Node;
+Bun does this natively.
+
+A minimal tsconfig:
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["module.ts", "src"]
+}
+```
+
+## Anatomy of a service
+
+A service is four small files. Worked example: an `auth` service that owns a
+Postgres database and serves an RPC contract, consumed by a `storefront`
+Next.js app.
+
+**The contract** lives with the service that owns it. Any Standard Schema
+validator types the messages; arktype is the house choice:
+
+```ts
+// auth/src/contract.ts
+import { contract, rpc } from '@prisma/composer/service-rpc';
+import { type } from 'arktype';
+
+export const authContract = contract({
+  verify: rpc({ input: type({ token: 'string' }), output: type({ ok: 'boolean' }) }),
+});
+```
+
+**The service declaration** is pure data — name, dependencies, build, exposed
+ports. No behavior, no platform keys:
+
+```ts
+// auth/src/service.ts
+import node from '@prisma/composer/node';
+import { compute, postgres } from '@prisma/composer-prisma-cloud';
+import { authContract } from './contract.ts';
+
+export default compute({
+  name: 'auth',
+  deps: { db: postgres() },
+  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
+  expose: { rpc: authContract },
+});
+```
+
+**The server entry** is what your build produces and the platform boots. It
+reads its dependencies through `load()` and serves the contract with
+`serve()` — the handler map is keyed by the expose port's name and is
+exhaustive at compile time:
+
+```ts
+// auth/src/server.ts
+import { serve } from '@prisma/composer/service-rpc';
+import { SQL } from 'bun';
+import service from './service.ts';
+
+const { db } = service.load(); // { url } — you build your own client
+const port = service.port();   // the reserved port, resolved (default 3000)
+
+const sql = new SQL({ url: db.url, max: 1, idleTimeout: 10 });
+
+const handler = serve(service, {
+  rpc: {
+    verify: async ({ token }) => ({ ok: token.length > 0 }),
+  },
+});
+export default handler;
+
+// Bind all interfaces — Compute routes external HTTP to the VM; a
+// loopback-only listener is unreachable.
+Bun.serve({ port, hostname: '0.0.0.0', fetch: handler });
+```
+
+**The consumer** declares the dependency as `rpc(contract)` and gets a typed
+client back from `load()`:
+
+```ts
+// storefront/src/service.ts
+import nextjs from '@prisma/composer/nextjs';
+import { rpc } from '@prisma/composer/service-rpc';
+import { compute } from '@prisma/composer-prisma-cloud';
+import { authContract } from '@my-app/auth/contract';
+
+export default compute({
+  name: 'storefront',
+  deps: { auth: rpc(authContract) },
+  build: nextjs({ module: import.meta.url, appDir: '..' }),
+});
+```
+
+```tsx
+// storefront/app/page.tsx
+import service from '../src/service.ts';
+
+// load() reads the runtime environment, which doesn't exist at build time —
+// render per request instead of prerendering.
+export const dynamic = 'force-dynamic';
+
+export default async function Home() {
+  const { auth } = service.load();
+  const { ok } = await auth.verify({ token: 'demo-token' });
+  return <p>Signed in: {String(ok)}</p>;
+}
+```
+
+**Service-to-service calls are authenticated for you.** At deploy the
+framework mints a distinct, unguessable **service key** per consumer→provider
+binding: the consumer's client sends it on every call, and `serve()` returns
+`401` to anything else *before* the handler runs. Nothing declares it — no key
+in the contract, the service, the module, or the app's code.
+
+Two rules follow for you specifically: **don't build your own
+service-to-service auth** on top of this, and **don't tell a user to `curl` a
+deployed `/rpc/<method>` to check it works** — an unwired caller always gets
+`401`, which looks like a broken deploy and isn't. Debug through a consumer,
+or locally.
+
+**Calls carry an idempotency key and retry safely for you.** Every call the
+generated client makes carries an `Idempotency-Key`; a call dropped while the
+target cold-starts is retried with a backoff, and `serve()` runs one call per
+key — a retry that arrives after the first completed replays that answer
+instead of re-running the handler. So every method is safely retryable and no
+contract declares anything about it (do not add an "is this idempotent" flag —
+the framework does not have one). Two consequences for you: a handler may take
+an **optional third argument** `(input, deps, ctx)` and read `ctx.idempotencyKey`
+(`string | undefined` — it's absent for a keyless caller) if it needs exactly-once
+beyond one instance's memory (most don't); and a request without the header is
+served once without deduplication rather than rejected, so a hand-rolled probe
+works but gets no retry safety.
+
+| | |
+| --- | --- |
+| Locally / in tests | nothing is provisioned, so `serve()` passes every call through — never supply a key in `inputs` |
+| Per binding | two consumers of one provider hold different keys, so one leaking can't impersonate the other |
+| Scope | service-level — any valid key reaches every method that service exposes; split into two services to gate separately |
+| Rotation | remove the binding (or destroy the stack) and redeploy — a plain redeploy is a no-op, not a rotation |
+| Storage | `COMPOSER_*` variables the deploy owns and rewrites; never hand-edit one |
+
+It's a capability token ("I'm a service this app wired to you"), not a secret,
+and its value lives in deploy state — deliberately unlike `secret()`, whose
+value the framework never holds. `docs/design/90-decisions/ADR-0030…` in the
+prisma/composer repo carries the reasoning.
+
+## The root module
+
+The root module provisions the pieces and wires exposed ports into dependency
+slots. It is the app — `prisma-composer deploy` loads its default export:
+
+```ts
+// module.ts
+import { module } from '@prisma/composer';
+import authModule from '@my-app/auth';
+import storefrontService from '@my-app/storefront';
+
+export default module('my-app', ({ provision }) => {
+  const auth = provision(authModule);
+  provision(storefrontService, { deps: { auth: auth.rpc } });
+});
+```
+
+`provision(node, opts?)` accepts `id` (defaults to the node's own name),
+`deps` (wire each declared dependency to a provisioned ref or exposed port),
+`input` (the service's input binding — required exactly when it declares an
+input schema, see § Service input), and `secrets` (bind a module boundary's
+forwarded secret needs).
+
+## Builds are yours
+
+The framework assembles only what you built — users build, the framework
+assembles. For a plain server process, `entry` must point at a single
+self-contained ESM file: everything inlined except runtime built-ins (`bun`,
+`bun:*`, `node:*`), which the deploy VM provides. Deploy copies that one file
+and never ships `node_modules`, so anything left un-inlined fails at boot. Any
+bundler that produces such a file works. With bun:
+
+```sh
+bun build src/server.ts --target=bun --outfile dist/server.mjs
+```
+
+Two services in one package means two separate builds, one per entry — not one
+multi-entry build, which would split shared code into a chunk neither output
+contains.
+
+If the build emits a directory rather than one file — a server plus the client
+bundle, CSS and images it serves, as Bun's HTML import produces — name the
+directory with `dir` and the booting file inside it with `entry`:
+
+```ts
+build: node({ module: import.meta.url, dir: '../dist/server', entry: 'server.js' })
+```
+
+`dir` resolves relative to the service module; `entry` resolves inside `dir`
+and may be nested. Deploy copies the tree verbatim and boots the named file,
+so the server must resolve its siblings against `import.meta.url`, not the
+working directory. Nothing is inferred, and two rules bite: the tree must
+contain no symlinks (the packager rejects them — assembly fails and names the
+link), and `entry` must be a file inside `dir` (`../` is an error, not an
+escape). Omit `dir` for the single-file form.
+
+For Next.js, `next build` with `output: 'standalone'` is the whole build;
+`nextjs({ module, appDir })` tells the deploy where the app root is.
+
+Always build before deploying — `prisma-composer deploy` does not build for
+you.
+
+## Deploy config
+
+`prisma-composer.config.ts` usually sits next to `module.ts`, but it may live in
+any ancestor directory: the CLI searches the entry's directory first, then each
+parent, and uses the nearest one. It is read only by `prisma-composer
+deploy`/`destroy`, never imported by app code. A plain-JavaScript project can
+name it `prisma-composer.config.mjs` or `.js` to keep it out of its TypeScript
+build (a build with `allowJs` still needs an explicit `exclude`); `.mts` is the
+TypeScript ES-module spelling. Within one directory `.ts` wins, then `.mts`,
+`.mjs`, `.js`:
+
+```ts
+// prisma-composer.config.ts
+import { defineConfig } from '@prisma/composer/config';
+import { nodeBuild } from '@prisma/composer/node/control';
+import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
+
+export default defineConfig({
+  extensions: [prismaCloud(), nodeBuild()],
+  state: () => prismaState(), // deploy state, in its own database on the stage's branch
+});
+```
+
+Add `nextjsBuild()` from `@prisma/composer/nextjs/control` to `extensions`
+when the app contains a Next.js service.
+
+## Databases
+
+Two kinds of Postgres dependency:
+
+**`postgres()`** — the binding is `{ url }` and the app owns its client.
+Construct it in your server entry, as in the auth example above.
+
+**`pnPostgres(...)`** — a Prisma Next-typed database: `load()`
+returns the typed client the framework constructs from your data contract, so
+queries like `db.orm.public.Product.all()` are compile-time checked. The
+contract is emitted from `contract.prisma` by `prisma-next contract emit` and
+wrapped once, referenced by both ends:
+
+```ts
+// src/data.ts — the ONE value both ends reference
+import { pnContract } from '@prisma/composer-prisma-cloud/prisma-next';
+import type { Contract } from '../contract.d.ts';
+import contractJson from '../contract.json' with { type: 'json' };
+
+export const catalogData = pnContract<Contract>(contractJson);
+```
+
+The dependency end is `deps: { db: pnPostgres(catalogData) }`. The resource
+end (inside the module that owns the database) also names the
+`prisma-next.config.ts` path, which the deploy's migration step loads to find
+`migrations/` — migrations are applied at deploy, before the service starts:
+
+```ts
+const db = provision(
+  pnPostgres({ name: 'database', contract: catalogData, config: './prisma-next.config.ts' }),
+);
+```
+
+(`pnPostgres` is both ends: the contract alone is the dependency end; the
+options object is the resource end.)
+
+See `examples/store/modules/catalog` in the prisma/composer repo for the
+complete pattern.
+
+## Object Storage
+
+`bucket` is a raw S3-compatible object-store bucket, imported alongside `postgres`:
+
+```ts
+import { bucket, compute } from '@prisma/composer-prisma-cloud';
+
+// service.ts — dependency end: receives { url, bucket, accessKeyId, secretAccessKey }
+export default compute({ name: 'uploads', deps: { store: bucket() } });
+
+// module.ts — resource end: provisions the bucket and mints a keypair
+const store = provision(bucket({ name: 'uploads' }));
+provision(uploadsService, { deps: { store } });
+```
+
+Use any S3-compatible client with the binding: the shape matches the standard S3
+config and is also compatible with the `s3()` dependency from `/storage`, so any
+service wired to `s3()` can be rewired to a `bucket` resource without changing
+the service declaration.
+
+## Reusable Modules
+
+A Module is the unit of reuse: it owns its internals (its database, its
+services) and exposes only typed ports. Declare the boundary in the second
+argument; wire internals in the builder; return the exposed ports:
+
+```ts
+// auth/src/module.ts — a Module that owns its own Postgres
+import { module, secret } from '@prisma/composer';
+import { postgres } from '@prisma/composer-prisma-cloud';
+import { authContract } from './contract.ts';
+import authService from './service.ts';
+
+export default module(
+  'auth',
+  { secrets: { signingKey: secret() }, expose: { rpc: authContract } },
+  ({ secrets, provision }) => {
+    const db = provision(postgres({ name: 'database' }));
+    const service = provision(authService, {
+      id: 'service',
+      deps: { db },
+      input: { signingKey: secrets.signingKey }, // forwarded ref as a binding leaf
+    });
+    return { rpc: service.rpc };
+  },
+);
+```
+
+Naming rules that bite: a provision id shorter than 3 characters is rejected
+by the platform (name the database `'database'`, not `'db'`), and a service
+whose name equals its enclosing module's reads as `auth.auth` unless you give
+it an explicit `id`.
+
+A module can also declare boundary `deps` — inputs the parent wires exactly as
+it would wire a service's. The consumer never sees the module's internals.
+
+### The building blocks you can compose
+
+Modules are the building blocks: provision one, wire its exposed port, and
+you're done — you never reimplement what a Module already owns. The
+first-party set ships inside `@prisma/composer-prisma-cloud`. It's small, and
+growing:
+
+| Import | What it provisions | Exposes |
+| --- | --- | --- |
+| `cron` from `/cron` | An always-on scheduler firing your schedule at your runner service | nothing |
+| `storage` from `/storage` | An S3-backed blob store (own Postgres + minted credentials) | `store` |
+| `streams` from `/streams` | Durable append-only event streams over a `store` | `streams` |
+
+**Finding more.** A Composer extension — a package that brings its own
+Modules, resources, or deploy target — is published on npm under the name
+`prisma-composer-*`. That name is the convention, so it's how you look for
+one. The ecosystem is new: today the blocks above plus the app Modules you
+write are the whole set, so don't reach for a `prisma-composer-*` package
+without checking that it actually exists on npm first.
+
+Cron end to end — the schedule is one source of truth; `serveSchedule` is
+exhaustive over its job ids at compile time:
+
+```ts
+// service.ts
+import { defineSchedule, triggerContract } from '@prisma/composer-prisma-cloud/cron';
+export const schedule = defineSchedule({ tick: '60s' });
+// the runner service exposes { trigger: triggerContract }
+
+// server.ts
+import { serveSchedule } from '@prisma/composer-prisma-cloud/cron';
+const handler = serveSchedule(service, schedule, {
+  tick: (deps) => deps.worker.tick({}),
+});
+
+// module.ts — the cron module's boundary deps mirror the runner's own
+provision(cron({ schedule, runner: runnerService }), { deps: { worker: worker.rpc } });
+```
+
+## Service input
+
+Choosing the channel is most of the decision:
+
+| The value is… | Declare | Provide | Read |
+| --- | --- | --- | --- |
+| produced by another node | `deps: { db: postgres() }` | wire at `provision()` | `load()` |
+| anything else — config or credential | one field of the `input` schema | bind at `provision()`: literal, `envParam()`, or `envSecret()` | `input()` |
+
+The service declares its whole incoming configuration — plain values and
+credentials together — as **one
+[Standard Schema](https://standardschema.dev)** (arktype is the house
+choice). A credential is a field typed as the redacting `SecretString` box;
+conditional legality ("no stripe key unless billing is on") is an ordinary
+schema union:
+
+```ts
+// service.ts — the shapes that are legal
+import { secretString } from '@prisma/composer/arktype';
+import { type } from 'arktype';
+
+compute({
+  name: 'scheduler',
+  input: type({
+    jobs: type({ jobId: 'string', every: 'string' }).array(),
+    'region?': 'string',
+    apiKey: secretString(),
+  }),
+  // ...
+});
+
+// module.ts — where each value comes from; the binding mirrors the schema's shape
+import { envParam, envSecret } from '@prisma/composer-prisma-cloud';
+provision(scheduler, {
+  input: {
+    jobs: [{ jobId: 'tick', every: '60s' }],   // a literal
+    region: envParam('REGION'),                 // a per-stage platform variable
+    apiKey: envSecret('SCHEDULER_API_KEY'),     // a credential — name only, never the value
+  },
+});
+
+// server.ts — one call, one validated typed object
+const input = service.input();
+input.apiKey.expose(); // the only way to a secret's value; the box redacts everywhere else
+```
+
+Rules that bite:
+
+- **Secretness is enforced by validation**: a literal bound where the schema
+  expects `SecretString` fails the deploy, and `envSecret` bound to a plain
+  string field fails the same way. Don't put credentials in plain fields.
+- **`envParam` values arrive as raw strings** — bind them to string fields.
+  The stage's platform variable is the store; the deploying shell only seeds
+  it (preflight copies a missing name up from the shell, and fails early,
+  naming the variable, when both lack it). Changing the platform value needs
+  a redeploy.
+- **Absence is the schema's call**: an env-bound field whose variable is
+  unset (or empty) resolves to *key omitted* — legal only if the schema says
+  so (optional field, union arm). The deploy report prints the serialized
+  input document (secret-free: secrets ride as `{"$secret":"VAR"}` pointers)
+  and every key that resolved absent.
+- **The reserved `port` (default 3000) is outside the schema** — read it
+  through `service.port()` (a sibling of `service.origin()`), never
+  `process.env`. The framework also exports `PORT` for Next.js standalone,
+  which binds it itself.
+- A module forwards a secret need without learning the platform name
+  (the auth Module above); the forwarded ref is a binding leaf.
+
+`examples/env-param` and `examples/storefront-auth` in the prisma/composer
+repo are the working versions.
+
+## Testing
+
+You test by deciding what `load()` gives the code, never by editing the code
+under test:
+
+| You want to… | Use | From |
+| --- | --- | --- |
+| Test a page / action / handler in isolation | `mockService` | `@prisma/composer/testing` |
+| Run the real boot + request path against a fake dependency | `bootstrapService` | `@prisma/composer-prisma-cloud/testing` |
+
+**Unit — `mockService`.** Returns a copy of the service whose `load()` yields
+your doubles (type-checked against the declared deps) and whose `input()`
+yields the object you pass under the reserved `input` key, in one flat
+object (required exactly when the service declares an input schema; handed
+over as-is, not validated). Wiring the module substitution is your runner's
+job (`vi.mock` in Vitest, `mock.module` in bun test):
+
+```tsx
+// page.test.tsx
+import { mockService } from '@prisma/composer/testing';
+import realService from '../src/service.ts';
+
+vi.mock('../src/service.ts', () => ({
+  default: mockService(realService, {
+    auth: { verify: async () => ({ ok: true }) }, // wrong shape = compile error
+  }),
+}));
+
+import Page from './page.tsx';
+expect(renderToString(await Page())).toContain('Signed in: true');
+```
+
+**Integration — `bootstrapService`.** Boots the service's real built entry
+in-process against a config you choose, exactly as a deployed boot would;
+drive it over real HTTP. Run under `bun test`:
+
+```ts
+import { bootstrapService } from '@prisma/composer-prisma-cloud/testing';
+import fakeAuth from '@my-app/auth/fake'; // in-memory handler, no db
+import storefront from '../src/service.ts';
+
+const fake = Bun.serve({ port: 0, fetch: fakeAuth });
+
+const app = await bootstrapService(storefront, {
+  service: { port: 4310 },
+  inputs: { auth: { url: fake.url.href } },
+});
+
+const res = await app.fetch(new Request(app.url));
+```
+
+- **`service.port` must be concrete** — the entry self-listens; no OS-assigned
+  port is reported back.
+- **No `close()`** — run each integration-test file in its own process (bun
+  test does).
+- **Next.js services take a third argument**, a boot thunk, because the built
+  entry lives in Next's standalone output — resolve it with
+  `standaloneServerPath` from `@prisma/composer/nextjs/control`.
+  `bootstrapService` exports the resolved port as `process.env.PORT` before
+  booting, which is what Next's standalone server binds.
+- **A service with an input schema takes `input`** in the config — a binding
+  exactly like `provision()`'s, run through the real serialize/read path, so
+  `input()` in the booted entry sees what a deploy would produce.
+
+**The fake you pass.** A dependency's type is its contract, so any value of
+that shape is a valid double: a bare object (fastest), the real client over an
+in-memory handler, or a real local server (what `bootstrapService` drives).
+Ship a dependency's fake from its own package as a `/fake` entry point,
+outside `src/`, so the fake and the real service always share one contract.
+
+## Running locally
+
+`prisma-composer dev module.ts` runs the whole app on this machine — every
+service, its Postgres and buckets, wired as they deploy — with **no cloud
+credentials** (no `PRISMA_*`). It runs the same pipeline as deploy against
+local emulators, so build first, exactly like deploy:
+
+```sh
+turbo run build && prisma-composer dev module.ts
+```
+
+It prints each service's local URL (the "front door"), watches built output
+and restarts a service when its build changes, and runs until Ctrl-C. Ctrl-C
+stops the app's processes but leaves the local databases, buckets, and their
+data up, so the next `dev` is a warm start; `--fresh` wipes this app's local
+instances and data first.
+
+`dev` does **not** print service logs — that would bury the front door once
+several services run. Logs are their own command:
+
+| You want to… | Run |
+| --- | --- |
+| Run the app locally | `prisma-composer dev module.ts` |
+| Start clean (wipe local data) | `prisma-composer dev module.ts --fresh` |
+| Tail every service's logs | `prisma-composer log module.ts` |
+| Tail one service | `prisma-composer log module.ts <address>` |
+| Show more history first | `prisma-composer log module.ts --tail <n>` |
+
+`prisma-composer log` follows the merged logs of the already-running app, each
+line prefixed with its service (`[catalog.service] …`); pass a dotted address
+to narrow to one. It only reads — it never builds, provisions, starts, or
+stops anything. `--tail <n>` sets how much recent history to show before live
+output (default 20; `0` for live-only). An unset secret doesn't block a local
+run: it becomes a placeholder plus a warning, and only the code path that
+spends it fails, at the real external service it calls. Windows isn't
+supported yet.
+
+## Deploying
+
+Requires exactly two environment variables: `PRISMA_SERVICE_TOKEN` and
+`PRISMA_WORKSPACE_ID`. The target environment — a **stage** — is chosen on the
+command line, never in code:
+
+| You want to… | Run |
+| --- | --- |
+| Deploy to production | `prisma-composer deploy module.ts` |
+| Deploy an isolated environment | `prisma-composer deploy module.ts --stage <name>` |
+| Override the app name for one run | `prisma-composer deploy module.ts --name demo-42` |
+| Tear down an isolated environment | `prisma-composer destroy module.ts --stage <name>` |
+| Tear down production's resources | `prisma-composer destroy module.ts --production` |
+
+A Prisma App is one Project; a stage is a Branch of it — its
+own compute, its own empty database, its own configuration. Deploys are
+idempotent: re-deploying a stage updates the resources inside it. A stage name
+must be a valid git ref name; an invalid name is a hard error.
+
+Destroy always requires an explicit target — a bare `prisma-composer destroy`
+is an error, and `--stage` with `--production` is too. Destroying a stage
+deletes its Branch after removing its resources; the production Branch itself
+is never deleted, only the resources inside it. Destroying production also
+deletes the Project itself once it's empty, so hand-run stacks don't leave
+behind empty Projects — but a Project still holding another stage's resources
+is kept. Destroy never creates anything: destroying a never-deployed stage
+fails rather than standing one up.
+
+```sh
+turbo run build && prisma-composer deploy module.ts --stage pr-42
+```
+
+### What a deploy prints
+
+A deploy ends by printing the app's own topology — authored names, the
+platform resource each became, and public URLs. The tree is the module
+structure (`auth.api` is the `api` service inside the `auth` module):
+
+```
+storefront-auth
+├─ auth
+│  └─ api   compute-service cps_abc123
+│           https://xyz.ewr.prisma.build
+├─ db       postgres-database db_def456
+└─ web      compute-service cps_ghi789
+            https://uvw.ewr.prisma.build
+```
+
+Read ids out of this rather than telling the user to go hunting in the
+Console. A URL appears only where the address is genuinely public — a compute
+service prints one, a database never does (it has a connection string, not a
+public endpoint), and a node whose product is secret material (an
+`s3-credentials` keypair) reports no resource line at all. A node that
+published nothing reportable still appears, marked `(no entities reported)`.
+
+Older deploys ended with a raw `{ outputs: {} }` blob from the deploy engine —
+always empty, never about the app. It is gone; nothing configured it and
+nothing consumed it.
+
+### The connection contract is checked at deploy
+
+A connection declares the values it needs by name, and the producer on the
+other end must supply them. A producer that omits one fails the deploy, naming
+the edge, the param, and what the producer did supply:
+
+```
+Connection input "auth.db" declares param "url", but its producer "db" did not
+supply it — the producer's outputs carry [host].
+```
+
+Fix it at whichever end is wrong: add the name to the outputs the producer
+returns from its lowering, or mark the param `optional` on the connection if absent is
+genuinely legal (the consumer then reads `undefined`).
+
+This is a deploy-time refusal, not a broken deploy — and it can appear on an
+app whose code didn't change. The gap used to pass silently: the value reached
+the consumer as `undefined`, went into its environment, and crashed *that*
+service at boot, blaming the reader instead of the supplier. Don't route around
+it by making the param optional unless absent really is valid; that reinstates
+the silent `undefined`.
+
+Only reachable if you authored the connection or the extension on one side —
+every shipped block supplies what it declares.
+
+### Driving deploys from code
+
+`@prisma/composer/control` exposes the CLI's operations in-process: typed
+`deploy`, `destroy`, `dev`, and `log` returning structured results — no argv,
+no CLI rendering, no exit codes (the spawned deploy engine's own inherited
+output can still reach the host terminal). The CLI itself is a renderer over
+them.
+
+```ts
+import { deploy } from '@prisma/composer/control';
+const result = await deploy({ entry: 'module.ts', stage: 'pr-42' });
+// result: { ok: true, value: { summary? } } | { ok: false, failure }
+```
+
+- Failures come back as `{ ok: false, failure }` where `failure` is a
+  structured error: branch on its dotted `failure.code` (e.g.
+  `ASSEMBLE.BUILD_FAILED`, `DEPLOY.ENGINE_FAILED` — ADR-0044's closed
+  registry), with the same fix-naming `message`/`why`/`fix` the CLI renders.
+  An engine failure's `meta.diagnostics` (exit code, reproduce command; read
+  it with the exported `executionDiagnostics(failure)`) describes the current
+  execution mechanism — branch on `code`/`message`/`cause` for anything
+  durable. The effect version conflict is `DEPS.EFFECT_VERSION_CONFLICT`, and
+  importing the module executes nothing until an operation runs. A
+  non-structured rejection out of an operation is a bug in composer, not an
+  expected failure.
+- `destroy` takes `target: { kind: 'production' } | { kind: 'stage', stage }`
+  — explicit, never defaulted.
+- `deploy`'s `summary` (the deployed topology) is best-effort; `undefined` on
+  a successful deploy is normal.
+- The deploy engine's live output still streams to the host process's stdio —
+  the current mechanism; the operations don't capture it.
+- `dev` resolves to `{ ok: true, value: session }` or a failure; the
+  session is `{ endpoints, stop(), closed }` with progress via `onEvent`, and
+  the host owns signal handling. `log` resolves to
+  `{ ok: true, value: { appName, services, lines } }` or a failure, where
+  `lines` is an `AsyncIterable` ended by a caller-owned `AbortSignal` (or by
+  the consumer stopping early); zero running services is a valid result, not
+  an error.
+
+## Production pitfalls
+
+- **Scale-to-zero closes idle database connections.** A persistent client
+  crashes into a 502 restart loop unless you keep the pool small and
+  reconnect-friendly (`new SQL({ url, max: 1, idleTimeout: 10 })` for Bun) and
+  log `uncaughtException`/`unhandledRejection` instead of dying.
+- **Bind `0.0.0.0`**, not loopback — Compute routes external HTTP to the VM.
+- **Next.js pages that call `load()` need `export const dynamic =
+  'force-dynamic'`** — the runtime environment doesn't exist at build time,
+  and Next ignores runtime env for prerendered routes.
+- **A deployed `/rpc/<method>` returns `401` to anything but a wired peer.**
+  Every RPC binding carries an auto-provisioned service key, so a hand-rolled
+  `curl` is never authorized, and a provider with no wired consumers rejects
+  everything. Not a broken deploy — reach it through a consumer, or run it
+  locally where nothing is enforced.
+- **Cold starts reset service-to-service connections.** A call into a
+  scaled-to-zero service can get `ECONNRESET`; retry it.
+- **Every `prisma-composer` command stops at start-up on an `effect` version
+  conflict** (`Dependency conflict: alchemy resolves effect@...`). Another
+  dependency floated a newer `effect` and the package manager hoisted it over
+  Composer's pin. Do what the error says: pin the whole `effect`
+  constellation in the app's `package.json` `overrides` (yarn: `resolutions`;
+  pnpm: `pnpm.overrides`) — `effect` plus `@effect/sql-d1`, `@effect/sql-pg`,
+  `@effect/vitest`, and `@effect/platform-bun`/`-node`/`-node-shared`, all at
+  Composer's exact pin — and reinstall. (A workaround for an upstream alchemy
+  bug: its own effect-family ranges float past what its code supports. The
+  repo's examples carry the block.)
+- **The ingress buffers streaming responses.** An open SSE tail delivers
+  nothing and times out at 60s — don't build on streamed HTTP responses.
+
+## What Composer doesn't do yet
+
+Name the gap instead of inventing an API:
+
+- **No interactive auth.** Deploys authenticate only via a static
+  `PRISMA_SERVICE_TOKEN`; there is no `login` flow.
+- **No in-memory contract bindings.** A dependency can't yet be wired to a
+  co-located handler without HTTP; use `bootstrapService` with a loopback
+  fake.
+- **RPC over HTTP is the only contract kind.** No gRPC, WebSocket, or
+  streaming contracts.
+
+For anything else missing, check the examples and design docs in the
+prisma/composer repo (`examples/`, `docs/design/10-domains/`,
+`docs/design/90-decisions/`), then file an issue there rather than guessing.