refactor(core): define each deploy-pipeline type by the code that reads it

[wmadden-electric]

What this looks like

Here's one step of the compute descriptor on main — the code that turns a service node into a Prisma Compute deployment:

deploy: ({ id }, provisioned, artifact, serialized) =>
  Prisma.Deployment(`${id}-deploy`, {
    computeServiceId: provisioned.outputs['serviceId'] as string,
    environment: serialized.outputs['environment'] as readonly Prisma.EnvironmentVariable[],
    port: typeof serialized.outputs['port'] === 'number' ? serialized.outputs['port'] : 3000,
  })

Three values, three casts. Each one is this descriptor reading back something it produced itself, one or two steps earlier. It has to cast, because the type it wrote those values into says nothing more specific than Record<string, unknown>.

After this PR:

deploy: ({ id }, provisioned, artifact, serialized) =>
  Prisma.Deployment(`${id}-deploy`, {
    computeServiceId: provisioned.serviceId,
    environment: serialized.environment,
    port: serialized.port,
  })

The casts aren't tidied away. They stopped being necessary.

The decision

Every value handed between parts of the deploy pipeline now has a type defined by the code that reads it, not by the code that writes it.

Three types where there was one, each named for its one job, each answering to its one reader — and named in the glossary's vocabulary (docs/design/03-domain-model/glossary.md), not new coinage.

Why the casts were there

A single type was the return value of every step:

interface LoweredNode { readonly outputs: Readonly<Record<string, unknown>> }

It was doing three unrelated jobs at once:

What it carried	Written by	Read by	Now
A descriptor's own working values (serviceId, environment, port)	one descriptor	the same descriptor, two steps later	descriptor-owned types, generic as ServiceLowering<P, S>
The Outputs a dependent node's connection params resolve against (url)	a descriptor	core's buildConfig, by param name	Outputs — the glossary's own noun
Anything else anyone needed to move — this is where #101's NodeReport went	anyone	anyone	nothing; reporting has its own types (below)

The first two have nothing to do with each other. The third only became possible because the first two already shared a type that accepts anything.

One type serving three jobs can only be as specific as the vaguest of them. So it was Record<string, unknown>, and every reader cast.

What the casts were hiding

serviceId was never a string.

Alchemy wraps every attribute of a resource in Output<T> — a lazy reference that becomes a real value later, when alchemy applies the plan. So svc.id is Output<string>. The old line said:

computeServiceId: provisioned.outputs['serviceId'] as string

and it compiled — because Prisma.Deployment's prop accepts Input<string>, which is string | Output<string> | …. It accepts the truth and the lie equally, so nothing ever complained.

Nobody wrote that cast dishonestly. outputs['serviceId'] reads like ordinary field access. Nothing marked it as the moment someone decided an unknown was a string, and no reviewer was ever asked to agree.

I made the same mistake writing the plan for this PR: I read the cast, believed it, and specified serviceId: string. The compiler refused it on first contact. Typing the value honestly is what deletes the cast — specifying string would have forced it straight back.

So the point isn't "untyped bags are bad"

That conclusion is tempting, and this PR disproves it with its own code. One blindCast survives, in the same file. It claims an Output<string> out of a value core hands over as unknown, and we are keeping it.

The difference isn't whether an unchecked claim exists. It's whether anyone was asked to agree with it:

• That surviving cast is one site, carrying a written justification, findable by grep. A reviewer can weigh it and say no.
• The old shared type let the same kind of claim be made anonymously, at every place anyone read it, with nothing recording that a claim was being made at all.

ADR-0033 records that, and the rule it implies: where the compiler can't reach — across the boundary into an extension — a precise claim needs a runtime check instead (isCloudApplication), and where nothing needs to claim anything, unknown is the honest type. That last one explains why the bug could only ever have been where it was: warm.url and creds.accessKeyId are also unresolved Output<string>s, but they travel as unknown-valued Outputs and never claimed otherwise.

Two things this made possible

1. A deploy now fails when a producer doesn't supply what its consumer asked for

Once the values a dependent consumes have a contract of their own — the consumer's declared connection params — you can check it.

Before, a missing value became undefined, was written into the consuming service's environment, and broke at boot, far from the mistake. Now:

LowerError: Connection input "auth.main" declares param "url", but its producer
"data" did not supply it — the producer's outputs carry [nothing]. Add "url" to
the outputs the producer returns from its lowering, or declare the param
optional on the connection.

