feat(prisma): object storage (resources + bindings), locked Postgres state backend, Deployment.redeployOn

[wmadden]

This PR completes three gaps in the Prisma provider that show up the moment a real framework embeds it. After it, this works:

// api.ts — the app entrypoint. `main: import.meta.filename` bundles this
// file, so the Compute is its default export.
import * as Prisma from "alchemy/Prisma";
import * as Effect from "effect/Effect";

export const project = Prisma.Project("app", {});

// Object storage: the last deferred Management API surface —
// resources *and* bindings.
export const media = Prisma.Bucket("media", { project });

export default Prisma.Compute(
  "Api",
  { project, appName: "api", main: import.meta.filename, port: 8080 },
  Effect.gen(function* () {
    // Binding a bucket auto-creates a scoped BucketKey and wires
    // endpoint + credentials into this host's environment.
    const bucket = yield* Prisma.ReadWriteBucket(media);
    return {
      fetch: Effect.gen(function* () {
        const logo = yield* bucket.get("logo.svg");
        // …
      }),
    };
  }).pipe(Effect.provide(Prisma.ReadWriteBucketBinding)),
);

// stack.ts
import * as Alchemy from "alchemy";
import * as Prisma from "alchemy/Prisma";
import { postgresState } from "alchemy/State/PostgresState";
import * as Config from "effect/Config";
import * as Effect from "effect/Effect";
import Api from "./api.ts";

export default Alchemy.Stack(
  "Media",
  {
    providers: Prisma.providers(),
    // Durable, *locked* state — what Compute's own docs ask for.
    state: postgresState({ url: Config.redacted("STATE_DATABASE_URL") }),
  },
  Effect.gen(function* () {
    const api = yield* Api;
    return { url: api.url };
  }),
);

The three ship together because they're the set a production embedder needs at once — we (Prisma Composer, the framework layer over Prisma Cloud) are deleting our own resource implementations in favor of this provider, and these were the things we couldn't do with it. Say the word and we'll split any of them out.

1. Object storage: resources + bindings

Covers the 7 previously deferred /v1/buckets routes (deferredRoutes is now empty in the contract fixture; coverage 71 → 78), with both halves of the equation:

Resources. Bucket (read-then-create reconcile, replace on identity change, identity-verified delete, real list for nuke) and BucketKey. The key secret is reveal-once — the API never returns it after create, so persisted state is authoritative (the Connection pattern). Keys are created under a deterministic instanceId-derived physical name and looked up before create, so a crash between the create call and the state write cannot mint a second, unenumerable credential — the orphan from the lost response is found by name and revoked before a fresh key is created.

Bindings. ReadBucket / WriteBucket / ReadWriteBucket, following the R2 capability shape: binding a bucket auto-creates a BucketKey for that (bucket, capability) — read-scoped for ReadBucket; the API has no write-only role, so write bindings carry read_write (documented) — and carries endpoint/bucket/credentials into the host environment on Connect's env-naming contract. Host dispatch matches ConnectBinding: env for Prisma Compute and Lambda, worker bindings for Cloudflare Workers. The runtime client reuses the distilled S3 machinery with an endpoint override (Prisma object storage is S3-compatible SigV4); get/head/put/delete/list plus presigned get/put. The credential-provisioning half is a separable function boundary (à la makeHttpBucketBinding), so embedders can reuse provisioning + env naming without the Effect runtime client.

Docs: prisma/data/buckets page + sidebar entry; the three bindings carry @binding reference docs.

2. Dual-registered dev mode

