Skip to content
Draft
4 changes: 4 additions & 0 deletions .drive/projects/variable-groups-compat/deferred.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,8 @@
- **Preflight does not see a value a user set on one service.** A platform variable set only as a service variable, through Console's "Save and Deploy", is reported unset, and a required one fails the deploy. The fix is one `resolved-variables?serviceId=` read per reading service that already exists, with each key's `updatedAt` added to that service's triggers. Not built because Composer has no way to declare such a value. From the design, section 4.1.
- **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.
- **A local client type and a cast stand in for the SDK's description of the resolved-variables read.** `ResolvedVariablesClient` and its `blindCast` in `packages/1-prisma-cloud/1-extensions/target/src/preflight.ts` exist because `@prisma/management-api-sdk` does not describe `GET /v1/projects/{projectId}/resolved-variables`. Remove both and use the SDK's types when it does.
- **The custom-group hint is a sentence because `prisma variable add … --group` does not exist.** When the CLI ships it, replace the sentence in `setCommands` with the command, and change ADR-0064's sentence that says no released CLI command writes to a custom group.
- **`scripts/e2e-first-deploy.ts` writes branch overrides and production rows with no group.** For a non-production environment it posts `class: preview` with a `branchId`, which the platform will reject; for production it posts a row with no `groupId`, which the resolved-variables read does not list. Slice 3 must change it to write to the branch's group.
- **`branchId ?? defaultBranchId` is still computed outside the container**, in `attachmentBranchIdOf` (`descriptors/shared.ts`, on `CloudApplication`) and in lowering's `deployed.ts`, on their own types. Minor; `PrismaCloudContainer.deployBranchId` is the one definition in the container.
- **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.
10 changes: 5 additions & 5 deletions .drive/projects/variable-groups-compat/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,22 +102,22 @@ From the response:

Everything preflight returns keeps its type. `updatedAt` is printed the same way by the old list call and the new read, so on a branch that receives `production` or `preview` the trigger values do not change, and upgrading replaces no deployment for this reason.

**A failed call fails the deploy.** A 404 for the project or the branch, or any other error, stops the deploy with a message that names the call, the status, and the project and branch ids, and says that the platform may not offer this read yet. There is no fallback to the old per-key lookup: the old lookup is what gives wrong answers, and falling back would bring them back without a word.
**A failed call fails the deploy.** An error status, a network failure, or a body that is not JSON or not the expected shape stops the deploy with a message that names the call, the project and branch ids, and the HTTP status when the client reports one, with at most a one-line excerpt of the body. Only a 404 adds that the platform may not offer this read yet; for other failures that sentence would point at the wrong cause. There is no fallback to the old per-key lookup: the old lookup is what gives wrong answers, and falling back would bring them back without a word.

**A paginated answer fails the deploy.** The read returns everything in one response today. If the platform ever pages it, a release that read only the first page would report the rest missing, and there are no patch releases to fix that. So a response that carries a pagination field or a cursor stops the deploy with a message that says this Composer version is too old for the platform.
**A paginated answer fails the deploy.** The read returns everything in one response today. If the platform ever pages it, a release that read only the first page would report the rest missing, and there are no patch releases to fix that. So an answer that says there is more to fetch (`hasMore: true`, or a non-empty `nextCursor` or `cursor`, at the top level or inside `pagination`) stops the deploy with a message that says this Composer version is too old for the platform. A complete answer in the platform's list envelope, such as `pagination: { nextCursor: null, hasMore: false }`, is accepted.

**Hint commands** are chosen by the class of the group the environment receives.

| `group.class` | Commands suggested |
| --- | --- |
| `production` | `prisma project env add 'NAME=<value>' --project <id> --role production` |
| `preview` | `prisma project env add 'NAME=<value>' --project <id> --role preview` |
| `custom` | `prisma variable add 'NAME=<value>' --project <id> --group <name>` |
| `custom`, or a class Composer does not know | A sentence: `Set NAME in the variable group "<name>" in the Prisma Console.` |

The group's name is quoted for the shell, as the project id is. Two changes from today:
Two changes from today:

1. **The `--branch <environment>` command is no longer suggested.** It creates a branch override, which the platform is removing.
2. **A custom group gets the new CLI's command.** `prisma project env` cannot write to a custom group. `prisma variable` is not released yet. A custom group cannot exist in production before the platform turns the feature on, and the platform's rollout releases the CLI first. The slice that builds this checks the command's exact spelling against `prisma/prisma-cli` before it merges. If the command has not shipped by then, the hint for a custom group is a sentence naming the group and Console, with no command.
2. **A custom group gets a sentence, not a command.** `prisma project env` cannot write to a custom group, and the `prisma variable add … --group` command does not exist yet: on 2026-11-20 it is only in a draft demo pull request on `prisma/prisma-cli` (#395). So the hint names the group in double quotes and says to set the value in the Prisma Console. Core's comment on `UnsetPlatformVariable.commands` says each line is a shell command where one exists, otherwise an instruction. When `prisma variable` ships, the hint becomes its command (see `deferred.md`).

The built-in groups keep `prisma project env` because it works with every CLI version. It is deprecated in the new CLI but keeps working. The hints move to `prisma variable` in a later change.

Expand Down
4 changes: 4 additions & 0 deletions .drive/projects/variable-groups-compat/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ Design sections 4.3 and 4.4. Builds on: nothing. Hands to slice 2: the client vi

Design section 4.1. Builds on: slice 1. Merges when the new read is live in production with the missing-group-id defect fixed. Until then the pull request is a draft.

Before merge: check again whether `prisma variable` has shipped (if it has, the custom-group hint becomes its command), and run manual QA once more against the platform's real read.

Note for any later read by `serviceId`: for a key set both as a branch override and as a service variable, the platform's read reports the override (it layers overrides last), while its deployment gives the service the service variable (it layers service variables last). A trigger built from that read would miss a change to the service variable. Raise it with the platform team before relying on that read.

## 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.
Expand Down
6 changes: 0 additions & 6 deletions architecture.config.json
Original file line number Diff line number Diff line change
Expand Up @@ -408,12 +408,6 @@
"layer": "extensions",
"plane": "shared"
},
{
"glob": "packages/1-prisma-cloud/1-extensions/target/src/map-with-concurrency.ts",
"domain": "prisma-cloud",
"layer": "extensions",
"plane": "control"
},
{
"glob": "packages/1-prisma-cloud/1-extensions/target/src/required-variables.ts",
"domain": "prisma-cloud",
Expand Down
12 changes: 10 additions & 2 deletions docs/design/03-domain-model/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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_` 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`.

### Platform variable node

Expand All @@ -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. Composer's own `COMPOSER_` rows are rows too, but not [platform variables](#platform-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 writes a service's `COMPOSER_` rows on a preview environment as branch overrides, so those writes 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 does not read or write one yet.

### Value resource

Expand Down
Loading
Loading