@prisma/composer-prisma-cloud 0.1.0-dev.16 → 0.1.0-dev.18

package/dist/control.d.mts

@@ -2,44 +2,19 @@ import { t as ProviderParamEntry } from "./serializer-Cx5slrV4-xJfH6EWS.mjs";
 import { createManagementApiClient } from "@prisma/management-api-sdk";
 import "effect/Context";
 import "effect/Effect";
-import * as Layer from "effect/Layer";
+import "effect/Layer";
 import "effect/Redacted";
 import "effect/Config";
 import "alchemy/Provider";
-import { Resource, StackServices } from "alchemy";
+import { Resource } from "alchemy";
 import "effect/Schedule";
-import postgres from "postgres";
-import { State, StateStoreError } from "alchemy/State";
 import * as Output from "alchemy/Output";
-import { ExtensionDescriptor } from "@prisma/composer/config";
+import { ExtensionDescriptor, StateDescriptor } from "@prisma/composer/config";
 //#region ../../1-prisma-cloud/0-lowering/lowering/dist/compute.d.mts
 /** Every region Prisma Compute serves — the runtime source of truth; `ComputeRegion` is derived from it so the two can never drift. */
 declare const COMPUTE_REGIONS: readonly ["us-east-1", "us-west-1", "eu-west-3", "eu-central-1", "ap-northeast-1", "ap-southeast-1"];
 type ComputeRegion = (typeof COMPUTE_REGIONS)[number];
 //#endregion
-//#region ../../1-prisma-cloud/0-lowering/lowering/dist/state.d.mts
-//#endregion
-//#region src/state/layer.d.ts
-/**
- * The hosted Alchemy state store. On layer init (scoped, once per stack
- * run): resolve the stage's Branch, find-or-create its `prisma-composer-state`
- * database, create a fresh connection, migrate the schema, and acquire the
- * (stack, stage) advisory lock — see `bootstrap.ts` and `lock.ts`. The
- * Management API plumbing (`ManagementClient`, `PrismaCredentials`) is
- * provided internally, so the returned layer's only requirements are the
- * ones alchemy itself already provides to every state store
- * (`StackServices`).
- *
- * Any bootstrap/lock/migration failure is wrapped into an operator-facing
- * `HostedStateBootstrapError` (naming the Project/Branch and the step that
- * failed, never the raw driver/API error — see `errors.ts`) before dying the
- * layer (loud, immediate, unrecoverable) rather than surfacing as a typed
- * error — matching core's `LowerOptions.state: Layer.Layer<State, never,
- * StackServices>` contract and alchemy's own convention (e.g. a missing
- * state store is `Effect.die` in `Stack.make`).
- */
-declare const prismaState: () => Layer.Layer<State, never, StackServices>;
-//#endregion
 //#region ../../1-prisma-cloud/1-extensions/target/dist/control.d.mts
 //#region src/descriptors/shared.d.ts
 /**
@@ -69,6 +44,8 @@ interface ProviderParam extends ProviderParamEntry {
 }
 //#endregion
 //#region src/control/extension.d.ts
+/** The user-facing state descriptor: `state: prismaState()` in `prisma-composer.config.ts` (ADR-0017). */
+declare const prismaState: () => StateDescriptor;
 interface PrismaCloudOptions {
   /** Defaults to the PRISMA_WORKSPACE_ID environment variable. */
   workspaceId?: string;

package/dist/control.mjs

@@ -622,7 +622,107 @@ const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 		})
 	};
 }));