Per review: providers() takes no options; every resource registers its live and dev implementations via ProviderLayer.dual (#963), with the dev stubs moved in-module (Internal/DevStub.ts). The engine picks by run mode, Alchemy.remote() works per-resource, and an embedder that wants different behavior constructs its own layer from the per-resource exports. Defaults unchanged.

3. A locked state backend: State/PostgresState

Compute's recovery docs tell users to "use a durable, locked state backend" — and no in-tree backend has locking. This adds one on the dependency the repo already carries (pg):

• per-(stack, stage) session advisory lock (pg_try_advisory_lock(hashtextextended(key, 0))) held on a reserved connection, with the holder re-verified against pg_locks from a different pool connection — so a silently dropped lock connection is detected, not trusted;
• a TTL-amortized lease check wrapping every operation; stage-less deleteStack locks each stage before touching it;
• schema migration under a transaction-scoped advisory lock, because concurrent create table if not exists genuinely fails on Postgres (duplicate pg_type errors — reproduced on PG 15).

Deliberately not re-exported from the State barrel (the barrel is bundled for workers; pg must stay off that graph — a comment says so). Deep import: alchemy/State/PostgresState. Tests are hermetic stubs per the existing backend convention; the two real-Postgres behaviors verified live during development are documented in comments.

4. Deployment.redeployOn

Prisma Cloud snapshots env vars into a deployment at create, and the low-level Deployment reuses the running deployment unless the artifact moves — so an env-value-only change (a rotated secret) updates the platform row but never reaches the running app. redeployOn takes any serializable inputs; their resolved values are salted-hashed into a new redeployHash attribute stored Redacted (no plaintext in state), and a changed hash plans a replace — the low-level counterpart of what Compute already does with its env fingerprint. Old rows lack the field and never replace on upgrade.

5. One-line core fix: Aliases typing

ResourceClass.Aliases is readonly string[] | undefined, but ResourceClassLike.Aliases?: readonly string[] — under a consumer tsconfig with exactOptionalPropertyTypes: true, every Provider.effect(cls, …) call fails to typecheck (we carry a pnpm patch for this today). The fix widens the optional to | undefined.

Verification

• bun run format:check clean; bun tsc -b (monorepo) clean.
• The bucket binding suite deploys a real stack per review: fixtures/ holds three Compute apps binding one shared bucket (read / write / read-write), the tests drive every client operation over HttpClient through the deployed apps — including presigned PUT/GET fetched by the test with no credentials of its own — with beforeAll(deploy) / afterAll(destroy). A cold full cycle (create → exercise → destroy, 8 resources) runs green against Prisma Cloud. Live runs are guarded by ALCHEMY_RUN_LIVE_PRISMA_TESTS + credentials, matching Compute.live.test.ts; without credentials the suite skips cleanly and the pure derivation tests still run.
• The live suite immediately caught a bug the stubbed suite structurally could not: the bucket secret's Redacted wrapper does not survive host env delivery (env rows carry plain strings), so the signer failed on every bucket operation in a deployed app. Fixed by rebuilding the wrapper at the runtime read, the same shape as Connect's accessors.
• bun alchemy-test --fast test/Prisma test/State: 0 failed; core engine suites (exercising the Resource.ts change) green.
• generate-api-reference: Prisma gains Bucket/BucketKey and the three binding pages; no new category; docs:check builds clean.

Alternatives considered

• Splitting into separate PRs. Offered above — kept together because they're one consumer's complete need and the review context overlaps (BucketKey's crash-window design references Connection's; the bindings provision through the resources).
• Per-operation bindings (the AWS S3 shape). R2's capability shape fits better: Prisma has one transport and coarse key roles, so ~30 per-op bindings would grant identical credentials with more surface. The capability clients still expose typed per-operation methods.
• Exporting postgresState from the State barrel. Poisons worker bundles with pg; deep import + comment instead.
• A migration-free schema bootstrap (plain create table if not exists). Fails under concurrency on real Postgres; see above.

[sam-goodwin]

Can you share sample of DX in PR description

[wmadden]

@sam-goodwin I rewrote the PR description - does the example there suffice?

[sam-goodwin]

This isn't something we typically do. Take a look at Provider.dual that we set up in #963

The user shouldn't provide them. If they want to override them, they can construct a new layer.

[wmadden]

OK, on it

[wmadden]

Done in 5c2a64b.

All resources now register via ProviderLayer.dual with their local stubs moved into the module. Shared helpers are in Internal/DevStub.ts.

Removed providers({dev}), PrismaLocalProviders, and liveProviders(). providers() is back to just the collection.

[wmadden]

Hey @sam-goodwin, I added one more fix for an issue already present: changing an environment variable's value never reached a running deployment. Prisma Cloud snapshots env vars into the deployment at create, and Deployment only replaces when its own props (artifact/port/app) change, so a value-only change updated the platform row but the app kept serving the old value.

I fixed this by adding an optional redeployOn prop to Deployment: pass it whatever inputs should force a redeploy (e.g. env values), and a change replaces the deployment.

The resolved values are salted-hashed and stored Redacted, so no plaintext lands in state.

[sam-goodwin]

Please use effect SQL instead of the async api

[sam-goodwin]

Use Data.TaggedError?

[wmadden]

done

[sam-goodwin]

Interesting. We'll also need to add bindings like we have in src/AWS/S3

Each API gets a binding and will automatically create the BucketKey resource and bind that to the environment.

For reference:

1. look in src/AWS/S3 and see how each operation (e.g. GetObject.ts) has a Binding.Service and a corresponding layer GetObjectHttp.ts.
2. look in src/Cloudflare/R2/ReadBucketHttp.ts - see how it creates an Account Api Token and binds granular policies to it.

Right now, your PR only considers the non-effectful DX. Every resource needs effectful bindings for interacting with it.

[wmadden]

I've added the bindings: ReadBucket / WriteBucket / ReadWriteBucket, following the R2 shape — binding a bucket auto-creates the BucketKey (read-scoped for reads; the API has no write-only role, so write bindings carry read_write), env round-trip follows Connect's naming contract, and the runtime client reuses the S3 machinery with an endpoint override. Get/put presign included.

Overall ~1.8k lines including tests. I debated extracting object storage to a separate PR — the bindings are the latest two commits, but I have a clean split prepared if you'd prefer it: #1061 would then deliver the state backend, the Aliases fix, dual registration and redeployOn, with buckets + bindings as the follow-up.

Also merged main — the pg optional-peer change (#1069) is honored: PostgresState now lazy-loads the driver with the same install-hint the other drivers use.

[sam-goodwin]

Don't stub. Deploy a real stack (in fixtures/) that deploys an actual app and then have the tests execute request with HttpClient

[sam-goodwin]

see how we use beforeAll and afterAll in other tests

[wmadden]

done

[wmadden]

you were right about the stubs. When I rewrote the tests against the real endpoints I found some errors that would only have surfaced when users ran it in production

I also realized I haven't been following the instructions in the repo or established conventions. I educated myself, gave my agent a kick in the pants and corrected my implementation and tests. there should be no novel decisions in my PR any more

BucketBinding.test.ts now follows the R2 Binding.test.ts shape: a fixtures/ stack deploying three Compute apps binding one shared bucket, beforeAll(deploy) / afterAll(destroy), every client method incl. presigned URLs driven over HttpClient. live runs are opt-in like Compute.live.test.ts; a cold create/exercise/destroy cycle runs green against real Prisma Cloud

and the description now shows the two-file export default shape from Compute's JSDoc