diff --git a/.drive/projects/variable-groups-compat/deferred.md b/.drive/projects/variable-groups-compat/deferred.md
index 776178063..e030c49aa 100644
--- a/.drive/projects/variable-groups-compat/deferred.md
+++ b/.drive/projects/variable-groups-compat/deferred.md
@@ -4,3 +4,6 @@
- **Hints use `prisma project env` for the built-in groups.** Move them to `prisma variable` when it is the CLI most users have.
- **An app upgrading directly from a version before the address change** can have one service receive another's old row once. The guide tells it to deploy with a release from 0.35.0 to 0.39.0 first. A check in preflight against the deploy state would refuse it instead.
- **Ask the platform to put the limit and the count in its quota error for service variables.** Composer checks its own count, but cannot count variables a user set in Console.
+- **The upstream pull requests for `variables`.** Alchemy (`Prisma.Deployment.variables`) and Distilled (the request field) are carried as `pnpm` patches; the proposed source changes are in `slices/upstream/`. The Distilled patch JSON guesses the converter's input shape name, `PostV1ServicesByServiceIdDeploymentsRequest`; check it against the generated spec. The patch to Distilled's compiled `lib/services/management.js` leaves the byte-offset index its `distilled-lazy` build reads out of date; nothing in this repository uses that build. Composer cannot release this change until both packages ship the field: a published package installs the unpatched provider, which drops `variables` without an error.
+- **Ask the platform for a "delete every key with this prefix I did not send" flag** on the create-deployment request. It would make `SentVariableNames` unnecessary and delete keys Composer never recorded.
+- **A structured error raised while a deploy is planned is reported as `DEPLOY.ENGINE_FAILED`.** The 50-variable refusal carries its own code, `DEPLOY.SERVICE_VARIABLE_LIMIT`, with a why and a fix, but the CLI wraps every failed converge as `DEPLOY.ENGINE_FAILED` (`convergeFailure` in `packages/0-framework/3-tooling/cli/src/operations/execute-deploy-destroy.ts`), so the user sees "Alchemy could not deploy the app" with the real message as one reason. Fixing it is a change to the framework's CLI and probably the converge contract: when every reason of a failed converge is a structured error raised during planning, report it under its own code. Found in manual QA of slice 3, 2026-11-21.
diff --git a/.drive/projects/variable-groups-compat/design.md b/.drive/projects/variable-groups-compat/design.md
index 0f0c16e91..7d11e86b2 100644
--- a/.drive/projects/variable-groups-compat/design.md
+++ b/.drive/projects/variable-groups-compat/design.md
@@ -148,7 +148,7 @@ With the pull request above merged, no value in the map depends on a deployment:
**Keys a service used to send are deleted.** A key the service's code no longer declares, such as a removed dependency's params or a renamed generated value, would otherwise stay stored: readable by every later deployment of that service, and counted toward the limit of 50, with no way for the user to delete it. So Composer keeps, for each service, a record of every key it has ever sent, and sends `null` for each recorded key that is not in this deploy's map.
-- The record is a Composer-owned Alchemy resource in the deploy state, one per service, like the one that keeps a generated value stable (`GeneratedParam`). Its input is this deploy's key names. Its output is every key name it has been given, ever. It holds names, never values.
+- The record is a Composer-owned Alchemy resource in the deploy state, `PrismaCloud.SentVariableNames` with the ID `
.sent-variable-names`, one per service, like the one that keeps a generated value stable (`GeneratedParam`). Its input is this deploy's key names. Its output is every key name it has been given, ever. It holds names, never values. As built, it is registered for the hosted and the local target.
- When the key names do not change, the record does not change, its output is known at plan time, and the map is the same as last time. So the `null`s are stable and replace nothing.
- When the key names change, the record changes and so does the map. That deploy replaces the deployment anyway, because the keys changed.
- The record starts at the first deploy with this version. Before it, Composer wrote rows, and Alchemy deleted the rows of removed keys itself.
@@ -168,7 +168,7 @@ variables?: Record | null>;
- **Declared `variables` with no recorded hash also replaces.** This differs from `triggers`, which records its first hash through an update. An update creates no deployment, so the values would never reach the platform.
- Leaving `variables` unset sends no field, so every existing user of the resource is unaffected.
-The generated client `@distilled.cloud/prisma` gains the field on the request type. It is generated from the platform's published production API description, and it can also carry a hand-written patch for a field the description does not have yet.
+The generated client `@distilled.cloud/prisma` gains the field on the request type. It is generated from the platform's published production API description, and it can also carry a hand-written patch for a field the description does not have yet. As built, both packages carry the field as `pnpm` patches under `patches/`, and the proposed upstream changes are in `slices/upstream/`.
**Under `prisma dev`.** The local `Prisma.Deployment` provider takes the service's own keys from its `variables` prop, where it reads `env.json` today. A `null` entry is left out. Everything else in `materializeEnv` stays: the emulator's port is still laid over `COMPOSER__PORT`, and the platform variables are still added. A changed `variables` is a changed prop, so a changed value still restarts the service.
@@ -182,14 +182,14 @@ A service that runs a dev server has no deployment, so it has no prop to carry t
2. Alchemy then deletes the resources that are in its state and no longer declared: the old variable rows, on production and on preview. Each row is deleted after the old deployment it fed has stopped. A deployment that is still draining open connections holds its rows until a later deploy finds it stopped, so rows can remain visible in Console after the first deploy.
3. While both exist, the service variable wins over the row.
4. On production, the `COMPOSER_` keys leave the user's production group.
-5. A row already deleted in Console, or one the platform manages, is skipped. A row the platform refuses to delete because its recorded identity does not match is removed from the deploy state and reported as a warning that names the key, so one bad row cannot fail this deploy and every deploy after it.
+5. A row already deleted in Console, or one the platform manages, is skipped (upstream's own delete does this). A row the platform refuses to delete because its recorded identity does not match is removed from the deploy state and reported as a warning that names the key, so one bad row cannot fail this deploy and every deploy after it. As built, Composer registers the hosted `Prisma.EnvironmentVariable` provider through its own layer (`providerForDeletingOldVariableRows()` in `lowering/src/providers.ts`), whose delete catches upstream's `EnvironmentVariableConflict`, logs the warning, and succeeds, so Alchemy drops the row from state.
6. If the deploy is interrupted after the replacements, the next deploy replaces nothing again and finishes the deletes.
Deleting a row by id keeps working after override writes are rejected.
**What is deleted with the rows.** The key-clash check and the code that computes the clashes: with no rows written, two rows cannot collide. One narrow case remains for an app that upgrades directly from a version before the address change: a service whose new key equals another service's old key, and which has no value for it, would receive the other service's old row once. The guide tells such an app to deploy once with any release from 0.35.0 to 0.39.0 first. `asOwnRow` is no longer applied to variables. Build reporting stops listing variable rows, except the deletes on the first deploy.
-**Going back to an older Composer** after a deploy with this version is not supported, and the release note says why: the older version writes rows again, and the stored service variables win over them, so a value that changed since never reaches the service.
+**Going back to an older Composer** after a deploy with this version is not possible: deploy state then holds a `PrismaCloud.SentVariableNames` resource per service, an older version registers no provider for it, and Alchemy stops while planning, before changing anything.
**Not part of this:** options on `prisma deploy` that set a user's value on a service, which the platform spec proposes as `--variable`. The decision that defines platform variables says the deploy sets no user values until that has its own design.
diff --git a/.drive/projects/variable-groups-compat/plan.md b/.drive/projects/variable-groups-compat/plan.md
index 81db6ad67..32453c979 100644
--- a/.drive/projects/variable-groups-compat/plan.md
+++ b/.drive/projects/variable-groups-compat/plan.md
@@ -14,7 +14,20 @@ Design section 4.1. Builds on: slice 1. Merges when the new read is live in prod
## Slice 3: a service's `COMPOSER_` keys travel with its deployment
-Design section 4.2. Builds on: the open pull request "an unchanged deploy no longer replaces a service that depends on another service", merged. Independent of slice 2. Opened early as a draft, with `pnpm` patches standing in for the upstream packages, for Ty to align his interface against. Needs one pull request on Distilled and one on Alchemy once the platform's field is final. Merges when the platform accepts `variables` in production and both upstream packages have released.
+Design section 4.2. Builds on: the open pull request "an unchanged deploy no longer replaces a service that depends on another service", merged. Opened early as a draft, with `pnpm` patches standing in for the upstream packages, for Ty to align his interface against. Needs one pull request on Distilled and one on Alchemy once the platform's field is final. Merges when the platform accepts `variables` in production and both upstream packages have released.
+
+Its code is independent of slice 2 and can be built and reviewed on its own, but it merges after slice 2: its glossary copies slice 2's entries for variable group and service variable word for word, and those entries describe slice 2's preflight, which reads the variable group the branch receives; on `main` before slice 2 they would be false. When slice 2 merges, rebase this branch onto it.
+
+Before marking the pull request ready:
+
+- [ ] The platform accepts `variables` on the create-deployment request in production.
+- [ ] `@distilled.cloud/prisma` and `@alchemy.run/prisma` have released the field.
+- [ ] Composer's pins are raised to those releases, `patches/` and `pnpm.patchedDependencies` are gone, and `check:patched-dependencies` passes.
+- [ ] The paragraphs about the patches in ADR-0069 (end of "Decision") and in `alchemy-lowering.md` (the `Prisma.Deployment` row) are removed.
+- [ ] The `Deploy, verify, destroy` check passes against a platform that accepts `variables`.
+- [ ] A manual upgrade against that platform: an app deployed with 0.39.0 on a production and a preview environment, then deployed with this branch, with the services watched for at least ten minutes afterwards.
+
+When opening the draft, the pull request description says the E2E deploy job fails until the platform accepts `variables` in production.
## Release
diff --git a/.drive/projects/variable-groups-compat/slices/slice-3-plan.md b/.drive/projects/variable-groups-compat/slices/slice-3-plan.md
new file mode 100644
index 000000000..d603774f5
--- /dev/null
+++ b/.drive/projects/variable-groups-compat/slices/slice-3-plan.md
@@ -0,0 +1,16 @@
+# Slice 3: a service's `COMPOSER_` keys travel with its deployment
+
+Design: [design.md](../design.md) section 4.2, with the tests in section 9 and in the principal engineer's design review. One pull request, opened as a draft for the platform team to align the create-deployment field against.
+
+This branch starts from `main` with the open pull request "an unchanged deploy no longer replaces a service that depends on another service" merged in. When that pull request merges, the branch is rebased onto `main`.
+
+## Dispatches, in order
+
+1. **The upstream prop, as local patches.** `pnpm` patches for `@alchemy.run/prisma` (the `variables` prop on `Prisma.Deployment`: sent on create, hashed for `diff`, replaces when changed, unresolved or first declared, never sent on update) and `@distilled.cloud/prisma` (the field on the create-deployment request). The same change is prepared as source diffs against the upstream clones, for the two upstream pull requests later.
+2. **The hosted deploy.** `serialize` returns the map; every key boot reads is a value or `null`; the per-service record of key names and the `null`s it produces; the limit of 50; `deploy` passes `variables`; triggers keep only platform variable members; `appAfter` keeps the producer wait; the key-clash check is deleted; the hosted variable provider stays registered. Tests with the real engine, including the upgrade from state written by today's code.
+3. **`prisma dev`.** The local deployment provider takes the service's keys from `variables`; `reserve` keeps rows for dev servers, never writes a `null`, and fails outside the local application.
+4. **Docs.** The new decision record and every record, guide and glossary entry the design's section 8 lists for 4.2.
+
+## Not in this slice
+
+The upstream pull requests themselves, which wait for the platform's field to be final.
diff --git a/.drive/projects/variable-groups-compat/slices/upstream/alchemy-prisma-deployment-variables.diff b/.drive/projects/variable-groups-compat/slices/upstream/alchemy-prisma-deployment-variables.diff
new file mode 100644
index 000000000..b00ee70e3
--- /dev/null
+++ b/.drive/projects/variable-groups-compat/slices/upstream/alchemy-prisma-deployment-variables.diff
@@ -0,0 +1,159 @@
+diff --git a/packages/prisma/src/Deployment.ts b/packages/prisma/src/Deployment.ts
+index 71258d31..704a5e02 100644
+--- a/packages/prisma/src/Deployment.ts
++++ b/packages/prisma/src/Deployment.ts
+@@ -144,6 +144,25 @@ export interface DeploymentProps {
+ * ```
+ */
+ triggers?: Record;
++ /**
++ * Variables the platform stores on the App, sent with the request that
++ * creates the deployment. A string sets a key, `null` deletes it, and a key
++ * left out keeps its stored value. The platform accepts them only when a
++ * deployment is created, so any change to the resolved map, a value that is
++ * not resolved while planning, or declaring `variables` on a deployment that
++ * was created without them replaces the deployment. They are never sent on
++ * an update.
++ *
++ * The values are stored on the App and outlive this deployment: deleting or
++ * replacing the Deployment leaves them, and so does removing `variables`
++ * from its props; only `null` or deleting the App removes one. Every
++ * Deployment of one App writes to the same store.
++ *
++ * Values may be wrapped in `Redacted.make(secret)`; they are unwrapped only
++ * for the request and the fingerprint. Leaving `variables` unset sends no
++ * field.
++ */
++ variables?: Record | null>;
+ }
+
+ export interface Deployment extends Resource<
+@@ -181,6 +200,11 @@ export interface Deployment extends Resource<
+ * state; absent when `triggers` is unset.
+ */
+ triggersHash?: Redacted.Redacted;
++ /**
++ * Salted fingerprint of the resolved `variables` this deployment was
++ * created with; absent when `variables` is unset.
++ */
++ variablesHash?: Redacted.Redacted;
+ /**
+ * Stable App endpoint domain after promotion.
+ */
+@@ -286,6 +310,7 @@ const attrsFrom = (
+ extra?: {
+ artifactHash?: string;
+ triggersHash?: Redacted.Redacted;
++ variablesHash?: Redacted.Redacted;
+ appEndpointDomain?: string;
+ },
+ ): Deployment["Attributes"] => ({
+@@ -296,6 +321,7 @@ const attrsFrom = (
+ previewDomain: deployment.previewDomain,
+ artifactHash: extra?.artifactHash,
+ triggersHash: extra?.triggersHash,
++ variablesHash: extra?.variablesHash,
+ appEndpointDomain: extra?.appEndpointDomain,
+ createdAt: deployment.createdAt,
+ });
+@@ -424,9 +450,43 @@ const triggersHashOf = (triggers: unknown) =>
+ triggers: unwrapRedacted(triggers) ?? null,
+ });
+
+-const persistedTriggersHash = (value: Redacted.Redacted | string | undefined) =>
++const persistedHash = (value: Redacted.Redacted | string | undefined) =>
+ Redacted.isRedacted(value) ? Redacted.value(value) : value;
+
++const VARIABLES_HASH_SALT = "alchemy/Prisma.Deployment/variables/v1";
++
++const variablesHashOf = (variables: unknown) =>
++ sha256Object({
++ salt: VARIABLES_HASH_SALT,
++ variables: unwrapRedacted(variables) ?? null,
++ });
++
++const requestVariables = (
++ variables: Record | string | null>,
++): Record =>
++ Object.fromEntries(
++ Object.entries(variables).map(([key, value]) => [
++ key,
++ Redacted.isRedacted(value) ? Redacted.value(value) : value,
++ ]),
++ );
++
++/**
++ * Whether the declared `variables` require a new deployment. Unlike
++ * `triggers`, a declaration with no recorded fingerprint replaces: an update
++ * creates no deployment, so the values would never reach the platform.
++ */
++const variablesChanged = Effect.fn(function* (
++ variables: unknown,
++ persisted: Redacted.Redacted | string | undefined,
++) {
++ if (variables === undefined) return false;
++ const recorded = persistedHash(persisted);
++ if (recorded === undefined) return true;
++ if (!isResolved({ variables })) return true;
++ return (yield* variablesHashOf(variables)) !== recorded;
++});
++
+ /**
+ * Whether the declared `triggers` inputs differ from the fingerprint the
+ * running deployment was created for.
+@@ -444,7 +504,7 @@ const triggersChanged = Effect.fn(function* (
+ triggers: unknown,
+ persisted: Redacted.Redacted | string | undefined,
+ ) {
+- const recorded = persistedTriggersHash(persisted);
++ const recorded = persistedHash(persisted);
+ if (triggers === undefined || recorded === undefined) return false;
+ if (!isResolved({ triggers })) return true;
+ return (yield* triggersHashOf(triggers)) !== recorded;
+@@ -510,6 +570,9 @@ const ProviderLive = () =>
+ if (yield* triggersChanged(news.triggers, output?.triggersHash)) {
+ return { action: "replace" } as const;
+ }
++ if (yield* variablesChanged(news.variables, output?.variablesHash)) {
++ return { action: "replace" } as const;
++ }
+ const replacementContent = {
+ portMapping: news.portMapping,
+ skipCodeUpload: news.skipCodeUpload,
+@@ -622,6 +685,10 @@ const ProviderLive = () =>
+ news.triggers === undefined
+ ? undefined
+ : Redacted.make(yield* triggersHashOf(news.triggers));
++ const variablesHash =
++ news.variables === undefined
++ ? undefined
++ : Redacted.make(yield* variablesHashOf(news.variables));
+ const appId = yield* resolveAppId(news.app);
+ const deploymentId = isPrismaDevId(output?.deploymentId)
+ ? undefined
+@@ -661,6 +728,9 @@ const ProviderLive = () =>
+ serviceId: appId,
+ ...(news.portMapping === undefined ? {} : { portMapping: news.portMapping }),
+ ...(news.skipCodeUpload === undefined ? {} : { skipCodeUpload: news.skipCodeUpload }),
++ ...(news.variables === undefined
++ ? {}
++ : { variables: requestVariables(news.variables) }),
+ }).pipe(
+ // A replayed create would make a second deployment; the retry
+ // policy cannot see the request, so opt out explicitly.
+@@ -740,6 +810,7 @@ const ProviderLive = () =>
+ return attrsFrom(deployment, appId, {
+ artifactHash,
+ triggersHash,
++ variablesHash,
+ appEndpointDomain,
+ });
+ }),
+@@ -778,6 +849,7 @@ const ProviderLocal = () =>
+ previewDomain: undefined,
+ artifactHash: undefined,
+ triggersHash: undefined,
++ variablesHash: undefined,
+ appEndpointDomain: undefined,
+ createdAt: DEV_TIMESTAMP,
+ }));
diff --git a/.drive/projects/variable-groups-compat/slices/upstream/distilled-prisma-006-add-deployment-variables.patch.json b/.drive/projects/variable-groups-compat/slices/upstream/distilled-prisma-006-add-deployment-variables.patch.json
new file mode 100644
index 000000000..6ae619bdf
--- /dev/null
+++ b/.drive/projects/variable-groups-compat/slices/upstream/distilled-prisma-006-add-deployment-variables.patch.json
@@ -0,0 +1,29 @@
+{
+ "description": "Declare the `variables` field the platform is adding to the create-deployment request (POST /v1/services/{serviceId}/deployments): a map from key to a string, which sets the key, or null, which deletes it. A key not sent keeps its stored value. Remove this patch once the published API description carries the field. The input shape name below follows the converter's naming for this operation and must be checked against .generated-specs before committing.",
+ "patches": [
+ {
+ "op": "add",
+ "path": "/shapes/com.prisma#ServiceVariables",
+ "value": {
+ "type": "map",
+ "key": {
+ "target": "smithy.api#String"
+ },
+ "value": {
+ "target": "smithy.api#String"
+ },
+ "traits": {
+ "smithy.api#sparse": {},
+ "smithy.api#documentation": "Variables stored on the service. A string sets the key, null deletes it, and a key not sent keeps its stored value."
+ }
+ }
+ },
+ {
+ "op": "add",
+ "path": "/shapes/com.prisma#PostV1ServicesByServiceIdDeploymentsRequest/members/variables",
+ "value": {
+ "target": "com.prisma#ServiceVariables"
+ }
+ }
+ ]
+}
diff --git a/.drive/projects/variable-groups-compat/slices/upstream/distilled-prisma-generated-management.diff b/.drive/projects/variable-groups-compat/slices/upstream/distilled-prisma-generated-management.diff
new file mode 100644
index 000000000..283199650
--- /dev/null
+++ b/.drive/projects/variable-groups-compat/slices/upstream/distilled-prisma-generated-management.diff
@@ -0,0 +1,20 @@
+diff --git a/packages/prisma/src/services/management.ts b/packages/prisma/src/services/management.ts
+index 7c0702e0..afed79d4 100644
+--- a/packages/prisma/src/services/management.ts
++++ b/packages/prisma/src/services/management.ts
+@@ -977,6 +977,7 @@ export interface CreateServiceDeploymentRequest {
+ serviceId: string;
+ portMapping?: CreateServiceDeploymentRequestPortMapping;
+ skipCodeUpload?: boolean;
++ variables?: { [key: string]: string | null };
+ }
+ export interface CreateServiceDeploymentResponseData {
+ id: string;
+@@ -6235,6 +6236,7 @@ function __c57(j: number): any {
+ serviceId: S.String.pipe(T.Label()),
+ portMapping: S.optional(__S(912, __c57, 0)),
+ skipCodeUpload: S.optional(S.Boolean),
++ variables: S.optional(S.Record(S.String, S.NullOr(S.String))),
+ }).pipe(T.Http({ method: "POST", uri: "/v1/services/{serviceId}/deployments", code: 200 })),
+ ).annotate({ identifier: "CreateServiceDeploymentRequest" });
+ case 2:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d10063921..6645fa07b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,6 +31,9 @@ jobs:
run: pnpm lint:retired-binary-name
- name: Lint (no control bytes in tracked files)
run: pnpm lint:control-bytes
+ # A pnpm patch never reaches a user's install, so a release must not depend on one.
+ - name: Lint (no published package depends on a patched package)
+ run: pnpm check:patched-dependencies
typecheck:
name: Type Check
diff --git a/.github/workflows/preview-publish.yml b/.github/workflows/preview-publish.yml
index 43ea0f686..e0497f4a1 100644
--- a/.github/workflows/preview-publish.yml
+++ b/.github/workflows/preview-publish.yml
@@ -56,6 +56,10 @@ jobs:
- name: Install dependencies
run: pnpm install --frozen-lockfile
+ # A preview install gets no pnpm patch, so a branch that needs one publishes no preview.
+ - name: Check no published package depends on a patched package
+ run: pnpm check:patched-dependencies
+
- name: Build packages
run: pnpm build
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index b467c5b8e..94b8c0dd0 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -91,6 +91,9 @@ jobs:
- name: Check publish dependency specifiers
run: pnpm check:publish-deps
+ - name: Check no published package depends on a patched package
+ run: pnpm check:patched-dependencies
+
# The remaining publish-blocking invariants, against the exact artifacts
# this run would upload (the build step above built everything):
# engine-once — the engine is an exact peer of the CLI package, external
diff --git a/architecture.config.json b/architecture.config.json
index 4b272e84b..1886e141e 100644
--- a/architecture.config.json
+++ b/architecture.config.json
@@ -349,7 +349,7 @@
"plane": "control"
},
{
- "glob": "packages/1-prisma-cloud/1-extensions/target/src/env-key-clash.ts",
+ "glob": "packages/1-prisma-cloud/1-extensions/target/src/sent-variable-names-resource.ts",
"domain": "prisma-cloud",
"layer": "extensions",
"plane": "control"
diff --git a/docs/design/03-domain-model/glossary.md b/docs/design/03-domain-model/glossary.md
index 01ae2ce7b..7ec2428f9 100644
--- a/docs/design/03-domain-model/glossary.md
+++ b/docs/design/03-domain-model/glossary.md
@@ -157,7 +157,7 @@ In code the type is `Value`, and `RealValuesOf` is the tuple of real-value
A [value](#value) whose data exists only on the platform the app is deployed to: the service reads it at boot. A platform variable node's value, `generatedParam()` and `serviceOrigin()` give one. In code a runtime value is `RuntimeValue`, which is `Value>`. `T` is the data the service receives: `string` for `serviceOrigin()`, and for a plain platform variable the type its `schema` gives, such as `RuntimeValue` for `variable({ name: 'SMTP_PORT', schema: type('number') })`.
-At deploy its real value is a **pointer**: an object that names the [variable on the platform](#a-variable-on-the-platform) holding the data. For a platform variable node's value that is the platform variable; for `generatedParam()` and `serviceOrigin()` it is one of Composer's own `COMPOSER_` rows. The deploy writes the pointer into the service's input document, and the service reads the variable at boot. A pointer has one of two kinds, which it records in its data:
+At deploy its real value is a **pointer**: an object that names the [variable on the platform](#a-variable-on-the-platform) holding the data. For a platform variable node's value that is the platform variable; for `generatedParam()` and `serviceOrigin()` it is one of the service's own `COMPOSER_` keys, which Composer sends as a [service variable](#service-variable). The deploy writes the pointer into the service's input document, and the service reads the variable at boot. A pointer has one of two kinds, which it records in its data:
- a **secret pointer**, typed `Pointer`, from a platform secret's value and a redacted `generatedParam()`;
- a **plain pointer**, typed `Pointer` for the data type `T` its source gives, from a plain platform variable's value, `serviceOrigin()` and a plain `generatedParam()`.
@@ -170,7 +170,7 @@ A pointer is typed by its source. `serviceOrigin()` and a plain `generatedParam(
### Platform variable
-A variable on the platform that a service reads by name at boot. The app declares each one with a [platform variable node](#platform-variable-node) in its root, so every message can name the node. The service reads it through a field of its `input`. "Plain platform variable" means the non-secret kind; the secret kind is a [platform secret](#platform-secret). A deploy does not copy its value from the developer's local environment and does not read it: the platform hands it to the running service. For now the operator sets it with `prisma project env add`. Under `prisma dev`, the local target plays the platform's part: it reads a plain platform variable's value from the app configuration and a platform secret's from the app secrets, and hands it to the local service. A variable has a class row (production or preview) and, on a preview environment, may have a branch row for one branch; the branch row wins ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). Composer's own `COMPOSER_` rows are [variables on the platform](#a-variable-on-the-platform) but not platform variables, because the app does not declare them. In code: `PlatformVariableReader`, `UnsetPlatformVariable`, `PlatformVariableCheck`.
+A variable on the platform that a service reads by name at boot. The app declares each one with a [platform variable node](#platform-variable-node) in its root, so every message can name the node. The service reads it through a field of its `input`. "Plain platform variable" means the non-secret kind; the secret kind is a [platform secret](#platform-secret). A deploy does not copy its value from the developer's local environment and does not read it: the platform hands it to the running service. For now the operator sets it on Prisma Cloud, in the [variable group](#variable-group) the environment's branch receives. Under `prisma dev`, the local target plays the platform's part: it reads a plain platform variable's value from the app configuration and a platform secret's from the app secrets, and hands it to the local service. A deployment receives the values of its branch's group, then the branch's overrides, then its service's [service variables](#service-variable); a later one wins. Deploy preflight checks the group and the overrides, not the service variables ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). Composer's own `COMPOSER_` keys are [service variables](#service-variable), not platform variables, because the app does not declare them. In code: `PlatformVariableReader`, `UnsetPlatformVariable`, `PlatformVariableCheck`.
### Platform variable node
@@ -194,7 +194,15 @@ A [platform variable](#platform-variable) whose value is handled as a secret: bo
### A variable on the platform
-Any entry, or **row**, in a Prisma Cloud project's environment variables: a name and a non-empty text, at a class and optionally a branch. That includes Composer's own `COMPOSER_` rows, which are not [platform variables](#platform-variable). The term names the platform's storage, as distinct from what the app reads. Prisma Cloud calls these rows environment variables.
+Any entry, or **row**, in a Prisma Cloud project's environment variables: a name and a non-empty text. An older Composer wrote its own `COMPOSER_` keys as rows; they were never [platform variables](#platform-variable), and Composer now sends them as [service variables](#service-variable). A **group row** belongs to a [variable group](#variable-group); what was called a class row is a row of the `production` or `preview` group. A **branch override** (formerly "branch row") belongs to one branch and wins over its group's value. The platform is removing branch overrides: after a notice period, it rejects a write that names a branch. Composer releases before [ADR-0069](../90-decisions/ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md) write a service's `COMPOSER_` rows on a preview environment as branch overrides, so their preview deploys fail once the platform rejects them. The term names the platform's storage, as distinct from what the app reads. Prisma Cloud calls these rows environment variables.
+
+### Variable group
+
+Prisma Cloud's term for a named set of [variables on the platform](#a-variable-on-the-platform) in one project. Every project has a `production` group and a `preview` group; it can add custom groups, each with one rule on a branch's git name (`equals` or `startsWith`). Each branch receives exactly one group: the production branch receives `production`, any other branch the custom group with the most precise matching rule, or else `preview`. Groups do not combine. A group's **class** is a field of the group that names its kind: `production`, `preview` or `custom`. It is not the old class of a row, which had only the values `production` and `preview`.
+
+### Service variable
+
+Prisma Cloud's term for a value stored on one platform service, which is one Composer [service](#service) in one environment (`Prisma.App` in code). It is set only when a deployment is created, through the create-deployment request, which Console's "Save and Deploy" sends, and is deleted with the platform service. It wins over the branch's group and overrides. Composer sends each service's `COMPOSER_` keys as service variables, a name Composer no longer sends as `null`, and reads none ([ADR-0069](../90-decisions/ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)).
### Value resource
@@ -242,7 +250,7 @@ Every node in the topology either has a managed lifecycle or names a value the o
### Address and logical ID
-A node's **address** is its identity: the path of provision IDs starting at the root, assigned by Load (`shop`, `shop.catalog`, `shop.auth.api`). The root's address is the deployed app name, so every address starts with it. A provision ID is the node's name (`publicUrl()` takes it as `id`) unless `provision()` sets an `id`, so a node's name is, by default, part of its identity. The app name starts with a letter or digit and contains only letters, digits, `-` and `_`; below the root, provision IDs contain only letters and digits. Every platform **name** Composer writes (an App's display name, a Connection's, Bucket's or access key's `name`) is the address too; it is a label, never identity. On the platform a Connection's name is the address followed by `-` and a 12-character token that upstream adds. On Prisma Cloud the address is the node's **logical ID** (`logicalId`): Composer writes it, byte for byte, on the node's topology entry and on the node's one platform row (Project, App, Database or Bucket). The same node on two branches has the same logical ID. A **display name** is a label only and never identity. An **Alchemy resource ID** names one of the resources a node lowers to: the address for the node's main resource (`shop.catalog`), and the address plus `.` and a role for its other pieces (`shop.catalog.connection`, `shop.web.deployment`). Alchemy's own docs call it a "logical ID"; it is a different field from the platform's `logicalId`. Composer's environment variable keys are `COMPOSER_` plus the address upper-cased, with `.` and `-` turned into `_` (`COMPOSER_SHOP_WEB_…`). Changing a node's address, including by changing its name, makes it a different entity; it is not a rename. A node that names something Composer does not own, such as a [platform variable node](#platform-variable-node), records no platform row and no topology node, and the thing it names keeps its owner's handle, such as the variable's name. See [ADR-0057](../90-decisions/ADR-0057-a-nodes-address-is-its-full-path-from-the-app-name.md).
+A node's **address** is its identity: the path of provision IDs starting at the root, assigned by Load (`shop`, `shop.catalog`, `shop.auth.api`). The root's address is the deployed app name, so every address starts with it. A provision ID is the node's name (`publicUrl()` takes it as `id`) unless `provision()` sets an `id`, so a node's name is, by default, part of its identity. The app name starts with a letter or digit and contains only letters, digits, `-` and `_`; below the root, provision IDs contain only letters and digits. Every platform **name** Composer writes (an App's display name, a Connection's, Bucket's or access key's `name`) is the address too; it is a label, never identity. On the platform a Connection's name is the address followed by `-` and a 12-character token that upstream adds. On Prisma Cloud the address is the node's **logical ID** (`logicalId`): Composer writes it, byte for byte, on the node's topology entry and on the node's one platform row (Project, App, Database or Bucket). The same node on two branches has the same logical ID. A **display name** is a label only and never identity. An **Alchemy resource ID** names one of the resources a node lowers to: the address for the node's main resource (`shop.catalog`), and the address plus `.` and a role for its other pieces (`shop.catalog.connection`, `shop.web.deployment`). Alchemy's own docs call it a "logical ID"; it is a different field from the platform's `logicalId`. The keys of a service's configuration, which reach it as environment variables and which Composer sends on Prisma Cloud as [service variables](#service-variable), are `COMPOSER_` plus the address upper-cased, with `.` and `-` turned into `_` (`COMPOSER_SHOP_WEB_…`). Changing a node's address, including by changing its name, makes it a different entity; it is not a rename. A node that names something Composer does not own, such as a [platform variable node](#platform-variable-node), records no platform row and no topology node, and the thing it names keeps its owner's handle, such as the variable's name. See [ADR-0057](../90-decisions/ADR-0057-a-nodes-address-is-its-full-path-from-the-app-name.md).
## Connections
@@ -502,22 +510,12 @@ is in `layering.md`; this is the term-by-term catalogue.
emits one Stack for the whole app; `prisma deploy` drives it over the
app module the config's `entry` names (no hand-written stack file — ADR-0003).
`→` **Topology / app root**.
-- **Resource\** — a managed entity with a string type
- tag, desired-input **Props**, and cloud-returned **Attributes**. Declared, then
- `yield*`-ed. Composer binds upstream alchemy's: `Prisma.Project`, `Database`,
- `Connection`, `App`, `Deployment`, `EnvironmentVariable`.
- `→` a **Service** lowers to `App` + `Deployment` (+ `EnvironmentVariable`); a
- first-class **Resource** (Postgres) lowers to `Database` + `Connection`.
+- **Resource\** — a managed entity with a string type tag, desired-input **Props**, and cloud-returned **Attributes**. Declared, then `yield*`-ed. Composer binds upstream alchemy's: `Prisma.Project`, `Database`, `Connection`, `App`, `Deployment`, `EnvironmentVariable`. `→` a **Service** lowers to `App` + `Deployment`, whose `variables` carry its `COMPOSER_` keys (an `EnvironmentVariable` row only for a dev server under `prisma dev`); a first-class **Resource** (Postgres) lowers to `Database` + `Connection`.
- **Props** — the desired configuration passed at declare time; diffed against
the last deploy to detect change. (A rebuild registers as a change because the
artifact is content-addressed: new bytes, new `artifactPath`.) `→` a node's **dependencies** +
**Input**.
-- **Attributes / Output\** — values the cloud returns (`appEndpointDomain`,
- `deploymentId`, ids); lazy references that flow into other Resources' Props.
- Resource-to-resource wiring is Output → Props. `→` a node's **exposed interfaces**; a
- **connection** (exposed interface→dependency) lowers to Output→Props, plus an
- `EnvironmentVariable` when the consumer reads it at runtime (what `AUTH_URL`
- does today).
+- **Attributes / Output\** — values the cloud returns (`appEndpointDomain`, `deploymentId`, ids); lazy references that flow into other Resources' Props. Resource-to-resource wiring is Output → Props. `→` a node's **exposed interfaces**; a **connection** (exposed interface→dependency) lowers to Output→Props: a value the consumer reads at runtime is a key in its Deployment's `variables`.
- **Provider** — implements a Resource type's lifecycle; an Effect `Layer`. We
author one per Prisma resource with `Provider.effect(Resource, reconcile)`,
bundled via `Provider.collection([…])` into a `Provider.ProviderCollection`
diff --git a/docs/design/05-prisma-cloud/alchemy-lowering.md b/docs/design/05-prisma-cloud/alchemy-lowering.md
index 441266007..a47c8cc9c 100644
--- a/docs/design/05-prisma-cloud/alchemy-lowering.md
+++ b/docs/design/05-prisma-cloud/alchemy-lowering.md
@@ -5,12 +5,7 @@ The Alchemy resource types Composer lowers to over the
lowering graphs — including the correction that makes deploy ordering a property
of the dependency graph rather than luck.
-The postgres family (`Project`, `Database`, `Connection`), the compute
-family (`App`, `Deployment`, `EnvironmentVariable`) and the bucket family
-(`Bucket`, `BucketAccessKey`) are **upstream alchemy's** (`@alchemy.run/prisma`), not
-ours: Composer registers their providers and binds their props. What
-`@internal/lowering` still owns is the artifact packager, `ServiceKey`, and the
-hosted state store.
+The postgres family (`Project`, `Database`, `Connection`), the compute family (`App`, `Deployment`, `EnvironmentVariable`) and the bucket family (`Bucket`, `BucketAccessKey`) are **upstream alchemy's** (`@alchemy.run/prisma`), not ours: Composer registers their providers and binds their props. What `@internal/lowering` still owns is the artifact packager, `ServiceKey`, and the hosted state store. A hosted deploy declares no `EnvironmentVariable`: a service's `COMPOSER_` keys go in its Deployment's `variables` ([ADR-0069](../90-decisions/ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)).
## Placement: one Project per application, one Branch per environment
@@ -24,10 +19,7 @@ Consequences, stated plainly:
- Config keys are namespaced per service by the pack's mapping (e.g.
`AUTH_DB_URL`, `STOREFRONT_AUTH_URL`) — collisions are a naming concern the
pack owns, not a reason to split projects.
-- The Project is thereby also the **secret-visibility boundary**: every service's
- process env physically contains its co-located siblings' variables. One
- application = one trust domain; anything that must not be visible across
- services belongs in a different project (a different application).
+- The Project is thereby also the **secret-visibility boundary**: every service on a Branch receives every variable of the group that Branch receives. A service's own `COMPOSER_` keys are service variables, stored on that service only. One application = one trust domain; anything that must not be visible across services belongs in a different project (a different application).
Every deploy environment — production, staging, a per-PR preview — is a
**Branch** of that one Project
@@ -68,8 +60,9 @@ behind them.
| `Prisma.Database` | Database | project, name?, region, branchId?, logicalId? | databaseId, connection strings | one per Module-provisioned postgres resource; never the project default; a branch-attached database is created with `branchId` and no display name (upstream refuses the combination — see [deploying.md](../../guides/deploying.md)) |
| `Prisma.Connection` | database connection info | database, name | connectionId, directConnectionString | Composer binds the DIRECT string explicitly; upstream's `databaseUrl` is pooled-first |
| `Prisma.App` | App | project, displayName, regionId, branchId?, logicalId? | appId, appEndpointDomain | `branchId` targets the Branch of an environment other than `production`; omitted, upstream attaches the App to the project's default (production) Branch. `appEndpointDomain` is available at provision — that is what a service's own origin and its published `url` are read from |
-| `Prisma.EnvironmentVariable` | ConfigVariable | project, class, key, value (Redacted), branchId? | environmentVariableId | production-class with no `branchId` for `production`; preview-class with `branchId` for any other environment. Values are write-only, so upstream re-applies the desired one on every deploy |
-| `Prisma.Deployment` | Deployment (ComputeVersion) + Promotion | app, artifactPath, artifactContentType, portMapping, triggers, start, promote | deploymentId, appEndpointDomain | provider reconcile: create → upload tar.gz → start → poll until running → promote; `appEndpointDomain` read **post-promote**; it is the same domain the App reports from its create. It is replaced, not updated, when its artifact fingerprint or its `triggers` fingerprint moves |
+| `Prisma.EnvironmentVariable` | ConfigVariable | project, class, key, value (Redacted), branchId? | environmentVariableId | declared by no hosted deploy. Its provider stays registered so Alchemy can delete the rows an older Composer wrote; Composer's layer around it drops a row the platform refuses to delete because its recorded identity differs, with a warning naming the key. Under `prisma dev`, `reserve` declares one per key a dev server reads |
+| `Prisma.Deployment` | Deployment (ComputeVersion) + Promotion | app, artifactPath, artifactContentType, portMapping, variables, triggers, start, promote | deploymentId, appEndpointDomain | provider reconcile: create (with `variables`) → upload tar.gz → start → poll until running → promote; `appEndpointDomain` read **post-promote**; it is the same domain the App reports from its create. It is replaced, not updated, when its artifact fingerprint, its `variables` fingerprint or its `triggers` fingerprint moves, and when `variables` is declared on a deployment that recorded none. `variables` is a `pnpm` patch until the platform accepts it in production and the upstream release carries it; `check:patched-dependencies` blocks a release until then |
+| `SentVariableNames` (Composer's) | none | names (this deploy's variable names) | names (every name ever given) | one per compute service; the deploy sends `null` for each name Composer no longer sends. Holds names, never values |
| `Prisma.Bucket` | Bucket | project, name, branchId?, logicalId? | bucketId, name | one per bucket resource; `Prisma.BucketAccessKey` mints its read-write S3 credentials, which become the node's outputs |
`logicalId` is set on every deploy except branchless local dev; [§ Platform identity](#platform-identity-logicalid) says what it carries.
@@ -114,8 +107,8 @@ Rules:
- The value is the address. Composer passes it explicitly, even where it equals the Alchemy resource ID, because upstream's Prisma resources default `logicalId` to their own fully qualified resource ID.
- For App, Database and Bucket, the resource that creates the row writes its `logicalId`, as a prop. No separate resource or later API call writes it.
-- On the app's own Project and Branch, the row holding a node's `logicalId` is that node's row. The descriptors declare App, Database, Bucket and `COMPOSER_` EnvironmentVariable resources with `asOwnRow` (Alchemy's `adopt(true)`), so a deploy resuming an interrupted create uses the row instead of failing with `OwnedBySomeoneElse`. On resume, Connections need nothing: their generated name already proves which create made them. Deployments and bucket access keys are never reported as someone else's, so an interrupted create of one is simply made again, and the first attempt can be left behind.
-- Other platform rows a node lowers to carry no `logicalId`: `Prisma.Connection`, `Prisma.Deployment`, `Prisma.EnvironmentVariable`, `Prisma.BucketAccessKey`. Composer's local resources (`ServiceKey`, `PgWarm`, `OrmMigration`, `GeneratedParam`, `S3Credentials`) create no platform row.
+- On the app's own Project and Branch, the row holding a node's `logicalId` is that node's row. The descriptors declare App, Database and Bucket resources with `asOwnRow` (Alchemy's `adopt(true)`), so a deploy resuming an interrupted create uses the row instead of failing with `OwnedBySomeoneElse`. On resume, Connections need nothing: their generated name already proves which create made them. Deployments and bucket access keys are never reported as someone else's, so an interrupted create of one is simply made again, and the first attempt can be left behind.
+- Other platform rows a node lowers to carry no `logicalId`: `Prisma.Connection`, `Prisma.Deployment`, `Prisma.BucketAccessKey`. Composer's local resources (`ServiceKey`, `PgWarm`, `OrmMigration`, `GeneratedParam`, `SentVariableNames`, `S3Credentials`) create no platform row.
- Branchless local dev creates no platform rows and writes none.
### Resource IDs
@@ -128,7 +121,8 @@ For the app `shop`:
| --- | --- | --- | --- |
| compute service `shop.web` | `Prisma.App` | `shop.web` | `web-svc` |
| | `Prisma.Deployment` | `shop.web.deployment` | `web-deploy` |
-| | `Prisma.EnvironmentVariable`, one per key | `shop.web.env.` | `-var` |
+| | `SentVariableNames` | `shop.web.sent-variable-names` | (new) |
+| | `Prisma.EnvironmentVariable` under `prisma dev`, one per key a dev server reads | `shop.web.env.` | (none) |
| | `GeneratedParam`, one per generated input leaf | `shop.web.generated.` | `:-generated` |
| | `ServiceKey` for an RPC input (per calling service and input) | `shop.web.servicekey.` | `servicekey-web.` |
| | `ServiceKey` for a streams provider (per providing service) | `.streamkey` | `streamskey-` |
@@ -140,7 +134,7 @@ For the app `shop`:
| | `Prisma.BucketAccessKey` | `shop.uploads.accesskey` | `uploads-key` |
| s3 credentials `shop.creds` | `S3Credentials` | `shop.creds` | `creds-creds` |
-Every role is a noun naming the piece: `deployment`, `env`, `generated`, `servicekey`, `streamkey`, `connection`, `warmup`, `migration`, `accesskey`. The old ID is computed in `legacy-resource-ids.ts` from `addressBelowApp(address, app)`, which removes the known `.` prefix, by the rule the previous release used. `` is the environment variable key the previous release wrote, built from that shorter address.
+Every role is a noun naming the piece: `deployment`, `sent-variable-names`, `env`, `generated`, `servicekey`, `streamkey`, `connection`, `warmup`, `migration`, `accesskey`. The old ID is computed in `legacy-resource-ids.ts` from `addressBelowApp(address, app)`, which removes the known `.` prefix, by the rule the previous release used. `` is the input document key the previous release used, built from that shorter address. Variable rows an older release wrote stay in deploy state under the ID they were stored with, and Alchemy deletes them as resources no longer declared.
**Platform names.** Every platform name Composer writes is the node's address (`shop.catalog`, `shop.auth.api`): the App `displayName`, the branchless Database `name`, and the Connection, Bucket and BucketAccessKey `name`. They are labels, never identity. Upstream adds `-` and a 12-character token to every Connection name, so a Connection's platform name is the address plus that suffix. `validatePlatformName` checks the address against each kind's limit (Connection 52, so the address fits beside the suffix in the platform's 65; Bucket 100; App 256; an access key has none) and fails naming the address; it never shortens a name. A hosted Database takes no name from Composer, because upstream refuses a name together with branch attachment; upstream derives its physical name from the resource ID and updates it in place.
@@ -148,11 +142,10 @@ On the upgrade deploy every one of these names changes from the short address to
- a Connection when its `name` or database changes, which mints new credentials;
- a BucketAccessKey when its `name`, `role` or bucket changes, which mints new credentials;
-- an EnvironmentVariable when its `key`, `class`, `branchId` or project changes;
- an App, Database or Bucket only when its project (or, for a Database, its region, source or default flag) changes;
-- a Deployment when its artifact or `triggers` fingerprint changes.
+- a Deployment when its artifact, `variables` or `triggers` fingerprint changes.
-So the upgrade updates every App, Database and Bucket in place, along with every `logicalId` and a hosted Database's derived name; a Bucket's display name is not its S3 bucket name, so its objects stay. It recreates each of Composer's Connections and bucket access keys with new credentials, and Composer's services receive them in the same deploy. Each replace is create-first and then deletes only the old Connection or key, by the id Composer stored, after checking its database or bucket and name still match. The database, the bucket's objects and any Connection or key made by hand are untouched. Environment variable rows are replaced because their keys change; their values are rewritten on every deploy, so nothing is lost, and the changed environment makes a new Deployment as any environment change does.
+So the upgrade updates every App, Database and Bucket in place, along with every `logicalId` and a hosted Database's derived name; a Bucket's display name is not its S3 bucket name, so its objects stay. It recreates each of Composer's Connections and bucket access keys with new credentials, and Composer's services receive them in the same deploy. Each replace is create-first and then deletes only the old Connection or key, by the id Composer stored, after checking its database or bucket and name still match. The database, the bucket's objects and any Connection or key made by hand are untouched. Every `COMPOSER_` key changes name, so every service's `variables` changes and its Deployment is replaced.
Status:
@@ -174,10 +167,7 @@ logic is untouched.
## The mapping, both directions
-- **Ours → PDP**: each resource's provider (`reconcile`/`delete`) calls the
- Management API; the table above is that mapping. One resource maps to one PDP
- entity except `Deployment`, which spans version-create + upload + start +
- promote (and therefore owns the env-snapshot moment).
+- **Ours → PDP**: each resource's provider (`reconcile`/`delete`) calls the Management API; the table above is that mapping. One resource maps to one PDP entity except `Deployment`, which spans version-create + upload + start + promote (and therefore owns the env-snapshot moment, and carries the service's `variables`).
- **PDP → ours**: `foundryVersionId`, `Promotion`, and Foundry's version record have no resource of ours; they are internal to the `Deployment` provider's behavior or unmodeled. **Branch** likewise has no Alchemy resource — it is resolved and its lifecycle managed by the CLI's container-resolution client, outside the Alchemy graph entirely (see [§ Environments and container resolution](#environments-and-container-resolution)). `serviceEndpointDomain` surfaces as `App.appEndpointDomain` and `Deployment.appEndpointDomain`; both are the same domain.
## The lowering graphs
@@ -202,15 +192,14 @@ flowchart LR
```mermaid
flowchart TB
subgraph P [Project: shop]
- DBa[(Database shop.authdb)] --> Ca[Connection shop.authdb.connection] -- url --> EVa["EnvironmentVariable(COMPOSER_SHOP_AUTH_DB_URL)"]
- DBs[(Database shop.storefrontdb)] --> Cs[Connection shop.storefrontdb.connection] -- url --> EVs["EnvironmentVariable(COMPOSER_SHOP_STOREFRONT_DB_URL)"]
+ DBa[(Database shop.authdb)] --> Ca[Connection shop.authdb.connection] -- "url → variables.COMPOSER_SHOP_AUTH_DB_URL" --> Da
+ DBs[(Database shop.storefrontdb)] --> Cs[Connection shop.storefrontdb.connection] -- "url → variables.COMPOSER_SHOP_STOREFRONT_DB_URL" --> Ds
Sa[App shop.auth] --> Da[Deployment shop.auth.deployment]
Ss[App shop.storefront] --> Ds[Deployment shop.storefront.deployment]
- EVa -- resource ref --> Da
- EVs -- resource ref --> Ds
- Sa -- appEndpointDomain --> EVu["EnvironmentVariable(COMPOSER_SHOP_STOREFRONT_AUTH_URL)"]
- EVu -- resource ref --> Ds
- Da -- "serviceId (after promote)" --> Ds
+ Ka[SentVariableNames shop.auth.sent-variable-names] -- names --> Da
+ Ks[SentVariableNames shop.storefront.sent-variable-names] -- names --> Ds
+ Sa -- "appEndpointDomain → variables.COMPOSER_SHOP_STOREFRONT_AUTH_URL" --> Ds
+ Da -- "serviceId (after promote), on app" --> Ds
end
```
@@ -218,31 +207,22 @@ How the pieces map:
- **The application** lowers to one `Project`, resolved by the CLI before
Alchemy runs. It provisions no variables of its own.
-- **Each service** lowers to an `App → Deployment` chain plus its own
- `Database → Connection`, whose url is written as that service's **explicitly
- named** variable — the same `serialize` path as any other config value.
-- **The connection** lowers to two edges: the producer's App's endpoint domain flows into a named `EnvironmentVariable`, and that **whole resource flows into the consumer's `Deployment`** through its `app` prop. The domain comes from the App, not the Deployment: the Deployment is promoted on every deploy, so its domain is unknown while planning, and a consumer's deployment, whose triggers hold the value, would be replaced on every deploy. Because the App's domain is known, an unchanged consumer keeps its deployment when its producer is redeployed.
-- Every `EnvironmentVariable` a Deployment boots with is threaded into its `app` — database URLs and connection URLs alike — so the deployment depends on its config being written first.
+- **Each service** lowers to an `App → Deployment` chain, a `SentVariableNames` record, plus its own `Database → Connection`, whose url is one of that service's **explicitly named** keys in the Deployment's `variables` — the same `serialize` path as any other config value.
+- **The connection** lowers to two edges: the producer's App's endpoint domain becomes a named key in the consumer's Deployment's `variables`, and the producer's outputs ride the consumer's `app` prop. The domain comes from the App, not the Deployment: the Deployment is promoted on every deploy, so its domain is unknown while planning, and a consumer's deployment, whose `variables` hold the value, would be replaced on every deploy. Because the App's domain is known, an unchanged consumer keeps its deployment when its producer is redeployed.
+- Every value a Deployment boots with is in its `variables`, so Alchemy schedules the Deployment after every resource those values come from.
- Every output of a consumer's producers is threaded into its Deployment's `app` too, so its deployment waits for its producers' promotion: a Compute producer's `serviceId` comes from its Deployment and resolves only after the promotion. The wait is on `app`, not in `triggers`, and upstream treats an unresolved `app` as unchanged, so an unchanged consumer is not replaced.
- The Deployment's `portMapping.http` rides the same seam: `serialize` resolves
the service's `port` param from the typed Config and surfaces it in its
outputs, and `deploy` routes the platform to it — so the routed port and the
`PORT` the app binds trace to one value and cannot drift.
-That ordering edge is essential and mirrors PDP's own dataflow — the
-deployment-create call literally contains the materialized env map, so the
-environment is genuinely an input to a deployment (see the
-[config lifecycle](pdp-data-model.md#the-config-lifecycle--what-is-resolved-when)).
-The edge's job is **ordering**: the variable write completes before
-deployment-create, so new and replacement deployments boot with the completed
-configuration updates.
-Without it the two race — the failure documented as PRO-211 in `gotchas.md`.
+That ordering mirrors PDP's own dataflow — the deployment-create call contains the service's variables, so they are genuinely an input to a deployment (see the [config lifecycle](pdp-data-model.md#the-config-lifecycle--what-is-resolved-when)).
-**Why the edge rides `app`.** Upstream's `Prisma.Deployment` has no `environment` prop (Composer's deleted one did). Alchemy derives its dependency graph from the resource references a prop's *value* is built from, so the descriptor builds `app` as an Output over the app id, every whole variable resource and every output of the service's producers, resolving to the app id itself: the graph gains the edges. A persisted variable ID can resolve before its pending value update finishes; the whole resource keeps that update as a dependency. The edge cannot ride `artifactPath` (or any of upstream's other replacement-block props): the diff reads that block as one unit and gives no opinion the moment any member is unresolved — and a brand-new variable's reference IS unresolved at plan time — which would skip the artifact comparison and silently drop a code change. [ADR-0048](../90-decisions/ADR-0048-prisma-cloud-resources-come-from-the-upstream-alchemy-provider.md) records the full argument, and `compute/__tests__/deployment-edge.test.ts` drives upstream's real diff.
+**Why the producer edge rides `app`.** Upstream's `Prisma.Deployment` has no prop for "wait for these". Alchemy derives its dependency graph from the resource references a prop's *value* is built from, so the descriptor builds `app` as an Output over the app id and every output of the service's producers, resolving to the app id itself (`appAfter`): the graph gains the edges. The edge cannot ride `artifactPath` (or any of upstream's other replacement-block props): the diff reads that block as one unit and gives no opinion the moment any member is unresolved, which would skip the artifact comparison and silently drop a code change. [ADR-0048](../90-decisions/ADR-0048-prisma-cloud-resources-come-from-the-upstream-alchemy-provider.md) records the full argument, and `compute/__tests__/deployment-edge.test.ts` drives upstream's real diff.
-**Change propagation is wired through `Prisma.Deployment.triggers`.** The platform freezes a deployment's environment at create, so a *value* change (a rotated URL) reaches a running service only through a new deployment. The compute descriptor declares one trigger member per environment row, carrying the same `Redacted` value the row writes; upstream folds the resolved members into a salted fingerprint inside its own encrypted state and plans a replacement exactly when one moved (and conservatively when a member cannot be resolved at plan time because the producing resource is itself changing). Unchanged service → same fingerprint → reuse; changed value or artifact → replace. Because upstream resolves the actual values, a value re-issued under a stable resource identity (a connection rotated in place, a re-minted service key) moves the fingerprint too. No plaintext lands in state — the members are `Redacted` in props and only the salted hash is persisted. A platform variable a row merely POINTS at (operator-owned; Composer never reads its value) contributes a `:updatedAt` member instead, read at preflight and handed to the lowering in the extension's preflight payload, so an out-of-band rotation still ships a new deployment. A service's input document is not an environment row and has no trigger member: it travels in the service's artifact, in the `inputDocument` field of `compute.bootstrap.json` ([ADR-0065](../90-decisions/ADR-0065-a-compute-services-input-document-travels-in-its-artifact.md)), so a changed document changes the artifact's bytes and its content-addressed `artifactPath`, which replaces the deployment. A platform variable the document names is still a `:updatedAt` member.
+**Change propagation is wired through `variables` and `triggers`.** The platform copies a deployment's environment at create, so a *value* change (a rotated URL) reaches a running service only through a new deployment. Upstream records a salted hash of the resolved `variables` and plans a replacement when it moves, when a value cannot be resolved at plan time because the producing resource is itself changing, and when `variables` is declared on a deployment that recorded no hash. Unchanged service → same hash → reuse; changed value or artifact → replace. Because upstream resolves the actual values, a value re-issued under a stable resource identity (a connection rotated in place, a re-minted service key) replaces too. Every key the service reads at boot is in `variables`, as its value or `null`, and `SentVariableNames` adds `null` for every name Composer no longer sends, so it is deleted from the service ([ADR-0069](../90-decisions/ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)). The values are stored in deploy state in plain text: Alchemy writes every prop to state, and a `Redacted` value as its text; each is a value the deploy produced, never a platform variable's. A platform variable the service reads (operator-owned; Composer never holds its value) contributes a `:updatedAt` member to `triggers` instead, read at preflight and handed to the lowering in the extension's preflight payload, so an out-of-band rotation still ships a new deployment. A service's input document is not in `variables` and has no trigger member: it travels in the service's artifact, in the `inputDocument` field of `compute.bootstrap.json` ([ADR-0065](../90-decisions/ADR-0065-a-compute-services-input-document-travels-in-its-artifact.md)), so a changed document changes the artifact's bytes and its content-addressed `artifactPath`, which replaces the deployment. A platform variable the document names is still a `:updatedAt` member.
-The compute descriptor constructs these edges (the `serialize` env-var records thread into `deploy` through the service SPI, and the producers' outputs come from the lowering context); no app author ever hand-wires them.
+The compute descriptor constructs these edges (the `serialize` map threads into `deploy` through the service SPI, and the producers' outputs come from the lowering context); no app author ever hand-wires them.
## Related
diff --git a/docs/design/05-prisma-cloud/build-reporting.md b/docs/design/05-prisma-cloud/build-reporting.md
index db375abe6..7af6b6f6e 100644
--- a/docs/design/05-prisma-cloud/build-reporting.md
+++ b/docs/design/05-prisma-cloud/build-reporting.md
@@ -149,9 +149,9 @@ The mapping, keyed by upstream `@alchemy.run/prisma` type ids:
| `Prisma.Bucket` | `bucket` |
| `Prisma.App` | `app` |
| `Prisma.Deployment` | `deployment` (also attaches the deployment to the build and records the app) |
-| `Prisma.EnvironmentVariable` | `config_variable` |
+| `Prisma.EnvironmentVariable` | `config_variable`. A hosted deploy declares none ([ADR-0069](../90-decisions/ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)), so the only ones reported are the rows an older Composer wrote, as `deleted`, on the first deploy with this version |
| `Prisma.BucketAccessKey` | not reported; no platform type corresponds |
-| `ServiceKey`, `PgWarm`, any other extension's resource | not reported; not a platform resource |
+| `ServiceKey`, `PgWarm`, `SentVariableNames`, any other extension's resource | not reported; not a platform resource |
| Terminal state status | Reported action |
| --- | --- |
diff --git a/docs/design/05-prisma-cloud/pdp-data-model.md b/docs/design/05-prisma-cloud/pdp-data-model.md
index ff701ebe5..c02b5735f 100644
--- a/docs/design/05-prisma-cloud/pdp-data-model.md
+++ b/docs/design/05-prisma-cloud/pdp-data-model.md
@@ -83,16 +83,13 @@ This is the timing model Prisma Composer's graph must respect:
| --- | --- | --- |
| default DB provisioned | the platform **writes** `DATABASE_URL` and `DATABASE_URL_POOLED` as ordinary project-level production-class ConfigVariable **templates** (user-set values win) | `compute-config/wireDefaultDatabaseUrl.ts` |
| any time | ConfigVariable rows are created/updated/deleted via the environment-variables API — **rows only; no effect on any existing version** | `routes/v1/environment-variables.ts` |
-| **version create** | `materializeBranchEnvVars(app.branchId)` resolves the complete map — production branch → production templates; preview branch → preview templates merged with that branch's overrides (override wins) — decrypts it, and hands the **plain map to Foundry with the version**. The env is **frozen into the version** | `routes/v1/versions.ts` → `resolveDeployEnvVars.ts` → `compute-config/materializeBranchEnvVars.ts` |
+| **version create** | `materializeBranchEnvVars(app.branchId)` resolves the branch's map — production branch → production templates; preview branch → preview templates merged with that branch's overrides (override wins) — and decrypts it; then the request's `variables`, when sent, are stored on the service (a string sets a key, `null` deletes it, a key not sent keeps its value), and every stored service variable is laid over the map. The plain map goes **to Foundry with the version**; the env is **frozen into the version** | `routes/v1/services.ts` (`POST /v1/services/{serviceId}/deployments`) → `interactors/compute/saveServiceVariablesAndDeploy.ts` → `compute-config/materializeBranchEnvVars.ts` |
| version start | boots the version; **no env re-resolution** | `routes/v1/version-handlers.ts` |
| promote | endpoint routed to the version; `serviceEndpointDomain` persisted. The domain returned at *create* names the domain the service will serve on | `interactors/compute/service.ts` |
Consequences Prisma Composer designs around:
-1. **A version's environment is a snapshot taken at version creation.** A config
- value that must be visible to a service's code has to exist as a
- ConfigVariable row *before* that service's version-create call (the failure
- mode when it doesn't is documented as PRO-211 in `gotchas.md`).
+1. **A version's environment is a snapshot taken at version creation.** A config value that must be visible to a service's code has to exist *before* that service's version-create call (the failure mode when it doesn't is documented as PRO-211 in `gotchas.md`). Composer sends a service's own keys in that call, as service variables, so they cannot arrive late ([ADR-0069](../90-decisions/ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)); a service variable wins over the branch's values.
2. **Changing config requires a new version to take effect.** There is no
restart-on-config-change and no live re-resolution; a late-written variable
never reaches an existing version. Propagating a changed value (e.g. a
@@ -101,7 +98,7 @@ Consequences Prisma Composer designs around:
the deployment, so the change reaches the running service (see the
change-propagation note in
[alchemy-lowering.md](alchemy-lowering.md#the-lowering-graphs)).
-3. **`DATABASE_URL` is not a separate mechanism.** It is a platform-written template flowing through the same materialization as user variables — a convenience for hand-provisioned single services. The platform owns it (system-managed) and writes it only for a project's default database. Prisma Composer refuses to bind or manage the name and creates no default database (see [alchemy-lowering.md](alchemy-lowering.md#database_url-is-forbidden--and-left-to-the-platform)); every database URL a service consumes is an explicit, service-named variable.
+3. **`DATABASE_URL` is not a separate mechanism.** It is a platform-written template flowing through the same materialization as user variables — a convenience for hand-provisioned single services. The platform owns it (system-managed) and writes it only for a project's default database. Prisma Composer refuses to bind or manage the name and creates no default database (see [alchemy-lowering.md](alchemy-lowering.md#database_url-is-forbidden--and-left-to-the-platform)); every database URL a service consumes is an explicit, service-named key.
4. **Branch + class is the platform's environments model** (production
templates vs preview templates + per-branch overrides) — the substrate
[an environment as a Branch](../10-domains/deploy-cli.md#environments-and-containers) is
diff --git a/docs/design/10-domains/config-params.md b/docs/design/10-domains/config-params.md
index 1ffcfbc39..86afb7dbe 100644
--- a/docs/design/10-domains/config-params.md
+++ b/docs/design/10-domains/config-params.md
@@ -80,16 +80,16 @@ Follow a compute service `web` in the app `shop`, with a `rawPostgres()` depende
Config = { service: { port: 3000 }, inputs: { db: { url: 'postgres://…' } } }
```
-**Deploy: serialize and store (the target).** `@prisma/composer-prisma-cloud` encodes each value as one environment variable on the platform, keyed `COMPOSER_` plus the full address, upper-cased, with `.` and `-` turned into `_`, then the owner and name. Every generated key carries the `COMPOSER_` prefix, the framework's reserved namespace, kept clear of the platform variables the operator sets:
+**Deploy: serialize and store (the target).** `@prisma/composer-prisma-cloud` encodes each value as one key in the `variables` of the service's deployment, which the platform stores on the service as a service variable ([ADR-0069](../90-decisions/ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)), keyed `COMPOSER_` plus the full address, upper-cased, with `.` and `-` turned into `_`, then the owner and name. Every generated key carries the `COMPOSER_` prefix, the framework's reserved namespace, kept clear of the platform variables the operator sets:
```
COMPOSER_SHOP_WEB_PORT = '3000'
COMPOSER_SHOP_WEB_DB_URL = '"postgres://…"'
```
-The service's deployment depends on these variables, so it is created after the writes and replaced when a value changes.
+The deployment is created with these keys, after every resource their values come from, and replaced when a value changes. A key with no value is sent as `null`, which deletes a value an earlier deploy stored.
-**Boot: deserialize (the target).** The service's bootstrap reads the rows back and reverses the encoding: `port` is validated into a number, and the dependency's params into its connection values.
+**Boot: deserialize (the target).** The service's bootstrap reads the keys back and reverses the encoding: `port` is validated into a number, and the dependency's params into its connection values.
**Runtime.** The service reads the port through `service.port()` and its dependencies through `service.load()`, which hydrates them. Its input comes separately, from its input document, through `service.input()` ([ADR-0042](../90-decisions/ADR-0042-service-input-is-one-standard-schema.md)).
diff --git a/docs/design/10-domains/core-model.md b/docs/design/10-domains/core-model.md
index 9927d8456..5ab126e3f 100644
--- a/docs/design/10-domains/core-model.md
+++ b/docs/design/10-domains/core-model.md
@@ -588,13 +588,13 @@ interface ServiceLowering
{
// references — the whole stack effect runs before Alchemy applies anything.
provision(ctx: LowerContext): Effect.Effect
// serialize: encode the typed Config core built into the service's runtime
- // environment (on Prisma Cloud: EnvironmentVariables on the project, and the
- // input document for the artifact), keyed by the deployment address.
+ // environment (on Prisma Cloud: the keys of the deployment's `variables`, and
+ // the input document for the artifact), keyed by the deployment address.
// The pack owns the encoding; run()'s deserialize reverses it through the same
// serializer, so writer and reader cannot drift. Leaf values are provisioning
- // refs → the env writes depend on the resources/producer (the ordering edges).
- // Returns the env-var records so `deploy` can reference them (the environment
- // edge — see alchemy-lowering.md), and whatever `package` puts in the artifact.
+ // refs → the deployment depends on the resources/producer (the ordering edges).
+ // Returns the encoded values so `deploy` can pass them (see
+ // alchemy-lowering.md), and whatever `package` puts in the artifact.
serialize(ctx: LowerContext, provisioned: P, config: Config):
Effect.Effect
// package: assemble the deployable artifact from the build adapter's normalized
@@ -778,19 +778,7 @@ nodes are edges only and never lower. Then for each service:
5. `deploy(artifact)` — the first version snapshots an environment that is already
complete.
-**How the ordering is actually enforced:** our walk only *assembles* Alchemy resource descriptions — Alchemy executes them in dependency order and runs unordered resources concurrently; declaration order is never consulted. So core realizes the sequence as **dependency edges**: most arise naturally from value flow (the env var consumes the project id and the producer's URL), and two do not. Deploy-after-serialize exists because the service descriptor builds the `Deployment`'s props out of the environment records it boots with, which is PDP's own dataflow restored (the deployment-create call literally contains the materialized env map). Deploy-after-producers exists because the service descriptor also builds them out of its producers' outputs, so a consumer's deployment is created after its producers go live. See the lowering graphs in
-[`../05-prisma-cloud/alchemy-lowering.md`](../05-prisma-cloud/alchemy-lowering.md).
-This is what makes the fresh-deploy config race (PRO-211) structurally impossible
-on every target — the edge's **ordering** job. Its second job, **propagating**
-a wire whose value genuinely changes, is wired by the deploy hook: a deploy
-whose environment differs from the running deployment's replaces the
-deployment, so changed values reach the running service. Secret *values* are
-never hashed or persisted for this — the mechanism keys off the non-secret
-material Composer's rows carry (ADR-0042 pointers) and platform metadata. The
-long-term carrier is the deployment resource itself (inputs it must be
-recreated for), tracked as an upstream follow-up.
-Secrets are platform-sourced and rotate through the platform, not this edge (see
-the [input glossary entry](../03-domain-model/glossary.md#input)).
+**How the ordering is actually enforced:** our walk only *assembles* Alchemy resource descriptions — Alchemy executes them in dependency order and runs unordered resources concurrently; declaration order is never consulted. So core realizes the sequence as **dependency edges**: most arise naturally from value flow (the consumer's deployment `variables` consume the producer's URL and the database connection), and two do not. Deploy-after-serialize exists because the service descriptor builds the `Deployment`'s props out of the values it boots with, which is PDP's own dataflow (the deployment-create call carries the service's variables). Deploy-after-producers exists because the service descriptor also builds them out of its producers' outputs, so a consumer's deployment is created after its producers go live. See the lowering graphs in [`../05-prisma-cloud/alchemy-lowering.md`](../05-prisma-cloud/alchemy-lowering.md). This is what makes the fresh-deploy config race (PRO-211) structurally impossible on every target — the edge's **ordering** job. Its second job, **propagating** a wire whose value genuinely changes, is wired by the deploy hook: a deploy whose environment differs from the running deployment's replaces the deployment, so changed values reach the running service. On Prisma Cloud the carrier is the deployment resource itself: a salted hash of its `variables`, and a `:updatedAt` trigger per platform variable it reads, whose value Composer never holds (ADR-0069). Secrets are platform-sourced and rotate through the platform, not this edge (see the [input glossary entry](../03-domain-model/glossary.md#input)).
**Deployment identity — address, bootstrap, and why.** A node's identity is its **address**: the path of provision ids starting at the root, assigned by Load from graph position. The root's address is the deployed app name, so every address starts with it (`shop`, `shop.catalog`, `shop.auth.api`). A provision id is the node's name unless `provision()` sets an `id`, and the path qualifies it, so registry modules with common internal names (`db`, `service`) cannot collide. Identity cannot travel through the environment: every App in a Project boots a byte-identical env (ConfigVariables are project+branch-scoped and snapshotted at version create — see the [PDP data model](../05-prisma-cloud/pdp-data-model.md)), so any "who am I" variable is one shared key, last write wins. The only per-service channel is the artifact itself. Hence the bootstrap: the artifact's entrypoint takes identity as a parameter, and deploy is the caller. The Compute artifact the pack assembles:
@@ -1087,27 +1075,29 @@ export const prismaCloud = (opts: PrismaCloudOptions = {}): ExtensionDescriptor
return { serviceId: svc.appId, projectId: projectIdOf(application), endpointDomain: svc.appEndpointDomain } // : ComputeProvisioned
}),
- // Encode the typed Config into the runtime environment — one env var per
- // leaf, keyed by the SAME serializer run() reads with at boot. Values are
- // the provisioning refs core built the Config from, so each env var depends
- // on its resource/producer (the ordering edges). Returns the records deploy
- // must depend on, plus the resolved listen port.
+ // Encode the typed Config into the runtime environment — one key per
+ // leaf, keyed by the SAME serializer run() reads with at boot, `null`
+ // when it has no value. Values are the provisioning refs core built the
+ // Config from, so the deployment depends on its resource/producer (the
+ // ordering edges). A record of every name ever sent adds `null` for each
+ // name Composer no longer sends. Returns the map deploy sends, plus the resolved listen port.
serialize: ({ address, node, graph }, provisioned, config) =>
Effect.gen(function* () {
- const records = []
+ const bootVariables = {}
for (const d of configOf(node)) {
const value = d.owner === "service" ? config.service[d.name] : config.inputs[d.owner.input]?.[d.name]
- if (value === undefined) continue
- records.push(yield* Prisma.EnvironmentVariable(`${address}.env.${configKey(address, d)}`, {
- project: provisioned.projectId, key: configKey(address, d),
- value: Redacted.make(encode(d.owner, value)), class: "production",
- }))
+ bootVariables[configKey(address, d)] = value === undefined ? null : Redacted.make(encode(d.owner, value))
}
+ const everSent = yield* SentVariableNames(`${address}.sent-variable-names`, { names: Object.keys(bootVariables).sort() })
+ const requestVariables = Output.map(everSent.names, (names) => ({
+ ...Object.fromEntries(names.map((name) => [name, null])),
+ ...bootVariables,
+ }))
// The input document is not a variable: its text travels in the artifact.
const binding = graph.inputBindings.find((b) => b.serviceAddress === address)?.binding
const input = serializeInput(node, address, binding)
const port = typeof config.service.port === "number" ? config.service.port : 3000
- return { environment: records, port, ...(input !== undefined ? { input } : {}) } // : ComputeSerialized → deploy's edges, package's document
+ return { bootVariables, requestVariables, port, ...(input !== undefined ? { input } : {}) } // : ComputeSerialized → deploy's variables, package's document
}),
// Print the bootstrap and assemble the deployable artifact from the build
@@ -1118,10 +1108,9 @@ export const prismaCloud = (opts: PrismaCloudOptions = {}): ExtensionDescriptor
package: ({ id }, { assembled, address }, serialized) =>
Effect.try(() => Prisma.packageComputeArtifact({ id, bundleDir: assembled.dir, appEntry: assembled.entry, address, inputDocument: serialized.input && JSON.parse(serialized.input.value) })),
- // create → upload → start → promote. The app id is read through
- // serialize's env-var records and every output of its producers, so the
- // deployment is created after its rows are written (PRO-211) and after
- // its producers are promoted. Returns a LoweredResult: `url` IS
+ // create (with the variables) → upload → start → promote. The app id is
+ // read through every output of its producers, so the deployment is
+ // created after its producers are promoted. Returns a LoweredResult: `url` IS
// published here — a Compute service's deployed URL is a public endpoint,
// and this descriptor is the only party that knows it. It is the App's
// domain, not the deployment's: the deployment is promoted on every
@@ -1135,8 +1124,9 @@ export const prismaCloud = (opts: PrismaCloudOptions = {}): ExtensionDescriptor
.flatMap((edge) => Object.values(lowered.get(edge.from) ?? {}))
.filter(Output.isOutput)
const deployment = yield* Prisma.Deployment(`${address}.deployment`, {
- app: appAfter(provisioned.serviceId, serialized.environment, producerOutputs),
+ app: appAfter(provisioned.serviceId, producerOutputs),
artifactPath: artifact.path,
+ variables: serialized.requestVariables,
artifactContentType: "application/gzip",
portMapping: { http: serialized.port }, start: true, promote: true,
})
diff --git a/docs/design/10-domains/local-dev.md b/docs/design/10-domains/local-dev.md
index cf99a7170..036380219 100644
--- a/docs/design/10-domains/local-dev.md
+++ b/docs/design/10-domains/local-dev.md
@@ -294,18 +294,7 @@ A start in flight ends with the first of these that applies:
The exit of a process the emulator no longer tracks is ignored.
-The env materialization is the one platform-side behavior the local target
-implements itself: the hosted platform joins the branch's config variables
-into a deployment at version-create; locally, the `Deployment` provider
-performs the same join from the `EnvironmentVariable` records the lowering
-emitted — against props defined in this repo, once, not an emulation of a
-foreign API. One pinned deviation: the local join is scoped to the
-service's own rows (plus any row outside the `COMPOSER_` namespace, which is
-a platform-owned name by definition), because the platform
-diffs a deployment only on its own referenced rows while an app-wide local
-snapshot diffs on bytes — which restart-amplified dependents on every
-first-after-cold converge. No sanctioned reader consumes sibling rows, so
-the scoping changes restart behavior only.
+The env materialization is the one platform-side behavior the local target implements itself: the hosted platform copies a service's variables into a deployment at version-create; locally, the `Deployment` provider builds the same environment from the `variables` the lowering gave the deployment ([ADR-0069](../90-decisions/ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)), leaving out a key sent as `null`, then lays the port the emulator assigned over `COMPOSER__PORT` and adds the platform variables the service reads — against props defined in this repo, once, not an emulation of a foreign API. A changed `variables` is a changed prop, so it restarts exactly the service that reads it. A dev server has no deployment: its rows, which `reserve` declares, are in `env.json`, and its environment is built from the rows under its own address (plus any row outside the `COMPOSER_` namespace, which is a platform-owned name by definition), so a sibling's row never changes it.
The Postgres and bucket emulators follow the same model: a database is an
instance with a generated id (`db_<16 hex digits>`), served by a
@@ -478,8 +467,8 @@ semantics):
| `Database` | the database instance the directory's record names for the resource, on its own `@prisma/dev` server hosted by the Postgres emulator; started if stopped, created when missing; `databaseId` is the instance id |
| `Connection` | the URL of the database instance its `Database` names |
| `App` | finds the service's Compute instance through the directory's record, creating it when there is none; the instance holds the service's port; `appEndpointDomain = http://localhost:` — which makes origin (ADR-0039) work unchanged. Deleting it deletes the instance |
-| `Deployment` | unpacks the artifact once per hash, reads the input document from its `compute.bootstrap.json`, materializes the env, and puts the deployment at the service's Compute instance, which (re)starts the child; updated when its instance does not run the recorded artifact |
-| `EnvironmentVariable` | a key→value row in the dev state store |
+| `Deployment` | unpacks the artifact once per hash, reads the input document from its `compute.bootstrap.json`, materializes the env from its `variables`, and puts the deployment at the service's Compute instance, which (re)starts the child; updated when its instance does not run the recorded artifact |
+| `EnvironmentVariable` | a key→value row in the dev state store (`env.json`); only `reserve` declares one, for a dev server |
| `Bucket` | the bucket instance the directory's record names for the resource, over a directory under `.prisma-composer/dev//buckets///`, served by the bucket emulator; `bucketId` is the instance id, also its S3 name |
| `BucketKey` | credentials registered with the bucket emulator for its bucket |
| `ServiceKey` | **unchanged** — mints locally, persists in state |
@@ -552,7 +541,7 @@ The worker thread of a `prisma dev` converge runs no adapter. The main thread pa
A rebuild runs no dev preflight, so a read of a platform variable that a code change adds would have no value. `prisma dev` therefore sends each converge's worker thread the reads of the graph it started with (`valueReads`: reader, node and path) and each read node's address and `props`. The worker, which has just loaded the app as it is on disk, compares them with its own graph's before it converges. If either differs, it does not converge; `prisma dev` emits the `value-reads-changed` event with the nodes whose reads were added, removed or changed, and pauses rebuilds until it is restarted. If the first converge sees a difference, which usually means an app file changed while `prisma dev` was starting, and otherwise that a module body builds a different graph each time it runs, `prisma dev` stops and names the reads that changed. For a rebuild the CLI prints a warning: `The platform variables the app reads changed since dev started: reads of "shop.smtpPort" were added, reads of "shop.emailFrom" were removed, and "shop.sender" was changed. Restart dev to apply them; rebuilds are paused until then.` An edit that adds or removes a node fails the rebuild with a message that says to restart `prisma dev`.
-The local `Deployment` provider gives each service only the variables its own input reads: the `$platform` markers in its input document, at any depth. For a service that runs its artifact, it reads the input document for this from the unpacked artifact's `compute.bootstrap.json`, with the reader `@internal/lowering` exports next to the packer. It ignores a `COMPOSER__INPUT` entry in `env.json` for such a service, whether or not the artifact holds a document, and does not put that key into the process's environment, because the artifact's bootstrap passes the document to `run()`. For a service that runs a dev server, which has no artifact, the compute descriptor's `reserve` writes the input document as a `COMPOSER__INPUT` variable, which the local target keeps in `env.json` with the service's other rows. This isolation is a requirement of the local target only. On Prisma Cloud every deployment receives every variable of its class.
+The local `Deployment` provider gives each service only the variables its own input reads: the `$platform` markers in its input document, at any depth. For a service that runs its artifact, it reads the input document for this from the unpacked artifact's `compute.bootstrap.json`, with the reader `@internal/lowering` exports next to the packer. It does not read `env.json` for such a service, and the artifact's bootstrap passes the document to `run()`. For a service that runs a dev server, which has no artifact, the compute descriptor's `reserve` writes the input document as a `COMPOSER__INPUT` row, which the local target keeps in `env.json` with the service's other rows. This isolation is a requirement of the local target only. On Prisma Cloud every deployment receives every variable of the group its branch receives.
To load `.env` files, list `dotenv()` in `config` and `secrets`, with `environmentVariables()` after it to keep the shell. It reads `.env`, `.env.local`, `.env.` and `.env..local` beside `prisma.config.ts`, through `dotenv-flow`, and skips `.env.local` for the environment `test`. Values in `.env.dev` are read only by the environment `dev`; values in `.env` and `.env.local` are read by every environment, `prisma deploy` to `production` included. The deploy does not copy a secret to the platform, but a plain value there reaches the root's input in every environment. `import 'dotenv/config'` at the top of `prisma.config.ts` still works with the default lists; remove it when you list `dotenv()`.
diff --git a/docs/design/90-decisions/ADR-0032-params-bind-at-provision-to-a-literal-or-a-deploy-time-value.md b/docs/design/90-decisions/ADR-0032-params-bind-at-provision-to-a-literal-or-a-deploy-time-value.md
index 288945376..380f06c98 100644
--- a/docs/design/90-decisions/ADR-0032-params-bind-at-provision-to-a-literal-or-a-deploy-time-value.md
+++ b/docs/design/90-decisions/ADR-0032-params-bind-at-provision-to-a-literal-or-a-deploy-time-value.md
@@ -37,7 +37,7 @@ A param takes no source: not a platform variable node's value, not `generatedPar
- A provision-time literal or deploy-time value is schema-validated when config is built, and beats the `default`.
- A required param that nothing binds fails the deploy loudly.
-- The deploy writes each param as one JSON-encoded row, `COMPOSER__`, and boot reads it back with the param's schema ([ADR-0019](ADR-0019-the-target-owns-config-serialization.md)). No param row names a variable on the platform.
+- The deploy sends each param as one JSON-encoded key, `COMPOSER__`, with the service's deployment ([ADR-0069](ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)), and boot reads it back with the param's schema ([ADR-0019](ADR-0019-the-target-owns-config-serialization.md)). No param names a variable on the platform.
- A value change needs a redeploy: a deployment snapshots its environment at creation.
- Where a compute service's port is set is not decided: through this per-key param, or somewhere else such as the build options.
diff --git a/docs/design/90-decisions/ADR-0039-a-compute-services-own-origin-is-a-target-resolved-property.md b/docs/design/90-decisions/ADR-0039-a-compute-services-own-origin-is-a-target-resolved-property.md
index a863e21d7..bc4fcfff5 100644
--- a/docs/design/90-decisions/ADR-0039-a-compute-services-own-origin-is-a-target-resolved-property.md
+++ b/docs/design/90-decisions/ADR-0039-a-compute-services-own-origin-is-a-target-resolved-property.md
@@ -44,12 +44,7 @@ the service will serve on. The framework never string-builds the URL from a
region map — that would couple it to the platform's URL convention and break
silently if the scheme changed (the no-guessing rule, ADR-0005).
-**The framework supplies the value in every environment**, like any other
-config: deploy writes the row unconditionally; a test harness sets
-`COMPOSER_ORIGIN` exactly as it sets other `COMPOSER_*` rows; a local runner
-writes it because it binds the port. Calling `origin()` where nothing supplied
-the row is an ordinary loud missing-config error, raised lazily at the call so
-services that never read it are unaffected.
+**The framework supplies the value in every environment**, like any other config: deploy sends the key unconditionally (ADR-0069); a test harness sets `COMPOSER_ORIGIN` exactly as it sets other `COMPOSER_*` keys; a local runner gives it because it binds the port. Calling `origin()` where nothing supplied the row is an ordinary loud missing-config error, raised lazily at the call so services that never read it are unaffected.
## Consequences
diff --git a/docs/design/90-decisions/ADR-0041-local-dev-runs-the-deploy-pipeline-against-local-providers.md b/docs/design/90-decisions/ADR-0041-local-dev-runs-the-deploy-pipeline-against-local-providers.md
index a82fe718e..162b7f61e 100644
--- a/docs/design/90-decisions/ADR-0041-local-dev-runs-the-deploy-pipeline-against-local-providers.md
+++ b/docs/design/90-decisions/ADR-0041-local-dev-runs-the-deploy-pipeline-against-local-providers.md
@@ -82,23 +82,11 @@ three clusters:
| Cluster | Resources | Local implementation |
| --- | --- | --- |
-| Compute | `ComputeService`, `Deployment`, `EnvironmentVariable` | a Compute **emulator** owning one child process per service, plus a local env-var store |
+| Compute | `ComputeService`, `Deployment`, `EnvironmentVariable` | a Compute **emulator** owning one child process per service, plus a local env-var store for dev servers |
| Postgres | `Project`, `Database`, `Connection` | the ORM CLI's local Postgres **emulator** (`prisma dev`) |
| Buckets | `Bucket`, `BucketKey` | a bucket **emulator**: the storage module's existing S3 wire handler + SigV4 verifier over a disk-backed object store — objects are plain files at their key paths |
-**The target runs one emulator per node kind — the platform's primitives,
-locally.** The extension's `emulators` hook inspects the loaded topology and
-ensures a machine-scoped emulator daemon per node kind the app uses: a
-**Compute emulator** (runs service processes), the **Postgres emulator** (the
-ORM's `prisma dev` — its daemon manager is the ORM CLI's own), and a **bucket
-emulator** (the S3 wire over disk). Each emulator is multi-tenant and
-long-lived — the firebase/supabase model — and is capable of creating an
-*isolated instance* of its node type: a running service, a database, a
-bucket. The local providers provision those instances by communicating with
-the emulators during converge, and the orchestration wires the instances to
-each other through the same lowered `EnvironmentVariable` records a deploy
-produces — the topology composes locally exactly as it does on the platform.
-Emulator instances are removed only by `--fresh`, through `teardown`.
+**The target runs one emulator per node kind — the platform's primitives, locally.** The extension's `emulators` hook inspects the loaded topology and ensures a machine-scoped emulator daemon per node kind the app uses: a **Compute emulator** (runs service processes), the **Postgres emulator** (the ORM's `prisma dev` — its daemon manager is the ORM CLI's own), and a **bucket emulator** (the S3 wire over disk). Each emulator is multi-tenant and long-lived — the firebase/supabase model — and is capable of creating an *isolated instance* of its node type: a running service, a database, a bucket. The local providers provision those instances by communicating with the emulators during converge, and the orchestration wires the instances to each other through the same lowered values a deploy produces — the `variables` of each service's `Deployment` ([ADR-0069](ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)), or, for a dev server, the `EnvironmentVariable` rows `reserve` declares — so the topology composes locally exactly as it does on the platform. Emulator instances are removed only by `--fresh`, through `teardown`.
**Converge terminates; the Compute emulator keeps serving.** Alchemy's
converge is a run-to-completion program (ADR-0007 drives it in a child
@@ -135,16 +123,7 @@ assembly consumes, never sources; the user's own watcher (`next dev` is not
involved — `tsdown --watch`, `bun build --watch`, whatever their build does)
produces the rebuild, and dev responds by re-running assemble and converge.
-**A service boots exactly as deployed.** The artifact's bootstrap calls
-`run(address, boot, inputDocument)` with the input document the artifact's
-`compute.bootstrap.json` holds
-([ADR-0065](ADR-0065-a-compute-services-input-document-travels-in-its-artifact.md)),
-against the same `COMPOSER_*` environment protocol a deploy's platform
-injection produces — the local `Deployment` provider materializes that
-environment from the same `EnvironmentVariable` records the lowering emitted,
-and reads the artifact's input document to work out which platform variables
-the service's process receives. Deserialization, stashing,
-`load()`/`config()`/`secrets()` all execute the deployed code path.
+**A service boots exactly as deployed.** The artifact's bootstrap calls `run(address, boot, inputDocument)` with the input document the artifact's `compute.bootstrap.json` holds ([ADR-0065](ADR-0065-a-compute-services-input-document-travels-in-its-artifact.md)), against the same `COMPOSER_*` environment protocol a deploy's platform injection produces — the local `Deployment` provider materializes that environment from the same `variables` the lowering gave the deployment, leaving out a key sent as `null`, and reads the artifact's input document to work out which platform variables the service's process receives. Deserialization, stashing, `load()`/`config()`/`secrets()` all execute the deployed code path.
## Reasoning
@@ -277,6 +256,7 @@ this repo owns.
provisioning seam that every extension must implement and keep from drifting,
duplicating exactly the orchestration the deploy pipeline already performs —
and contradicting goals.md's stand-in-beside-provider shape.
+- **Every service's keys in the local env-var store.** The position before ADR-0069: the local `Deployment` provider read each service's own rows from `env.json`, which the lowering's `EnvironmentVariable` records filled. A deployment now carries its keys in `variables`, and only a dev server, which has no deployment, keeps rows.
- **Direct-injection boot** (`service.runLocal(values)` — hand the service its
hydrated bindings, bypassing the env wire protocol). Retained as a *testing*
convenience only. Dev drives the real `run(address, boot)` path so that
diff --git a/docs/design/90-decisions/ADR-0044-errors-are-structural-envelopes-with-dotted-namespace-codes.md b/docs/design/90-decisions/ADR-0044-errors-are-structural-envelopes-with-dotted-namespace-codes.md
index c95a18501..53e479409 100644
--- a/docs/design/90-decisions/ADR-0044-errors-are-structural-envelopes-with-dotted-namespace-codes.md
+++ b/docs/design/90-decisions/ADR-0044-errors-are-structural-envelopes-with-dotted-namespace-codes.md
@@ -64,7 +64,7 @@ Closed subcode registry:
- `CONFIG` — SECTION_MISSING, FIELD_INVALID, FIELD_UNKNOWN, FIELD_RETIRED, FILE_MISSING, FILE_RETIRED, EXTENSION_DUPLICATE, EXTENSION_MISSING, DESCRIPTOR_MISSING, DESCRIPTOR_KIND_MISMATCH, ENTRY_MISSING, ADAPTER_FAILED, ADAPTER_INVALID, SECRET_AS_PLAIN_VALUE *(EXPORT_INVALID, PATH_MISMATCH and EVALUATION_FAILED retired by [ADR-0049](ADR-0049-composers-configuration-is-the-composer-section-of-prisma-config.md))*. ENTRY_MISSING: neither `entry` in the `composer` section nor `--entry`, or the operation's `entry` input, names the entry module. ADAPTER_FAILED: a config or secrets adapter threw or rejected; its message is redacted. ADAPTER_INVALID: an adapter returned something other than an object of values, or a secrets adapter returned a value that is not text. SECRET_AS_PLAIN_VALUE: a plain value Load read would contain a known secret, a value under a secrets key the graph names; `deploy` raises it before anything is created, `destroy` and `prisma dev` before they write the app configuration file. The error names the field or configuration key and the secrets key, never the value.
- `COMPOSE` — ENTRY_UNLOADABLE, ENTRY_EXPORT_INVALID, ROOT_NOT_MODULE, NAME_MISSING, GRAPH_INVALID. ENTRY_EXPORT_INVALID: the entry's default export is not the app's root, an app root built with `appRoot()` or a module built with `module()`. ROOT_NOT_MODULE: the entry default-exports a service; the fix provisions the service inside an `appRoot()` root. Both are raised before Load, by every command that loads the entry.
- `ASSEMBLE` — EXTENSION_MISSING, DESCRIPTOR_MISSING, DESCRIPTOR_KIND_MISMATCH, SERVICE_MISSING, BUILD_FAILED
-- `DEPLOY` — FLAG_INVALID, TARGET_CONFLICT, TARGET_MISSING, TARGET_NOT_FOUND, ENVIRONMENT_INVALID, ENVIRONMENT_UNVALIDATABLE, ENVIRONMENT_REQUIRED, CONTAINER_FAILED, PREFLIGHT_FAILED, ENGINE_FAILED, TEARDOWN_FAILED, CONTAINER_REMOVE_FAILED, BUILD_REQUIRED, INTERRUPTED, CONVERGE_RUNNING, WORKER_THREAD, MANAGEMENT_API_URL_CONFLICT *(STAGE_INVALID, STAGE_UNVALIDATABLE and SCOPE_MISSING retired by [ADR-0059](ADR-0059-a-deployment-environment-is-called-an-environment.md); ALCHEMY_BIN_MISSING, NODE_MISSING and STACK_WRITE_FAILED retired by [ADR-0068](ADR-0068-destroy-runs-alchemy-in-process.md))*. ENVIRONMENT_REQUIRED: a `destroy` call names no environment. ENGINE_FAILED: Alchemy failed. `deploy` and `destroy` run Alchemy in process ([ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md), [ADR-0068](ADR-0068-destroy-runs-alchemy-in-process.md)); `prisma deploy` exits 2. INTERRUPTED: the abort signal stopped the plan or apply of a `deploy` or a `destroy`. `prisma deploy` exits 130 (143 for SIGTERM): it reports this code as a message event and ends with the engine's abort, `CLI.ABORTED`. CONVERGE_RUNNING: another in-process converge holds this process's working directory and the reporter variables it sets in the environment. WORKER_THREAD: `deploy` or `destroy` was called from a worker thread with a `cwd` other than the process's working directory, which a worker cannot change. MANAGEMENT_API_URL_CONFLICT: the deploy was given a Management API client, and `PRISMA_API_URL` names another host than the one that client sends to (`PRISMA_MANAGEMENT_API_URL`, or `https://api.prisma.io`). Raised by the Prisma Cloud extension when it resolves the environment's container, for `deploy` and `destroy`, and when it builds its providers or its state store, for `deploy`.
+- `DEPLOY` — FLAG_INVALID, TARGET_CONFLICT, TARGET_MISSING, TARGET_NOT_FOUND, ENVIRONMENT_INVALID, ENVIRONMENT_UNVALIDATABLE, ENVIRONMENT_REQUIRED, CONTAINER_FAILED, PREFLIGHT_FAILED, ENGINE_FAILED, TEARDOWN_FAILED, CONTAINER_REMOVE_FAILED, BUILD_REQUIRED, INTERRUPTED, CONVERGE_RUNNING, WORKER_THREAD, MANAGEMENT_API_URL_CONFLICT, SERVICE_VARIABLE_LIMIT *(STAGE_INVALID, STAGE_UNVALIDATABLE and SCOPE_MISSING retired by [ADR-0059](ADR-0059-a-deployment-environment-is-called-an-environment.md); ALCHEMY_BIN_MISSING, NODE_MISSING and STACK_WRITE_FAILED retired by [ADR-0068](ADR-0068-destroy-runs-alchemy-in-process.md))*. ENVIRONMENT_REQUIRED: a `destroy` call names no environment. ENGINE_FAILED: Alchemy failed. `deploy` and `destroy` run Alchemy in process ([ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md), [ADR-0068](ADR-0068-destroy-runs-alchemy-in-process.md)); `prisma deploy` exits 2. INTERRUPTED: the abort signal stopped the plan or apply of a `deploy` or a `destroy`. `prisma deploy` exits 130 (143 for SIGTERM): it reports this code as a message event and ends with the engine's abort, `CLI.ABORTED`. CONVERGE_RUNNING: another in-process converge holds this process's working directory and the reporter variables it sets in the environment. WORKER_THREAD: `deploy` or `destroy` was called from a worker thread with a `cwd` other than the process's working directory, which a worker cannot change. MANAGEMENT_API_URL_CONFLICT: the deploy was given a Management API client, and `PRISMA_API_URL` names another host than the one that client sends to (`PRISMA_MANAGEMENT_API_URL`, or `https://api.prisma.io`). Raised by the Prisma Cloud extension when it resolves the environment's container, for `deploy` and `destroy`, and when it builds its providers or its state store, for `deploy`. SERVICE_VARIABLE_LIMIT: the app declares more values for one Compute service than Prisma Cloud stores on a service; the summary names the service, the count and the limit. Raised by the Prisma Cloud extension while it plans the service, before any resource is created, changed or deleted, for `deploy` and for `prisma dev`, which refuses what a deploy would ([ADR-0069](ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)). It is reported today as the tag of one of the reasons of `DEPLOY.ENGINE_FAILED` for `deploy`, and of `DEV.CONVERGE_FAILED` for `prisma dev`.
- `DEV` — PLATFORM_UNSUPPORTED, TARGET_UNSUPPORTED, CONTAINER_FAILED, TEARDOWN_FAILED, PREFLIGHT_FAILED, EMULATOR_FAILED, SERVICE_START_FAILED, CONVERGE_FAILED, ATTACH_FAILED, EMULATORS_DIR_INVALID, EMULATOR_UNREACHABLE, SERVICE_READY_TIMEOUT_INVALID, NOT_STARTED_HERE, ADDRESS_UNKNOWN, NOT_RUNNING, INTERRUPTED, CONVERGE_RUNNING, WORKER_THREAD, ENVIRONMENT_WRITE_FAILED *(STACK_WRITE_FAILED retired by [ADR-0067](ADR-0067-prisma-dev-converges-in-a-worker-thread.md): `prisma dev` writes no stack file)*. CONVERGE_FAILED: a dev converge failed or could not start. When the engine failed, it carries the tag and message of each error the engine failed with. It is also raised, with no engine errors, when the first converge sees other reads of platform variables than dev prepared for, and when a rebuild finds a node added or removed, or a root input field the root did not pass on at start. An error raised before the converge with a code of its own, such as `COMPOSE.ENTRY_UNLOADABLE`, fails the first converge under that code. INTERRUPTED: the abort signal stopped the first converge. CONVERGE_RUNNING: another converge in this process, a deploy's or a dev session's, holds the working directory. WORKER_THREAD: `dev` was called from a thread that cannot change the process's working directory, with a `cwd` other than that directory; only the main thread can change it. ENVIRONMENT_WRITE_FAILED: the dev environment's folder could not be written. EMULATOR_UNREACHABLE is raised by the emulator client when it cannot connect, so `log` raises it under `DEV` too; for a connection failure it takes the place of SERVICE_START_FAILED, ATTACH_FAILED and `LOG.ATTACH_FAILED`. `devUrl` also raises it when the emulator a node runs on is not running. NOT_STARTED_HERE (no `prisma dev` has recorded an app in the directory) is raised by `devUrl` and `devStop`; ADDRESS_UNKNOWN (the recorded app has no node at that address; the known addresses are listed) and NOT_RUNNING (the node exists but is not running; its state is named, and the reason and fix depend on it) by `devUrl` alone ([ADR-0053](ADR-0053-dev-url-dev-stop-and-emulator-list.md)). Both operations raise EMULATOR_FAILED when the local target fails without a code. `emulator list` fails only with EMULATORS_DIR_INVALID; an emulator it cannot list is reported in that emulator's entry with EMULATOR_UNREACHABLE or EMULATOR_FAILED.
- `LOG` — PLATFORM_UNSUPPORTED, ATTACH_FAILED, ADDRESS_UNKNOWN
- `DEPS` — EXECUTOR_UNLOADABLE, EXTENSION_INCOMPATIBLE, CONVERGE_UNRESOLVABLE, CONVERGE_CONTRACT_MISMATCH *(EFFECT_VERSION_CONFLICT retired by [ADR-0049](ADR-0049-composers-configuration-is-the-composer-section-of-prisma-config.md))*. EXTENSION_INCOMPATIBLE: an installed extension is older than the Composer running the deploy or destroy, so the container it resolved, rebuilt through its own `deserialize`, does not name the environment that was asked for. CONVERGE_UNRESOLVABLE: `deploy` cannot load `@prisma/composer/internal/converge` from the app's own install, or that install predates it ([ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md)). CONVERGE_CONTRACT_MISMATCH: the app's `@prisma/composer` speaks another converge contract than the `prisma` CLI's Composer; the message names both contract numbers and both package versions, and the fix says which side to upgrade. Different package versions with the same contract are accepted.
diff --git a/docs/design/90-decisions/ADR-0048-prisma-cloud-resources-come-from-the-upstream-alchemy-provider.md b/docs/design/90-decisions/ADR-0048-prisma-cloud-resources-come-from-the-upstream-alchemy-provider.md
index 4ba87166f..8b1e3e2df 100644
--- a/docs/design/90-decisions/ADR-0048-prisma-cloud-resources-come-from-the-upstream-alchemy-provider.md
+++ b/docs/design/90-decisions/ADR-0048-prisma-cloud-resources-come-from-the-upstream-alchemy-provider.md
@@ -4,8 +4,6 @@ Amended by [ADR-0057](ADR-0057-a-nodes-address-is-its-full-path-from-the-app-nam
Amended 2026-10-30: from Alchemy 2.0.0-beta.84 the provider is its own package, `@alchemy.run/prisma`, versioned in lockstep with `alchemy`; before that it was the `alchemy/Prisma` module of the `alchemy` package. Only `@prisma/composer-prisma-cloud` and the Prisma Cloud internals it bundles depend on it; `@prisma/composer` and `@prisma/composer-cli` depend on `alchemy` alone. The move kept every resource type id (`Prisma.*`), so deploy state carries over unchanged. The decision below is unchanged.
-Amended 2026-11-20: a compute service's published `url` is its App's `appEndpointDomain`, not its Deployment's: the Deployment is updated on every deploy, so its domain is unknown while planning, and every consumer's deployment, whose `triggers` hold the url, would be replaced on every deploy. A consumer's deployment waits for its producers' promotion through the deployment's `app` prop, which also carries every output of the nodes it depends on (a compute producer's `serviceId` resolves only after its promotion), never through `triggers`, so an unchanged consumer is reused.
-
## Decision
Composer does not implement Alchemy resources for Prisma Cloud's Management API. It composes the official upstream Prisma provider's (`@alchemy.run/prisma`, formerly `alchemy/Prisma`) resources and providers, and defines its own resources only where the upstream provider has no support yet (buckets, whose routes upstream deferred) or where no Management API exists behind them (local mechanisms like migration steps).
@@ -20,7 +18,7 @@ Layer.mergeAll(
Prisma.ConnectionProvider(),
Prisma.AppProvider(),
Prisma.DeploymentProvider(),
- Prisma.EnvironmentVariableProvider(),
+ providerForDeletingOldVariableRows(), // upstream's, deleting the rows an older Composer wrote (ADR-0069)
),
// + Composer's own resources: Bucket, BucketKey, ServiceKey,
// GeneratedParam, S3Credentials, OrmMigration, PgWarm
@@ -30,10 +28,11 @@ and a lowered compute service is upstream resources wired by Composer's descript
```ts
const app = Prisma.App(`${id}-svc`, { project, regionId, branchId });
-const vars = records.map((r) => Prisma.EnvironmentVariable(...));
const deployment = Prisma.Deployment(`${id}-deploy`, {
- app: appAfter(app, vars, producerOutputs), // see "The ordering edge" below
- artifactPath, // Composer's own tar.gz — never built by Alchemy
+ app: appAfter(app.appId, producerOutputs), // see "The ordering edge" below
+ artifactPath, // Composer's own tar.gz — never built by Alchemy
+ variables, // the service's COMPOSER_ keys (ADR-0069)
+ triggers, // one `:updatedAt` per platform variable it reads
start: true,
promote: true,
});
@@ -45,34 +44,39 @@ Why hand Composer's most platform-critical surface to an external package: the p
## The compute family binds the low-level trio, not `Prisma.Compute`
-Upstream offers two shapes for compute: a composite `Prisma.Compute` that owns app, environment, and deployment in one resource, and the low-level `App` / `Deployment` / `EnvironmentVariable`. Composer uses the low-level trio. The deciding constraint is a cycle:
+Upstream offers two shapes for compute: a composite `Prisma.Compute` that owns app, environment, and deployment in one resource, and the low-level `App` / `Deployment` / `EnvironmentVariable`. Composer uses `App` and `Deployment`; `EnvironmentVariable` is declared only by `prisma dev` for a dev server, and its hosted provider stays registered to delete rows an older Composer wrote ([ADR-0069](ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)). The deciding constraint is a cycle:
-Every service's environment includes `COMPOSER__ORIGIN` — the service's *own* platform-assigned endpoint domain (ADR-0039). A composite resource that owns both the environment rows and the app makes that row an input of the very resource that produces the domain: a self-edge the planner rejects. Split, the wiring is legal: the App exists first and hands out `appEndpointDomain`, environment rows are written from it, the Deployment comes last.
+Every service's environment includes `COMPOSER__ORIGIN` — the service's *own* platform-assigned endpoint domain (ADR-0039). A composite resource that owns both the environment and the app makes that value an input of the very resource that produces the domain: a self-edge the planner rejects. Split, the wiring is legal: the App exists first and hands out `appEndpointDomain`, and the Deployment is created with the value in its `variables`.
Two supporting reasons:
-- `Compute` owns environment rows through an internal ownership map and refuses in-scope rows absent from it; Composer's per-key rows have no honest mapping into that map.
+- `Compute` manages environment rows through an internal ownership map and refuses in-scope rows absent from it; Composer's keys are service variables on the create-deployment request, which that map does not describe.
- `Compute` carries build, framework detection, and bundling. Its `artifactPath` prop bypasses them, but a bypass is a prop value; `Prisma.Deployment` has **no build path at all**, which is ADR-0005's guarantee in structural form.
What the trio costs: `Compute`'s preview/stable health checks and automatic rollback are not inherited, and deployment reuse must be handled by Composer (next two sections).
## The ordering edge rides the `app` prop
-Environment rows must be written before the deployment is created, because the platform snapshots the branch environment into a deployment at create. Upstream's `Deployment` has no prop for that dependency, so Composer builds the edge into the `app` prop: an Output over the app id *and* every whole environment resource, resolving to the app id (`lowering/src/compute/deployment-edge.ts`). A persisted variable ID is stable and can resolve while its value update is still pending; depending on that ID loses the ordering edge. Whole-resource references preserve the dependency on completion of the writes, including updates to existing variables. Alchemy derives its graph from those resource references inside prop values, so every row is scheduled first.
+A consumer's deployment must not go live before its producers', or a consumer could call a method its producer has only just added. A compute service publishes its App's `appEndpointDomain` as its `url`, not its Deployment's: the Deployment is updated on every deploy, so its domain is unknown while planning, and every consumer whose `variables` hold the url would be replaced on every deploy. The App exists before any deployment, so the url alone orders nothing. Upstream's `Deployment` has no prop for that dependency, so Composer builds the edge into the `app` prop: an Output over the app id *and* every output of the nodes the service depends on, resolving to the app id (`appAfter` in `lowering/src/compute/deployment-edge.ts`). A compute producer's `serviceId` output comes from its Deployment and resolves only after the producer is promoted. Alchemy derives its graph from the resource references inside prop values, so every producer is promoted first, and an unchanged consumer is still reused because nothing in its `variables` or `triggers` changes.
-The edge must not ride `artifactPath`. Upstream's diff reads `{portMapping, skipCodeUpload, artifactPath, artifactContentType}` as one block and offers no opinion when any member is unresolved — and a brand-new environment row is always unresolved at plan time. The consequence of getting this wrong is severe and quiet: the artifact comparison never runs, the engine falls back to a plain update, and the reconcile keeps the running deployment while recording the new artifact's fingerprint as deployed — a code change silently never ships, and every later deploy agrees it already did. The `app` prop sits outside that block and tolerates being unresolved. `compute/__tests__/deployment-edge.test.ts` drives upstream's real diff and real Output machinery and fails if the edge ever moves back.
+The edge must not ride `artifactPath`. Upstream's diff reads `{portMapping, skipCodeUpload, artifactPath, artifactContentType}` as one block and offers no opinion when any member is unresolved — and an output of a resource the same deploy is changing is unresolved at plan time. The consequence of getting this wrong is severe and quiet: the artifact comparison never runs, the engine falls back to a plain update, and the reconcile keeps the running deployment while recording the new artifact's fingerprint as deployed — a code change silently never ships, and every later deploy agrees it already did. The `app` prop sits outside that block and tolerates being unresolved. `compute/__tests__/deployment-edge.test.ts` drives upstream's real diff and real Output machinery and fails if the edge ever moves back.
## A deployment is replaced when its environment changes
-The platform bakes environment values into a deployment at create, and upstream reuses a deployment whose artifact is unchanged — so a value-only change (a rotated secret) would update the platform's variable row and never reach the running app. Composer closes this by declaring each service's environment values as `Prisma.Deployment.triggers` (upstream's replacement-inputs prop, shipped in alchemy 2.0.0-beta.74; designed as `redeployOn` and renamed in review): one `Redacted` member per environment row, carrying the same value the row writes. Alchemy resolves the members, folds them into a salted fingerprint inside its own encrypted state, and plans a replacement exactly when one moved — unchanged service, same fingerprint, deployment reused; changed value or artifact, replace. A service's input document is not an environment row: it travels in the artifact ([ADR-0065](ADR-0065-a-compute-services-input-document-travels-in-its-artifact.md)), so a changed document changes the artifact and replaces the deployment that way. A member that cannot be resolved at plan time (its producing resource is itself changing in the same deploy) replaces conservatively, and the first deploy that declares triggers records its fingerprint through a plain update rather than forcing a replacement.
+The platform copies a service's environment into a deployment when it creates it, and upstream reuses a deployment whose artifact is unchanged — so a value-only change (a rotated secret) must replace the deployment to reach the running app. Two props of `Prisma.Deployment` carry the values whose change replaces it.
+
+- **`variables`**, the service's `COMPOSER_` keys ([ADR-0069](ADR-0069-a-services-composer-keys-travel-with-its-deployment-as-service-variables.md)). Upstream records a salted hash of the resolved map and plans a replacement when the hash changes, when a value is not resolved at plan time (its producing resource is itself changing in the same deploy), and when the prop is declared on a deployment that recorded no hash, because an update creates no deployment and the values would never reach the platform. Because upstream resolves the actual values, a value re-issued under a stable resource identity (a connection rotated in place, a re-minted service key) replaces too.
+- **`triggers`** (upstream's replacement-inputs prop, shipped in alchemy 2.0.0-beta.74; designed as `redeployOn` and renamed in review), with one member per platform variable the service reads. Composer never holds such a variable's value, so its out-of-band rotation is detected through its `updatedAt` metadata, read at preflight and passed to the lowering as a value (a timestamp, never a variable's value), and joined as a `:updatedAt` member. Upstream folds the members into a salted fingerprint and replaces when one moved; a member unresolved at plan time replaces conservatively, and the first deploy that declares `triggers` records its fingerprint through a plain update.
+
+A service's input document is in neither: it travels in the artifact ([ADR-0065](ADR-0065-a-compute-services-input-document-travels-in-its-artifact.md)), so a changed document changes the artifact and replaces the deployment that way.
-No plaintext reaches state: members are `Redacted` in props, and only the salted hash is persisted. Because alchemy resolves the actual values, a value re-issued under a stable resource identity (a connection rotated in place, a re-minted service key) moves the fingerprint too — the narrowing the earlier Composer-side fingerprint (a hash of non-secret environment material folded into the artifact path, deleted with the beta.74 bump) had to accept is closed. A pointed platform variable Composer never writes still has no value to trigger on; its out-of-band rotation is detected through its `updatedAt` metadata, read at preflight, carried to the Alchemy process over the framework's preflight-transport channel (a timestamp, never a value), and joined as a `:updatedAt` trigger member.
+The values in `variables` are stored in deploy state in plain text: Alchemy writes every prop to state, and writes a `Redacted` value as its text. `Redacted` keeps them out of logs and error messages. Each is a value the deploy produced, never a platform variable's value, which the deploy never holds.
## Consequences
- **Namespaces.** The `Prisma.*` resource type-id namespace and the `'Prisma'` collection tag belong to upstream. Composer's collection tag is `'PrismaComposer'` and its own resources are `PrismaComposer.*`. Rows persisted under retired Composer type-ids are rewritten on read by the hosted state store (`state/legacy-resources.ts`): ids, attribute shapes, and the retirement of the `DATABASE_URL` claim rows that earlier versions tracked as resources (see "Claim both names with a placeholder" under Alternatives considered). The module is the durable compatibility boundary for state written by earlier Composer versions. Scope: "legacy" here means rows already INSIDE the platform state API (ADR-0045), written under retired type-ids or shapes. The older generation — the retired SQL `prisma-composer-state` stores — stays under ADR-0045's own rule: never read, cleaned up by destroy or Branch deletion. The two rules govern different stores and do not overlap.
- **Branch-stage databases carry generated physical names.** Upstream refuses an explicit name combined with branch attachment at create — and it is right to: the Management API creates the database and attaches the branch in separate transactions with no idempotency key, so a lost response is indistinguishable from a foreign database. Attaching after create does not survive either: upstream's reconcile detaches a branch its props don't declare. So branch stages attach at create and take the generated name; production keeps explicit names.
-- **The platform's `DATABASE_URL` is left alone.** Prisma Cloud writes `DATABASE_URL`/`DATABASE_URL_POOLED` only when a project is created with a database, or when a database is created as the project's default, and marks them system-managed; upstream refuses to manage system-managed variables. Composer creates projects without a database and never creates a default one, so the platform writes neither on a Composer project. Composer never creates, overwrites, updates, deletes, or tracks either variable. The guarantee that apps read configuration through the framework is held at the authoring end: `variable()` and `variable.secret()` reject the reserved names (`variable-name.ts`), and every row Composer writes is `COMPOSER_`-prefixed. An app that reads `process.env.DATABASE_URL` directly sees whatever the platform or the user put there.
+- **The platform's `DATABASE_URL` is left alone.** Prisma Cloud writes `DATABASE_URL`/`DATABASE_URL_POOLED` only when a project is created with a database, or when a database is created as the project's default, and marks them system-managed; upstream refuses to manage system-managed variables. Composer creates projects without a database and never creates a default one, so the platform writes neither on a Composer project. Composer never creates, overwrites, updates, deletes, or tracks either variable. The guarantee that apps read configuration through the framework is held at the authoring end: `variable()` and `variable.secret()` reject the reserved names (`variable-name.ts`), and every key Composer sends is `COMPOSER_`-prefixed. An app that reads `process.env.DATABASE_URL` directly sees whatever the platform or the user put there.
- **Auth never touches Alchemy's profile store.** Alchemy's own credential flow prompts on a TTY and hard-fails non-interactive; Composer runs alchemy as a subprocess with piped stdio. Composer provides `PrismaEnvironment` directly from `PRISMA_SERVICE_TOKEN`, with one base-URL resolver shared between upstream's providers and Composer's own SDK client so both always target the same host.
- **A known weakness is inherited:** upstream retries a conflicting App delete for only a few seconds, where Composer's own resource waited out deployment drain for minutes. Slow drains can fail a destroy and need a re-run.
@@ -82,6 +86,8 @@ No plaintext reaches state: members are `Redacted` in props, and only the salted
- **The composite `Prisma.Compute`.** Rejected for the self-edge, the environment-ownership map, and ADR-0005 (above).
- **Vendor the provider's source into Composer.** Mechanically possible; inherits its dependencies and permanent drift. Kept only as a fallback if a future alchemy upgrade proves unshippable.
- **Adopt upstream's built-in dev mode instead of the local target.** Would replace a whole-layer seam that already works with per-provider substitution, and tie local-dev iteration to an external release cadence.
+- **Write each `COMPOSER_` key as a `Prisma.EnvironmentVariable` row, ordered before the deployment through the `app` prop, with one `triggers` member per row repeating its value.** The position before ADR-0069. The `app` edge held every whole row resource, because a persisted variable ID can resolve while its value update is still pending. Rows were branch overrides on preview, which the platform is removing; the record of that change is ADR-0069.
+- **Take a consumer's url from its producer's Deployment.** Its domain is unknown while planning, so every consumer would be replaced on every deploy.
- **Replace the deployment on every deploy** (the pre-adoption behavior). Ships every change by brute force but gives up upstream's reuse entirely; superseded first by the Composer-side fingerprint, then by `Deployment.triggers`.
- **Claim both names with a placeholder.** Earlier versions wrote `"-"` under `DATABASE_URL` and `DATABASE_URL_POOLED`, in the production and preview classes at project level, so the platform could not put a live credential there. The first versions did it through tracked `EnvironmentVariable` resources, so the rows were in deploy state; later versions did it with create-only calls outside deploy state. Both rested on the belief that the platform fills in a missing `DATABASE_URL` on the first Compute deploy from any ready database in the project. The platform does not do that, so on a Composer project the rows protected nothing. Rows already written stay on existing projects. State entries from the tracked form are dropped on read by `state/legacy-resources.ts`, with no call to the platform.
- **Hash environment values Composer-side.** A bare hash of a secret in a plaintext path or state row is an offline-guessing target; rejected. The interim Composer-side fingerprint therefore hashed only material that was non-secret by construction (accepting the re-issued-value narrowing above); upstream's `triggers` avoids the exposure differently — a salted fingerprint computed and persisted inside alchemy's own state, never a bare hash of a secret in the open.
diff --git a/docs/design/90-decisions/ADR-0056-prisma-dev-runs-a-service-with-its-build-adapters-dev-server.md b/docs/design/90-decisions/ADR-0056-prisma-dev-runs-a-service-with-its-build-adapters-dev-server.md
index eef452250..4477dbe7f 100644
--- a/docs/design/90-decisions/ADR-0056-prisma-dev-runs-a-service-with-its-build-adapters-dev-server.md
+++ b/docs/design/90-decisions/ADR-0056-prisma-dev-runs-a-service-with-its-build-adapters-dev-server.md
@@ -216,7 +216,7 @@ export interface ServiceLowering
{
In core's lowering loop, for an address in `unassembled`: `provision` and `serialize` run as always; the bundle lookup and `missingBundleError` are skipped; `package` is not called; `reserve` is called with the same `ctx`, `provisioned` and `serialized` that `deploy` would get; its result is stored in `lowered` and `entries` exactly as `deploy`'s is. A descriptor without `reserve` fails the lowering with a `LowerError` whose message is ``service "