@samebase/alchemy-convex 0.4.1 → 0.6.0

package/README.md

@@ -90,6 +90,32 @@ reads them through the stack's config provider (process env, `.env`, stack secre
 A key that does not fit the deployment is not used: the provider uses the access token. To pass
 values explicitly: `Convex.providers(Convex.fromValues({ accessToken, deployKey }))`.
 
+## State in Convex
+
+`state: Convex.state({ team })` keeps the Alchemy state of every stack and stage of a Convex team in
+one project of that team, `alchemy-state`, so a repository holds one secret and a stack can create
+and destroy its own project. [docs/design/convex-state.md](docs/design/convex-state.md) records the
+decisions and the measurements.
+
+```ts
+export default Alchemy.Stack(
+  process.env["GITHUB_REPOSITORY"] ?? "my-org/my-app", // the stack name: the repository
+  { providers: Convex.providers(), state: Convex.state({ team: "my-team" }) },
+  Effect.gen(function* () {
+    /* ... */
+  }),
+);
+```
+
+Every run needs the team token in `CONVEX_ACCESS_TOKEN`, or the Convex CLI login on a laptop. The
+first run of a team creates the project `alchemy-state` and pushes the store functions to its
+production deployment with the Convex CLI of the app; a later version of this package pushes a
+newer store when it finds an older one, and never an older one over a newer one. Each run makes a
+deploy key of that deployment that can only run the store's internal functions, and deletes it at
+the end. Rows are in the tables `resources` and `outputs` in the dashboard, under the stack name.
+The store has no lock: run one deploy of a stage at a time, such as with a CI concurrency group.
+The names of the store functions are a wire contract: never renamed or removed.
+
 ## Resources
 
 - `Convex.Project`: `{ team, name, deploymentRegion?, deploymentType? }` creates a project with its

package/lib/index.d.ts

@@ -5,8 +5,10 @@ import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
 import { Resource } from "alchemy";
 import * as Provider from "alchemy/Provider";