This is a behaviour change: an app that deployed yesterday can fail today, without its author changing a line. That's deliberate. The mistake was always there; it now reports itself where it was made, before anything is provisioned. It's reachable only if you wrote the connection or the extension on one side of the wire — every block shipped with the framework supplies what it declares.

No first-party pair under-delivers. That's measured, not assumed: deliberately breaking the real postgres descriptor turns three end-to-end tests red, so we know the check reaches real code.

2. A deploy now tells you what it built

Reporting was the third job the old type was doing badly. With it gone, results have their own types — the map from Composer entities to Deployment entities: DeploymentResult is the result of the Deploy operation ({app, nodes}), each DeployedNode pairs a graph node with the DeployedEntitys it became (kind, platform id, url only when the descriptor says the address is public).

Proven live, both cases. A fresh deploy printed:

spi-render-proof
├─ auth
│  ├─ database   postgres-database db_cmrp02nz60gui1adzqrexwri0
│  └─ service    compute-service cps_yylkilyzn6h1lnrf2ffmeigk
│                https://yylkilyzn6h1lnrf2ffmeigk.ewr.prisma.build
└─ storefront    compute-service cps_vxadcvnbcmlj0pmk2j1dng66
                 https://vxadcvnbcmlj0pmk2j1dng66.ewr.prisma.build

and an unchanged redeploy — Plan: 17 to noop, Done: 0 succeeded — still printed the same tree (that's what the report's nonce exists for). No JSON blob in either run. The printed database id was then fetched directly (GET /databases/db_cmrp02… → 200, named auth.database), so the ids are real platform objects, not plausible strings. The live run also caught a docs error nothing else could: the sample trees had an invented pdb_ id prefix; the real one is db_. Deployed resources were torn down after (service first, then project; workspace back to its prior state).

The database reports its id and no URL — a connection string is not a public endpoint. The credentials resource reports nothing at all. Core can't infer any of this: postgres's own Outputs have a url key meaning the exact opposite of compute's. The descriptor names what's publishable; LoweredResult.entities is required, so "this node became no Deployment entities" must be said out loud ([]), never by omission.

The renderer runs inside the deploy child process, which already holds both your graph and the results — so there's no transport to build. It rides an alchemy Action, which runs during apply with real resolved values.

Verification

typecheck 58/58 · test 48/48 · lint clean · lint:deps clean · casts 32 → 30 · website content 9/9.

Two checks were found not checking, both by deliberately breaking something to see if they'd notice:

• lint:deps was passing blind for new public files. A deliberate layering violation sailed through. architecture.config.json lists public source files one by one, so a new file matches nothing and no rule applies to it; separately, an unlisted path made the import unresolvable. Fixed for the new file — the mechanism fix is filed separately, because new public files are unguarded by default and that's bigger than this PR.
• A pnpm lint failure was reported as a pass, because the command only printed on success and silence got read as success. Caught in review.

Every alchemy citation in the ADR was derived against the installed source (2.0.0-beta.59) and then independently re-verified; several line numbers in our working notes had drifted.

What we're deliberately not doing

• Per-node success/failure diagnostics. lower() is orDie — one failure kills the run, so a per-node ok would read true on everything that exists. Making it real means collect-and-continue, which is a deploy-semantics decision, not a reporting one.
• Per-resource created/updated/noop. Alchemy publishes that only to its own CLI event stream, not to programs.
• A --json output for CI. That needs a real cross-process transport; nothing needs it yet.
• Refreshing core-model.md's wider model, which is stale beyond this PR's reach. Filed separately rather than bundled into a code review.

Alternatives considered

• NodeReport on the shared type (#101). The original attempt, and the reason this PR exists. It hung an untyped reporting field on the type dependents read for their config — a fourth job for a type already failing at three.
• A separate describe() hook for descriptors to report what they built. Buys nothing: the alchemy resources live inside deploy()'s effect, so describe() would need them handed back out, which is just returning them with extra plumbing.
• Sending results to the CLI parent process — by parsing stdout, writing a JSON file, or reading them back out of the state store. All rejected once it became clear the child process already holds both the graph and the results. The state-store version was the worst of the three: it let a storage concern dictate the shape of an in-memory return value.
• Making the whole result the stack's return value. Alchemy persists whatever a stack returns, so this would have forced our types to be JSON-serializable, and graph nodes carry functions and schemas. Only plain data crosses; the join back to nodes happens on our side.
• Leaving entities optional. Raised in review and rejected: it let a descriptor claim "I built nothing" by staying silent — the same anonymous claim this PR exists to remove.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@117

npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@117

commit: 6d13738