Skip to content
Merged
43 changes: 10 additions & 33 deletions docs/design/05-prisma-cloud/alchemy-lowering.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,9 @@ behind them.
| `Prisma.Project` | Project | name | projectId | **one per Prisma Composer application**; resolved by the CLI before Alchemy runs, so no lowering yields one |
| `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 is read from |
| `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** (create-time domain is a placeholder — PRO-200). It is replaced, not updated, when its artifact fingerprint or its `triggers` fingerprint moves |
| `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.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.
Expand Down Expand Up @@ -178,14 +178,7 @@ logic is untouched.
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).
- **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` (before the first
deploy) and `Deployment.appEndpointDomain` (post-promote).
- **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

Expand Down Expand Up @@ -215,8 +208,9 @@ flowchart TB
Ss[App shop.storefront] --> Ds[Deployment shop.storefront.deployment]
EVa -- resource ref --> Da
EVs -- resource ref --> Ds
Da -- appEndpointDomain --> EVu["EnvironmentVariable(COMPOSER_SHOP_STOREFRONT_AUTH_URL)"]
Sa -- appEndpointDomain --> EVu["EnvironmentVariable(COMPOSER_SHOP_STOREFRONT_AUTH_URL)"]
EVu -- resource ref --> Ds
Da -- "serviceId (after promote)" --> Ds
end
```

Expand All @@ -227,12 +221,9 @@ How the pieces map:
- **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 endpoint domain flows
into a named `EnvironmentVariable`, and that **whole resource flows into the
consumer's `Deployment`** through its `app` prop.
- 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.
- **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.
- 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
Expand All @@ -247,25 +238,11 @@ 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`.

**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 AND every whole variable
resource, 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.
`compute/deployment-edge.ts` records the full argument and its test drives
upstream's real diff.
**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.

**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 `<name>: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 `<name>:updatedAt` member.

The framework's core constructs these edges when lowering a connection (the
`serialize` env-var records thread into `deploy` through the service SPI); no pack
author and no app author ever hand-wires them.
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.

## Related

Expand Down
2 changes: 1 addition & 1 deletion docs/design/05-prisma-cloud/pdp-data-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ This is the timing model Prisma Composer's graph must respect:
| 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 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* time is a placeholder region — only the post-promote read is trustworthy (PRO-200) | `interactors/compute/service.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:

Expand Down
46 changes: 20 additions & 26 deletions docs/design/10-domains/core-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -670,7 +670,7 @@ type Outputs = Readonly<Record<string, unknown>>
// `url` is present only when the descriptor declares the address publicly
// reachable — a connection string is never a `url` (no core-level rule is safe:
// `url` on compute is an endpoint, on postgres it would be a DSN). A descriptor
// constructing one holds `deployment.appEndpointDomain` — an Output<T>, not a T,
// constructing one holds the App's `appEndpointDomain` — an Output<T>, not a T,
// because the stack effect runs before Alchemy applies — so construction sites
// traffic in `Input<DeployedEntity>` (LoweredResult.entities above); apply
// resolves them before any reader sees them.
Expand Down Expand Up @@ -766,13 +766,7 @@ module-provisioned **resource** lowers exactly once via its extension's
nodes are edges only and never lower. Then for each service:

1. `provision` — the service now has identity (its App).
2. core **builds the typed `Config`** — each input's declared params matched by
name to its producer's `outputs` through the one `dependency` edge:
whatever the module wired in — a resource's outputs (shared by every consumer
wired to it) or a producer service's deploy outputs (the producer, earlier in
topo order, is already fully deployed — its URL is real, not the create-time
placeholder) — plus service-param defaults. Leaf values are provisioning refs,
not strings.
2. core **builds the typed `Config`** — each input's declared params matched by name to its producer's `outputs` through the one `dependency` edge: whatever the module wired in — a resource's outputs (shared by every consumer wired to it) or a producer service's deploy outputs — plus service-param defaults. Leaf values are provisioning refs, not strings. Core lowers a producer before its consumers, so a consumer's hooks receive the producer's outputs; how a target makes the consumer's deployment wait for its producers is the target's ([Prisma Cloud](../05-prisma-cloud/alchemy-lowering.md#the-lowering-graphs)).
3. `serialize(config)` — the pack encodes that typed Config into the service's
runtime environment (Prisma Cloud: one env write per leaf, keyed by the
pack's own naming from the address, value = the ref; the input document
Expand All @@ -784,15 +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 the one that
doesn't — 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). See the lowering graphs in
**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**
Expand Down Expand Up @@ -1098,7 +1084,7 @@ export const prismaCloud = (opts: PrismaCloudOptions = {}): ExtensionDescriptor
const svc = yield* Prisma.App(address, {
project: projectIdOf(application), displayName: address, regionId: o.region ?? "us-east-1", logicalId: address,
})
return { serviceId: svc.appId, projectId: projectIdOf(application) } // : ComputeProvisioned
return { serviceId: svc.appId, projectId: projectIdOf(application), endpointDomain: svc.appEndpointDomain } // : ComputeProvisioned
}),

// Encode the typed Config into the runtime environment — one env var per
Expand Down Expand Up @@ -1133,22 +1119,30 @@ export const prismaCloud = (opts: PrismaCloudOptions = {}): ExtensionDescriptor
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, so the deployment depends on them — the
// ordering edge that kills PRO-211. Returns a LoweredResult: `url` IS
// 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
// published here — a Compute service's deployed URL is a public endpoint,
// and this descriptor is the only party that knows it. Both fields are
// still Output refs until apply.
deploy: ({ address }, provisioned, artifact, serialized) =>
// 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
// deploy, so its domain is unknown while planning, and every service
// reading the URL would get a new deployment. Both fields are still
// Output refs until apply.
deploy: ({ id, address, graph, lowered }, provisioned, artifact, serialized) =>
Effect.gen(function* () {
const producerOutputs = graph.edges
.filter((edge) => edge.kind === "dependency" && edge.to === id)
.flatMap((edge) => Object.values(lowered.get(edge.from) ?? {}))
.filter(Output.isOutput)
const deployment = yield* Prisma.Deployment(`${address}.deployment`, {
app: appAfterEnvironment(provisioned.serviceId, serialized.environment),
app: appAfter(provisioned.serviceId, serialized.environment, producerOutputs),
artifactPath: artifact.path,
artifactContentType: "application/gzip",
portMapping: { http: serialized.port }, start: true, promote: true,
})
return {
outputs: { url: deployment.appEndpointDomain, projectId: provisioned.projectId },
entities: [{ kind: "compute-service", id: provisioned.serviceId, url: deployment.appEndpointDomain }],
outputs: { url: provisioned.endpointDomain, projectId: provisioned.projectId, serviceId: deployment.appId },
entities: [{ kind: "compute-service", id: provisioned.serviceId, url: provisioned.endpointDomain }],
}
}),
},
Expand Down
Loading
Loading