-import "effect/process/ChildProcessSpawner";
+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
+import "effect/Scope";
+import { State, StateStoreError } from "alchemy/State";
 import { components } from "@convex-dev/platform/managementApi";
 //#region src/Credentials.d.ts
 interface ResolvedCredentials {
@@ -339,5 +341,18 @@ export declare class ProjectNotFound extends ProjectNotFound_base {
   get message(): string;
 }
 //#endregion
+//#region src/State.d.ts
+/** The name of the state project in each team. */
+export declare const STORE_PROJECT_NAME = "alchemy-state";
+/**
+ * Alchemy state in the `alchemy-state` project of `team`, with the team token
+ * in CONVEX_ACCESS_TOKEN or the Convex CLI login. The first use of the run
+ * finds or creates the project and pushes the store when it is missing or
+ * older. `alchemy plan` on another stack never touches Convex.
+ */
+export declare const state: (options: {
+  readonly team: string | number;
+}) => Layer.Layer<State, never, ChildProcessSpawner.ChildProcessSpawner>;
+//#endregion
 export type { DeploymentAttributes, DeploymentProps, DeploymentRegion, EnvValue, ProjectAttributes, ProjectProps, Source };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/Push.ts","../src/Deployment.ts","../src/Project.ts"],"mappings":";;;;;;;;;;;UA6BiB;;WAEN,aAAa,SAAS;;WAEtB;;UAGM;;WAEN,aAAa,OAAO,OAAO;;WAE3B,gBAAgB,OAAO;;WAEvB,WAAW,OAAO,OAAO,SAAS;;;qBAGhC,oBAAoB;;qBAKpB;;qBAGA;;;;qBAOA,yBAAyB;;;;;;;;;qBAiCzB,kBAAiB,MAAM,MAAM;;qBA0B7B,aAAc;WAChB,cAAc,SAAS;WACvB,YAAY,SAAS;MAC5B,MAAM,MAAM;;;KC3GJ,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;qBAQR,uBAAuB;UAuBnB;;WAEN,UAAU,GACjB,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,cACP,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,0BACxC,OAAO,aAAa;;WAEhB,oBAAoB,GAC3B,mBACA,6BACA,WAAW,SAAS,kBACpB,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,gBAAgB,0BAA0B,OAAO,eAAe;;;;;;;;WAQhE,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBClFtB,kBAAkB;;;;;;qBAOlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,8CAAA,mCAAA,oDAAA;;;;KC8BlE,oBAAoB,SAAS;;;;;KAM7B;;WAIG;;;;;;;;WAQA;;;;;;;WAOA;;;;;;qBA2BF,0BAA0B;MAIxB;;;;;;qBAMF,0BAA0B;MAIxB;;;;;;;;;qBAMF,uBAAuB;MAMrB;;;;;;;qBAQF,2BAA2B;MAIzB;;;;;;;qBAMF,oCAAoC;MAIlC;;;;;;qBAMF,kCAAkC;MAIhC;;;qBAuCF,oBACX;EACG;EAAa;;;;UCzHR;;WAEC;aAAoB;;;;;;;;WAOpB,SAAS;;WAET,MAAM,SAAS,eAAe;;KAG7B,mBACP;;WAEU;MAEV;;WAEU;;;;;WAKA;;;UAIL;WACC;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;UAGM,6BAA6B;;WAEnC;;WAEA;;YAGC,aAAa,8BAEvB,iBACA,6BAEA;qBAEW,8BAAU,cAAA;;;;;;;;;qBAKV,iCAAiC;MAU/B;;;;;;qBAMF,qCAAqC;MAInC;;;;;;;;;qBAMF,4BAA4B;MAS1B;;;;;KChJH,mBAAmB;KAEnB;;WAGG;;WAEA;;WAEA,mBAAmB;;WAEnB;;;WAIA;;WAEA;;UAGE;WACN;WACA;WACA;WACA;WACA;WACA;;YAGC,UAAU,2BAA2B,cAAc,0BAA0B;qBAC5E,2BAAO,cAAA;;;;;;;qBAGP,0BAA0B;MAIxB;;;;;;;;;;;;qBASF,gCAAgC;MAS9B;;;;;;;;qBAOF,yBAAyB;MAKvB;;;;;;qBAMF,+BAA+B;MAI7B;;;;;;;qBAMF,wBAAwB;MAItB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/Push.ts","../src/Deployment.ts","../src/Project.ts","../src/State.ts"],"mappings":";;;;;;;;;;;;;UA6BiB;;WAEN,aAAa,SAAS;;WAEtB;;UAGM;;WAEN,aAAa,OAAO,OAAO;;WAE3B,gBAAgB,OAAO;;WAEvB,WAAW,OAAO,OAAO,SAAS;;;qBAGhC,oBAAoB;;qBAKpB;;qBAGA;;;;qBAOA,yBAAyB;;;;;;;;;qBAiCzB,kBAAiB,MAAM,MAAM;;qBA0B7B,aAAc;WAChB,cAAc,SAAS;WACvB,YAAY,SAAS;MAC5B,MAAM,MAAM;;;KC3GJ,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;qBAQR,uBAAuB;UAuBnB;;WAEN,UAAU,GACjB,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,cACP,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,0BACxC,OAAO,aAAa;;WAEhB,oBAAoB,GAC3B,mBACA,6BACA,WAAW,SAAS,kBACpB,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,gBAAgB,0BAA0B,OAAO,eAAe;;;;;;;;WAQhE,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBClFtB,kBAAkB;;;;;;qBAOlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,8CAAA,mCAAA,oDAAA;;;;KC+BlE,oBAAoB,SAAS;;;;;KAM7B;;WAIG;;;;;;;;WAQA;;;;;;;WAOA;;;;;;qBAkCF,0BAA0B;MAIxB;;;;;;qBAMF,0BAA0B;MAIxB;;;;;;;;;qBAMF,uBAAuB;MAMrB;;;;;;;qBAQF,2BAA2B;MAIzB;;;;;;;qBAMF,oCAAoC;MAIlC;;;;;;qBAMF,kCAAkC;MAIhC;;;qBAuCF,oBACX;EACG;EAAa;;;;UChIR;;WAEC;aAAoB;;;;;;;;WAOpB,SAAS;;WAET,MAAM,SAAS,eAAe;;KAG7B,mBACP;;WAEU;MAEV;;WAEU;;;;;WAKA;;;UAIL;WACC;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;UAGM,6BAA6B;;WAEnC;;WAEA;;YAGC,aAAa,8BAEvB,iBACA,6BAEA;qBAEW,8BAAU,cAAA;;;;;;;;;qBAKV,iCAAiC;MAU/B;;;;;;qBAMF,qCAAqC;MAInC;;;;;;;;;qBAMF,4BAA4B;MAS1B;;;;;KC5IH,mBAAmB;KAEnB;;WAGG;;WAEA;;WAEA,mBAAmB;;WAEnB;;;WAIA;;WAEA;;UAGE;WACN;WACA;WACA;WACA;WACA;WACA;;YAGC,UAAU,2BAA2B,cAAc,0BAA0B;qBAC5E,2BAAO,cAAA;;;;;;;qBAGP,0BAA0B;MAIxB;;;;;;;;;;;;qBASF,gCAAgC;MAS9B;;;;;;;;qBAOF,yBAAyB;MAKvB;;;;;;qBAMF,+BAA+B;MAI7B;;;;;;;qBAMF,wBAAwB;MAItB;;;;;qBChDF;;;;;;;qBA8UA,QAAS;WACX;MACP,MAAM,MAAM,cAAc,oBAAoB"}

package/lib/index.js

@@ -25,6 +25,9 @@ import { hashDirectory } from "alchemy/Command/Memo";
 import * as Clock from "effect/Clock";
 import * as ChildProcess from "effect/process/ChildProcess";
 import * as Stream from "effect/Stream";
+import { fileURLToPath } from "node:url";
+import * as Scope from "effect/Scope";
+import { STATE_STORE_VERSION, State, StateStoreError, encodeState, reviveState } from "alchemy/State";
 //#region src/Credentials.ts
 var Credentials = class extends Context.Service()("@samebase/alchemy-convex/Credentials") {};
 /** Environment variable for the access token, read by {@link fromConfig}. */
@@ -226,7 +229,7 @@ const sourceOf = (source) => typeof source === "string" ? {
 };
 /** Lifetime of a push key. Long enough for a slow push with index backfills. */
 const PUSH_KEY_LIFETIME_MS = 72e5;
-/** The only actions a push key gets. */
+/** The only actions a key for `convex deploy` gets. */
 const PUSH_KEY_ACTIONS = [
 	"deployment:deploy",
 	"deployment:env:view",
@@ -328,7 +331,7 @@ const parseDeployOutput = (text) => {
 };
 /** The last non-empty lines of `text`, without escape codes and with every secret replaced. */
 const outputTail = (text, secrets) => secrets.reduce((redacted, secret) => redacted.split(secret).join("[REDACTED]"), stripVTControlCharacters(text)).split(/\r?\n|\r/).filter((line) => line.trim() !== "").slice(-20).join("\n");
-const valueOf = (value) => Redacted.isRedacted(value) ? Redacted.value(value) : value;
+const valueOf$1 = (value) => Redacted.isRedacted(value) ? Redacted.value(value) : value;
 /** The app directory: the nearest directory at or above the parent of `source` with a package.json. */
 const appDirectoryOf = (source) => Effect.tryPromise({
 	try: async () => {
@@ -396,7 +399,7 @@ const pushHash = (options) => Effect.gen(function* () {
 			lockfile: true
 		}
 	})));
-	const env = Object.entries(options.env).map(([name, value]) => [name, valueOf(value)]).sort(([a], [b]) => a < b ? -1 : 1);
+	const env = Object.entries(options.env).map(([name, value]) => [name, valueOf$1(value)]).sort(([a], [b]) => a < b ? -1 : 1);
 	return createHash("sha256").update(JSON.stringify({
 		files,
 		deployment: options.deployment,
@@ -423,29 +426,41 @@ const cliEnvironment = (home) => ({
 	XDG_CONFIG_HOME: home
 });
 /**
-* Creates a deploy key for one push, runs `use` with it, and deletes it
-* afterwards. Without a push command, the key can only deploy and read and
-* write variables. The delete is skipped for a key that is the OAuth credential.
-* A failed delete is logged: the key expires anyway.
+* A deploy key of `deployment` that expires after PUSH_KEY_LIFETIME_MS, with
+* only `allowedActions`, or every action when that is undefined. Delete it
+* with {@link deleteDeployKey} when the work is done.
 */
-const withPushKey = (api, deployment, source, use) => Effect.acquireUseRelease(Effect.gen(function* () {
+const createDeployKey = (api, deployment, name, allowedActions) => Effect.gen(function* () {
 	const now = yield* Clock.currentTimeMillis;
 	const created = yield* api.request("create deploy key", (client) => client.POST("/deployments/{deployment_name}/create_deploy_key", {
 		params: { path: { deployment_name: deployment } },
 		body: {
-			name: "alchemy-push",
-			...source === void 0 || sourceOf(source).command === void 0 ? { allowedActions: [...PUSH_KEY_ACTIONS] } : {},
+			name,
+			...allowedActions === void 0 ? {} : { allowedActions: [...allowedActions] },
 			expiresAt: now + PUSH_KEY_LIFETIME_MS
 		}
 	}));
 	return Redacted.make(Schema.decodeUnknownSync(CreatedDeployKey)(created).deployKey);
-}), use, (key) => Effect.gen(function* () {
+});
+/**
+* Deletes a key that {@link createDeployKey} made. The delete is skipped for
+* a key that is the OAuth credential. A failed delete is logged: the key
+* expires anyway.
+*/
+const deleteDeployKey = (api, deployment, key) => Effect.gen(function* () {
 	if (yield* api.isCredentialToken(Redacted.value(key))) return;
 	yield* absentAsUndefined(retryIdempotentWrite(api.requestVoid("delete deploy key", (client) => client.POST("/deployments/{deployment_name}/delete_deploy_key", {
 		params: { path: { deployment_name: deployment } },
 		body: { id: Redacted.value(key) }
 	}))));
-}).pipe(Effect.catch((error) => Effect.logWarning(`Convex.Deployment could not delete its push key on ${deployment} (${error.message}). The key expires on its own within ${PUSH_KEY_LIFETIME_MS / 6e4} minutes.`))));
+}).pipe(Effect.catch((error) => Effect.logWarning(`Convex.Deployment could not delete its key on ${deployment} (${error.message}). The key expires on its own within ${PUSH_KEY_LIFETIME_MS / 6e4} minutes.`)));
+/**
+* Creates a deploy key for one push, runs `use` with it, and deletes it
+* afterwards, also after a failure. `allowedActions` is PUSH_KEY_ACTIONS for
+* `convex deploy`, or undefined for a push command, which can do more than a
+* push, such as the uploads of convex-hosting through `convex run`.
+*/
+const withPushKey = (api, deployment, allowedActions, use) => Effect.acquireUseRelease(createDeployKey(api, deployment, "alchemy-push", allowedActions), use, (key) => deleteDeployKey(api, deployment, key));
 /** Every variable of the deployment with its value. */
 const listVariables = (url, key) => settle("list environment variables", () => createDeploymentClient(url, Redacted.value(key)).GET("/list_environment_variables")).pipe(Effect.map((body) => Schema.decodeUnknownSync(EnvironmentVariableList)(body).environmentVariables));
 /** One call that sets variables, or removes those whose value is null. */
@@ -486,15 +501,15 @@ const push = (spawner, key, options) => Effect.gen(function* () {
 	} : yield* retryIdempotentWrite(Effect.gen(function* () {
 		const current = yield* listVariables(options.url, key);
 		if (!options.adopt) {
-			const taken = env.filter(([name, value]) => !options.previousEnvNames.includes(name) && Object.hasOwn(current, name) && current[name] !== valueOf(value)).map(([name]) => name);
+			const taken = env.filter(([name, value]) => !options.previousEnvNames.includes(name) && Object.hasOwn(current, name) && current[name] !== valueOf$1(value)).map(([name]) => name);
 			if (taken.length > 0) return yield* new VariablesOwnedBySomeoneElse({
 				deployment: options.deployment,
 				names: taken
 			});
 		}
-		const changes = [...env.filter(([name, value]) => current[name] !== valueOf(value)).map(([name, value]) => ({
+		const changes = [...env.filter(([name, value]) => current[name] !== valueOf$1(value)).map(([name, value]) => ({
 			name,
-			value: valueOf(value)
+			value: valueOf$1(value)
 		})), ...removed.filter((name) => Object.hasOwn(current, name)).map((name) => ({
 			name,
 			value: null
@@ -933,7 +948,7 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 			}) : access.kind === "previewKey" ? push(spawner, access.key, {
 				...options,
 				previewName: target.previewName
-			}) : withPushKey(access.api, target.name, news.source, (key) => push(spawner, key, {
+			}) : withPushKey(access.api, target.name, typeof news.source === "object" && news.source.command !== void 0 ? void 0 : PUSH_KEY_ACTIONS, (key) => push(spawner, key, {
 				...options,
 				previewName: void 0
 			}))).pipe(Effect.onError(() => created && access.kind !== "deployKey" ? absentAsUndefined(retryIdempotentWrite(access.api.requestVoid("delete deployment", (client) => client.POST("/deployments/{deployment_name}/delete", { params: { path: { deployment_name: target.name } } })))).pipe(Effect.catch((error) => Effect.logWarning(`Convex.Deployment could not delete ${target.name} after the failed push (${error.message}). The next run takes it over only with --adopt.`))) : Effect.void));
@@ -1041,7 +1056,9 @@ const DeploymentRow = Schema.Struct({
 	name: Schema.String,
 	deploymentType: Schema.String,
 	isDefault: Schema.Boolean,
-	deploymentUrl: Schema.String
+	deploymentUrl: Schema.String,
+	/** Absent or null until the first push. */
+	lastDeployTime: Schema.optionalKey(Schema.NullOr(Schema.Number))
 });
 const DeploymentRows = Schema.Array(DeploymentRow);
 /**
@@ -1067,10 +1084,71 @@ const checkCreateTimeProps = (projectId, olds, news) => {
 };
 /** True when `team`, a slug or a numeric id, names the team of the project. */
 const isTeamOf = (details, team) => typeof team === "number" || /^\d+$/.test(team) ? details.teamId === Number(team) : details.teamSlug === team;
+/** The row of the project's default production deployment, or undefined. */
+const prodDeploymentOf = (api, projectId) => api.request("list deployments", (client) => client.GET("/projects/{project_id}/list_deployments", { params: { path: { project_id: projectId } } })).pipe(Effect.map((rows) => Schema.decodeUnknownSync(DeploymentRows)(rows).find((row) => row.deploymentType === "prod" && row.isDefault)));
+/** GET /projects/{id}, or undefined after a 404. */
+const getProjectById = (api, projectId) => absentAsUndefined(api.request("get project", (client) => client.GET("/projects/{project_id}", { params: { path: { project_id: projectId } } }))).pipe(Effect.map((body) => body === void 0 ? void 0 : Schema.decodeUnknownSync(ProjectDetails)(body)));
+/**
+* Every project in the team with exactly this name, in the order of the
+* listing. Reads every page. `q` narrows the listing on the server, and the
+* exact match here decides. Pattern from Confect
+* `packages/alchemy/src/ConvexClient.ts` and `Project.ts`
+* (https://github.com/rjdellecese/confect, ISC license).
+*/
+const listProjectsByName = (api, teamId, name) => Effect.gen(function* () {
+	const matches = [];
+	const seenCursors = /* @__PURE__ */ new Set();
+	let cursor;
+	while (true) {
+		const body = yield* api.request("list projects", (client) => client.GET("/teams/{team_id}/projects", { params: {
+			path: { team_id: teamId },
+			query: {
+				q: name,
+				...cursor === void 0 ? {} : { cursor }
+			}
+		} }));
+		const page = Schema.decodeUnknownSync(ProjectPage)(body);
+		matches.push(...page.items.filter((row) => row.name === name));
+		if (!page.pagination.hasMore) break;
+		const next = page.pagination.nextCursor;
+		if (next === void 0 || next === null || seenCursors.has(next)) return yield* new ConvexApiError({
+			operation: "list projects",
+			status: 0,
+			code: "InvalidPagination",
+			message: `The project listing of team ${teamId} reports more pages but gives no new cursor. Convex.Project stops so that it does not miss a project named "${name}".`
+		});
+		seenCursors.add(next);
+		cursor = next;
+	}
+	return matches;
+});
+/** The one project in the team with exactly this name, or undefined. More than one is an error. */
+const findProjectByName = (api, teamId, name) => listProjectsByName(api, teamId, name).pipe(Effect.flatMap((matches) => matches.length > 1 ? new AmbiguousProject({
+	teamId,
+	name,
+	projectIds: matches.map((row) => row.id)
+}) : Effect.succeed(matches[0])));
+/**
+* POST /teams/{team_id}/create_project, then GET /projects/{id}. The identity
+* comes from the create response, never from a name lookup.
+*/
+const createProject = (api, teamId, props) => Effect.gen(function* () {
+	const created = yield* api.request("create project", (client) => client.POST("/teams/{team_id}/create_project", {
+		params: { path: { team_id: teamId } },
+		body: {
+			projectName: props.name,
+			deploymentType: props.deploymentType,
+			...props.deploymentRegion === void 0 ? {} : { deploymentRegion: props.deploymentRegion }
+		}
+	}));
+	const { projectId } = Schema.decodeUnknownSync(CreatedProject)(created);
+	const details = yield* getProjectById(api, projectId);
+	if (details === void 0) return yield* new CreatedProjectNotFound({ projectId });
+	return details;
+});
 const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 	const api = yield* ManagementApi;
-	const prodDeployment = (projectId) => api.request("list deployments", (client) => client.GET("/projects/{project_id}/list_deployments", { params: { path: { project_id: projectId } } })).pipe(Effect.map((rows) => Schema.decodeUnknownSync(DeploymentRows)(rows).find((row) => row.deploymentType === "prod" && row.isDefault)));
-	const attributesOf = (details) => prodDeployment(details.id).pipe(Effect.map((prod) => ({
+	const attributesOf = (details) => prodDeploymentOf(api, details.id).pipe(Effect.map((prod) => ({
 		projectId: details.id,
 		slug: details.slug,
 		name: details.name,
@@ -1078,51 +1156,13 @@ const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 		prodDeploymentName: prod?.name ?? details.prodDeploymentName ?? void 0,
 		prodDeploymentUrl: prod?.deploymentUrl
 	})));
-	const getById = (projectId) => absentAsUndefined(api.request("get project", (client) => client.GET("/projects/{project_id}", { params: { path: { project_id: projectId } } }))).pipe(Effect.map((body) => body === void 0 ? void 0 : Schema.decodeUnknownSync(ProjectDetails)(body)));
+	const getById = (projectId) => getProjectById(api, projectId);
 	/** The project with this slug in the team, or undefined. Official endpoint; the team can be a slug. */
 	const getBySlug = (team, slug) => absentAsUndefined(api.request("get project by slug", (client) => client.GET("/teams/{team_id_or_slug}/projects/{project_slug}", { params: { path: {
 		team_id_or_slug: String(team),
 		project_slug: slug
 	} } }))).pipe(Effect.map((body) => body === void 0 ? void 0 : Schema.decodeUnknownSync(ProjectDetails)(body)));
-	/**
-	* The one project in the team with exactly this name, or undefined.
-	* Reads every page. `q` narrows the listing on the server, and the
-	* exact match here decides. Pattern from Confect
-	* `packages/alchemy/src/ConvexClient.ts` and `Project.ts`
-	* (https://github.com/rjdellecese/confect, ISC license).
-	*/
-	const findByName = (teamId, name) => Effect.gen(function* () {
-		const matches = [];
-		const seenCursors = /* @__PURE__ */ new Set();
-		let cursor;
-		while (true) {
-			const body = yield* api.request("list projects", (client) => client.GET("/teams/{team_id}/projects", { params: {
-				path: { team_id: teamId },
-				query: {
-					q: name,
-					...cursor === void 0 ? {} : { cursor }
-				}
-			} }));
-			const page = Schema.decodeUnknownSync(ProjectPage)(body);
-			matches.push(...page.items.filter((row) => row.name === name));
-			if (!page.pagination.hasMore) break;
-			const next = page.pagination.nextCursor;
-			if (next === void 0 || next === null || seenCursors.has(next)) return yield* new ConvexApiError({
-				operation: "list projects",
-				status: 0,
-				code: "InvalidPagination",
-				message: `The project listing of team ${teamId} reports more pages but gives no new cursor. Convex.Project stops so that it does not miss a project named "${name}".`
-			});
-			seenCursors.add(next);
-			cursor = next;
-		}
-		if (matches.length > 1) return yield* new AmbiguousProject({
-			teamId,
-			name,
-			projectIds: matches.map((row) => row.id)
-		});
-		return matches[0];
-	});
+	const findByName = (teamId, name) => findProjectByName(api, teamId, name);
 	/**
 	* Brings an existing project to the desired name. The team cannot
 	* change, so a project in another team fails.
@@ -1228,17 +1268,11 @@ const ProjectProvider = () => Provider.effect(Project, Effect.gen(function* () {
 					return yield* converge(existing, teamId, news.name);
 				}
 			}
-			const created = yield* api.request("create project", (client) => client.POST("/teams/{team_id}/create_project", {
-				params: { path: { team_id: teamId } },
-				body: {
-					projectName: news.name,
-					deploymentType: news.deploymentType ?? "prod",
-					...news.deploymentRegion === void 0 ? {} : { deploymentRegion: news.deploymentRegion }
-				}
-			}));
-			const { projectId } = Schema.decodeUnknownSync(CreatedProject)(created);
-			const details = yield* getById(projectId);
-			if (details === void 0) return yield* new CreatedProjectNotFound({ projectId });
+			const details = yield* createProject(api, teamId, {
+				name: news.name,
+				deploymentType: news.deploymentType ?? "prod",
+				deploymentRegion: news.deploymentRegion
+			});
 			return yield* converge(details, teamId, news.name);
 		}),
 		delete: Effect.fn(function* ({ output }) {
@@ -1256,6 +1290,235 @@ var Providers = class extends Provider.ProviderCollection()("Convex") {};
 */
 const providers = (credentials = fromConfig()) => Layer.effect(Providers, Provider.collection([Project, Deployment])).pipe(Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider())), Layer.provide(ManagementApiLive()), Layer.provide(credentials), Layer.orDie);
 //#endregion
-export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectNotFound, ProjectTeamChange, Providers, PushTargetMismatch, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers };
+//#region src/State.ts
+/** The name of the state project in each team. */
+const STORE_PROJECT_NAME = "alchemy-state";
+/**
+* The actions of the key of one run: the internal queries and mutations of
+* the store, nothing else. Measured: `deployment:data:view` and
+* `deployment:data:write` do not run an internal function.
+*/
+const RUN_KEY_ACTIONS = ["deployment:functions:runInternalQueries", "deployment:functions:runInternalMutations"];
+/** The body of POST /api/function, with HTTP 200 for a function error too. */
+const Reply = Schema.Union([Schema.Struct({
+	status: Schema.Literal("success"),
+	value: Schema.Unknown
+}), Schema.Struct({
+	status: Schema.Literal("error"),
+	errorMessage: Schema.String
+})]);
+/** The error reply of /api/function for a function that the deployment does not have (recorded). */
+const MISSING_FUNCTION = /Could not find function for '/;
+/** HTTP 401 or 403 from the function API: the key is gone or expired (recorded: 403 without a key). */
+const isUnauthorized = (error) => error.http?.status === 401 || error.http?.status === 403;
+const failure = (message) => new StateStoreError({ message: `Convex state: ${message}` });
+/** No reply, HTTP 429, or HTTP 5xx: a new attempt can succeed. Every call of the store is idempotent. */
+const isTransient = (error) => error.http !== void 0 && (error.http.status === void 0 || error.http.status === 429 || error.http.status >= 500);
+const post = (url, headers, body) => Effect.tryPromise({
+	try: () => fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			...headers
+		},
+		body: JSON.stringify(body)
+	}),
+	catch: () => new StateStoreError({
+		message: `Convex state: POST ${url} failed`,
+		http: {}
+	})
+}).pipe(Effect.flatMap((response) => response.ok || response.status === 560 ? Effect.tryPromise({
+	try: () => response.json(),
+	catch: () => failure(`${url} gave no JSON`)
+}) : Effect.fail(new StateStoreError({
+	message: `Convex state: POST ${url} failed with HTTP ${response.status}`,
+	http: { status: response.status }
+}))), Effect.retry({
+	while: isTransient,
+	schedule: Schedule.exponential("100 millis").pipe(Schedule.jittered),
+	times: 5
+}));
+const decode = (schema, what) => (value) => Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(() => failure(`bad ${what}`)));
+const makeFunctionApi = (url, key) => ({ call: (path, args) => post(`${url}/api/function`, { Authorization: `Convex ${Redacted.value(key)}` }, {
+	path,
+	args,
+	format: "json"
+}).pipe(Effect.flatMap(decode(Reply, `reply of ${path}`))) });
+/** The value of a reply, or the Convex message, which names the function and the cause, such as a missing key action. */
+const valueOf = (reply) => reply.status === "success" ? Effect.succeed(reply.value) : Effect.fail(failure(reply.errorMessage.trim()));
+/** The functions of the store with Alchemy's encoding: the JSON text of encodeState. */
+const remoteOf = (api) => {
+	const run = (name, args) => api.call(`state:${name}`, args).pipe(Effect.flatMap(valueOf));
+	const strings = (name, args) => run(name, args).pipe(Effect.flatMap(decode(Schema.Array(Schema.String), name)));
+	const optional = (name, args) => run(name, args).pipe(Effect.flatMap(decode(Schema.NullOr(Schema.String), name)));
+	const encode = (value) => JSON.stringify(encodeState(value));
+	return {
+		listStacks: () => strings("stacks", {}),
+		listStages: (stack) => strings("stages", { stack }),
+		list: (r) => strings("list", {
+			stack: r.stack,
+			stage: r.stage
+		}),
+		get: (r) => optional("get", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn
+		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
+		getReplacedResources: (r) => strings("replaced", {
+			stack: r.stack,
+			stage: r.stage
+		}).pipe(Effect.map((texts) => texts.map((text) => JSON.parse(text, reviveState)))),
+		getOutput: (r) => optional("getOutput", {
+			stack: r.stack,
+			stage: r.stage
+		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
+		set: (r) => run("set", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn,
+			value: encode(r.value)
+		}),
+		delete: (r) => run("remove", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn
+		}),
+		deleteStack: (r) => run("removeStack", {
+			stack: r.stack,
+			stage: r.stage
+		}),
+		setOutput: (r) => run("setOutput", {
+			stack: r.stack,
+			stage: r.stage,
+			value: encode(r.value)
+		})
+	};
+};
+/** The version that the store answers, or undefined when the deployment has no `state:version`. */
+const storeVersion = (api) => api.call("state:version", {}).pipe(Effect.flatMap((reply) => reply.status === "error" && MISSING_FUNCTION.test(reply.errorMessage) ? Effect.succeed(void 0) : valueOf(reply).pipe(Effect.flatMap(decode(Schema.Number, "store version")))));
+/**
+* The functions directory of the store app, `src/store/convex` of this
+* package. This file is `src/State.ts` in a checkout and a chunk in `lib/`
+* in the installed package, which ships `src` too, so the directory is
+* `../src/store/convex` from either place.
+*/
+const storeDirectory = () => join(dirname(fileURLToPath(import.meta.url)), "..", "src", "store", "convex");
+/**
+* Pushes `store` to the production deployment of the state project with the
+* installed Convex CLI: no typecheck, no codegen, the key only in the
+* environment of the CLI.
+*/
+const pushStore = (options, deployment) => Effect.gen(function* () {
+	const cli = yield* installedCli(join(options.store, ".."));
+	yield* Effect.logInfo(`Convex state: pushing the store version 1 to ${deployment.name}`);
+	yield* withPushKey(options.api, deployment.name, PUSH_KEY_ACTIONS, (key) => push(options.spawner, key, {
+		deployment: deployment.name,
+		url: deployment.deploymentUrl,
+		source: {
+			path: options.store,
+			command: [
+				...cli,
+				"deploy",
+				"--typecheck",
+				"disable",
+				"--codegen",
+				"disable"
+			]
+		},
+		env: {},
+		previousEnvNames: [],
+		adopt: false,
+		previewName: void 0
+	}));
+});
+/**
+* Creates the state project of the team. Two first runs can both create one:
+* the run whose project is not the oldest deletes its own, which holds
+* nothing yet, and uses the oldest, so that every run ends on one store.
+*/
+const createStoreProject = (api, teamId, team) => Effect.gen(function* () {
+	yield* Effect.logInfo(`Convex state: creating the project ${STORE_PROJECT_NAME} in team ${team}`);
+	const created = yield* createProject(api, teamId, {
+		name: STORE_PROJECT_NAME,
+		deploymentType: "prod",
+		deploymentRegion: void 0
+	});
+	const oldest = (yield* listProjectsByName(api, teamId, STORE_PROJECT_NAME)).reduce((a, b) => b.id < a.id ? b : a, created);
+	if (oldest.id === created.id) return created;
+	yield* Effect.logInfo(`Convex state: another run created ${STORE_PROJECT_NAME} ${oldest.id} first; project ${created.id} is deleted again.`);
+	yield* absentAsUndefined(retryIdempotentWrite(api.requestVoid("delete project", (client) => client.POST("/projects/{project_id}/delete", { params: { path: { project_id: created.id } } }))));
+	return oldest;
+});
+/**
+* The StateService over the `alchemy-state` project of the team: found or
+* created, its store pushed when it is missing or older, and read and
+* written with the keys of this run.
+*/
+const makeConvexState = (options) => Effect.gen(function* () {
+	const { api, team } = options;
+	const teamId = yield* api.resolveTeamId(team);
+	const project = (yield* findProjectByName(api, teamId, "alchemy-state")) ?? (yield* createStoreProject(api, teamId, team));
+	const deployment = yield* prodDeploymentOf(api, project.id);
+	if (deployment === void 0) return yield* new ProductionDeploymentNotFound({ projectId: project.id });
+	const keys = [];
+	yield* Scope.addFinalizer(options.scope, Effect.suspend(() => Effect.forEach(keys, (key) => deleteDeployKey(api, deployment.name, key), { discard: true })));
+	const mint = createDeployKey(api, deployment.name, "alchemy-state", RUN_KEY_ACTIONS).pipe(Effect.map((key) => {
+		keys.push(key);
+		return makeFunctionApi(deployment.deploymentUrl, key);
+	}), Effect.mapError((error) => failure(`no key for ${deployment.name}: ${error.message}`)));
+	let current = yield* mint;
+	const functions = { call: (path, args) => current.call(path, args).pipe(Effect.catchIf(isUnauthorized, () => mint.pipe(Effect.flatMap((next) => {
+		current = next;
+		return next.call(path, args);
+	})))) };
+	const version = yield* storeVersion(functions);
+	if (version === void 0 || version < 1) {
+		if (version === void 0 && deployment.lastDeployTime) return yield* failure(`project ${STORE_PROJECT_NAME} (${project.id}) of team ${team} has code that is not the state store, and Convex.state does not push over it. Rename that project in the Convex dashboard.`);
+		const now = yield* storeVersion(functions);
+		if (now === void 0 || now < 1) {
+			yield* pushStore(options, deployment);
+			const pushed = yield* storeVersion(functions);
+			if (pushed === void 0 || pushed < 1) return yield* failure(`${deployment.name} answers store version ${pushed ?? "none"} after the push of version 1.`);
+		}
+	} else if (version > 1) yield* Effect.logInfo(`Convex state: the store of team ${team} is version ${version}, newer than version 1 of this package, and it stays.`);
+	const remote = remoteOf(functions);
+	return {
+		id: "convex",
+		getVersion: () => Effect.succeed(STATE_STORE_VERSION),
+		listStacks: remote.listStacks,
+		listStages: remote.listStages,
+		list: remote.list,
+		get: remote.get,
+		getReplacedResources: remote.getReplacedResources,
+		getOutput: remote.getOutput,
+		set: (request) => remote.set(request).pipe(Effect.as(request.value)),
+		delete: (request) => remote.delete(request).pipe(Effect.asVoid),
+		deleteStack: (request) => remote.deleteStack(request).pipe(Effect.asVoid),
+		setOutput: (request) => remote.setOutput(request).pipe(Effect.as(request.value))
+	};
+});
+/**
+* Alchemy state in the `alchemy-state` project of `team`, with the team token
+* in CONVEX_ACCESS_TOKEN or the Convex CLI login. The first use of the run
+* finds or creates the project and pushes the store when it is missing or
+* older. `alchemy plan` on another stack never touches Convex.
+*/
+const state = (options) => Layer.effect(State, Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const scope = yield* Scope.Scope;
+	const context = yield* Effect.context();
+	return yield* Effect.cached(Effect.gen(function* () {
+		const api = yield* ManagementApi.pipe(Effect.provide(ManagementApiLive().pipe(Layer.provide(fromConfig()))));
+		return yield* makeConvexState({
+			team: options.team,
+			api,
+			spawner,
+			scope,
+			store: storeDirectory()
+		});
+	}).pipe(Effect.provideContext(context), Effect.orDie));
+}));
+//#endregion
+export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectNotFound, ProjectTeamChange, Providers, PushTargetMismatch, STORE_PROJECT_NAME, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers, state };
 
 //# sourceMappingURL=index.js.map