@geekmidas/cli 10.0.0-alpha.85 → 10.0.0-alpha.87

package/dist/{seeds-B_Beuv0o.cjs → seeds-CsI0A_Ef.cjs}

@@ -1,12 +1,12 @@
 const require_rolldown_runtime = require("./rolldown-runtime-C0BPl7ul.cjs");
-const require_run = require("./run-fVZ-rLnc.cjs");
+const require_credentials = require("./credentials-tr26-KML.cjs");
 const require_discover = require("./discover-D1It5r_h.cjs");
 const require_derive = require("./derive-DAbo49sm.cjs");
-const require_workspace = require("./workspace-Bic_R3tz.cjs");
+const require_workspace = require("./workspace-CT0JM3Y8.cjs");
 const require_config = require("./config.cjs");
 const require_EndpointGenerator = require("./EndpointGenerator-CwLjBCFE.cjs");
 const require_SubscriberGenerator = require("./SubscriberGenerator-BVn7cQ-2.cjs");
-const require_resolve = require("./resolve-CztIqBOI.cjs");
+const require_resolve = require("./resolve-BXeXzpmU.cjs");
 let node_path = require("node:path");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
@@ -31,6 +31,8 @@ let _aws_sdk_client_sns = require("@aws-sdk/client-sns");
 let _aws_sdk_client_sqs = require("@aws-sdk/client-sqs");
 let pg = require("pg");
 let _geekmidas_cache_postgres = require("@geekmidas/cache/postgres");
+let _geekmidas_storage_s3_url = require("@geekmidas/storage/s3-url");
+_geekmidas_storage_s3_url = require_rolldown_runtime.__toESM(_geekmidas_storage_s3_url, 1);
 //#region src/workspace/rootSite.ts
 /**
 * Which site the base domain points at — deployed and locally alike.
@@ -602,7 +604,7 @@ function folderName(path) {
 function getKeystoreDir(project) {
 	if (!PROJECT_KEY.test(project.key)) throw new KeystoreProjectInvalid(project.key);
 	const [namespace, name] = project.key.split("/");
-	return (0, node_path.join)(project.home ?? require_run.gkmHome(), "keys", namespace, name);
+	return (0, node_path.join)(project.home ?? require_credentials.gkmHome(), "keys", namespace, name);
 }
 /** Get the path to a stage's encryption key. */
 function getKeyPath(stage, project) {
@@ -619,7 +621,7 @@ function legacyKeyPaths(stage, project) {
 		key,
 		home: project.home
 	}));
-	const homes = [.../* @__PURE__ */ new Set([project.home ?? require_run.gkmHome(), (0, node_path.join)((0, node_os.homedir)(), ".gkm")])];
+	const homes = [.../* @__PURE__ */ new Set([project.home ?? require_credentials.gkmHome(), (0, node_path.join)((0, node_os.homedir)(), ".gkm")])];
 	const names = (project.legacy ?? []).filter(isLegacyName);
 	return [...aliases, ...names.flatMap((name) => homes.map((home) => (0, node_path.join)(home, name, `${stage}.key`)))];
 }
