Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
d1adc72
chore(drive): plan for the slice that sends a service's COMPOSER_ key…
wmadden-electric Nov 20, 2026
76932bc
build(deps): Prisma.Deployment can be created with variables stored o…
wmadden-electric Nov 20, 2026
f1a4f17
feat(prisma-cloud): a service's COMPOSER_ keys travel with its deploy…
wmadden-electric Nov 20, 2026
bfcf0e2
test(prisma-cloud): deploys under the real engine send every key with…
wmadden-electric Nov 20, 2026
90d363e
feat(prisma-cloud): under prisma dev a service that runs its artifact…
wmadden-electric Nov 20, 2026
4b490dc
docs(glossary): variable group and service variable, worded as the pr…
wmadden-electric Nov 20, 2026
26681b7
docs: a service's COMPOSER_ keys travel with its deployment as servic…
wmadden-electric Nov 20, 2026
030b99b
ci: no release while a published package depends on a package this wo…
wmadden-electric Nov 20, 2026
4c81fb2
build(deps): the patched Prisma.Deployment says its variables outlive…
wmadden-electric Nov 20, 2026
6832d03
refactor(prisma-cloud): names that say what each piece holds, and the…
wmadden-electric Nov 20, 2026
764826d
docs: Console, the upgrade deploy, the 50-variable refusal and the re…
wmadden-electric Nov 20, 2026
5e8f521
chore(drive): record that a planning-time refusal is reported as an e…
wmadden-electric Nov 20, 2026
8882e0b
ci: the patched-dependency check follows the lockfile, and preview pa…
wmadden-electric Nov 20, 2026
2246588
fix(prisma-cloud): the 50-variable refusal says what is true under pr…
wmadden-electric Nov 20, 2026
a1d1835
docs: an older Composer cannot deploy an environment this version has…
wmadden-electric Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .drive/projects/variable-groups-compat/deferred.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
8 changes: 4 additions & 4 deletions .drive/projects/variable-groups-compat/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<address>.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.
Expand All @@ -168,7 +168,7 @@ variables?: Record<string, Redacted.Redacted<string> | 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_<ADDRESS>_PORT`, and the platform variables are still added. A changed `variables` is a changed prop, so a changed value still restarts the service.

Expand All @@ -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.

Expand Down
15 changes: 14 additions & 1 deletion .drive/projects/variable-groups-compat/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
16 changes: 16 additions & 0 deletions .drive/projects/variable-groups-compat/slices/slice-3-plan.md
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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<string, unknown>;
+ /**
+ * 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<string, Redacted.Redacted<string> | null>;
}

export interface Deployment extends Resource<
@@ -181,6 +200,11 @@ export interface Deployment extends Resource<
* state; absent when `triggers` is unset.
*/
triggersHash?: Redacted.Redacted<string>;
+ /**
+ * Salted fingerprint of the resolved `variables` this deployment was
+ * created with; absent when `variables` is unset.
+ */
+ variablesHash?: Redacted.Redacted<string>;
/**
* Stable App endpoint domain after promotion.
*/
@@ -286,6 +310,7 @@ const attrsFrom = (
extra?: {
artifactHash?: string;
triggersHash?: Redacted.Redacted<string>;
+ variablesHash?: Redacted.Redacted<string>;
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> | string | undefined) =>
+const persistedHash = (value: Redacted.Redacted<string> | 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, Redacted.Redacted<string> | string | null>,
+): Record<string, string | null> =>
+ 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> | 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> | 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,
}));
Loading
Loading