-Data.TaggedError("ContainerNotFoundError");
+//#endregion
+//#region ../../1-prisma-cloud/0-lowering/lowering/dist/index.mjs
+/** Raised with `ensure: false` when the app's Project (or a named stage's Branch) doesn't exist. */
+var ContainerNotFoundError = class extends Data.TaggedError("ContainerNotFoundError") {};
+const listAllProjects = (client) => Effect.gen(function* () {
+	const projects = [];
+	let cursor;
+	for (;;) {
+		const query = cursor === void 0 ? {} : { cursor };
+		const page = yield* call(() => client.GET("/v1/projects", { params: { query } }));
+		projects.push(...page.data);
+		if (!page.pagination.hasMore || page.pagination.nextCursor === null) break;
+		cursor = page.pagination.nextCursor;
+	}
+	return projects;
+});
+/**
+* Workspace ids circulate in two shapes: `wksp_`-prefixed and bare. Compare
+* bare-to-bare so a `wksp_`-prefixed API id still matches a bare configured
+* one (the same normalization `state/bootstrap.ts` applies to the same
+* `/v1/projects` listing).
+*/
+const bareWorkspaceId = (id) => id.startsWith("wksp_") ? id.slice(5) : id;
+/**
+* Finds the app's Project by name in the workspace — PDP allows duplicate
+* project names, so more than one can match; the oldest wins. Creates one
+* if none match, unless `ensure` is `false` (find-only — `destroy`), in
+* which case an absent Project fails with `ContainerNotFoundError`. No
+* ownership marker and no `--project` override (both deferred — see
+* ADR-0019).
+*/
+const resolveProject = (client, workspaceId, appName, ensure) => Effect.gen(function* () {
+	const oldest = (yield* listAllProjects(client)).filter((p) => bareWorkspaceId(p.workspace.id) === bareWorkspaceId(workspaceId) && p.name === appName).sort((a, b) => a.createdAt.localeCompare(b.createdAt))[0];
+	if (oldest !== void 0) return oldest.id;
+	if (!ensure) return yield* Effect.fail(new ContainerNotFoundError({ appName }));
+	return (yield* call(() => client.POST("/v1/projects", { body: {
+		name: appName,
+		workspaceId
+	} }))).data.id;
+});
+const findBranchId = (client, projectId, gitName) => call(() => client.GET("/v1/projects/{projectId}/branches", { params: {
+	path: { projectId },
+	query: { gitName }
+} })).pipe(Effect.map((page) => page.data[0]?.id));
+/**
+* Finds the stage's Branch by its exact `gitName`, creating it if absent
+* unless `ensure` is `false` (find-only — `destroy`), in which case an
+* absent Branch fails with `ContainerNotFoundError`. The Management API has
+* no server-side "create-or-return" idempotency (`POST
+* /v1/projects/:id/branches` 409s on a duplicate `gitName`, with no request
+* field to make that a no-op), so idempotency is client-side: observe
+* first, and on a racing 409 from create, re-observe rather than fail.
+*/
+const resolveBranch = (client, projectId, gitName, appName, ensure) => Effect.gen(function* () {
+	const existing = yield* findBranchId(client, projectId, gitName);
+	if (existing !== void 0) return existing;
+	if (!ensure) return yield* Effect.fail(new ContainerNotFoundError({
+		appName,
+		stage: gitName
+	}));
+	return yield* call(() => client.POST("/v1/projects/{projectId}/branches", {
+		params: { path: { projectId } },
+		body: { gitName }
+	})).pipe(Effect.map((r) => r.data.id), Effect.catch((err) => err.status === 409 ? findBranchId(client, projectId, gitName).pipe(Effect.flatMap((id) => id === void 0 ? Effect.fail(err) : Effect.succeed(id))) : Effect.fail(err)));
+});
+/**
+* Resolves the two containers a stage's deploy runs into (ADR-0019): the
+* app's **Project**, found-or-created by name, and — for a named stage
+* only — its **Branch**, found-or-created by `gitName`. The default stage
+* (no `stage`) creates no Branch; `branchId` is omitted. With `ensure:
+* false` (`destroy`), nothing is created — an absent Project or Branch
+* fails with `ContainerNotFoundError` instead.
+*/
+const resolveContainer = (opts) => Effect.gen(function* () {
+	const client = yield* ManagementClient;
+	const ensure = opts.ensure ?? true;
+	const projectId = yield* resolveProject(client, opts.workspaceId, opts.appName, ensure);
+	if (opts.stage === void 0) return { projectId };
+	return {
+		projectId,
+		branchId: yield* resolveBranch(client, projectId, opts.stage, opts.appName, ensure)
+	};
+});
+/**
+* Soft-deletes a Branch. Tolerates a 404 (already gone). The API refuses if
+* the Branch still has live members or is the production/default Branch —
+* that surfaces as a `PrismaApiError`.
+*/
+const deleteBranch = (branchId) => Effect.gen(function* () {
+	const client = yield* ManagementClient;
+	yield* callVoid(() => client.DELETE("/v1/branches/{branchId}", { params: { path: { branchId } } }));
+});
+/**
+* Deletes a Project. Tolerates a 404 (already gone). The API refuses with a
+* 400 if the Project still has live dependencies (e.g. another stage's
+* Branch/resources) — that surfaces as a `PrismaApiError`.
+*/
+const deleteProject = (projectId) => Effect.gen(function* () {
+	const client = yield* ManagementClient;
+	yield* callVoid(() => client.DELETE("/v1/projects/{id}", { params: { path: { id: projectId } } }));
+});
 /** The collection of Prisma resource providers. */
 var Providers = class extends Provider.ProviderCollection()("Prisma") {};
 /**
@@ -1280,11 +1380,8 @@ const guardStateService = (service, checkLive, now = Date.now) => {
 * StackServices>` contract and alchemy's own convention (e.g. a missing
 * state store is `Effect.die` in `Stack.make`).
 */
