@prisma/composer 0.16.0 → 0.17.0-dev.1

package/dist/{run-alchemy--ZIvgqyU-BtZTukrY.mjs → run-alchemy-B6u4TxA0-DMUphChq.mjs}

@@ -1,16 +1,14 @@
 import { t as CliStructuredError } from "./errors-0e8IVwzi.mjs";
 import * as fs$1 from "node:fs";
 import * as path$1 from "node:path";
-import { spawn } from "node:child_process";
-//#region ../../0-framework/3-tooling/cli/dist/run-alchemy--ZIvgqyU.mjs
+import spawn from "cross-spawn";
+//#region ../../0-framework/3-tooling/cli/dist/run-alchemy-B6u4TxA0.mjs
 /**
 * Pipeline step 7 (deploy-cli.md § The pipeline; design-notes.md's "Driving
-* Alchemy" call): hand the terminal to the generated stack file. Resolves the
-* workspace's own installed `alchemy` bin (walking up `node_modules/.bin`
-* from the generated file's package dir) rather than going through
-* `bunx`/`npx`, so this works the same under node and bun — the resolved
-* bin's own launcher (`alchemy/bin/cli.js`) does its own node/bun dispatch
-* from there, driven by the env it inherits.
+* Alchemy" call): hand the terminal to the generated stack file.
+*
+* Resolves the installed `alchemy` bin and launches package-manager shims with
+* cross-spawn.
 *
 * This module composes the invocation; it does not decide how the child is
 * started. Under the CLI the engine starts it (`ctx.spawn`), which is what
@@ -91,4 +89,4 @@ const spawnAlchemy = async (invocation) => {
 //#endregion
 export { spawnAlchemy as n, alchemyInvocation as t };
 
-//# sourceMappingURL=run-alchemy--ZIvgqyU-BtZTukrY.mjs.map
+//# sourceMappingURL=run-alchemy-B6u4TxA0-DMUphChq.mjs.map

package/dist/run-alchemy-B6u4TxA0-DMUphChq.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-alchemy-B6u4TxA0-DMUphChq.mjs","names":["path","fs"],"sources":["../../../0-framework/3-tooling/cli/dist/run-alchemy-B6u4TxA0.mjs"],"sourcesContent":["import { CliStructuredError } from \"@internal/foundation/errors\";\nimport * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport spawn from \"cross-spawn\";\n//#region src/run-alchemy.ts\n/**\n* Pipeline step 7 (deploy-cli.md § The pipeline; design-notes.md's \"Driving\n* Alchemy\" call): hand the terminal to the generated stack file.\n*\n* Resolves the installed `alchemy` bin and launches package-manager shims with\n* cross-spawn.\n*\n* This module composes the invocation; it does not decide how the child is\n* started. Under the CLI the engine starts it (`ctx.spawn`), which is what\n* makes Ctrl-C reach the child natively and keeps signal policy in one place.\n* `spawnAlchemy` is the default for programmatic hosts driving\n* `@prisma/composer/control`, which have no engine to borrow.\n*/\n/** Walks up from `startDir` looking for `node_modules/.bin/alchemy`. */\nfunction resolveAlchemyBin(startDir) {\n\tlet dir = startDir;\n\twhile (true) {\n\t\tconst candidate = path.join(dir, \"node_modules\", \".bin\", \"alchemy\");\n\t\tif (fs.existsSync(candidate)) return candidate;\n\t\tconst parent = path.dirname(dir);\n\t\tif (parent === dir) throw new CliStructuredError(\"DEPLOY.ALCHEMY_BIN_MISSING\", `Could not find an installed \\`alchemy\\` bin above \"${startDir}\".`, { fix: \"Add \\\"alchemy\\\" as a dependency of your app.\" });\n\t\tdir = parent;\n\t}\n}\n/**\n* Resolves the invocation against this machine — the step every adapter takes\n* and no caller should. Raises DEPLOY.ALCHEMY_BIN_MISSING when the app has no\n* alchemy installed.\n*/\nfunction alchemyCommandLine(invocation) {\n\treturn {\n\t\tcommand: resolveAlchemyBin(invocation.cwd),\n\t\targs: [\n\t\t\tinvocation.action,\n\t\t\tinvocation.stackFileRelativePath,\n\t\t\t\"--yes\",\n\t\t\t\"--stage\",\n\t\t\tinvocation.stage\n\t\t],\n\t\tcwd: invocation.cwd,\n\t\tenv: invocation.env\n\t};\n}\n/** What becomes `alchemy deploy|destroy <stack file> --yes --stage <stage>`. */\nfunction alchemyInvocation(input) {\n\treturn {\n\t\taction: input.command,\n\t\tstackFileRelativePath: input.stackFileRelativePath,\n\t\tcwd: input.cwd,\n\t\tstage: input.stage,\n\t\tenv: {\n\t\t\t...input.containerEnv,\n\t\t\t...input.preflightEnv,\n\t\t\t...input.env\n\t\t}\n\t};\n}\n/**\n* The default runner for hosts with no engine: inherited stdio, the caller's\n* own process group, and the child's status returned verbatim. It does not\n* collapse a signal into an exit code — that collapse is what made a\n* Ctrl-C'd deploy report itself as a failure.\n*/\nconst spawnAlchemy = async (invocation) => {\n\tconst line = alchemyCommandLine(invocation);\n\treturn new Promise((resolve, reject) => {\n\t\tconst child = spawn(line.command, [...line.args], {\n\t\t\tcwd: line.cwd,\n\t\t\tstdio: \"inherit\",\n\t\t\tenv: {\n\t\t\t\t...process.env,\n\t\t\t\t...line.env\n\t\t\t}\n\t\t});\n\t\tchild.on(\"error\", reject);\n\t\tchild.on(\"close\", (exitCode, signal) => {\n\t\t\tresolve({\n\t\t\t\texitCode,\n\t\t\t\tsignal\n\t\t\t});\n\t\t});\n\t});\n};\n//#endregion\nexport { spawnAlchemy as i, alchemyInvocation as n, resolveAlchemyBin as r, alchemyCommandLine as t };\n\n//# sourceMappingURL=run-alchemy-B6u4TxA0.mjs.map"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,SAAS,kBAAkB,UAAU;CACpC,IAAI,MAAM;CACV,OAAO,MAAM;EACZ,MAAM,YAAYA,OAAK,KAAK,KAAK,gBAAgB,QAAQ,SAAS;EAClE,IAAIC,KAAG,WAAW,SAAS,GAAG,OAAO;EACrC,MAAM,SAASD,OAAK,QAAQ,GAAG;EAC/B,IAAI,WAAW,KAAK,MAAM,IAAI,mBAAmB,8BAA8B,sDAAsD,SAAS,KAAK,EAAE,KAAK,+CAA+C,CAAC;EAC1M,MAAM;CACP;AACD;;;;;;AAMA,SAAS,mBAAmB,YAAY;CACvC,OAAO;EACN,SAAS,kBAAkB,WAAW,GAAG;EACzC,MAAM;GACL,WAAW;GACX,WAAW;GACX;GACA;GACA,WAAW;EACZ;EACA,KAAK,WAAW;EAChB,KAAK,WAAW;CACjB;AACD;;AAEA,SAAS,kBAAkB,OAAO;CACjC,OAAO;EACN,QAAQ,MAAM;EACd,uBAAuB,MAAM;EAC7B,KAAK,MAAM;EACX,OAAO,MAAM;EACb,KAAK;GACJ,GAAG,MAAM;GACT,GAAG,MAAM;GACT,GAAG,MAAM;EACV;CACD;AACD;;;;;;;AAOA,MAAM,eAAe,OAAO,eAAe;CAC1C,MAAM,OAAO,mBAAmB,UAAU;CAC1C,OAAO,IAAI,SAAS,SAAS,WAAW;EACvC,MAAM,QAAQ,MAAM,KAAK,SAAS,CAAC,GAAG,KAAK,IAAI,GAAG;GACjD,KAAK,KAAK;GACV,OAAO;GACP,KAAK;IACJ,GAAG,QAAQ;IACX,GAAG,KAAK;GACT;EACD,CAAC;EACD,MAAM,GAAG,SAAS,MAAM;EACxB,MAAM,GAAG,UAAU,UAAU,WAAW;GACvC,QAAQ;IACP;IACA;GACD,CAAC;EACF,CAAC;CACF,CAAC;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma/composer",
-  "version": "0.16.0",
+  "version": "0.17.0-dev.1",
   "type": "module",
   "description": "Prisma Composer — build a Prisma App by composing Modules. Core authoring, deploy pipeline, and the service-rpc/node/nextjs authoring surfaces. The `prisma-composer` CLI lives in @prisma/composer-cli.",
   "exports": {
@@ -33,21 +33,22 @@
     "alchemy": "2.0.0-beta.74",
     "arktype": "^2.2.3",
     "c12": "^3.3.4",
+    "cross-spawn": "^7.0.6",
     "effect": "4.0.0-rc.112",
     "esbuild": "^0.28.1",
     "@prisma/management-api-sdk": "^1.60.0"
   },
   "devDependencies": {
     "@effect/vitest": "4.0.0-rc.112",
-    "@internal/assemble": "0.16.0",
-    "@internal/cli": "0.16.0",
-    "@internal/core": "0.16.0",
-    "@internal/foundation": "0.16.0",
-    "@internal/lowering": "0.16.0",
-    "@internal/nextjs": "0.16.0",
-    "@internal/node": "0.16.0",
-    "@internal/service-rpc": "0.16.0",
-    "@internal/tsdown-config": "0.16.0",
+    "@internal/assemble": "0.17.0-dev.1",
+    "@internal/cli": "0.17.0-dev.1",
+    "@internal/core": "0.17.0-dev.1",
+    "@internal/foundation": "0.17.0-dev.1",
+    "@internal/lowering": "0.17.0-dev.1",
+    "@internal/nextjs": "0.17.0-dev.1",
+    "@internal/node": "0.17.0-dev.1",
+    "@internal/service-rpc": "0.17.0-dev.1",
+    "@internal/tsdown-config": "0.17.0-dev.1",
     "@types/node": "^26.0.1",
     "tsdown": "^0.22.7",
     "typescript": "^6.0.3"

package/skills/prisma-composer-core-concepts/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: prisma-composer-core-concepts
+metadata:
+  library: "@prisma/composer"
+  library_version: "0.17.0-dev.1"
+  version: 2026.9.1
+description: >-
+  Use when deploying or managing an app that uses Prisma Composer
+  (`@prisma/composer`): wiring its services and Modules, running it locally,
+  testing composed services, or standing up / tearing down an environment.
+  Triggers on "prisma composer", "@prisma/composer", "prisma app", the
+  `prisma-composer` CLI, `compute()`, `module()`, `contract()`,
+  `service.load()`, `mockService`, `bootstrapService`.
+---
+
+# Prisma Composer core concepts
+
+A **Prisma App** is a tree of typed declarations composed in TypeScript and
+handed to the `prisma-composer` CLI. This file covers structures,
+hierarchies, relationships, and workflows: the concepts you cannot observe
+from the code or the CLI's help output. It is not a CLI reference; discover
+any individual command and its flags with `--help`. Commands named here
+belong to the `prisma-composer` CLI itself; a host CLI that embeds Composer
+may not carry every verb, so confirm a command exists via `--help` rather
+than inferring it. The Prisma platform moves fast, so treat this file as the
+stable conceptual core and find current, fuller documentation at
+<https://www.prisma.io/docs>. For working code, read `examples/` in the
+prisma/composer repo.
+
+Two principles govern everything and are binding
+(`docs/design/01-principles/`):
+
+1. **Your code never reads its environment.** Dependencies, configuration,
+   credentials, and the port all arrive through the service node, typed.
+   `process.env` is never the answer.
+2. **Composer never bundles or transforms your code.** You build with your own
+   bundler; the framework assembles the built output by deterministic steps
+   and hands it to the configured deploy target.
+
+## Declarations are data
+
+Everything you author is a declaration: plain data describing a piece of the
+app, executing nothing when imported. Three node kinds exist:
+
+| Kind | Declared with | Purpose |
+| --- | --- | --- |
+| Service | `compute()` | A running unit of your code; atomic, Composer sees only its ports |
+| Resource | `rawPostgres()`, `bucket()` | A stateful managed dependency |
+| Module | `module()` | A grouping boundary; runs no code of its own, exposes typed ports |
+
+Nodes connect through **ports**: `deps` declares what a node requires,
+`expose` declares what it offers. Wiring happens in a Module's builder via
+`provision()`, and the root Module, handed to the CLI, is the App:
+
+```ts
+// module.ts
+import { module } from '@prisma/composer';
+
+export default module('store', ({ provision }) => {
+  const catalog = provision(catalogModule);
+  provision(storefrontService, { deps: { catalog: catalog.rpc } });
+});
+```
+
+Because ports are typed, **the compiler verifies every wire**. A dependency
+wired to the wrong producer, a missing RPC handler, a literal input value of
+the wrong shape: all of it fails `tsc`, not the deploy. Env-bound input is
+the exception: those values exist only at deploy, so secret-binding
+mismatches and missing platform variables surface as early deploy-time
+refusals instead (see Two channels below). Typecheck, then build, then
+deploy; don't use the cloud to find out whether the wiring is correct.
+
+Composer itself is target-agnostic: `@prisma/composer` carries authoring,
+testing, and the CLI, coupled to no platform. A deploy target is an extension
+registered in the deploy config; `@prisma/composer-prisma-cloud` is the
+Prisma Cloud target and the one this skill's deploy sections assume. Its
+root exports `compute`, `rawPostgres`, `bucket`, `envSecret`, and
+`envParam`; the ORM vocabulary (`postgres`, `dataContract`) lives under the
+`/orm` subpath, alongside the shared `/cron`, `/storage`, `/streams`,
+`/auth`, and `/email` modules. These are the only two Composer packages a
+basic Prisma Cloud app needs, and nothing installs them for you: a fresh
+project starts with neither, so add both as dependencies first. An
+extension adds its own `prisma-composer-*` package alongside them. Compose
+an existing Module before implementing a capability yourself; wiring one in
+is a couple of lines.
+
+Within the entry graph (everything reachable from `module.ts`), write
+relative imports with explicit `.ts` extensions (`./service.ts`, with
+`allowImportingTsExtensions` in tsconfig): that form resolves everywhere.
+The `prisma-composer` CLI also maps `./service.js` and extensionless
+`./service` to the `.ts` source, but other hosts may not.
+
+## The service node is the only doorway
+
+Your runtime code receives everything from the service declaration it
+imports:
+
+1. `service.load()`: dependencies (typed RPC clients, database bindings).
+2. `service.input()`: the whole input as one schema-validated object;
+   credentials in it are redacting `SecretString` boxes.
+3. `service.port()`: the reserved port to bind (default 3000).
+
+A service declaration is pure data; the server entry is what your build
+produces and the platform boots:
+
+```ts
+// service.ts
+export default compute({
+  name: 'auth',
+  deps: { db: rawPostgres() },
+  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
+  expose: { rpc: authContract },
+});
+
+// server.ts
+const { db } = service.load(); // { url }: you construct your own client
+const handler = serve(service, {
+  rpc: { verify: async ({ token }) => ({ ok: token.length > 0 }) },
+});
+Bun.serve({ port: service.port(), hostname: '0.0.0.0', fetch: handler });
+```
+
+The consumer declares `deps: { auth: rpc(authContract) }` and gets a typed
+client back from `load()`.
+
+## Two channels: dependencies and input
+
+| The value is… | Declare | Provide | Read |
+| --- | --- | --- | --- |
+| produced by another node | `deps: { db: rawPostgres() }` | 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
+`secretString()` from `@prisma/composer/arktype`; conditional legality ("no
+stripe key unless billing is on") is an ordinary schema union. The binding at
+`provision()` mirrors the schema's shape; `envSecret('NAME')` names the
+platform variable and never carries the value.
+
+Rules that bite:
+
+1. **Secretness is enforced by validation.** A literal bound where the schema
+   expects `SecretString` fails the deploy; `envSecret` bound to a plain
+   string field fails the same way.
+2. **`envParam` values arrive as raw strings**; bind them to string fields.
+   The stage's platform variable is the store; the deploying shell only seeds
+   a missing name (and the deploy fails early, naming the variable, when both
+   lack it). Changing the platform value needs a redeploy.
+3. **Absence is the schema's call.** An env-bound field whose variable is
+   unset or empty resolves to *key omitted*, which is legal only if the
+   schema allows it (optional field, union arm). The deploy report prints the
+   serialized input document (secrets ride as `{"$secret":"VAR"}` pointers)
+   and every key that resolved absent.
+4. **The reserved `port` is outside the schema.** Read it through
+   `service.port()`, never `process.env`. The framework also exports `PORT`
+   for Next.js standalone, which binds it itself.
+5. **A Module forwards a secret need without learning the platform name.**
+   Declare `secrets: { signingKey: secret() }` on the Module boundary and
+   pass the forwarded ref as a binding leaf; the parent binds the real
+   source.
+6. `input.apiKey.expose()` is the only way to a secret's value; the box
+   redacts everywhere else (logs, JSON, errors).
+
+## Contracts and RPC
+
+A contract is the typed interface through which services communicate. It
+lives with the service that owns it, typed by any Standard Schema validator,
+and both provider (`serve()`, exhaustive over the contract's methods at
+compile time) and consumer (`rpc(contract)`) reference the same value. Calls
+travel as RPC over HTTP. Two behaviours are provisioned for you and must not
+be reimplemented:
+
+1. **Service keys.** At deploy, Composer mints a distinct unguessable key per
+   consumer→provider binding; `serve()` returns `401` to anything else before
+   the handler runs. Nothing in your code declares it. Consequences: don't
+   build your own service-to-service auth, and don't `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, where nothing is enforced. Keys are per binding (one leaking
+   can't impersonate another consumer), service-scoped (any valid key
+   reaches every method; split services to gate separately), rotated only by
+   removing the binding or destroying the stack and redeploying, and stored
+   in deploy-owned `COMPOSER_*` variables you never hand-edit.
+2. **Idempotency and retries.** Every generated-client call carries an
+   `Idempotency-Key`; dropped calls retry with backoff, and `serve()` runs
+   one call per key, replaying the completed answer to late retries. Every
+   method is therefore safely retryable and no contract declares anything
+   about it (there is no "is this idempotent" flag; don't invent one). A
+   handler may take an optional third argument `(input, deps, ctx)` and read
+   `ctx.idempotencyKey` (`string | undefined`) if it needs exactly-once
+   beyond one instance's memory; most don't. Locally and in tests nothing is
+   provisioned, so `serve()` passes every call through: never supply a key
+   in test inputs.
+
+## Builds are yours
+
+You 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:*`). Deploy copies that one file and never
+ships `node_modules`, so anything left un-inlined fails at boot, not at
+deploy. Rules that bite:
+
+1. **Two services in one package means two separate builds**, one per entry.
+   A single multi-entry build splits shared code into a chunk neither output
+   contains.
+2. **A directory build uses `dir` + `entry`** (`dir` relative to the service
+   module, `entry` a file inside `dir`; `../` is an error). The tree is
+   copied verbatim, so the server must resolve siblings against
+   `import.meta.url`, not the working directory. The tree must contain no
+   symlinks: the packager rejects them, names the link, and assembly fails.
+3. **Next.js**: `next build` with `output: 'standalone'` is the whole build;
+   `nextjs({ module, appDir })` names the app root. Any page or action that
+   calls `load()` needs `export const dynamic = 'force-dynamic'`, because
+   the runtime environment doesn't exist at build time and Next ignores
+   runtime env for prerendered routes.
+4. **Always build before `deploy` or `dev`.** Neither builds for you.
+
+Deploy configuration lives in `prisma-composer.config.ts` (or `.mts`, `.mjs`,
+`.js`; nearest ancestor of the entry wins, `.ts` first within a directory).
+It registers extensions (`prismaCloud()`, `nodeBuild()`, `nextjsBuild()` when
+the app has a Next.js service) and the deploy-state backend
+(`prismaState()`). It is read by the CLI's operations (deploy, destroy, and
+dev; a `dev` run without one refuses, naming the missing file) and never
+imported by app code.
+
+## Databases and migrations
+
+Two kinds of Postgres dependency:
+
+1. **`rawPostgres()`**: the binding is `{ url }` and the app owns its client.
+2. **`postgres(...)`**: a Prisma-ORM-typed database. The binding is
+   `{ url, client }` (ADR-0040): the raw connection URL plus the typed
+   client Composer constructs from your data contract, lazily on first
+   access, so queries go through `binding.client` and are compile-time
+   checked. Both `postgres` and `dataContract` import from
+   `@prisma/composer-prisma-cloud/orm`, not the package root. One
+   `dataContract`-wrapped value (emitted from `contract.prisma` by
+   `prisma contract emit`) is referenced by both the dependency end
+   (`deps: { db: postgres(catalogData) }`) and the resource end, which also
+   names the `prisma.config.ts` path so the deploy's migration step can
+   find `migrations/`.
+
+**Deploys are replay-only**: they apply the migrations committed under
+`migrations/` and never create schema themselves. Every schema change,
+including the first schema of a new database, follows one loop:
+
+1. Edit `contract.prisma`.
+2. `prisma contract emit` regenerates `contract.json` + `contract.d.ts`.
+3. `prisma migration plan --name <slug>` authors the migration (on an empty
+   graph this authors the baseline).
+4. Commit `migrations/` with the change, then deploy. A fresh database
+   replays the whole path from empty.
+
+If no authored path reaches the target contract, deploy (and `dev` against a
+stale local database) refuses with `MIGRATION_PATH_NOT_FOUND`; its message
+lists the two ways out: author the missing migration, or, when iterating
+against a local
+database only, `prisma db update`. Never skip step 3 before a deploy. See
+`examples/store/modules/catalog` for the complete pattern.
+
+## Deploy model: converge, don't script
+
+Deploy compares the declared topology against recorded deploy state and
+applies only the difference. Re-deploying with nothing changed is a no-op;
+removing a node removes its deployed resource. The Prisma Cloud target
+requires exactly two environment variables: `PRISMA_SERVICE_TOKEN` and
+`PRISMA_WORKSPACE_ID`. There is no interactive login.
+
+**Stages.** A stage is an environment name chosen on the command line at
+deploy time, never written in the topology. The identical graph deploys
+everywhere. On the Prisma Cloud target, a Prisma App is one Project and a
+stage is a Branch of it, with its own running services, its own empty
+database, its own configuration. 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 destroy is an error,
+and naming a stage and production together is too. Destroying a stage
+deletes its Branch after removing its resources. Destroying production
+removes only the resources inside the production Branch, never the Branch
+itself directly; once the Project is empty it is deleted too, and that
+deletion takes the production Branch with it. 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.
+
+**The engine underneath is alchemy.** Convergence is executed by
+[alchemy](https://alchemy.run), a third-party infrastructure-as-code engine
+that arrives as an ordinary, exactly-pinned npm dependency of
+`@prisma/composer` (2.0.0-beta.74 at this library version). Your code never
+imports or configures it; consult alchemy's own docs for the engine itself.
+What matters operationally:
+
+1. Deploy and destroy write the pipeline's results to a generated, gitignored
+   stack file at `.prisma-composer/alchemy.run.ts`, then run the alchemy CLI
+   against it as a child process; `dev` does the same at
+   `.prisma-composer/dev/alchemy.run.ts` with local providers. The file
+   carries the computed values as literals but reads credentials via
+   `fromEnv()`, so nothing sensitive lands on disk, and it is regenerated
+   every run: output, not configuration, never edited.
+2. Failures are bisectable through that file. A failing deploy names its
+   path; running `alchemy deploy .prisma-composer/alchemy.run.ts` directly
+   separates "the framework computed the wrong thing" from "the engine or
+   platform rejected the right thing". An engine failure surfaces as
+   `DEPLOY.ENGINE_FAILED` carrying the exit code and that reproduce command;
+   the child's live output streams to the terminal either way.
+3. Destroy evaluates the same stack program as deploy, and evaluating it
+   packages the assembled bundles, so **an app must be built before it can
+   be torn down**.
+4. alchemy is why the `effect` pin exists: it resolves the `effect`
+   constellation, and a hoisted newer `effect` halts every command (failure
+   mode 1 below).
+
+**The deploy report** ends with the app's own topology: authored names, the
+platform resource each became, and public URLs. Read ids out of it rather
+than hunting in the Console. A URL appears only where the address is
+genuinely public: a service prints one, a database never does, and a
+node whose product is secret material reports no resource line at all.
+
+**Connection contract refusals.** A connection declares the values it needs
+by name; a producer that omits one fails the deploy, naming the edge, the
+param, and what the producer did supply:
+
+```text
+Connection input "auth.db" declares param "url", but its producer "db" did not
+supply it — the producer's outputs carry [host].
+```
+
+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 as `undefined`
+and crash the consumer at boot). Fix whichever end is wrong; don't mark the
+param `optional` unless absent really is legal. Only reachable if you
+authored the connection or an extension on one side.
+
+**Driving deploys from code.** `@prisma/composer/control` exposes typed
+`deploy`, `destroy`, `dev`, and `log` returning structured results. Failures
+come back as `{ ok: false, failure }` with a dotted `failure.code` from a
+closed registry (e.g. `ASSEMBLE.BUILD_FAILED`, `DEPLOY.ENGINE_FAILED`,
+`DEPS.EFFECT_VERSION_CONFLICT`); branch on the code, not the message. A
+non-structured rejection out of an operation is a bug in composer, not an
+expected failure.
+
+## Local development
+
+The `dev` command runs the whole app on this machine, wired as it deploys,
+against local emulators. No cloud credentials are needed or read. Concepts
+that surprise:
+
+1. It runs the same pipeline as deploy, so **build first**, exactly like
+   deploy. It watches built output and restarts a service when its build
+   changes.
+2. Ctrl-C stops the app's processes but leaves local databases, buckets, and
+   their data up: the next `dev` is a warm start. Starting clean, wiping
+   this app's local instances and data first, is an explicit opt-in flag.
+3. `dev` does not print service logs; `log` is a separate, read-only command
+   that follows the already-running app's merged logs. It never builds,
+   provisions, starts, or stops anything.
+4. 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 external
+   service it calls.
+5. Windows isn't supported yet.
+
+## Testing is an environment seam
+
+A test is just another environment: one where you decide what `load()` and
+`input()` return, 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` |
+
+`mockService` returns a copy of the service whose `load()` yields your
+doubles (type-checked against the declared deps) and whose `input()` yields
+the object passed under the reserved `input` key (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).
+
+`bootstrapService` boots the service's real built entry in-process against a
+config you choose; drive it over real HTTP. Gotchas:
+
+1. `service.port` must be concrete: the entry self-listens, and no
+   OS-assigned port is reported back.
+2. There is no `close()`; run each integration-test file in its own process
+   (bun test does).
+3. Next.js services take a third argument, a boot thunk, resolved with
+   `standaloneServerPath` from `@prisma/composer/nextjs/control`.
+4. A service with an input schema takes `input` in the config, a binding
+   exactly like `provision()`'s, run through the real serialize/read path.
+
+A dependency's type is its contract, so any value of that shape is a valid
+double: a bare object, the real client over an in-memory handler, or a real
+local server. Ship a dependency's fake from its own package as a `/fake`
+entry point, outside `src/`, so the fake and the real service share one
+contract.
+
+## Building blocks and extensions
+
+First-party Modules ship inside `@prisma/composer-prisma-cloud` and
+provision exactly like your own:
+
+| 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` |
+| `auth` from `/auth` | Signup, login, sessions, and JWT verification (Better Auth in one service, own database) | `api`, `session`, `admin` |
+| `email` from `/email` | Transactional email with a stored outbox (own service and database) | `send`, `outbox` |
+
+`bucket()` (imported alongside `rawPostgres`) is a raw S3-compatible bucket:
+the dependency end receives `{ url, bucket, accessKeyId, secretAccessKey }`,
+shape-compatible with `/storage`'s `s3()` dependency, so a service wired to
+`s3()` can be rewired to a `bucket` resource unchanged.
+
+An extension (a package bringing its own Modules, resources, or deploy
+target) is published on npm as `prisma-composer-*`. The ecosystem is new:
+today the blocks above plus your own Modules are the whole set, so verify a
+`prisma-composer-*` package exists on npm before reaching for it.
+
+## Failure modes quick reference
+
+1. **Every `prisma-composer` command halts 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. 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, then reinstall. The repo's examples carry the
+   block.
+2. **A deployed `/rpc/<method>` returns `401` to anything but a wired
+   peer.** Not a broken deploy; see Contracts above.
+3. **Scale-to-zero closes idle database connections.** A persistent client
+   crashes into a 502 restart loop unless the pool is small and
+   reconnect-friendly (`new SQL({ url, max: 1, idleTimeout: 10 })` for Bun)
+   and the process logs `uncaughtException`/`unhandledRejection` instead of
+   dying. Under `dev` watch-restarts against the local emulator, add
+   `prepare: false` as well: restarted processes collide on
+   prepared-statement names in the emulator's shared session.
+4. **Cold starts reset service-to-service connections.** A call into a
+   scaled-to-zero service can get `ECONNRESET`; retry it.
+5. **Bind `0.0.0.0`, not loopback.** The platform routes external HTTP to
+   the VM; a loopback-only listener is unreachable.
+6. **The ingress buffers streaming responses.** An open SSE tail delivers
+   nothing and times out at 60s; don't build on streamed HTTP responses.
+7. **Naming rules fail at load, not typecheck.** Provision ids and declared
+   node names must be ASCII letters and digits only (`[A-Za-z0-9]`): they
+   derive config keys and address segments, so a hyphenated name like
+   `my-db` passes `tsc` and then fails the load. The root module's name is
+   exempt. 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
+   given an explicit `id`.
+8. **`MIGRATION_PATH_NOT_FOUND`**: see Databases above; author the missing
+   migration, don't skip the plan step.
+9. **Date/time columns hand back `Temporal.*` values on read.** Bun and
+   stock Node ship no global `Temporal`, so a service with `DateTime`
+   contract columns compiles and deploys, then fails on the first timestamp
+   read. Provide the global at the server entry
+   (`import 'temporal-polyfill/global'`) or use string column types.
+
+## What Composer doesn't do yet
+
+Name the gap instead of inventing an API:
+
+1. **No interactive auth in the `prisma-composer` CLI.** Its deploys
+   authenticate only via a static
+   `PRISMA_SERVICE_TOKEN`; there is no `login` flow.
+2. **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.
+3. **RPC over HTTP is the only contract kind.** No gRPC, WebSocket, or
+   streaming contracts.
+
+For anything else missing, check `examples/`, `docs/design/10-domains/`, and
+`docs/design/90-decisions/` in the prisma/composer repo, then file an issue
+there rather than guessing.

package/dist/dist-CVk7Pk4B.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"dist-CVk7Pk4B.mjs","names":[],"sources":["../../../0-framework/2-authoring/bundle-paths/dist/index.mjs"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\n//#region src/bundle-paths.ts\n/**\n* The path-containment predicate and bundle-link validation shared by every\n* assembly and packaging seam (node/nextjs adapters, the compute artifact\n* writer, the local extractor). This predicate is the enforcement point of\n* ADR-0047's boundary — a symlink may be preserved only while its target\n* stays inside the assembled bundle — so it exists exactly once.\n*/\n/** Lexical containment: `candidate` is `root` itself or below it. Both paths\n* must already be absolute or share a resolution base; no filesystem access. */\nfunction isWithin(root, candidate) {\n\tconst relative = path.relative(root, candidate);\n\treturn relative === \"\" || !relative.startsWith(`..${path.sep}`) && relative !== \"..\" && !path.isAbsolute(relative);\n}\n/** Walks the assembled bundle and rejects a dangling symlink or one whose\n* resolved target escapes the bundle root. Symlinked directories are not\n* descended: their targets are validated, and their contents belong to the\n* target's own location. */\nasync function assertBundleSymlinksStayInside(bundleDir) {\n\tconst realRoot = await fs.promises.realpath(bundleDir);\n\tconst walk = async (directory) => {\n\t\tfor (const entry of await fs.promises.readdir(directory, { withFileTypes: true })) {\n\t\t\tconst full = path.join(directory, entry.name);\n\t\t\tif (entry.isSymbolicLink()) {\n\t\t\t\tlet realTarget;\n\t\t\t\ttry {\n\t\t\t\t\trealTarget = await fs.promises.realpath(full);\n\t\t\t\t} catch {\n\t\t\t\t\tthrow new Error(`the assembled bundle contains a dangling symlink: ${full}`);\n\t\t\t\t}\n\t\t\t\tif (!isWithin(realRoot, realTarget)) throw new Error(`the assembled bundle contains a symlink whose target escapes the bundle: ${full} -> ${await fs.promises.readlink(full)}`);\n\t\t\t} else if (entry.isDirectory()) await walk(full);\n\t\t}\n\t};\n\tawait walk(bundleDir);\n}\n//#endregion\nexport { assertBundleSymlinksStayInside, isWithin };\n\n//# sourceMappingURL=index.mjs.map"],"mappings":";;;;;;;;;;;;AAYA,SAAS,SAAS,MAAM,WAAW;CAClC,MAAM,WAAW,KAAK,SAAS,MAAM,SAAS;CAC9C,OAAO,aAAa,MAAM,CAAC,SAAS,WAAW,KAAK,KAAK,KAAK,KAAK,aAAa,QAAQ,CAAC,KAAK,WAAW,QAAQ;AAClH;;;;;AAKA,eAAe,+BAA+B,WAAW;CACxD,MAAM,WAAW,MAAM,GAAG,SAAS,SAAS,SAAS;CACrD,MAAM,OAAO,OAAO,cAAc;EACjC,KAAK,MAAM,SAAS,MAAM,GAAG,SAAS,QAAQ,WAAW,EAAE,eAAe,KAAK,CAAC,GAAG;GAClF,MAAM,OAAO,KAAK,KAAK,WAAW,MAAM,IAAI;GAC5C,IAAI,MAAM,eAAe,GAAG;IAC3B,IAAI;IACJ,IAAI;KACH,aAAa,MAAM,GAAG,SAAS,SAAS,IAAI;IAC7C,QAAQ;KACP,MAAM,IAAI,MAAM,qDAAqD,MAAM;IAC5E;IACA,IAAI,CAAC,SAAS,UAAU,UAAU,GAAG,MAAM,IAAI,MAAM,4EAA4E,KAAK,MAAM,MAAM,GAAG,SAAS,SAAS,IAAI,GAAG;GAC/K,OAAO,IAAI,MAAM,YAAY,GAAG,MAAM,KAAK,IAAI;EAChD;CACD;CACA,MAAM,KAAK,SAAS;AACrB"}

package/dist/run-alchemy--ZIvgqyU-BtZTukrY.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-alchemy--ZIvgqyU-BtZTukrY.mjs","names":["path","fs"],"sources":["../../../0-framework/3-tooling/cli/dist/run-alchemy--ZIvgqyU.mjs"],"sourcesContent":["import { CliStructuredError } from \"@internal/foundation/errors\";\nimport * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport { spawn } from \"node:child_process\";\n//#region src/run-alchemy.ts\n/**\n* Pipeline step 7 (deploy-cli.md § The pipeline; design-notes.md's \"Driving\n* Alchemy\" call): hand the terminal to the generated stack file. Resolves the\n* workspace's own installed `alchemy` bin (walking up `node_modules/.bin`\n* from the generated file's package dir) rather than going through\n* `bunx`/`npx`, so this works the same under node and bun — the resolved\n* bin's own launcher (`alchemy/bin/cli.js`) does its own node/bun dispatch\n* from there, driven by the env it inherits.\n*\n* This module composes the invocation; it does not decide how the child is\n* started. Under the CLI the engine starts it (`ctx.spawn`), which is what\n* makes Ctrl-C reach the child natively and keeps signal policy in one place.\n* `spawnAlchemy` is the default for programmatic hosts driving\n* `@prisma/composer/control`, which have no engine to borrow.\n*/\n/** Walks up from `startDir` looking for `node_modules/.bin/alchemy`. */\nfunction resolveAlchemyBin(startDir) {\n\tlet dir = startDir;\n\twhile (true) {\n\t\tconst candidate = path.join(dir, \"node_modules\", \".bin\", \"alchemy\");\n\t\tif (fs.existsSync(candidate)) return candidate;\n\t\tconst parent = path.dirname(dir);\n\t\tif (parent === dir) throw new CliStructuredError(\"DEPLOY.ALCHEMY_BIN_MISSING\", `Could not find an installed \\`alchemy\\` bin above \"${startDir}\".`, { fix: \"Add \\\"alchemy\\\" as a dependency of your app.\" });\n\t\tdir = parent;\n\t}\n}\n/**\n* Resolves the invocation against this machine — the step every adapter takes\n* and no caller should. Raises DEPLOY.ALCHEMY_BIN_MISSING when the app has no\n* alchemy installed.\n*/\nfunction alchemyCommandLine(invocation) {\n\treturn {\n\t\tcommand: resolveAlchemyBin(invocation.cwd),\n\t\targs: [\n\t\t\tinvocation.action,\n\t\t\tinvocation.stackFileRelativePath,\n\t\t\t\"--yes\",\n\t\t\t\"--stage\",\n\t\t\tinvocation.stage\n\t\t],\n\t\tcwd: invocation.cwd,\n\t\tenv: invocation.env\n\t};\n}\n/** What becomes `alchemy deploy|destroy <stack file> --yes --stage <stage>`. */\nfunction alchemyInvocation(input) {\n\treturn {\n\t\taction: input.command,\n\t\tstackFileRelativePath: input.stackFileRelativePath,\n\t\tcwd: input.cwd,\n\t\tstage: input.stage,\n\t\tenv: {\n\t\t\t...input.containerEnv,\n\t\t\t...input.preflightEnv,\n\t\t\t...input.env\n\t\t}\n\t};\n}\n/**\n* The default runner for hosts with no engine: inherited stdio, the caller's\n* own process group, and the child's status returned verbatim. It does not\n* collapse a signal into an exit code — that collapse is what made a\n* Ctrl-C'd deploy report itself as a failure.\n*/\nconst spawnAlchemy = async (invocation) => {\n\tconst line = alchemyCommandLine(invocation);\n\treturn new Promise((resolve, reject) => {\n\t\tconst child = spawn(line.command, [...line.args], {\n\t\t\tcwd: line.cwd,\n\t\t\tstdio: \"inherit\",\n\t\t\tenv: {\n\t\t\t\t...process.env,\n\t\t\t\t...line.env\n\t\t\t}\n\t\t});\n\t\tchild.on(\"error\", reject);\n\t\tchild.on(\"close\", (exitCode, signal) => {\n\t\t\tresolve({\n\t\t\t\texitCode,\n\t\t\t\tsignal\n\t\t\t});\n\t\t});\n\t});\n};\n//#endregion\nexport { spawnAlchemy as i, alchemyInvocation as n, resolveAlchemyBin as r, alchemyCommandLine as t };\n\n//# sourceMappingURL=run-alchemy--ZIvgqyU.mjs.map"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,SAAS,kBAAkB,UAAU;CACpC,IAAI,MAAM;CACV,OAAO,MAAM;EACZ,MAAM,YAAYA,OAAK,KAAK,KAAK,gBAAgB,QAAQ,SAAS;EAClE,IAAIC,KAAG,WAAW,SAAS,GAAG,OAAO;EACrC,MAAM,SAASD,OAAK,QAAQ,GAAG;EAC/B,IAAI,WAAW,KAAK,MAAM,IAAI,mBAAmB,8BAA8B,sDAAsD,SAAS,KAAK,EAAE,KAAK,+CAA+C,CAAC;EAC1M,MAAM;CACP;AACD;;;;;;AAMA,SAAS,mBAAmB,YAAY;CACvC,OAAO;EACN,SAAS,kBAAkB,WAAW,GAAG;EACzC,MAAM;GACL,WAAW;GACX,WAAW;GACX;GACA;GACA,WAAW;EACZ;EACA,KAAK,WAAW;EAChB,KAAK,WAAW;CACjB;AACD;;AAEA,SAAS,kBAAkB,OAAO;CACjC,OAAO;EACN,QAAQ,MAAM;EACd,uBAAuB,MAAM;EAC7B,KAAK,MAAM;EACX,OAAO,MAAM;EACb,KAAK;GACJ,GAAG,MAAM;GACT,GAAG,MAAM;GACT,GAAG,MAAM;EACV;CACD;AACD;;;;;;;AAOA,MAAM,eAAe,OAAO,eAAe;CAC1C,MAAM,OAAO,mBAAmB,UAAU;CAC1C,OAAO,IAAI,SAAS,SAAS,WAAW;EACvC,MAAM,QAAQ,MAAM,KAAK,SAAS,CAAC,GAAG,KAAK,IAAI,GAAG;GACjD,KAAK,KAAK;GACV,OAAO;GACP,KAAK;IACJ,GAAG,QAAQ;IACX,GAAG,KAAK;GACT;EACD,CAAC;EACD,MAAM,GAAG,SAAS,MAAM;EACxB,MAAM,GAAG,UAAU,UAAU,WAAW;GACvC,QAAQ;IACP;IACA;GACD,CAAC;EACF,CAAC;CACF,CAAC;AACF"}