@@ -4877,7 +4879,7 @@ function bucketPolicies(plan) {
 * client, can be admitted by the policy where the client would have said no.
 * Prefer `**` where crossing segments is what you meant.
 */
-function bucketPolicy(bucket, open) {
+function bucketPolicy$1(bucket, open) {
 	return JSON.stringify({
 		Version: "2012-10-17",
 		Statement: [{
@@ -4959,7 +4961,7 @@ async function databasesExist(client, names) {
 async function applyPolicies(client, policies) {
 	const applied = [];
 	for (const { bucket, open } of policies) {
-		const wanted = bucketPolicy(bucket, open);
+		const wanted = bucketPolicy$1(bucket, open);
 		const describe = `open paths on ${bucket}`;
 		if (equivalent(await client.policy(bucket), wanted)) {
 			applied.push({
@@ -5578,7 +5580,7 @@ function localCredentialsPath(project) {
 	const keys = getKeystoreDir(project);
 	const name = keys.split(/[\\/]/).at(-1);
 	const namespace = keys.split(/[\\/]/).at(-2);
-	return (0, node_path.join)(project.home ?? require_run.gkmHome(), "local", namespace, `${name}.json`);
+	return (0, node_path.join)(project.home ?? require_credentials.gkmHome(), "local", namespace, `${name}.json`);
 }
 /** The local stage's logins file is there, and its key is not. */
 var LocalCredentialsKeyMissing = class extends Error {
@@ -6607,15 +6609,21 @@ function isUnder(file, dir) {
 * chain applies — the stage's shared `AWS_ACCESS_KEY_ID`/
 * `AWS_SECRET_ACCESS_KEY` when it set them, or a role.
 *
-* `--allow-dev-services minio,mailpit` is the way out for a stage that is
-* not production — a preview, a demo: the target runs the dev service and
-* derives the keys from it. Keys the stage did set still win. Every run that
-* uses one says so, loudly.
+* `--allow-dev-services` is the way out for a stage that is not production —
+* a preview, a demo: every construct the stage does not account for gets the
+* dev service the local stage runs for it — a bucket MinIO, mail Mailpit —
+* and the target derives the keys from it. What the stage does account for
+* still wins: a key set in its secrets, or a provider (`deploy.objects`)
+* that backs the kind. Every run that uses one says so, loudly.
 *
 * Pure: what each target runs is decided here from declarations and the
 * stage's values, and the targets do the running.
 */
-/** The dev services a deployed stage may be allowed to run. */
+/**
+* The dev services a deployed stage can run — one per kind that has one on
+* every server target: a bucket's MinIO and mail's Mailpit. A cache or a
+* database is not here because a server stage runs its own anyway.
+*/
 const DEV_SERVICES = ["minio", "mailpit"];
 /**
 * The S3 client's shared key pair. Optional: a bucket whose URL carries its own
@@ -6624,27 +6632,45 @@ const DEV_SERVICES = ["minio", "mailpit"];
 * chain finds — a role.
 */
 const STORAGE_KEY_PAIR = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"];
-/** A `--allow-dev-services` value that is not a dev service. */
-var UnknownDevService = class extends Error {
-	value;
-	constructor(value) {
-		super(`'${value}' is not a dev service. --allow-dev-services takes a comma-separated list of ${DEV_SERVICES.join(", ")}: --allow-dev-services ${DEV_SERVICES.join(",")}`);
-		this.value = value;
-		this.name = "UnknownDevService";
-	}
-};
 /** Dev services asked of a target that runs no containers. */
 var DevServicesNeedServerTarget = class extends Error {
 	target;
-	services;
-	constructor(target, services) {
-		super(`--allow-dev-services applies to server targets only, and '${target}' deploys to AWS, where a bucket is S3 and mail is the stage's own. Drop --allow-dev-services ${services.join(",")}.`);
+	constructor(target) {
+		super(`--allow-dev-services applies to server targets only, and '${target}' deploys to AWS, where a bucket is S3 and mail is the stage's own. Drop --allow-dev-services.`);
 		this.target = target;
-		this.services = services;
 		this.name = "DevServicesNeedServerTarget";
 	}
 };
 /**
+* `--allow-dev-services` given a value — the list it used to take. It is a
+* switch now: every construct the stage does not account for gets its dev
+* service.
+*/
+var AllowDevServicesTakesNoValue = class extends Error {
+	value;
+	constructor(value) {
+		super(`--allow-dev-services takes no value (it was given '${value}'). It runs the dev service for every bucket and mail the stage does not account for — no key in its secrets, no provider in deploy.<kind>.<stage> — so there is nothing to list. Pass --allow-dev-services on its own.`);
+		this.value = value;
+		this.name = "AllowDevServicesTakesNoValue";
+	}
+};
+/**
+* Refuses `--allow-dev-services <value>` and `--allow-dev-services=<value>` on
+* a command line, with the reason, before the parser calls the value an
+* excess argument. `gkm deploy` and `gkm compose` take no positional
+* argument, so whatever follows the flag and is not a flag was meant for it.
+*
+* @throws {AllowDevServicesTakesNoValue}
+*/
+function assertDevServicesFlag(argv) {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg.startsWith("--allow-dev-services=")) throw new AllowDevServicesTakesNoValue(arg.slice(arg.indexOf("=") + 1));
+		const next = argv[i + 1];
+		if (arg === "--allow-dev-services" && next && !next.startsWith("-")) throw new AllowDevServicesTakesNoValue(next);
+	}
+}
+/**
 * A deployed stage with mail or object storage that its secrets do not
 * configure — every missing key, across every app, at once.
 */
@@ -6652,33 +6678,18 @@ var ExternalServicesNotConfigured = class extends Error {
 	stage;
 	missing;
 	constructor(stage, missing) {
-		const services = [...new Set(missing.map((m) => m.service))].sort();
+		const standIns = missing.some((m) => m.service !== void 0);
 		const lines = missing.map((m) => {
 			const by = m.apps?.length ? `, read by ${m.apps.join(", ")}` : "";
-			return `  gkm secrets:set ${m.key} '${m.example}' --stage ${stage}\n      ${m.what}${by}` + (m.note ? `\n      ${m.note}` : "");
+			return `  gkm secrets:set ${m.key} '${m.example}' --stage ${stage}\n      ${m.what}${by}` + (m.note ? `\n      ${m.note}` : "") + (m.hint ? `\n      ${m.hint}` : "");
 		});
-		super(`The stage '${stage}' is deployed, and a deployed stage's mail and object storage are real services: gkm runs no Mailpit or MinIO for it. Set ${missing.length === 1 ? "this key" : `these ${missing.length} keys`} in the stage's secrets:\n\n${lines.join("\n")}\n\nFor a stage that is not production — a preview, a demo — the dev services can run instead, with --allow-dev-services ${services.join(",")}. Mailpit delivers no mail, and MinIO keeps every object on one container's disk.\n\nOr run: gkm secrets:add --stage ${stage}`);
+		super(`The stage '${stage}' is deployed, and a deployed stage's mail and object storage are real services: gkm runs no Mailpit or MinIO for it. Set ${missing.length === 1 ? "this key" : `these ${missing.length} keys`} in the stage's secrets:\n\n${lines.join("\n")}\n\n` + (standIns ? "For a stage that is not production — a preview, a demo — the dev services can run instead, with --allow-dev-services. Mailpit delivers no mail, and MinIO keeps every object on one container's disk.\n\n" : "") + `Or run: gkm secrets:add --stage ${stage}`);
 		this.stage = stage;
 		this.missing = missing;
 		this.name = "ExternalServicesNotConfigured";
 	}
 };
 /**
-* The dev services a value names: `'minio,mailpit'`, or a list of them.
-*
-* @throws {UnknownDevService} for anything that is not one
-*/
-function parseDevServices(value) {
-	if (value === void 0) return [];
-	const items = (typeof value === "string" ? [value] : value).flatMap((item) => item.split(",")).map((item) => item.trim()).filter(Boolean);
-	const services = /* @__PURE__ */ new Set();
-	for (const item of items) {
-		if (!DEV_SERVICES.includes(item)) throw new UnknownDevService(item);
-		services.add(item);
-	}
-	return [...services].sort();
-}
-/**
 * Every mail and storage construct a manifest declares, with the apps that
 * depend on each — what a target that provisions the whole manifest checks.
 */
@@ -6720,6 +6731,8 @@ function requiredStageKeys(input) {
 	const apps = (d) => d.apps?.length ? { apps: [...d.apps].sort() } : {};
 	if (!input.local) {
 		const services = byId(input.services);
+		const objects = input.providers?.objects;
+		const storage = objects?.accounted ? objects.hint ? { hint: objects.hint } : {} : { service: "minio" };
 		for (const d of services.filter((d) => d.kind === "email")) {
 			add({
 				key: (0, _geekmidas_manifest.provideKey)(d.id, "url"),
@@ -6747,7 +6760,7 @@ function requiredStageKeys(input) {
 			what: `the bucket '${d.id}' — S3, R2, or any S3-compatible store (add &endpoint=… for one that is not S3)`,
 			note: `credentials are optional: a key for this bucket alone in the URL (s3://KEY:SECRET@${require_derive.appKey(d.id)}?…) wins; without one, the shared AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or a role signs`,
 			example: `s3://${require_derive.appKey(d.id)}?region=eu-west-1`,
-			service: "minio",
+			...storage,
 			...apps(d)
 		});
 		for (const d of services.filter((d) => d.kind === "file-server")) add({
@@ -6756,7 +6769,7 @@ function requiredStageKeys(input) {
 			kind: "file-server",
 			what: `the public address '${d.id}' serves its bucket on — a CDN or the bucket's own domain`,
 			example: `https://${require_derive.appKey(d.id)}.${domain}`,
-			service: "minio",
+			...storage,
 			...d.of ? { of: d.of } : {},
 			...apps(d)
 		});
@@ -6805,20 +6818,23 @@ function externalServices(input) {
 	const required = requiredStageKeys({
 		local: false,
 		services: input.declarations,
-		...input.domain ? { domain: input.domain } : {}
+		...input.domain ? { domain: input.domain } : {},
+		...input.providers ? { providers: input.providers } : {}
 	});
-	const mailpit = required.filter((k) => k.kind === "email" && k.key === (0, _geekmidas_manifest.provideKey)(k.id, "url")).filter((k) => !has(k.key) && allow.includes("mailpit")).map((k) => k.id);
-	const minio = required.filter((k) => k.kind === "bucket").filter((k) => !has(k.key) && allow.includes("minio")).map((k) => k.id);
+	const standIn = (k) => allow && k.service !== void 0 && !has(k.key);
+	const mailpit = required.filter((k) => k.kind === "email" && k.key === (0, _geekmidas_manifest.provideKey)(k.id, "url")).filter(standIn).map((k) => k.id);
+	const minio = required.filter((k) => k.kind === "bucket").filter(standIn).map((k) => k.id);
 	const covered = (k) => k.kind === "email" && mailpit.includes(k.id) || k.kind === "bucket" && minio.includes(k.id) || k.kind === "file-server" && k.of !== void 0 && minio.includes(k.of);
 	return {
-		missing: required.filter((k) => !has(k.key) && !covered(k)).map(({ key, id, what, note, example, service, apps }) => ({
+		missing: required.filter((k) => !has(k.key) && !covered(k)).map(({ key, id, what, note, example, service, apps, hint }) => ({
 			key,
 			id,
 			what,
 			...note ? { note } : {},
 			example,
-			service,
-			...apps ? { apps } : {}
+			...service ? { service } : {},
+			...apps ? { apps } : {},
+			...hint ? { hint } : {}
 		})),
 		minio,
 		mailpit
@@ -6867,6 +6883,360 @@ function reportDevServices(ctx, uses) {
 	}
 }
 //#endregion
+//#region src/deploy/StateProvider.ts
+/**
+* Check if value is a StateProvider implementation.
+*/
+function isStateProvider(value) {
+	return typeof value === "object" && value !== null && typeof value.read === "function" && typeof value.write === "function";
+}
+//#endregion
+//#region src/deploy/StateStore.ts
+/**
+* Deploy state store.
+*
+* `StateProvider` reads and writes a whole stage at once, with nothing to stop
+* two runs of the same stage from overwriting each other and nowhere to record
+* a resource the moment it exists. A `StateStore` adds the three things a
+* deploy needs to be safe against crashes and concurrent runs:
+*
+* - `lock(stage)`: one run per stage. A second gets `StateLocked`, naming the
+*   holder, instead of racing the first.
+* - Versioned `read` and conditional `write`: a write names the version it was
+*   based on, and raises `StateVersionConflict` when the stored state moved on
+*   underneath it, so nothing is lost silently even without the lock.
+* - Per-resource records: `putResource` journals one resource at a time, so a
+*   run that dies half way leaves behind the ids of everything it created.
+*
+* Built-in stores: `LocalStateStore`, `SSMStateStore`, `S3StateStore`. A
+* custom `StateProvider` is wrapped by `LegacyStateStore`, which keeps it
+* working but cannot lock.
+*/
+var StateLocked = class extends Error {
+	stage;
+	holder;
+	location;
+	constructor(stage, holder, location) {
+		const by = holder ? `${holder.owner}@${holder.host} (pid ${holder.pid}) since ${holder.acquiredAt}${holder.operation ? ` for '${holder.operation}'` : ""}` : "a run that did not record who it was";
+		super(`Deploy state for stage '${stage}' is locked by ${by} (${location}). Wait for that run to finish; if it crashed, release the lock with \`gkm state:unlock --stage ${stage}\`.`);
+		this.stage = stage;
+		this.holder = holder;
+		this.location = location;
+		this.name = "StateLocked";
+	}
+};
+var StateVersionConflict = class extends Error {
+	stage;
+	expectedVersion;
+	actualVersion;
+	constructor(stage, expectedVersion, actualVersion) {
+		super(`Deploy state for stage '${stage}' changed since it was read (expected ${expectedVersion ? `version ${expectedVersion}` : "no state"}, found ${actualVersion ? `version ${actualVersion}` : "no state"}). Another run wrote it: read the state again and re-apply the change, and hold the stage's lock so runs take turns.`);
+		this.stage = stage;
+		this.expectedVersion = expectedVersion;
+		this.actualVersion = actualVersion;
+		this.name = "StateVersionConflict";
+	}
+};
+var StageStateMissing = class extends Error {
+	stage;
+	constructor(stage) {
+		super(`There is no deploy state for stage '${stage}' to record a resource in. Write the stage's state first (write with expectedVersion: null).`);
+		this.stage = stage;
+		this.name = "StageStateMissing";
+	}
+};
+var StateUnreadable = class extends Error {
+	stage;
+	location;
+	constructor(stage, location, cause) {
+		super(`Deploy state for stage '${stage}' at ${location} is not valid JSON. Restore it from a backup (or the provider's history) rather than deploying without it — a deploy without state recreates every resource.`, { cause });
+		this.stage = stage;
+		this.location = location;
+		this.name = "StateUnreadable";
+	}
+};
+var StateSchemaTooNew = class extends Error {
+	stage;
+	schemaVersion;
+	constructor(stage, schemaVersion) {
+		super(`Deploy state for stage '${stage}' has schema version ${String(schemaVersion)}, newer than this @geekmidas/cli understands (2). Upgrade @geekmidas/cli to the version that wrote it.`);
+		this.stage = stage;
+		this.schemaVersion = schemaVersion;
+		this.name = "StateSchemaTooNew";
+	}
+};
+/**
+* Not thrown: emitted (once per store) when a custom `StateProvider` stands
+* in for a store, so a deploy that cannot be protected from a concurrent one
+* says so.
+*/
+var StateStoreWithoutLocking = class extends Error {
+	provider;
+	constructor(provider) {
+		super(`The custom state provider '${provider}' has no lock and no versions, so two deploys of the same stage can still overwrite each other. Implement StateStore (lock, versioned read, conditional write) or use the 'local', 'ssm' or 's3' state provider.`);
+		this.provider = provider;
+		this.name = "StateStoreWithoutLocking";
+	}
+};
+var StateStoreNeedsWorkspaceName = class extends Error {
+	provider;
+	constructor(provider) {
+		super(`The '${provider}' state provider keys state by workspace name. Set "name" in gkm.config.ts.`);
+		this.provider = provider;
+		this.name = "StateStoreNeedsWorkspaceName";
+	}
+};
+var UnknownStateProvider = class extends Error {
+	config;
+	constructor(config) {
+		super(`Unknown state provider ${JSON.stringify(config)}. Use 'local', 'ssm', 's3', or an object implementing StateStore or StateProvider.`);
+		this.config = config;
+		this.name = "UnknownStateProvider";
+	}
+};
+/** A lock or write that could not get at the state backend in time. */
+var StateStoreBusy = class extends Error {
+	stage;
+	location;
+	constructor(stage, location) {
+		super(`Timed out waiting to write deploy state for stage '${stage}' (${location}). If no other gkm process is running, remove ${location}.`);
+		this.stage = stage;
+		this.location = location;
+		this.name = "StateStoreBusy";
+	}
+};
+function decodeDocument(stage, body, location) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (error) {
+		throw new StateUnreadable(stage, location, error);
+	}
+	if (typeof parsed !== "object" || parsed === null) throw new StateUnreadable(stage, location, parsed);
+	const schemaVersion = parsed.schemaVersion;
+	if (schemaVersion === void 0) return {
+		schemaVersion: 1,
+		state: parsed
+	};
+	if (schemaVersion === 2) return {
+		schemaVersion: 2,
+		document: parsed
+	};
+	throw new StateSchemaTooNew(stage, schemaVersion);
+}
+function encodeDocument(document) {
+	return JSON.stringify(document, null, 2);
+}
+/**
+* v1 state as a v2 document. The ids v1 kept are seeded as `ready` records,
+* so the first journaled deploy after an upgrade adopts them rather than
+* treating them as unknown.
+*/
+function migrateV1(stage, state) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const resources = {};
+	const seed = (type, name, id) => {
+		if (!id) return;
+		const key = name ? `${type}:${name}` : type;
+		resources[key] = {
+			key,
+			type,
+			id,
+			status: "ready",
+			updatedAt: now
+		};
+	};
+	seed("project", null, state.projectId);
+	seed("environment", null, state.environmentId);
+	for (const [app, id] of Object.entries(state.applications ?? {})) seed("application", app, id);
+	seed("postgres", null, state.services?.postgresId);
+	seed("redis", null, state.services?.redisId);
+	seed("backup-destination", null, state.backups?.destinationId);
+	return {
+		schemaVersion: 2,
+		stage,
+		serial: 1,
+		state,
+		resources,
+		updatedAt: now
+	};
+}
+function newLockHolder(options) {
+	let owner = "unknown";
+	try {
+		owner = (0, node_os.userInfo)().username;
+	} catch {}
+	return {
+		id: (0, node_crypto.randomUUID)(),
+		owner,
+		host: (0, node_os.hostname)(),
+		pid: process.pid,
+		acquiredAt: (/* @__PURE__ */ new Date()).toISOString(),
+		operation: options?.operation
+	};
+}
+function contentVersion(body) {
+	return (0, node_crypto.createHash)("sha256").update(body).digest("hex").slice(0, 16);
+}
+/**
+* A store over a backend that can read and conditionally write one blob per
+* stage, and create a lock object only if it does not exist. Migration and
+* resource records are the same for every such backend, so they live here.
+*/
+var DocumentStateStore = class {
+	async lock(stage, options) {
+		const holder = newLockHolder(options);
+		await this.createLock(stage, holder);
+		let released = false;
+		return {
+			stage,
+			holder,
+			release: async () => {
+				if (released) return;
+				released = true;
+				await this.removeLock(stage, holder);
+			}
+		};
+	}
+	async forceUnlock(stage) {
+		const holder = await this.readLock(stage);
+		await this.removeLock(stage, null);
+		return holder;
+	}
+	async read(stage) {
+		const current = await this.readDocument(stage);
+		if (!current) return null;
+		return {
+			state: current.document.state,
+			resources: current.document.resources,
+			version: current.version
+		};
+	}
+	async write(stage, state, options) {
+		if (options.expectedVersion === null) {
+			const document = {
+				schemaVersion: 2,
+				stage,
+				serial: 1,
+				state,
+				resources: {},
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			return this.writeRaw(stage, encodeDocument(document), null);
+		}
+		return this.mutate(stage, options.expectedVersion, (document) => ({
+			...document,
+			state
+		}));
+	}
+	async putResource(stage, record, options) {
+		return this.mutate(stage, options?.expectedVersion, (document) => ({
+			...document,
+			resources: {
+				...document.resources,
+				[record.key]: {
+					...record,
+					updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+				}
+			}
+		}));
+	}
+	async deleteResource(stage, key, options) {
+		return this.mutate(stage, options?.expectedVersion, (document) => {
+			const { [key]: _removed, ...resources } = document.resources;
+			return {
+				...document,
+				resources
+			};
+		});
+	}
+	async mutate(stage, expectedVersion, change) {
+		const current = await this.readDocument(stage);
+		if (!current) {
+			if (expectedVersion !== void 0) throw new StateVersionConflict(stage, expectedVersion, null);
+			throw new StageStateMissing(stage);
+		}
+		if (expectedVersion !== void 0 && current.version !== expectedVersion) throw new StateVersionConflict(stage, expectedVersion, current.version);
+		const next = change(current.document);
+		next.serial = current.document.serial + 1;
+		next.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		return this.writeRaw(stage, encodeDocument(next), current.version);
+	}
+	/**
+	* Reads the stage's document, migrating v1 in place on the way. The
+	* migration is itself a conditional write: if another run migrated (or
+	* wrote) first, its result is read instead.
+	*/
+	async readDocument(stage, attempt = 0) {
+		const raw = await this.readRaw(stage);
+		if (!raw) return null;
+		const decoded = decodeDocument(stage, raw.body, this.location(stage));
+		if (decoded.schemaVersion === 2) return {
+			document: decoded.document,
+			version: raw.version
+		};
+		await this.writeV1Backup(stage, raw.body);
+		const document = migrateV1(stage, decoded.state);
+		try {
+			return {
+				document,
+				version: await this.writeRaw(stage, encodeDocument(document), raw.version)
+			};
+		} catch (error) {
+			if (error instanceof StateVersionConflict && attempt < 2) return this.readDocument(stage, attempt + 1);
+			throw error;
+		}
+	}
+};
+function isStateStore(value) {
+	return typeof value === "object" && value !== null && typeof value.lock === "function" && typeof value.read === "function" && typeof value.write === "function" && typeof value.putResource === "function";
+}
+/**
+* The store for a workspace's `state` config:
+*
+* - none / `'local'`: `LocalStateStore` under `.gkm/`
+* - `'ssm'`: `SSMStateStore`, with no local cache — SSM is read directly, so
+*   a stale local copy can never win over it
+* - `'s3'`: `S3StateStore`
+* - a `StateStore` object: used as is
+* - a `StateProvider` object: wrapped by `LegacyStateStore`
+*/
+async function createStateStore(options) {
+	const { config, workspaceRoot, workspaceName } = options;
+	if (!config || config.provider === "local") {
+		const { LocalStateStore } = await Promise.resolve().then(() => require("./LocalStateStore-CLwa2DpK.cjs")).then((n) => n.LocalStateStore_exports);
+		return new LocalStateStore(workspaceRoot);
+	}
+	if (isStateStore(config.provider)) return config.provider;
+	if (isStateProvider(config.provider)) {
+		const { LegacyStateStore } = await Promise.resolve().then(() => require("./LegacyStateStore-CWG_HVC0.cjs"));
+		return new LegacyStateStore(config.provider, { warn: options.warn });
+	}
+	if (config.provider === "ssm") {
+		if (!workspaceName) throw new StateStoreNeedsWorkspaceName("ssm");
+		const { SSMStateStore } = await Promise.resolve().then(() => require("./SSMStateStore-aBOTF018.cjs"));
+		const ssm = config;
+		return SSMStateStore.create({
+			workspaceName,
+			region: ssm.region,
+			profile: ssm.profile
+		});
+	}
+	if (config.provider === "s3") {
+		if (!workspaceName) throw new StateStoreNeedsWorkspaceName("s3");
+		const { S3StateStore } = await Promise.resolve().then(() => require("./S3StateStore-Cea9_5gF.cjs"));
+		const s3 = config;
+		return S3StateStore.create({
+			workspaceName,
+			bucket: s3.bucket,
+			prefix: s3.prefix,
+			region: s3.region,
+			profile: s3.profile
+		});
+	}
+	throw new UnknownStateProvider(config);
+}
+//#endregion
 //#region src/docker/imageRef.ts
 /**
 * An image reference, checked before it reaches `docker`.
@@ -6954,7 +7324,7 @@ async function buildDockerImage(app, buildRoot, options) {
 	const fullImageName = validateImageRef(registry ? `${registry}/${app.imageName}:${tag}` : `${app.imageName}:${tag}`);
 	logger.log(`\n🐳 Building Docker image: ${fullImageName}`);
 	try {
-		await require_run.run("docker", [
+		await require_credentials.run("docker", [
 			"build",
 			`--file=${(0, node_path.relative)(buildRoot, app.dockerfile)}`,
 			`--tag=${fullImageName}`,
@@ -6981,7 +7351,7 @@ async function pushDockerImage(imageName, options, cwd) {
 	const fullImageName = validateImageRef(`${registry}/${imageName}:${tag}`);
 	logger.log(`\n🚀 Pushing Docker image: ${fullImageName}`);
 	try {
-		await require_run.run("docker", ["push", fullImageName], { cwd });
+		await require_credentials.run("docker", ["push", fullImageName], { cwd });
 		logger.log(`✅ Docker image pushed: ${fullImageName}`);
 	} catch (error) {
 		throw new DockerPushFailed(fullImageName, error);
@@ -7178,6 +7548,71 @@ function printRunInstructions(workspace) {
 	logger.log(`   docker compose -f ${COMPOSE_PATH}${project} --profile apps up --build`);
 }
 //#endregion
+//#region src/providers/types.ts
+/** The manifest kinds a stage can name a provider for. */
+const PROVIDER_KINDS = ["objects"];
+//#endregion
+//#region src/providers/notes.ts
+/** The constructs of a kind: `objects` is every bucket. */
+function constructsOf$1(manifest, kind) {
+	return Object.entries(manifest).filter(([, d]) => d.kind === kind).map(([id]) => id).sort();
+}
+/** A stage that names `false` for a kind, and declares constructs of it. */
+var StageProviderDisabled = class extends Error {
+	kind;
+	stage;
+	ids;
+	constructor(kind, stage, ids) {
+		super(`deploy.${kind}.${stage} is false — the stage has no ${kind} — and ${ids.join(", ")} ${ids.length === 1 ? "is" : "are"} declared. Name what backs ${ids.length === 1 ? "it" : "them"} on '${stage}' (deploy.${kind}.${stage}: 'external', or a provider), or remove the ${ids.length === 1 ? "construct" : "constructs"}.`);
+		this.kind = kind;
+		this.stage = stage;
+		this.ids = ids;
+		this.name = "StageProviderDisabled";
+	}
+};
+/** The command a stage's providers are run with. */
+function provisionCommand(stage) {
+	return `gkm setup --stage ${stage}`;
+}
+/**
+* The line a stage missing a key a provider would write is given: what
+* creates it, and with which credentials. Undefined when no provider backs
+* the kind on the stage.
+*/
+function provisionHint(workspace, kind, stage) {
+	const choice = require_workspace.stageProvider(workspace, kind, stage);
+	if (choice.mode !== "provider") return void 0;
+	const provisioning = require_workspace.provisioningOf(kind, choice.name);
+	if (!provisioning) return void 0;
+	return `deploy.${kind}.${stage} is ${choice.name}: ${provisionCommand(stage)} creates it and writes this key, with ${provisioning.describe}` + (provisioning.login ? `, or gkm login --provider ${provisioning.login}` : "");
+}
+/**
+* What a deploy's checks read off the stage's providers: whether each kind is
+* accounted for — a provider, or `false` — so no dev service stands in for
+* it, and what creates a missing key of it.
+*/
+function stageProviderNotes(workspace, stage) {
+	if (require_workspace.stageProvider(workspace, "objects", stage).mode === "external") return {};
+	const hint = provisionHint(workspace, "objects", stage);
+	return { objects: {
+		accounted: true,
+		...hint ? { hint } : {}
+	} };
+}
+/**
+* A kind the stage set to `false`, declared anyway — refused before anything
+* else is checked. Pure: what a stack is composed from.
+*
+* @throws {StageProviderDisabled}
+*/
+function assertStageProvidersEnabled(workspace, manifest, stage) {
+	for (const kind of PROVIDER_KINDS) {
+		const ids = constructsOf$1(manifest, kind);
+		if (ids.length === 0) continue;
+		if (require_workspace.stageProvider(workspace, kind, stage).mode === "none") throw new StageProviderDisabled(kind, stage, ids);
+	}
+}
+//#endregion
 //#region src/deploy/journal.ts
 var DeployJournal = class DeployJournal {
 	store;
@@ -7434,6 +7869,1044 @@ function setPostgresBackupId(state, backupId) {
 	if (state.backups) state.backups.postgresBackupId = backupId;
 }
 //#endregion
+//#region src/providers/aws.ts
+/**
+* The AWS account a provider provisions in — the stage's, found the way the
+* SSM and Secrets Manager stores find it.
+*
+* 1. `--profile`, resolved on its own: exported keys left over from another
+*    account never win over a profile someone named.
+* 2. `AWS_PROFILE`, else `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` — the
+*    deploy's own `aws` credential kind (`storedCredentials`).
+* 3. The SDK's default chain: `~/.aws` default profile, SSO, a role. In CI,
+*    whatever `aws-actions/configure-aws-credentials` exported.
+*
+* None of them: the provider has no provisioning credentials, and the stage
+* is treated as `external`.
+*/
+async function awsProvisioningCredentials(lookup) {
+	const region = lookup.env.AWS_REGION ?? lookup.env.AWS_DEFAULT_REGION;
+	const where = region ? { region } : {};
+	if (lookup.profile) return {
+		profile: lookup.profile,
+		...where
+	};
+	const stored = await require_credentials.storedCredentials({
+		env: lookup.env,
+		...lookup.home ? { home: lookup.home } : {}
+	}).get({
+		kind: "aws",
+		stage: lookup.stage
+	});
+	if (stored) return stored;
+	try {
+		const { fromNodeProviderChain } = await import("@aws-sdk/credential-providers");
+		await fromNodeProviderChain({
+			timeout: 1e3,
+			maxRetries: 0
+		})();
+		return {
+			chain: true,
+			...where
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* An S3-compatible endpoint the environment points the SDK at — the AWS
+* emulator in tests. The SDK reads it itself; it is read here too, because
+* an emulator takes path-style requests, and a key written for one has to
+* say where it is.
+*/
+function awsEndpoint(env, service) {
+	return env[`AWS_ENDPOINT_URL_${service}`] ?? env.AWS_ENDPOINT_URL;
+}
+/** An SDK client's config for a provisioning credential. */
+async function awsClientConfig(credential, region) {
+	if ("profile" in credential) {
+		const { fromIni } = await import("@aws-sdk/credential-providers");
+		return {
+			region,
+			credentials: fromIni({ profile: credential.profile })
+		};
+	}
+	if ("accessKeyId" in credential) return {
+		region,
+		credentials: {
+			accessKeyId: credential.accessKeyId,
+			secretAccessKey: credential.secretAccessKey,
+			...credential.sessionToken ? { sessionToken: credential.sessionToken } : {}
+		}
+	};
+	return { region };
+}
+const SUFFIX_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+/** A name that S3 would refuse — what the name builder never returns. */
+var InvalidBucketName = class extends Error {
+	bucket;
+	reason;
+	constructor(bucket, reason) {
+		super(`'${bucket}' is not a valid S3 bucket name: ${reason}. Rename the construct or set deploy.namespace in gkm.config.ts to something that leaves room for it.`);
+		this.bucket = bucket;
+		this.reason = reason;
+		this.name = "InvalidBucketName";
+	}
+};
+/** Lowercase `[a-z0-9-]`, runs of anything else one `-`, no edge dashes. */
+function part(value) {
+	return (0, _geekmidas_manifest.kebabCase)(value).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/**
+* `parts` joined by `-`, shortened to `max` characters by trimming the longest
+* part one character at a time — so a long construct id gives way before a
+* short stage name does, and every part keeps its start.
+*/
+function fitParts(parts, max) {
+	const kept = parts.map(part).filter(Boolean);
+	const length = () => kept.reduce((sum, p) => sum + p.length, 0) + kept.length - 1;
+	while (length() > max) {
+		let longest = 0;
+		for (let i = 1; i < kept.length; i++) if (kept[i].length > kept[longest].length) longest = i;
+		if (kept[longest].length <= 1) break;
+		kept[longest] = kept[longest].slice(0, -1).replace(/-+$/, "");
+	}
+	return kept.join("-");
+}
+/** Why `name` is not a valid bucket name, or undefined when it is. */
+function bucketNameProblem(name) {
+	if (name.length < 3 || name.length > 63) return `it is ${name.length} characters, and S3 takes 3 to 63`;
+	if (!/^[a-z0-9-]+$/.test(name)) return "it may hold only lowercase letters, digits and -";
+	if (!/^[a-z0-9].*[a-z0-9]$/.test(name)) return "it must start and end with a letter or a digit";
+	if (name.startsWith("xn--") || name.startsWith("sthree-")) return "it starts with a prefix S3 reserves ('xn--', 'sthree-')";
+	if (name.endsWith("-s3alias") || name.endsWith("--ol-s3")) return "it ends with a suffix S3 reserves ('-s3alias', '--ol-s3')";
+}
+/**
+* The good name: `<namespace>-<project>-<stage>-<bucket id>`, lowercased, no
+* dots, shortened to leave room for a clash's suffix.
+*
+* @throws {InvalidBucketName} when nothing usable is left
+*/
+function bucketName(input) {
+	const name = fitParts([
+		input.scope,
+		input.stage,
+		input.id
+	], 56);
+	const problem = bucketNameProblem(name);
+	if (problem) throw new InvalidBucketName(name, problem);
+	return name;
+}
+/** Six random `[a-z0-9]` characters. */
+function randomSuffix(random = node_crypto.randomInt) {
+	let suffix = "";
+	for (let i = 0; i < 6; i++) suffix += SUFFIX_ALPHABET[random(36)];
+	return suffix;
+}
+/** The good name with a clash's suffix. */
+function suffixedBucketName(good, suffix) {
+	return `${good}-${suffix}`;
+}
+/**
+* The IAM user a bucket is reached with on a stage:
+* `gkm-<project>-<stage>-<bucket id>`, at most 64 characters.
+*/
+function iamUserName(input) {
+	return fitParts([
+		"gkm",
+		input.scope,
+		input.stage,
+		input.id
+	], 64);
+}
+/** The path every user gkm creates is under, so it finds its own. */
+const IAM_USER_PATH = "/gkm/";
+/** The inline policy each user is given. */
+const IAM_POLICY_NAME = "gkm-bucket";
+//#endregion
+//#region src/providers/s3/origins.ts
+/**
+* Which browser origins may call a bucket: the stage's sites that depend on
+* an API using it.
+*
+* The same reading of the graph an API's own CORS origins are — its callers —
+* taken one step further: a site that calls an API which hands it a presigned
+* upload URL is a site whose browser PUTs to the bucket. A site that reads the
+* bucket (or a file server over it) itself is one too. Nothing is written
+* down: add a site that calls the API and the next provision run allows it.
+*/
+/** The keys a reader of this bucket holds: its URL, and each server's over it. */
+function bucketKeys(manifest, bucket) {
+	return [(0, _geekmidas_manifest.provideKey)(bucket, "url"), ...Object.entries(manifest).filter(([, d]) => d.kind === "file-server" && d.of === bucket).map(([id]) => (0, _geekmidas_manifest.provideKey)(id, "url"))];
+}
+function bucketOrigins(input) {
+	const { manifest, workspace, stage } = input;
+	const keys = bucketKeys(manifest, input.bucket);
+	const readers = Object.entries(manifest).filter(([, d]) => d.kind === "rest-api" || d.kind === "site").filter(([id]) => {
+		const env = appEnvKeys(manifest, require_derive.appKey(id), input.runnables);
+		return env !== void 0 && keys.some((key) => env.has(key));
+	});
+	const sites = /* @__PURE__ */ new Set();
+	for (const [id, declaration] of readers) {
+		if (declaration.kind === "site") {
+			sites.add(id);
+			continue;
+		}
+		for (const caller of (0, _geekmidas_manifest.dependentsOf)(manifest, id)) if (manifest[caller]?.kind === "site") sites.add(caller);
+	}
+	const origins = /* @__PURE__ */ new Set();
+	const unresolved = [];
+	for (const id of [...sites].sort()) {
+		const name = require_derive.appKey(id);
+		const app = workspace.apps[name];
+		if (!app) {
+			unresolved.push(name);
+			continue;
+		}
+		try {
+			const host = resolveHost(name, app, stage, workspace.deploy?.domains, isMainFrontendApp(name, app, workspace.apps));
+			origins.add(`https://${host}`);
+		} catch (error) {
+			if (!(error instanceof NoDomainForStage)) throw error;
+			unresolved.push(name);
+		}
+	}
+	return {
+		origins: [...origins].sort(),
+		unresolved
+	};
+}
+//#endregion
+//#region src/providers/s3/policy.ts
+const bucketArn = (bucket) => `arn:aws:s3:::${bucket}`;
+/**
+* What the app's key may do: objects in this bucket, and listing it — and
+* nothing else in the account.
+*
+* Multipart uploads are in it because a presigned upload of a large file is
+* one, and an abandoned one is cleaned up by the app. Reading old versions is
+* added only when the bucket keeps them.
+*/
+function userPolicy(bucket, options = {}) {
+	return {
+		Version: "2012-10-17",
+		Statement: [{
+			Sid: "GkmObjects",
+			Effect: "Allow",
+			Action: [
+				"s3:GetObject",
+				"s3:PutObject",
+				"s3:DeleteObject",
+				"s3:AbortMultipartUpload",
+				"s3:ListMultipartUploadParts",
+				...options.versioning ? ["s3:GetObjectVersion"] : []
+			],
+			Resource: `${bucketArn(bucket)}/*`
+		}, {
+			Sid: "GkmBucket",
+			Effect: "Allow",
+			Action: [
+				"s3:ListBucket",
+				"s3:GetBucketLocation",
+				"s3:ListBucketMultipartUploads"
+			],
+			Resource: bucketArn(bucket)
+		}]
+	};
+}
+/**
+* One open pattern as the resource it is public on. A `**` is S3's `*`; a
+* single `*` is too, which crosses `/` where the construct's own check does
+* not — the construct is the stricter of the two (see `bucketPolicy` in
+* reconcile, which the local MinIO is given the same way).
+*/
+function openResource(bucket, pattern) {
+	const path = pattern.replace(/^\/+/, "").replace(/\*\*/g, "*");
+	return `${bucketArn(bucket)}/${path}`;
+}
+/**
+* The bucket's own policy: every request refused unless it came over TLS,
+* and — only when a file server opens paths on it — anonymous `s3:GetObject`
+* on exactly those prefixes.
+*/
+function bucketPolicy(bucket, open = []) {
+	const statements = [{
+		Sid: "GkmDenyInsecureTransport",
+		Effect: "Deny",
+		Principal: "*",
+		Action: "s3:*",
+		Resource: [bucketArn(bucket), `${bucketArn(bucket)}/*`],
+		Condition: { Bool: { "aws:SecureTransport": "false" } }
+	}];
+	if (open.length > 0) statements.push({
+		Sid: "GkmOpenPaths",
+		Effect: "Allow",
+		Principal: "*",
+		Action: "s3:GetObject",
+		Resource: [...new Set(open.map((p) => openResource(bucket, p)))].sort()
+	});
+	return {
+		Version: "2012-10-17",
+		Statement: statements
+	};
+}
+/**
+* Block Public Access. All four flags on, unless the bucket has open paths:
+* then a *policy* may make it public (`BlockPublicPolicy`,
+* `RestrictPublicBuckets` off), and ACLs still may not.
+*/
+function publicAccessBlock(open) {
+	return {
+		BlockPublicAcls: true,
+		IgnorePublicAcls: true,
+		BlockPublicPolicy: !open,
+		RestrictPublicBuckets: !open
+	};
+}
+function corsRule(origins) {
+	return {
+		AllowedMethods: [
+			"GET",
+			"HEAD",
+			"POST",
+			"PUT"
+		],
+		AllowedOrigins: [...new Set(origins)].sort(),
+		AllowedHeaders: ["*"],
+		ExposeHeaders: ["ETag"],
+		MaxAgeSeconds: 3e3
+	};
+}
+/**
+* A policy document in one canonical form — keys sorted, a lone string a
+* one-element list, lists sorted — so one AWS reformatted reads as the same
+* document rather than as drift.
+*/
+function canonicalPolicy(value) {
+	return JSON.stringify(canonical(value));
+}
+function canonical(value, key) {
+	if (Array.isArray(value)) {
+		const items = value.map((v) => canonical(v));
+		return key === "Statement" ? items : items.map((v) => JSON.stringify(v)).sort();
+	}
+	if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((k) => {
+		const v = value[k];
+		return [k, canonical(k === "Action" || k === "Resource" || k === "AWS" ? Array.isArray(v) ? v : [v] : v, k)];
+	}));
+	return value;
+}
+//#endregion
+//#region src/providers/s3/index.ts
+/** The tags gkm finds its own buckets and users by. */
+const TAG_PROJECT = "gkm:project";
+const TAG_STAGE = "gkm:stage";
+const TAG_CONSTRUCT = "gkm:construct";
+function bucketConstructs(manifest) {
+	return Object.entries(manifest).filter(([, d]) => d.kind === "objects").map(([id, d]) => ({
+		id,
+		versioned: d.versioned === true,
+		servers: Object.entries(manifest).filter(([, s]) => s.kind === "file-server" && s.of === id).map(([sid, s]) => ({
+			id: sid,
+			open: s.open ?? []
+		})).sort((a, b) => a.id.localeCompare(b.id))
+	})).sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+* The region the stage's buckets are created in: the entry's, the secrets
+* store's when it is in AWS, the credential's, `AWS_REGION`.
+*/
+function s3Region(ctx, env = process.env) {
+	const store = ctx.workspace.secrets?.store;
+	const storeRegion = store && typeof store === "object" && "region" in store ? store.region : void 0;
+	const region = ctx.config.region ?? storeRegion ?? ctx.credential?.region ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION;
+	if (!region) throw new require_workspace.S3RegionRequired(ctx.stage);
+	return region;
+}
+/**
+* The address a file server over `bucket` serves on: the bucket's regional
+* virtual-host endpoint, which is what `FileServer.url(key)` appends a key to
+* — `https://<bucket>.s3.<region>.amazonaws.com/<key>`. Against an emulator,
+* its path-style address.
+*/
+function bucketPublicUrl(bucket, region, endpoint) {
+	if (endpoint) return `${endpoint.replace(/\/+$/, "")}/${bucket}`;
+	return `https://${bucket}.s3.${region}.amazonaws.com`;
+}
+/** What an AWS SDK error is called, whichever field carries it. */
+function errorName(error) {
+	const e = error;
+	return e?.Code ?? e?.name ?? "";
+}
+/** A read whose "there is none" answer is one of `missing`. */
+async function readOr(read, missing) {
+	try {
+		return await read();
+	} catch (error) {
+		if (missing.includes(errorName(error))) return void 0;
+		throw error;
+	}
+}
+const defaultClients = async (credential, region) => {
+	const S3 = await import("@aws-sdk/client-s3");
+	const IAM = await import("@aws-sdk/client-iam");
+	const config = await awsClientConfig(credential, region);
+	const endpoint = awsEndpoint(process.env, "S3");
+	return {
+		S3,
+		IAM,
+		s3: new S3.S3Client({
+			...config,
+			...endpoint ? {
+				endpoint,
+				forcePathStyle: true
+			} : {}
+		}),
+		iam: new IAM.IAMClient(config),
+		region,
+		...endpoint ? { endpoint } : {}
+	};
+};
+/** For tests: what makes the clients. */
+let makeClients = defaultClients;
+async function ensureS3(ctx) {
+	const region = s3Region(ctx);
+	const clients = await makeClients(ctx.credential, region);
+	for (const construct of bucketConstructs(ctx.manifest)) await ensureBucket(ctx, clients, construct);
+}
+/** The keys gkm tags a bucket and a user with. */
+function identityTags(ctx, id) {
+	return [
+		{
+			Key: TAG_PROJECT,
+			Value: ctx.identity.key
+		},
+		{
+			Key: TAG_STAGE,
+			Value: ctx.stage
+		},
+		{
+			Key: TAG_CONSTRUCT,
+			Value: id
+		}
+	];
+}
+async function ensureBucket(ctx, clients, construct) {
+	const { id } = construct;
+	const nameInput = {
+		scope: ctx.identity.scope,
+		stage: ctx.stage,
+		id: require_derive.appKey(id)
+	};
+	const versioning = ctx.config.versioning ?? construct.versioned;
+	const open = [...new Set(construct.servers.flatMap((s) => s.open))].sort();
+	const { bucket, exists } = await ensureBucketName(ctx, clients, id, bucketName(nameInput));
+	await ensureBucketSettings(ctx, clients, {
+		id,
+		bucket,
+		exists,
+		versioning,
+		open
+	});
+	await ensureAccessKey(ctx, clients, {
+		id,
+		bucket,
+		...await ensureUser(ctx, clients, id, iamUserName(nameInput), userPolicy(bucket, { versioning }))
+	});
+	const publicUrl = bucketPublicUrl(bucket, clients.region, clients.endpoint);
+	for (const server of construct.servers) {
+		const key = (0, _geekmidas_manifest.provideKey)(server.id, "url");
+		const entry = {
+			key: `file-server:${server.id}`,
+			type: "url"
+		};
+		const recorded = ctx.state.record(entry.key)?.id;
+		const current = ctx.secrets[key];
+		if (current === publicUrl) {
+			await ctx.state.ready(entry, publicUrl);
+			continue;
+		}
+		if (current !== void 0 && current !== recorded) {
+			ctx.log(`   ${key} is set to ${current} by you, and kept — the bucket's own address is ${publicUrl}`);
+			continue;
+		}
+		await ctx.change({
+			construct: server.id,
+			resource: key,
+			change: `set to ${publicUrl}`
+		}, async () => {
+			await ctx.writeSecrets({ [key]: publicUrl });
+			await ctx.state.ready(entry, publicUrl);
+		});
+	}
+}
+/**
+* The bucket's name: the recorded one, else the good name, else the good
+* name with a random suffix — up to {@link SUFFIX_ATTEMPTS} times.
+*/
+async function ensureBucketName(ctx, clients, id, good) {
+	const { S3, s3, region } = clients;
+	const key = `s3-bucket:${id}`;
+	const record = ctx.state.record(key);
+	const entry = (name) => ({
+		key,
+		type: "s3-bucket",
+		data: {
+			name,
+			region
+		}
+	});
+	/** Whether this account holds `name`: yes, no, or someone else does. */
+	const probe = async (name) => {
+		try {
+			await s3.send(new S3.HeadBucketCommand({ Bucket: name }));
+			return "ours";
+		} catch (error) {
+			const name = errorName(error);
+			if (name === "NotFound" || name === "NoSuchBucket") return "none";
+			if (name === "Forbidden" || name === "AccessDenied") return "taken";
+			throw error;
+		}
+	};
+	const create = async (name) => {
+		if (ctx.dryRun) {
+			const found = await probe(name);
+			if (found === "none") {
+				await ctx.change({
+					construct: id,
+					resource: `bucket ${name}`,
+					change: `create in ${region}`
+				}, async () => {});
+				return "created";
+			}
+			return found;
+		}
+		await ctx.state.pending(entry(name));
+		try {
+			await s3.send(new S3.CreateBucketCommand({
+				Bucket: name,
+				...region === "us-east-1" ? {} : { CreateBucketConfiguration: { LocationConstraint: region } }
+			}));
+		} catch (error) {
+			const code = errorName(error);
+			if (code === "BucketAlreadyOwnedByYou") return "ours";
+			if (code === "BucketAlreadyExists") return "taken";
+			throw error;
+		}
+		await ctx.change({
+			construct: id,
+			resource: `bucket ${name}`,
+			change: `create in ${region}`
+		}, async () => {});
+		return "created";
+	};
+	const adopt = async (name) => {
+		const owner = (await readOr(() => s3.send(new S3.GetBucketTaggingCommand({ Bucket: name })), ["NoSuchTagSet", "NoSuchTagSetError"]))?.TagSet?.find((t) => t.Key === TAG_PROJECT)?.Value;
+		if (owner && owner !== ctx.identity.key) throw new require_workspace.BucketOwnedByAnotherProject(name, owner, ctx.identity.key);
+	};
+	if (record?.status === "ready" && record.id) {
+		const found = await probe(record.id);
+		if (found === "ours") return {
+			bucket: record.id,
+			exists: true
+		};
+		if (found === "taken") throw new require_workspace.RecordedBucketUnreachable(id, record.id);
+		const made = await create(record.id);
+		if (made === "taken") throw new require_workspace.RecordedBucketUnreachable(id, record.id);
+		if (!ctx.dryRun) await ctx.state.ready(entry(record.id), record.id);
+		return {
+			bucket: record.id,
+			exists: made === "ours"
+		};
+	}
+	const pending = record?.data?.name;
+	const names = [
+		...typeof pending === "string" && pending !== good ? [pending] : [],
+		good,
+		...Array.from({ length: 5 }, () => suffixedBucketName(good, randomSuffix()))
+	];
+	const tried = [];
+	for (const name of names) {
+		tried.push(name);
+		const made = await create(name);
+		if (made === "taken") continue;
+		if (made === "ours") await adopt(name);
+		if (!ctx.dryRun) await ctx.state.ready(entry(name), name);
+		if (name !== good) ctx.log(`   '${good}' is taken by another account; '${id}' is '${name}', recorded in the stage's state`);
+		return {
+			bucket: name,
+			exists: made === "ours"
+		};
+	}
+	throw new require_workspace.BucketNameUnavailable(id, tried.filter((n) => n !== pending));
+}
+/** Tags, Block Public Access, encryption, policy, versioning and CORS. */
+async function ensureBucketSettings(ctx, clients, input) {
+	const { S3, s3 } = clients;
+	const { id, bucket } = input;
+	const Bucket = bucket;
+	const fresh = ctx.dryRun && !input.exists;
+	const read = async (fn, missing) => fresh ? void 0 : readOr(fn, missing);
+	const set = (change, apply) => ctx.change({
+		construct: id,
+		resource: `bucket ${bucket}`,
+		change
+	}, () => apply().then(() => void 0));
+	const tagged = await read(() => s3.send(new S3.GetBucketTaggingCommand({ Bucket })), ["NoSuchTagSet", "NoSuchTagSetError"]);
+	const ours = identityTags(ctx, id);
+	const others = (tagged?.TagSet ?? []).filter((t) => !ours.some((o) => o.Key === t.Key));
+	if (ours.some((o) => !tagged?.TagSet?.some((t) => t.Key === o.Key && t.Value === o.Value))) await set("tag", () => s3.send(new S3.PutBucketTaggingCommand({
+		Bucket,
+		Tagging: { TagSet: [...others, ...ours].map((t) => ({
+			Key: t.Key,
+			Value: t.Value
+		})) }
+	})));
+	const isOpen = input.open.length > 0;
+	const block = publicAccessBlock(isOpen);
+	const ensureBlock = async () => {
+		const now = (await read(() => s3.send(new S3.GetPublicAccessBlockCommand({ Bucket })), ["NoSuchPublicAccessBlockConfiguration"]))?.PublicAccessBlockConfiguration;
+		if (!(now && Object.keys(block).every((k) => (now[k] ?? false) === block[k]))) await set(isOpen ? "block public access (ACLs; the policy opens the open paths)" : "block all public access", () => s3.send(new S3.PutPublicAccessBlockCommand({
+			Bucket,
+			PublicAccessBlockConfiguration: block
+		})));
+	};
+	const policy = bucketPolicy(bucket, input.open);
+	const ensurePolicy = async () => {
+		const current = await read(() => s3.send(new S3.GetBucketPolicyCommand({ Bucket })), ["NoSuchBucketPolicy"]);
+		if (!(current?.Policy !== void 0 && canonicalPolicy(JSON.parse(current.Policy)) === canonicalPolicy(policy))) await set(isOpen ? `policy: TLS only, public read on ${input.open.join(", ")}` : "policy: TLS only", () => s3.send(new S3.PutBucketPolicyCommand({
+			Bucket,
+			Policy: JSON.stringify(policy)
+		})));
+	};
+	if (isOpen) {
+		await ensureBlock();
+		await ensurePolicy();
+	} else {
+		await ensurePolicy();
+		await ensureBlock();
+	}
+	if ((await read(() => s3.send(new S3.GetBucketEncryptionCommand({ Bucket })), ["ServerSideEncryptionConfigurationNotFoundError"]))?.ServerSideEncryptionConfiguration?.Rules?.[0]?.ApplyServerSideEncryptionByDefault?.SSEAlgorithm !== "AES256" && !fresh) await set("encrypt by default (SSE-S3)", () => s3.send(new S3.PutBucketEncryptionCommand({
+		Bucket,
+		ServerSideEncryptionConfiguration: { Rules: [{ ApplyServerSideEncryptionByDefault: { SSEAlgorithm: "AES256" } }] }
+	})));
+	const status = (await read(() => s3.send(new S3.GetBucketVersioningCommand({ Bucket })), []))?.Status;
+	if (input.versioning && status !== "Enabled") await set("enable versioning", () => s3.send(new S3.PutBucketVersioningCommand({
+		Bucket,
+		VersioningConfiguration: { Status: "Enabled" }
+	})));
+	else if (!input.versioning && status === "Enabled") await set("suspend versioning", () => s3.send(new S3.PutBucketVersioningCommand({
+		Bucket,
+		VersioningConfiguration: { Status: "Suspended" }
+	})));
+	const { origins, unresolved } = bucketOrigins({
+		workspace: ctx.workspace,
+		manifest: ctx.manifest,
+		runnables: ctx.runnables,
+		stage: ctx.stage,
+		bucket: id
+	});
+	if (unresolved.length > 0) ctx.log(`   ${unresolved.join(", ")} ${unresolved.length === 1 ? "has" : "have"} no address on '${ctx.stage}' (deploy.domains.${ctx.stage}), so ${unresolved.length === 1 ? "is" : "are"} not in '${bucket}''s CORS`);
+	if (origins.length === 0) return;
+	const rule = corsRule(origins);
+	const cors = await read(() => s3.send(new S3.GetBucketCorsCommand({ Bucket })), ["NoSuchCORSConfiguration"]);
+	if (!(cors?.CORSRules?.length === 1 && canonicalCors(cors.CORSRules[0]) === canonicalCors(rule))) await set(`CORS for ${origins.join(", ")}`, () => s3.send(new S3.PutBucketCorsCommand({
+		Bucket,
+		CORSConfiguration: { CORSRules: [rule] }
+	})));
+}
+function canonicalCors(rule) {
+	const sorted = (list) => [...list ?? []].sort();
+	return JSON.stringify({
+		AllowedMethods: sorted(rule.AllowedMethods),
+		AllowedOrigins: sorted(rule.AllowedOrigins),
+		AllowedHeaders: sorted(rule.AllowedHeaders),
+		ExposeHeaders: sorted(rule.ExposeHeaders),
+		MaxAgeSeconds: rule.MaxAgeSeconds ?? null
+	});
+}
+/** The bucket's IAM user and its inline policy. */
+async function ensureUser(ctx, clients, id, user, policy) {
+	const { IAM, iam } = clients;
+	const entry = {
+		key: `iam-user:${id}`,
+		type: "iam-user"
+	};
+	const found = await readOr(() => iam.send(new IAM.GetUserCommand({ UserName: user })), ["NoSuchEntity", "NoSuchEntityException"]);
+	if (found?.User) {
+		const tags = await iam.send(new IAM.ListUserTagsCommand({ UserName: user }));
+		const tag = (key) => tags.Tags?.find((t) => t.Key === key)?.Value;
+		if (found.User.Path !== "/gkm/" || tag("gkm:project") !== ctx.identity.key || tag("gkm:stage") !== ctx.stage) throw new require_workspace.IamUserNotOwned(user, ctx.identity.key, ctx.stage);
+		await ctx.state.ready(entry, user);
+	} else await ctx.change({
+		construct: id,
+		resource: `IAM user ${user}`,
+		change: `create under ${IAM_USER_PATH}`
+	}, async () => {
+		await ctx.state.pending(entry);
+		await iam.send(new IAM.CreateUserCommand({
+			UserName: user,
+			Path: IAM_USER_PATH,
+			Tags: identityTags(ctx, id)
+		}));
+		await ctx.state.ready(entry, user);
+	});
+	const exists = Boolean(found?.User) || !ctx.dryRun;
+	const current = exists ? await readOr(() => iam.send(new IAM.GetUserPolicyCommand({
+		UserName: user,
+		PolicyName: IAM_POLICY_NAME
+	})), ["NoSuchEntity", "NoSuchEntityException"]) : void 0;
+	const document = current?.PolicyDocument ? JSON.parse(decodePolicy(current.PolicyDocument)) : void 0;
+	if (!document || canonicalPolicy(document) !== canonicalPolicy(policy)) await ctx.change({
+		construct: id,
+		resource: `IAM user ${user}`,
+		change: `policy ${IAM_POLICY_NAME}: this bucket only`
+	}, async () => {
+		await iam.send(new IAM.PutUserPolicyCommand({
+			UserName: user,
+			PolicyName: IAM_POLICY_NAME,
+			PolicyDocument: JSON.stringify(policy)
+		}));
+	});
+	return {
+		user,
+		exists
+	};
+}
+/** IAM returns a policy document URL-encoded; an emulator may not. */
+function decodePolicy(document) {
+	try {
+		return decodeURIComponent(document);
+	} catch {
+		return document;
+	}
+}
+/**
+* The user's access key, in the stage's secrets as the bucket's URL.
+*
+* - First run: one key, written into the stage's secrets.
+* - `--rotate-keys`: a second key, written in place of the first; the first
+*   stays active until the stage has deployed with the second, and the next
+*   run after that deploy — or `--retire-old-keys` — deletes it.
+* - A key the secrets no longer hold (a store emptied by hand): replaced the
+*   same way, since its secret cannot be read back.
+*/
+async function ensureAccessKey(ctx, clients, input) {
+	const { IAM, iam } = clients;
+	const { id, bucket, user } = input;
+	const urlKey = (0, _geekmidas_manifest.provideKey)(id, "url");
+	const entryKey = `iam-access-key:${id}`;
+	const record = ctx.state.record(entryKey);
+	const given = ctx.secrets[urlKey];
+	let inUrl;
+	if (given !== void 0) {
+		let parsed;
+		try {
+			parsed = _geekmidas_storage_s3_url.parse(given);
+		} catch {
+			parsed = void 0;
+		}
+		if (parsed?.bucket !== bucket) throw new require_workspace.BucketKeySetElsewhere(urlKey, bucket, parsed?.bucket ?? given.replace(/\/\/[^@]*@/, "//"), ctx.stage);
+		inUrl = parsed.accessKeyId;
+	}
+	const listed = input.exists ? (await iam.send(new IAM.ListAccessKeysCommand({ UserName: user }))).AccessKeyMetadata?.map((k) => k.AccessKeyId) ?? [] : [];
+	let current = record?.status === "ready" ? record.id : void 0;
+	let previous = typeof record?.data?.previous === "string" ? record.data.previous : void 0;
+	const rotatedAt = typeof record?.data?.rotatedAt === "string" ? record.data.rotatedAt : void 0;
+	const entry = (data = {}) => ({
+		key: entryKey,
+		type: "iam-access-key",
+		data: {
+			user,
+			...data
+		}
+	});
+	if (previous && current) {
+		const deployed = rotatedAt !== void 0 && ctx.state.lastDeployedAt !== void 0 && ctx.state.lastDeployedAt > rotatedAt;
+		if (ctx.retireOldKeys || deployed) {
+			const old = previous;
+			const keep = current;
+			await ctx.change({
+				construct: id,
+				resource: `IAM user ${user}`,
+				change: `delete the rotated-out access key ${old}`
+			}, async () => {
+				if (listed.includes(old)) await iam.send(new IAM.DeleteAccessKeyCommand({
+					UserName: user,
+					AccessKeyId: old
+				}));
+				await ctx.state.ready(entry(), keep);
+			});
+			previous = void 0;
+		} else ctx.log(`   ${id}: the old access key ${previous} stays active until '${ctx.stage}' is deployed with the new one; the next gkm setup --stage ${ctx.stage} after that deletes it (or pass --retire-old-keys)`);
+	}
+	if (!current && inUrl && listed.includes(inUrl)) {
+		await ctx.state.ready(entry(), inUrl);
+		current = inUrl;
+	}
+	if (current !== void 0 && listed.includes(current) && inUrl === current && !ctx.rotateKeys) return;
+	if (ctx.rotateKeys && previous) throw new require_workspace.RotationInProgress(id, previous, ctx.stage);
+	const outgoing = current && listed.includes(current) ? current : void 0;
+	if (listed.length >= 2) throw new require_workspace.AccessKeyLimit(user, listed);
+	const why = !current ? "create an access key" : ctx.rotateKeys ? "rotate: issue a new access key" : "issue a new access key (the secrets no longer hold the recorded one)";
+	await ctx.change({
+		construct: id,
+		resource: `IAM user ${user}`,
+		change: why
+	}, async () => {
+		await ctx.state.pending(entry(outgoing ? { previous: outgoing } : {}));
+		const key = (await iam.send(new IAM.CreateAccessKeyCommand({ UserName: user }))).AccessKey;
+		await ctx.writeSecrets({ [urlKey]: _geekmidas_storage_s3_url.build({
+			bucket,
+			region: clients.region,
+			...clients.endpoint ? {
+				endpoint: clients.endpoint,
+				forcePathStyle: true
+			} : {},
+			accessKeyId: key.AccessKeyId,
+			secretAccessKey: key.SecretAccessKey
+		}) });
+		await ctx.state.ready(entry(outgoing ? {
+			previous: outgoing,
+			rotatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		} : {}), key.AccessKeyId);
+	});
+	if (outgoing) ctx.log(`   ${urlKey} holds the new key. Deploy '${ctx.stage}' now; the next gkm setup --stage ${ctx.stage} after that deploy deletes the old key ${outgoing}`);
+}
+/**
+* Each provisioned bucket answers `HeadBucket` to the key in the stage's
+* secrets — the one the apps will use. A bucket whose URL carries no key is
+* not one this provider wrote, and the deploy's own check covers a URL that
+* is missing.
+*/
+async function verifyS3(ctx) {
+	const S3 = await import("@aws-sdk/client-s3");
+	for (const { id } of bucketConstructs(ctx.manifest)) {
+		const url = ctx.secrets[(0, _geekmidas_manifest.provideKey)(id, "url")];
+		if (url === void 0) continue;
+		const address = _geekmidas_storage_s3_url.parse(url);
+		if (!address.accessKeyId || !address.secretAccessKey) continue;
+		const client = new S3.S3Client({
+			region: address.region ?? ctx.config.region ?? "us-east-1",
+			credentials: {
+				accessKeyId: address.accessKeyId,
+				secretAccessKey: address.secretAccessKey
+			},
+			...address.endpoint ? { endpoint: address.endpoint } : {},
+			...address.forcePathStyle ? { forcePathStyle: true } : {}
+		});
+		try {
+			await client.send(new S3.HeadBucketCommand({ Bucket: address.bucket }));
+		} catch (error) {
+			const name = errorName(error);
+			throw new require_workspace.ProvisionedBucketUnreachable(id, address.bucket, ctx.stage, name === "NotFound" ? "it does not exist" : name === "Forbidden" ? "the key is refused" : name || String(error));
+		} finally {
+			client.destroy();
+		}
+	}
+}
+//#endregion
+//#region src/providers/registry.ts
+/**
+* The providers gkm ships, by kind and name — registered the way a deploy
+* target's built-ins are (`target/builtins.ts`). A provider from a package is
+* one more entry here once there is a loading story for it.
+*/
+const BUILTIN_PROVIDERS = { objects: { s3: {
+	kind: "objects",
+	name: "s3",
+	check: require_workspace.checkS3Config,
+	provisioning: require_workspace.S3_PROVISIONING,
+	credentials: awsProvisioningCredentials,
+	runtimeKeys(manifest) {
+		return bucketConstructs(manifest).flatMap((b) => [(0, _geekmidas_manifest.provideKey)(b.id, "url"), ...b.servers.map((s) => (0, _geekmidas_manifest.provideKey)(s.id, "url"))]);
+	},
+	ensure: ensureS3,
+	verify: verifyS3
+} } };
+/** The provider `kind` names `name`, if gkm has one. */
+function builtinProvider(kind, name) {
+	return Object.hasOwn(BUILTIN_PROVIDERS[kind], name) ? BUILTIN_PROVIDERS[kind][name] : void 0;
+}
+//#endregion
+//#region src/providers/index.ts
+/** The constructs of a kind: `objects` is every bucket. */
+function constructsOf(manifest, kind) {
+	return Object.entries(manifest).filter(([, d]) => d.kind === kind).map(([id]) => id).sort();
+}
+/**
+* What every deploy runs: each provider's `verify()` — the cheap check that
+* what it created is still there and the stage's key reaches it. Nothing on
+* the local stage, and nothing for a kind on `external`.
+*
+* @throws {StageProviderDisabled} for a declared kind the stage has none of
+*/
+async function verifyStageProviders(input) {
+	assertStageProvidersEnabled(input.workspace, input.manifest, input.stage);
+	const verified = [];
+	for (const kind of PROVIDER_KINDS) {
+		if (constructsOf(input.manifest, kind).length === 0) continue;
+		const choice = require_workspace.stageProvider(input.workspace, kind, input.stage);
+		if (choice.mode !== "provider") continue;
+		const provider = builtinProvider(kind, choice.name);
+		await provider.verify({
+			workspace: input.workspace,
+			manifest: input.manifest,
+			stage: input.stage,
+			config: choice.config,
+			secrets: input.secrets
+		});
+		verified.push(`${kind}: ${provider.name}`);
+	}
+	return verified;
+}
+/**
+* `ensure()` for every provider the stage configures — find or create, fix
+* drift, record in the stage's state, write the runtime keys into its
+* secrets. A provider without provisioning credentials leaves the stage as
+* `external` and says how to supply them.
+*/
+async function provisionStage(options) {
+	const { workspace, stage } = options;
+	const dryRun = options.dryRun === true;
+	const env = options.env ?? process.env;
+	const log = options.log ?? ((line) => console.log(line));
+	const named = PROVIDER_KINDS.some((kind) => require_workspace.stageProvider(workspace, kind, stage).mode === "provider");
+	let found = options.manifest;
+	let runnables = options.runnables ?? {};
+	if (!found && named) {
+		runnables = {};
+		found = await require_discover.discover({
+			patterns: constructGlobs(workspace),
+			cwd: workspace.root,
+			runnables
+		});
+	}
+	const manifest = found ?? {};
+	const reports = [];
+	const configured = [];
+	for (const kind of PROVIDER_KINDS) {
+		const choice = require_workspace.stageProvider(workspace, kind, stage);
+		if (choice.mode !== "provider") {
+			reports.push({
+				kind,
+				mode: choice.mode,
+				actions: []
+			});
+			continue;
+		}
+		const provider = builtinProvider(kind, choice.name);
+		const report = {
+			kind,
+			mode: "provider",
+			provider: provider.name,
+			actions: []
+		};
+		reports.push(report);
+		if (constructsOf(manifest, kind).length === 0) {
+			log(`   ${kind}: ${provider.name} — nothing declared to provision`);
+			continue;
+		}
+		const credential = await provider.credentials({
+			stage,
+			env,
+			...options.profile ? { profile: options.profile } : {},
+			...options.home ? { home: options.home } : {}
+		});
+		report.credentials = credential !== void 0;
+		if (credential === void 0) {
+			log(`   ${kind}: ${provider.name} — no credentials to provision with, so '${stage}' is external for now: its keys (${provider.runtimeKeys(manifest).join(", ")}) are yours to set with gkm secrets:add --stage ${stage}. To have gkm create them, supply ${provider.provisioning.describe}` + (provider.provisioning.login ? `, or run gkm login --provider ${provider.provisioning.login}` : "") + `, and run ${provisionCommand(stage)}.`);
+			continue;
+		}
+		configured.push({
+			kind,
+			provider,
+			config: choice.config,
+			credential,
+			report
+		});
+	}
+	if (configured.length === 0) return reports;
+	const identity = deployIdentity(workspace, stage);
+	const secretsStore = await secretsStoreFor(workspace, stage, {
+		...options.profile ? { profile: options.profile } : {},
+		...options.home ? { home: options.home } : {}
+	});
+	let secrets = (await secretsStore.read(stage))?.custom ?? {};
+	const stateStore = await createStateStore({
+		config: workspace.state,
+		workspaceRoot: workspace.root,
+		workspaceName: workspace.name
+	});
+	const lock = dryRun ? void 0 : await stateStore.lock(stage, { operation: "provision" });
+	try {
+		const state = dryRun ? await readOnlyState(stateStore, stage) : journalState(await DeployJournal.open(stateStore, stage, () => createEmptyState(stage, "", "")));
+		const writeSecrets = async (values) => {
+			if (dryRun) return;
+			const stored = await secretsStore.read(stage) ?? initStageSecrets(stage);
+			const next = {
+				...stored,
+				custom: {
+					...stored.custom,
+					...values
+				},
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			await secretsStore.write(stage, next);
+			secrets = next.custom;
+		};
+		for (const entry of configured) {
+			log(`   ${entry.kind}: ${entry.provider.name}${dryRun ? " (dry run)" : ""}`);
+			await entry.provider.ensure({
+				workspace,
+				manifest,
+				runnables,
+				stage,
+				identity,
+				config: entry.config,
+				credential: entry.credential,
+				get secrets() {
+					return secrets;
+				},
+				state,
+				dryRun,
+				rotateKeys: options.rotateKeys === true,
+				retireOldKeys: options.retireOldKeys === true,
+				async change(action, apply) {
+					if (!dryRun) await apply();
+					entry.report.actions.push(action);
+					log(`   ${dryRun ? "would " : ""}${action.change} — ${action.resource}`);
+				},
+				writeSecrets,
+				log
+			});
+			if (entry.report.actions.length === 0) log("   up to date");
+		}
+	} finally {
+		await lock?.release();
+	}
+	return reports;
+}
+/** The journal as `ensure()` sees it. */
+function journalState(journal) {
+	return {
+		record: (key) => journal.record(key),
+		pending: (entry) => journal.pending(entry),
+		ready: (entry, id) => journal.ready(entry, id),
+		lastDeployedAt: journal.existed ? journal.state.lastDeployedAt : void 0
+	};
+}
+/** What a dry run reads, and the writes it does not make. */
+async function readOnlyState(store, stage) {
+	const stored = await store.read(stage);
+	return {
+		record: (key) => stored?.resources[key],
+		pending: async () => {},
+		ready: async () => {},
+		...stored ? { lastDeployedAt: stored.state.lastDeployedAt } : {}
+	};
+}
+//#endregion
 //#region src/secrets/stale.ts
 /**
 * Stored secrets an older gkm generated that now shadow a derived value.
@@ -7582,6 +9055,12 @@ function reportPlannedSeeds(planned, log) {
 	for (const { folder, seeds } of planned) log(`🌱 ${folder}: would run ${seeds.length} (${seeds.join(", ")})`);
 }
 //#endregion
+Object.defineProperty(exports, "AllowDevServicesTakesNoValue", {
+	enumerable: true,
+	get: function() {
+		return AllowDevServicesTakesNoValue;
+	}
+});
 Object.defineProperty(exports, "CLUSTER_DATABASE", {
 	enumerable: true,
 	get: function() {
@@ -7636,6 +9115,12 @@ Object.defineProperty(exports, "DockerPushFailed", {
 		return DockerPushFailed;
 	}
 });
+Object.defineProperty(exports, "DocumentStateStore", {
+	enumerable: true,
+	get: function() {
+		return DocumentStateStore;
+	}
+});
 Object.defineProperty(exports, "EMULATOR_ACCESS_KEY_ID", {
 	enumerable: true,
 	get: function() {
@@ -7720,22 +9205,52 @@ Object.defineProperty(exports, "STORAGE_KEY_PAIR", {
 		return STORAGE_KEY_PAIR;
 	}
 });
-Object.defineProperty(exports, "TELEMETRY_CONTAINER", {
+Object.defineProperty(exports, "StageProviderDisabled", {
 	enumerable: true,
 	get: function() {
-		return TELEMETRY_CONTAINER;
+		return StageProviderDisabled;
 	}
 });
-Object.defineProperty(exports, "TURBO_VERSION", {
+Object.defineProperty(exports, "StageStateMissing", {
 	enumerable: true,
 	get: function() {
-		return TURBO_VERSION;
+		return StageStateMissing;
+	}
+});
+Object.defineProperty(exports, "StateLocked", {
+	enumerable: true,
+	get: function() {
+		return StateLocked;
 	}
 });
-Object.defineProperty(exports, "UnknownDevService", {
+Object.defineProperty(exports, "StateStoreBusy", {
 	enumerable: true,
 	get: function() {
-		return UnknownDevService;
+		return StateStoreBusy;
+	}
+});
+Object.defineProperty(exports, "StateStoreWithoutLocking", {
+	enumerable: true,
+	get: function() {
+		return StateStoreWithoutLocking;
+	}
+});
+Object.defineProperty(exports, "StateVersionConflict", {
+	enumerable: true,
+	get: function() {
+		return StateVersionConflict;
+	}
+});
+Object.defineProperty(exports, "TELEMETRY_CONTAINER", {
+	enumerable: true,
+	get: function() {
+		return TELEMETRY_CONTAINER;
+	}
+});
+Object.defineProperty(exports, "TURBO_VERSION", {
+	enumerable: true,
+	get: function() {
+		return TURBO_VERSION;
 	}
 });
 Object.defineProperty(exports, "WORKER_PORT", {
@@ -7792,6 +9307,12 @@ Object.defineProperty(exports, "applyPostgres", {
 		return applyPostgres;
 	}
 });
+Object.defineProperty(exports, "assertDevServicesFlag", {
+	enumerable: true,
+	get: function() {
+		return assertDevServicesFlag;
+	}
+});
 Object.defineProperty(exports, "assertExternalServices", {
 	enumerable: true,
 	get: function() {
@@ -7804,6 +9325,12 @@ Object.defineProperty(exports, "assertNoStaleSecrets", {
 		return assertNoStaleSecrets;
 	}
 });
+Object.defineProperty(exports, "assertStageProvidersEnabled", {
+	enumerable: true,
+	get: function() {
+		return assertStageProvidersEnabled;
+	}
+});
 Object.defineProperty(exports, "backendsOf", {
 	enumerable: true,
 	get: function() {
@@ -7846,6 +9373,12 @@ Object.defineProperty(exports, "constructGlobs", {
 		return constructGlobs;
 	}
 });
+Object.defineProperty(exports, "contentVersion", {
+	enumerable: true,
+	get: function() {
+		return contentVersion;
+	}
+});
 Object.defineProperty(exports, "createCredentialsPreload", {
 	enumerable: true,
 	get: function() {
@@ -7864,6 +9397,12 @@ Object.defineProperty(exports, "createEntryWrapper", {
 		return createEntryWrapper;
 	}
 });
+Object.defineProperty(exports, "createStateStore", {
+	enumerable: true,
+	get: function() {
+		return createStateStore;
+	}
+});
 Object.defineProperty(exports, "deployIdentity", {
 	enumerable: true,
 	get: function() {
@@ -8128,16 +9667,16 @@ Object.defineProperty(exports, "networkEnv", {
 		return networkEnv;
 	}
 });
-Object.defineProperty(exports, "ownershipMarker", {
+Object.defineProperty(exports, "newLockHolder", {
 	enumerable: true,
 	get: function() {
-		return ownershipMarker;
+		return newLockHolder;
 	}
 });
-Object.defineProperty(exports, "parseDevServices", {
+Object.defineProperty(exports, "ownershipMarker", {
 	enumerable: true,
 	get: function() {
-		return parseDevServices;
+		return ownershipMarker;
 	}
 });
 Object.defineProperty(exports, "pgClient", {
@@ -8212,6 +9751,18 @@ Object.defineProperty(exports, "providerOf", {
 		return providerOf;
 	}
 });
+Object.defineProperty(exports, "provisionCommand", {
+	enumerable: true,
+	get: function() {
+		return provisionCommand;
+	}
+});
+Object.defineProperty(exports, "provisionStage", {
+	enumerable: true,
+	get: function() {
+		return provisionStage;
+	}
+});
 Object.defineProperty(exports, "quoteIdentifier", {
 	enumerable: true,
 	get: function() {
@@ -8356,6 +9907,12 @@ Object.defineProperty(exports, "stackRedis", {
 		return stackRedis;
 	}
 });
+Object.defineProperty(exports, "stageProviderNotes", {
+	enumerable: true,
+	get: function() {
+		return stageProviderNotes;
+	}
+});
 Object.defineProperty(exports, "storageBackendFor", {
 	enumerable: true,
 	get: function() {
@@ -8416,6 +9973,12 @@ Object.defineProperty(exports, "validateImageRef", {
 		return validateImageRef;
 	}
 });
+Object.defineProperty(exports, "verifyStageProviders", {
+	enumerable: true,
+	get: function() {
+		return verifyStageProviders;
+	}
+});
 Object.defineProperty(exports, "withCustomSecret", {
 	enumerable: true,
 	get: function() {
@@ -8483,4 +10046,4 @@ Object.defineProperty(exports, "workspace_exports", {
 	}
 });
 
-//# sourceMappingURL=seeds-B_Beuv0o.cjs.map
+//# sourceMappingURL=seeds-CsI0A_Ef.cjs.map