-const prismaState = () => {
-	const projectId = process.env["PRISMA_PROJECT_ID"];
-	if (projectId === void 0 || projectId.length === 0) throw new Error("prismaState(): environment variable PRISMA_PROJECT_ID is required (the CLI sets it — deploy via `prisma-composer deploy`).");
-	const branchIdEnv = process.env["PRISMA_BRANCH_ID"];
-	const branchId = branchIdEnv === void 0 || branchIdEnv.length === 0 ? void 0 : branchIdEnv;
+const prismaStateLayer = (ids) => {
+	const { projectId, branchId } = ids;
 	return Layer.effect(State, Effect.gen(function* () {
 		const stack = yield* Stack;
 		const container = branchId === void 0 ? projectId : `${projectId}/${branchId}`;
@@ -1307,18 +1404,181 @@ const prismaState = () => {
 };
 //#endregion
 //#region ../../1-prisma-cloud/1-extensions/target/dist/control.mjs
+const PRISMA_CLOUD_EXTENSION_ID = "@prisma/composer-prisma-cloud";
+var PrismaCloudContainer = class {
+	input;
+	projectId;
+	branchId;
+	constructor(input, projectId, branchId) {
+		this.input = input;
+		this.projectId = projectId;
+		this.branchId = branchId;
+	}
+	serialize() {
+		return JSON.stringify({
+			input: this.input,
+			projectId: this.projectId,
+			...this.branchId !== void 0 ? { branchId: this.branchId } : {}
+		});
+	}
+};
+/** `instanceof` — parent-side instances and child-side deserialized instances are both constructed by this module. */
+function isPrismaCloudContainer(value) {
+	return value instanceof PrismaCloudContainer;
+}
+/** Narrow-or-throw for hook inputs. */
+function prismaCloudContainerOf(value) {
+	if (!isPrismaCloudContainer(value)) throw new Error("the Prisma Cloud container was not resolved — the extension's container descriptor did not run.");
+	return value;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function invalidPayloadError(reason) {
+	return /* @__PURE__ */ new Error(`${PRISMA_CLOUD_EXTENSION_ID}: invalid container transport payload — ${reason}.`);
+}
+/** Reconstructs a `PrismaCloudContainer` from `serialize()`'s JSON output — real narrowing, no casts. */
+function deserialize(serialized) {
+	let parsed;
+	try {
+		parsed = JSON.parse(serialized);
+	} catch (error) {
+		throw invalidPayloadError(`not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+	}
+	if (!isRecord(parsed)) throw invalidPayloadError("not an object");
+	const input = parsed["input"];
+	if (!isRecord(input)) throw invalidPayloadError("\"input\" is not an object");
+	const appName = input["appName"];
+	if (typeof appName !== "string") throw invalidPayloadError("\"input.appName\" is not a string");
+	const stage = input["stage"];
+	if (stage !== void 0 && typeof stage !== "string") throw invalidPayloadError("\"input.stage\" is not a string or absent");
+	const projectId = parsed["projectId"];
+	if (typeof projectId !== "string") throw invalidPayloadError("\"projectId\" is not a string");
+	const branchId = parsed["branchId"];
+	if (branchId !== void 0 && typeof branchId !== "string") throw invalidPayloadError("\"branchId\" is not a string or absent");
+	return new PrismaCloudContainer({
+		appName,
+		stage
+	}, projectId, branchId);
+}
+const workspaceRequiredError = () => /* @__PURE__ */ new Error("environment variable PRISMA_WORKSPACE_ID is required.");
+const tokenRequiredError$2 = () => /* @__PURE__ */ new Error("environment variable PRISMA_SERVICE_TOKEN is required.");
+function requireWorkspaceId() {
+	const workspaceId = process.env["PRISMA_WORKSPACE_ID"];
+	if (workspaceId === void 0 || workspaceId.length === 0) throw workspaceRequiredError();
+	return workspaceId;
+}
+function requireTokenUnlessInjected(deps) {
+	if (deps?.client === void 0 && (process.env["PRISMA_SERVICE_TOKEN"] ?? "").length === 0) throw tokenRequiredError$2();
+}
+async function ensureContainer(input, deps) {
+	const workspaceId = requireWorkspaceId();
+	requireTokenUnlessInjected(deps);
+	const program = resolveContainer({
+		workspaceId,
+		appName: input.appName,
+		...input.stage !== void 0 ? { stage: input.stage } : {},
+		ensure: true
+	}).pipe(Effect.map((c) => ({
+		ok: true,
+		container: c
+	})), Effect.catchTag("PrismaApiError", (e) => Effect.succeed({
+		ok: false,
+		message: `Prisma Management API error resolving containers: ${e.message}.`
+	})));
+	const provided = deps?.client !== void 0 ? program.pipe(Effect.provideService(ManagementClient, deps.client)) : program.pipe(Effect.provide(layer().pipe(Layer.provide(fromEnv()))));
+	const outcome = await Effect.runPromise(provided);
+	if (!outcome.ok) throw new Error(outcome.message);
+	return new PrismaCloudContainer(input, outcome.container.projectId, outcome.container.branchId);
+}
+async function locateContainer(input, deps) {
+	const workspaceId = requireWorkspaceId();
+	requireTokenUnlessInjected(deps);
+	const program = resolveContainer({
+		workspaceId,
+		appName: input.appName,
+		...input.stage !== void 0 ? { stage: input.stage } : {},
+		ensure: false
+	}).pipe(Effect.map((c) => ({
+		ok: true,
+		container: c
+	})), Effect.catchTag("ContainerNotFoundError", () => Effect.succeed({ ok: false })), Effect.catchTag("PrismaApiError", (e) => Effect.fail(/* @__PURE__ */ new Error(`Prisma Management API error resolving containers: ${e.message}.`))));
+	const provided = deps?.client !== void 0 ? program.pipe(Effect.provideService(ManagementClient, deps.client)) : program.pipe(Effect.provide(layer().pipe(Layer.provide(fromEnv()))));
+	const outcome = await Effect.runPromise(provided);
+	if (!outcome.ok) return void 0;
+	return new PrismaCloudContainer(input, outcome.container.projectId, outcome.container.branchId);
+}
+/**
+* Soft-deletes a named stage's Branch after a successful `alchemy destroy`
+* has removed its members — the Management API refuses to delete a Branch
+* that still has live members.
+*/
+async function removeStageBranch(branchId, deps) {
+	requireTokenUnlessInjected(deps);
+	const program = deleteBranch(branchId).pipe(Effect.map(() => ({ ok: true })), Effect.catchTag("PrismaApiError", (e) => Effect.succeed({
+		ok: false,
+		message: `Failed to delete the stage Branch: ${e.message}.`
+	})));
+	const provided = deps?.client !== void 0 ? program.pipe(Effect.provideService(ManagementClient, deps.client)) : program.pipe(Effect.provide(layer().pipe(Layer.provide(fromEnv()))));
+	const outcome = await Effect.runPromise(provided);
+	if (!outcome.ok) throw new Error(outcome.message);
+}
+/**
+* Best-effort cleanup after a successful `--production` destroy: removes
+* the app's Project so hand-run stacks don't accumulate as empty Projects
+* (they eventually hit the workspace's plan limit). Unlike `removeStageBranch`,
+* this never throws: the destroy itself already succeeded, and the API's own
+* 400 ("still has dependencies") is the only check that matters — failing
+* the command over a cleanup step would be worse than leaving a Project shell.
+*/
+async function removeAppProject(projectId, deps) {
+	if (deps?.client === void 0 && (process.env["PRISMA_SERVICE_TOKEN"] ?? "").length === 0) {
+		console.warn(`Skipped removing the Project (${projectId}): PRISMA_SERVICE_TOKEN is not set.`);
+		return;
+	}
+	const program = deleteProject(projectId).pipe(Effect.map(() => ({ ok: true })), Effect.catchTag("PrismaApiError", (e) => Effect.succeed({
+		ok: false,
+		error: e
+	})));
+	const provided = deps?.client !== void 0 ? program.pipe(Effect.provideService(ManagementClient, deps.client)) : program.pipe(Effect.provide(layer().pipe(Layer.provide(fromEnv()))));
+	const outcome = await Effect.runPromise(provided);
+	if (outcome.ok) {
+		console.log(`Removed the Project (${projectId}) — nothing was left in it.`);
+		return;
+	}
+	if (outcome.error.status === 400) {
+		console.log(`Kept the Project (${projectId}) — it still has another stage's resources.`);
+		return;
+	}
+	console.warn(`Could not remove the Project (${projectId}) after destroy: ${outcome.error.message}.`);
+}
+function containerDescriptor(deps) {
+	return {
+		ensure: (input) => ensureContainer(input, deps),
+		locate: (input) => locateContainer(input, deps),
+		remove: (instance) => instance.input.stage !== void 0 ? removeStageBranch(instance.branchId ?? missingBranchId(instance), deps) : removeAppProject(instance.projectId, deps),
+		deserialize
+	};
+}
+/** Defensive: a named-stage container always resolves a Branch together with its stage — `ensure`/`locate`/`deserialize` never produce one without the other. */
+function missingBranchId(instance) {
+	throw new Error(`${PRISMA_CLOUD_EXTENSION_ID}: a named-stage ("${instance.input.stage}") container instance is missing its branchId — this is a bug in ensure/locate/deserialize.`);
+}
 const PRISMA_NAME_MIN = 3;
 const PRISMA_NAME_MAX = 65;
 function validateName(value, source) {
 	if (value.length < PRISMA_NAME_MIN || value.length > PRISMA_NAME_MAX) throw new Error(`prisma-cloud: ${source} "${value}" (${value.length} characters) is not a valid Prisma resource name — Prisma requires ${PRISMA_NAME_MIN}–${PRISMA_NAME_MAX} characters. Rename the provision id (or the deploy --name) to fit.`);
 }
 function isCloudApplication(value) {
-	return typeof value === "object" && value !== null && "projectId" in value && typeof value.projectId === "string";
+	return typeof value === "object" && value !== null && "projectId" in value && typeof value.projectId === "string" && "branchId" in value && (value.branchId === void 0 || typeof value.branchId === "string");
 }
 /** Narrows `ctx.application`, which core hands over as `unknown`, to this extension's own product; throws naming the hook when it hasn't run. */
-function projectIdOf(application) {
+function cloudApplicationOf(application) {
 	if (!isCloudApplication(application)) throw new Error("prisma-cloud: ctx.application is not this extension's application product — the prismaCloud() application hook must run before any node lowers.");
-	return application.projectId;
+	return application;
+}
+function projectIdOf(application) {
+	return cloudApplicationOf(application).projectId;
 }
 /**
 * One Bucket per module-provisioned bucket resource — `id` is the module
@@ -1327,13 +1587,14 @@ function projectIdOf(application) {
 * carrier, and its attributes (endpoint, bucketName, accessKeyId,
 * secretAccessKey) become the four S3Config outputs consumers resolve by name.
 */
-function bucketDescriptor(o) {
+function bucketDescriptor(_o) {
 	const lowering = ({ id, application }) => Effect.gen(function* () {
 		validateName(id, "resource name (from provision id)");
+		const branchId = cloudApplicationOf(application).branchId;
 		const bkt = yield* Bucket(`${id}-bucket`, {
 			projectId: projectIdOf(application),
 			name: id,
-			...o.branchId !== void 0 ? { branchId: o.branchId } : {}
+			...branchId !== void 0 ? { branchId } : {}
 		});
 		const key = yield* BucketKey(`${id}-key`, {
 			bucketId: bkt.id,
@@ -1369,20 +1630,22 @@ function computeDescriptor(o) {
 		provision: ({ id, application }) => Effect.gen(function* () {
 			validateName(id, "service name (from provision id)");
 			const projectId = projectIdOf(application);
+			const branchId = cloudApplicationOf(application).branchId;
 			return {
 				serviceId: (yield* ComputeService(`${id}-svc`, {
 					projectId,
 					name: id,
 					region: o.region ?? "us-east-1",
-					...o.branchId !== void 0 ? { branchId: o.branchId } : {}
+					...branchId !== void 0 ? { branchId } : {}
 				})).id,
 				projectId
 			};
 		}),
 		serialize: (ctx, provisioned, config) => Effect.gen(function* () {
 			const { address, node, graph } = ctx;
-			const cls = o.branchId ? "preview" : "production";
-			const branch = o.branchId !== void 0 ? { branchId: o.branchId } : {};
+			const branchId = cloudApplicationOf(ctx.application).branchId;
+			const cls = branchId ? "preview" : "production";
+			const branch = branchId !== void 0 ? { branchId } : {};
 			const projectId = provisioned.projectId;
 			const svc = node;
 			const records = [];
@@ -1522,11 +1785,12 @@ const PgWarmProvider = () => Provider.effect(PgWarm, Effect.succeed(pgWarmProvid
 function postgresDescriptor(o) {
 	const lowering = ({ id, application }) => Effect.gen(function* () {
 		validateName(id, "resource name (from provision id)");
+		const branchId = cloudApplicationOf(application).branchId;
 		const db = yield* Database(`${id}-db`, {
 			projectId: projectIdOf(application),
 			name: id,
 			region: o.region ?? "us-east-1",
-			...o.branchId !== void 0 ? { branchId: o.branchId } : {}
+			...branchId !== void 0 ? { branchId } : {}
 		});
 		const conn = yield* Connection(`${id}-conn`, {
 			databaseId: db.id,
@@ -1790,11 +2054,12 @@ const PnMigrationProvider = () => Provider.effect(PnMigration, Effect.succeed(pn
 function prismaNextDescriptor(o) {
 	const lowering = ({ id, node, application }) => Effect.gen(function* () {
 		validateName(id, "resource name (from provision id)");
+		const branchId = cloudApplicationOf(application).branchId;
 		const db = yield* Database(`${id}-db`, {
 			projectId: projectIdOf(application),
 			name: id,
 			region: o.region ?? "us-east-1",
-			...o.branchId !== void 0 ? { branchId: o.branchId } : {}
+			...branchId !== void 0 ? { branchId } : {}
 		});
 		const conn = yield* Connection(`${id}-conn`, {
 			databaseId: db.id,
@@ -1931,7 +2196,7 @@ function s3StoreDescriptor(o) {
 *
 * Control-plane only (imported by control.ts → prisma-composer.config.ts); runs
 * in the CLI parent, so it builds its own Management API client from env — the
-* same credential path `ensureContainers` uses.
+* same credential path `container.ts`'s `ensure`/`locate` use.
 */
 /** production for the default stage; preview for a named stage — matching how the pack writes config rows. */
 const classFor = (branchId) => branchId === void 0 ? "production" : "preview";
@@ -1974,21 +2239,21 @@ async function existsOnPlatform(client, projectId, branchId, key) {
 * EnvironmentVariable.ts). A 409 means a concurrent deploy already provisioned
 * it — tolerated. The value is never logged.
 */
-async function fillMissing(client, input, key, value) {
+async function fillMissing(client, projectId, branchId, key, value) {
 	const res = await client.POST("/v1/environment-variables", { body: {
-		projectId: input.projectId,
-		class: classFor(input.branchId),
+		projectId,
+		class: classFor(branchId),
 		key,
 		value,
-		...input.branchId !== void 0 ? { branchId: input.branchId } : {}
+		...branchId !== void 0 ? { branchId } : {}
 	} });
 	if (res.error !== void 0 && res.response.status !== 409) throw fillFailedError(key, res.error);
 }
 const tokenRequiredError$1 = () => /* @__PURE__ */ new Error("environment variable PRISMA_SERVICE_TOKEN is required for deploy preflight.");
 const listFailedError = (key, error) => /* @__PURE__ */ new Error(`deploy preflight: Prisma Management API error listing "${key}": ${JSON.stringify(error)}.`);
 const fillFailedError = (key, error) => /* @__PURE__ */ new Error(`deploy preflight: failed to provision "${key}" from the deploy shell: ${JSON.stringify(error)}.`);
-function missingError(missing, input) {
-	const scope = input.branchId === void 0 ? "the production class (project-level template)" : `the preview class of stage "${input.stage ?? input.branchId}" (branch override or template)`;
+function missingError(missing, branchId, stage) {
+	const scope = branchId === void 0 ? "the production class (project-level template)" : `the preview class of stage "${stage ?? branchId}" (branch override or template)`;
 	const lines = missing.map((m) => `  - ${m.name}  (required by service "${m.serviceAddress}")`);
 	return /* @__PURE__ */ new Error(`Deploy preflight failed — ${missing.length} env var(s) (secret or env-sourced param) are not provisioned on Prisma Cloud for ${scope}, and are absent from the deploy shell:\n${lines.join("\n")}\n\nSet each in the deploy shell environment (the CLI will provision it on deploy), or create it on the platform (Prisma Console or the Management API) in ${scope}.`);
 }
@@ -2007,6 +2272,7 @@ async function managementClient$1() {
 * from env.
 */
 async function runPreflight(input, deps) {
+	const { projectId, branchId } = prismaCloudContainerOf(input.container);
 	const names = /* @__PURE__ */ new Map();
 	for (const binding of provisionManifest(input.graph)) {
 		const name = secretName(binding);
@@ -2027,15 +2293,15 @@ async function runPreflight(input, deps) {
 	const client = deps?.client ?? await managementClient$1();
 	const missing = [];
 	for (const meta of names.values()) {
-		if (await existsOnPlatform(client, input.projectId, input.branchId, meta.name)) continue;
+		if (await existsOnPlatform(client, projectId, branchId, meta.name)) continue;
 		const shellValue = process.env[meta.name];
 		if (shellValue !== void 0 && shellValue.length > 0) {
-			await fillMissing(client, input, meta.name, shellValue);
+			await fillMissing(client, projectId, branchId, meta.name, shellValue);
 			continue;
 		}
 		missing.push(meta);
 	}
-	if (missing.length > 0) throw missingError(missing, input);
+	if (missing.length > 0) throw missingError(missing, branchId, input.stage);
 }
 const tokenRequiredError = () => /* @__PURE__ */ new Error("environment variable PRISMA_SERVICE_TOKEN is required for destroy teardown.");
 async function managementClient() {
@@ -2060,12 +2326,13 @@ async function managementClient() {
 * builds a client from env and verifies against the real database.
 */
 async function runTeardown(input, deps) {
-	const isNamedStage = input.branchId !== void 0;
+	const { projectId, branchId } = prismaCloudContainerOf(input.container);
+	const isNamedStage = branchId !== void 0;
 	try {
 		const client = deps?.client ?? await managementClient();
 		await Effect.runPromise(deleteStateDatabaseWith({
-			projectId: input.projectId,
-			...input.branchId !== void 0 ? { branchId: input.branchId } : {}
+			projectId,
+			...branchId !== void 0 ? { branchId } : {}
 		}, deps?.verify ?? verifyOwnership).pipe(Effect.provideService(ManagementClient, client)));
 	} catch (error) {
 		const reason = error instanceof Error ? error.message : String(error);
@@ -2143,6 +2410,17 @@ const streamsApiKeyValue = (refs) => {
 		return distinct[0] ?? "";
 	});
 };
+/** The user-facing state descriptor: `state: prismaState()` in `prisma-composer.config.ts` (ADR-0017). */
+const prismaState = () => ({
+	extension: PRISMA_CLOUD_EXTENSION_ID,
+	create: (container) => {
+		const { projectId, branchId } = prismaCloudContainerOf(container);
+		return prismaStateLayer(branchId !== void 0 ? {
+			projectId,
+			branchId
+		} : { projectId });
+	}
+});
 const KNOWN_REGION_SET = new Set(COMPUTE_REGIONS);
 function isComputeRegion(value) {
 	return KNOWN_REGION_SET.has(value);
@@ -2198,34 +2476,25 @@ function buildProviderParams(entries, values) {
 const PROVIDER_PARAMS = buildProviderParams(RESERVED_PROVIDER_PARAMS, PROVIDER_PARAM_VALUES);
 /**
 * Resolves the factory's env-or-option inputs, failing fast with the exact
-* variable name. `projectId`/`branchId` aren't required here — `prismaCloud()`
-* also runs in the CLI parent, before they're set; the required check lives in `application.provision`.
+* variable name.
 */
 function resolveOptions(opts) {
 	const workspaceId = opts.workspaceId ?? process.env["PRISMA_WORKSPACE_ID"];
 	if (workspaceId === void 0 || workspaceId.length === 0) throw new Error("prismaCloud(): environment variable PRISMA_WORKSPACE_ID is required.");
-	const projectId = process.env["PRISMA_PROJECT_ID"] || void 0;
-	const branchId = process.env["PRISMA_BRANCH_ID"] || void 0;
 	if (opts.region !== void 0) return {
 		workspaceId,
 		region: opts.region,
-		projectId,
-		branchId,
 		providerParams: PROVIDER_PARAMS
 	};
 	const region = process.env["PRISMA_REGION"];
 	if (region === void 0 || region.length === 0) return {
 		workspaceId,
-		projectId,
-		branchId,
 		providerParams: PROVIDER_PARAMS
 	};
 	if (!isComputeRegion(region)) throw new Error(`prismaCloud(): environment variable PRISMA_REGION="${region}" is not a known region (expected one of: ${COMPUTE_REGIONS.join(", ")}).`);
 	return {
 		workspaceId,
 		region,
-		projectId,
-		branchId,
 		providerParams: PROVIDER_PARAMS
 	};
 }
@@ -2233,21 +2502,24 @@ function resolveOptions(opts) {
 const prismaCloud = (opts = {}) => {
 	const o = resolveOptions(opts);
 	return {
-		id: "@prisma/composer-prisma-cloud",
+		id: PRISMA_CLOUD_EXTENSION_ID,
+		container: containerDescriptor(),
 		providers: () => asProvidersLayer(Layer.mergeAll(providers(), PgWarmProvider(), PnMigrationProvider(), S3CredentialsProvider(), ServiceKeyProvider())),
 		preflight: (input) => runPreflight(input),
 		teardown: (input) => runTeardown(input),
-		application: { provision: () => Effect.gen(function* () {
-			const projectId = o.projectId;
-			if (projectId === void 0 || projectId.length === 0) throw new Error("prismaCloud(): environment variable PRISMA_PROJECT_ID is required (the CLI sets it — deploy via `prisma-composer deploy`).");
+		application: { provision: (ctx) => Effect.gen(function* () {
+			const { projectId, branchId } = prismaCloudContainerOf(ctx.container);
 			for (const key of ["DATABASE_URL", "DATABASE_URL_POOLED"]) yield* EnvironmentVariable(`${key}-poison`, {
 				projectId,
 				key,
 				value: "-",
-				class: o.branchId ? "preview" : "production",
-				...o.branchId !== void 0 ? { branchId: o.branchId } : {}
+				class: branchId ? "preview" : "production",
+				...branchId !== void 0 ? { branchId } : {}
 			});
-			return { projectId };
+			return {
+				projectId,
+				branchId
+			};
 		}) },
 		provisions: PROVISIONERS,
 		nodes: {