@samebase/alchemy-convex 0.6.1 → 0.8.0

package/lib/index.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
-import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { access, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, posix, relative, resolve, sep, win32 } from "node:path";
 import * as Config from "effect/Config";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
@@ -20,11 +20,12 @@ import { Stack } from "alchemy/Stack";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
 import * as Schedule from "effect/Schedule";
 import { createHash } from "node:crypto";
-import { stripVTControlCharacters } from "node:util";
+import { promisify, stripVTControlCharacters } from "node:util";
 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 { execFile } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import * as Scope from "effect/Scope";
 import { STATE_STORE_VERSION, State, StateStoreError, encodeState, reviveState } from "alchemy/State";
@@ -281,13 +282,15 @@ const EnvironmentVariableList = Schema.Struct({ environmentVariables: Schema.Rec
 /** No `convex` package resolves from the app directory. */
 var ConvexCliNotFound = class extends Schema.TaggedError()("ConvexCliNotFound", { cwd: Schema.String }) {
 	get message() {
-		return `Convex.Deployment found no installed convex package from ${this.cwd}, and it does not download one. Install convex in the app (npm install convex), or set source to the functions directory of the app.`;
+		return `Convex.Deployment found no installed convex package from ${this.cwd}, and it does not download one. Install convex in the app (npm install convex), or set rootDir to the directory of the app.`;
 	}
 };
-/** No directory at or above the parent of `source` has a package.json. */
-var ConvexAppNotFound = class extends Schema.TaggedError()("ConvexAppNotFound", { source: Schema.String }) {
+/** The app directory (`rootDir`) has no package.json. */
+var ConvexAppNotFound = class extends Schema.TaggedError()("ConvexAppNotFound", { 
+/** The app directory, resolved against the working directory of the deploy. */
+rootDir: Schema.String }) {
 	get message() {
-		return `Convex.Deployment found no package.json at or above the parent of ${this.source}. Set source to the functions directory of a Convex app, such as "./convex".`;
+		return `Convex.Deployment found no package.json in ${this.rootDir}. Set rootDir to the directory of the Convex app, relative to the directory where the deploy runs, such as "apps/web".`;
 	}
 };
 /** The Convex CLI failed, or exited 0 without the deployment URL. The output tail never contains the key. */
@@ -371,28 +374,26 @@ 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$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 () => {
-		let directory = dirname(resolve(source));
-		while (true) try {
-			await access(join(directory, "package.json"));
-			return directory;
-		} catch {
-			const parent = dirname(directory);
-			if (parent === directory) throw new Error("no package.json");
-			directory = parent;
-		}
-	},
-	catch: () => new ConvexAppNotFound({ source })
-});
-/** `source` is not the functions directory that the Convex CLI pushes from this app. */
+/**
+* The app directory: `rootDir` resolved against the working directory of the
+* deploy. It must have a package.json. There is no search above it.
+*/
+const appDirectoryOf = (rootDir) => {
+	const directory = resolve(rootDir);
+	return Effect.tryPromise({
+		try: () => access(join(directory, "package.json")).then(() => directory),
+		catch: () => new ConvexAppNotFound({ rootDir: directory })
+	});
+};
+/** `source` is not the functions directory that the Convex CLI pushes from the app directory. */
 var SourceMismatch = class extends Schema.TaggedError()("SourceMismatch", {
+	/** The app directory, resolved. */
+	rootDir: Schema.String,
 	source: Schema.String,
 	functions: Schema.String
 }) {
 	get message() {
-		return `Convex.Deployment source is ${this.source}, but the Convex CLI pushes ${this.functions} in this app (the "functions" field of convex.json, or convex/ by default). Set source to ${this.functions}.`;
+		return `Convex.Deployment source is ${this.source}, but the Convex CLI pushes ${this.functions} from the app directory ${this.rootDir} (the "functions" field of convex.json, or convex/ by default). Set rootDir to the directory of the Convex app, and source to its functions directory relative to rootDir, such as "./convex".`;
 	}
 };
 const ConvexJson = Schema.Struct({ functions: Schema.optionalKey(Schema.String) });
@@ -401,8 +402,9 @@ const checkFunctionsDirectory = (cwd, path) => Effect.gen(function* () {
 	const text = yield* Effect.promise(() => readFile(join(cwd, "convex.json"), "utf8").catch(() => void 0));
 	const configured = text === void 0 ? void 0 : Schema.decodeUnknownSync(Schema.fromJsonString(ConvexJson))(text).functions;
 	const functions = resolve(cwd, configured ?? "convex");
-	if (functions !== resolve(path)) return yield* new SourceMismatch({
-		source: resolve(path),
+	if (functions !== path) return yield* new SourceMismatch({
+		rootDir: cwd,
+		source: path,
 		functions
 	});
 });
@@ -426,18 +428,24 @@ const installedCli = (cwd) => Effect.tryPromise({
 */
 const pushHash = (options) => Effect.gen(function* () {
 	const source = options.source === void 0 ? void 0 : sourceOf(options.source);
-	const files = source === void 0 ? void 0 : yield* appDirectoryOf(source.path).pipe(Effect.flatMap((cwd) => hashDirectory({
-		cwd,
-		memo: source.include === void 0 ? {} : {
-			include: [
-				`${relative(cwd, resolve(source.path)).split("\\").join("/")}/**`,
-				"package.json",
-				"convex.json",
-				...source.include
-			],
-			lockfile: true
-		}
-	})));
+	const files = source === void 0 ? void 0 : yield* appDirectoryOf(options.rootDir).pipe(Effect.flatMap((cwd) => {
+		const functions = relative(cwd, resolve(cwd, source.path)).split("\\").join("/");
+		return hashDirectory({
+			cwd,
+			memo: source.include !== void 0 ? {
+				include: [
+					`${functions}/**`,
+					"package.json",
+					"convex.json",
+					...source.include
+				],
+				lockfile: true
+			} : functions === ".." || functions.startsWith("../") ? {
+				include: ["**/*", `${functions}/**`],
+				lockfile: true
+			} : {}
+		});
+	}));
 	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,
@@ -509,13 +517,13 @@ const writeVariables = (url, key, changes) => settleVoid("update environment var
 })) } }));
 /**
 * The app directory and the program of a push. Fails before any change when
-* `source` is not the functions directory of the app, or when the app has no
-* installed Convex CLI and no push command.
+* `rootDir` has no package.json, when `source` is not the functions directory
+* of the app, or when the app has no installed Convex CLI and no push command.
 */
-const checkSource = (input) => Effect.gen(function* () {
+const checkSource = (rootDir, input) => Effect.gen(function* () {
 	const source = sourceOf(input);
-	const cwd = yield* appDirectoryOf(source.path);
-	yield* checkFunctionsDirectory(cwd, source.path);
+	const cwd = yield* appDirectoryOf(rootDir);
+	yield* checkFunctionsDirectory(cwd, resolve(cwd, source.path));
 	return {
 		cwd,
 		program: source.command ?? (yield* installedCli(cwd))
@@ -529,7 +537,7 @@ const checkSource = (input) => Effect.gen(function* () {
 */
 const push = (spawner, key, options) => Effect.gen(function* () {
 	const source = options.source === void 0 ? void 0 : sourceOf(options.source);
-	const resolved = options.source === void 0 ? void 0 : yield* checkSource(options.source);
+	const resolved = options.source === void 0 ? void 0 : yield* checkSource(options.rootDir, options.source);
 	const cwd = resolved?.cwd;
 	const program = resolved?.program;
 	const env = Object.entries(options.env).sort(([a], [b]) => a < b ? -1 : 1);
@@ -627,7 +635,43 @@ const runPush = (spawner, key, options) => Effect.gen(function* () {
 });
 //#endregion
 //#region src/Deployment.ts
-const Deployment = Resource("Convex.Deployment", { defaultRemovalPolicy: "retain" });
+/** The resource class. Stacks call {@link Deployment}, which writes `rootDir` into the props. */
+const DeploymentResource = Resource("Convex.Deployment", { defaultRemovalPolicy: "retain" });
+/** `rootDir` in POSIX form, without "./" and a trailing slash, such as `apps/web` or ".". */
+const normalizeRootDir = (rootDir) => {
+	const normalized = posix.normalize(rootDir.replaceAll("\\", "/"));
+	return normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+};
+/** `rootDir` is an absolute path. The declaration stops with it as a defect, before the plan. */
+var AbsoluteRootDir = class extends Schema.TaggedError()("AbsoluteRootDir", { rootDir: Schema.String }) {
+	get message() {
+		return `Convex.Deployment rootDir ${this.rootDir} is an absolute path. State keeps rootDir for every machine that runs the stack, so set it relative to the directory where the deploy runs, such as "apps/web".`;
+	}
+};
+/**
+* `Convex.Deployment("id", props)`. The props go to state with `rootDir` in
+* POSIX form, and with "." when it is not set, so that every row names the
+* app directory of its deployment. An absolute `rootDir` stops the
+* declaration, so it never reaches the plan or state. The check dies,
+* because the program of `Alchemy.Stack` can fail only with a ConfigError.
+* `win32.isAbsolute` also answers true for a POSIX absolute path. The other
+* fields keep it usable where Alchemy takes a resource class, such as
+* `Provider.collection`.
+*/
+const Deployment = Object.assign((id, props) => {
+	const rootDir = props.rootDir ?? ".";
+	return win32.isAbsolute(rootDir) ? Effect.die(new AbsoluteRootDir({ rootDir })) : DeploymentResource(id, {
+		...props,
+		rootDir: normalizeRootDir(rootDir)
+	});
+}, {
+	Type: DeploymentResource.Type,
+	Props: DeploymentResource.Props,
+	Self: DeploymentResource.Self,
+	Provider: DeploymentResource.Provider,
+	Aliases: DeploymentResource.Aliases,
+	ref: (id, options) => DeploymentResource.ref(id, options)
+});
 /** The props name another deployment than the one in state. */
 var DeploymentIdentityChange = class extends Schema.TaggedError()("DeploymentIdentityChange", {
 	/** Name of the deployment in state, such as `happy-animal-123`. */
@@ -749,7 +793,7 @@ const ProjectSlugs = Schema.Struct({
 });
 /** True for an answer that says this credential cannot read the object. */
 const isRefused = (error) => error.status === 400 || error.status === 401 || error.status === 403 || error.status === 404;
-const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function* () {
+const DeploymentProvider = () => Provider.effect(DeploymentResource, Effect.gen(function* () {
 	const api = yield* ManagementApi;
 	const credentials = yield* Credentials;
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -842,7 +886,8 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 		return row === void 0 ? void 0 : targetOf(row, output.type, output.previewName);
 	});
 	/** The content identity of `source` and `env` on a deployment, or undefined when there is nothing to push. */
-	const wantedHash = (news, deployment) => news.source === void 0 && Object.keys(news.env ?? {}).length === 0 ? Effect.succeed(void 0) : pushHash({
+	const wantedHash = (news, rootDir, deployment) => news.source === void 0 && Object.keys(news.env ?? {}).length === 0 ? Effect.succeed(void 0) : pushHash({
+		rootDir,
 		source: news.source,
 		deployment,
 		env: news.env ?? {}
@@ -853,12 +898,15 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 			"type",
 			"previewName"
 		],
-		diff: Effect.fn(function* ({ news, output }) {
+		diff: Effect.fn(function* ({ news, olds, output }) {
 			if (!isResolved(news) || output === void 0) return void 0;
 			yield* checkIdentity(output, news);
+			const rootDir = news.rootDir ?? ".";
+			if (news.source !== void 0) yield* checkSource(rootDir, news.source);
+			if (olds.rootDir !== rootDir) return { action: "update" };
 			const access = yield* accessFor(addressOf(news), changesEnv(news, output));
 			if ((yield* live(access, output))?.name !== output.name) return { action: "update" };
-			return (yield* wantedHash(news, output.name)) === output.hash ? { action: "noop" } : { action: "update" };
+			return (yield* wantedHash(news, rootDir, output.name)) === output.hash ? { action: "noop" } : { action: "update" };
 		}),
 		read: Effect.fn(function* ({ olds, output }) {
 			if (output !== void 0) {
@@ -896,7 +944,8 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 		}),
 		reconcile: Effect.fn(function* ({ fqn, news, output }) {
 			if (output !== void 0) yield* checkIdentity(output, news);
-			if (news.source !== void 0) yield* checkSource(news.source);
+			const rootDir = news.rootDir ?? ".";
+			if (news.source !== void 0) yield* checkSource(rootDir, news.source);
 			const address = addressOf(news);
 			const access = yield* accessFor(address, changesEnv(news, output));
 			const env = news.env ?? {};
@@ -904,7 +953,7 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 			const adopt = yield* shouldAdopt(fqn);
 			const refuse = (name) => new OwnedBySomeoneElse({
 				message: `Project ${address.projectId} already has ${news.type} deployment ${name}${news.type === "prod" ? " with code" : ` named "${news.name}"`}. Re-run with --adopt to take it over${news.type === "prod" ? "" : ", or use another name"}.`,
-				resourceType: Deployment.Type,
+				resourceType: DeploymentResource.Type,
 				physicalName: name
 			});
 			const { target, created } = yield* Effect.gen(function* () {
@@ -962,7 +1011,7 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 				};
 			});
 			const previousEnvNames = output?.name === target.name ? envNamesOf(output) : [];
-			const before = yield* wantedHash(news, target.name);
+			const before = yield* wantedHash(news, rootDir, target.name);
 			if (before === void 0 && previousEnvNames.length === 0) return {
 				...target,
 				hash: void 0,
@@ -976,6 +1025,7 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 			const options = {
 				deployment: target.name,
 				url: target.url,
+				rootDir,
 				source: news.source,
 				env,
 				previousEnvNames,
@@ -993,7 +1043,7 @@ const DeploymentProvider = () => Provider.effect(Deployment, Effect.gen(function
 			}))).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));
 			return {
 				...target,
-				hash: yield* wantedHash(news, target.name),
+				hash: yield* wantedHash(news, rootDir, target.name),
 				envNames: Object.keys(env).sort()
 			};
 		}),
@@ -1327,7 +1377,126 @@ var Providers = class extends Provider.ProviderCollection()("Convex") {};
 * default lookup (`CONVEX_ACCESS_TOKEN`, then the Convex CLI login, and
 * `CONVEX_DEPLOY_KEY`).
 */
-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);
+const providers = (credentials = fromConfig()) => Layer.effect(Providers, Provider.collection([Project, DeploymentResource])).pipe(Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider())), Layer.provide(ManagementApiLive()), Layer.provide(credentials), Layer.orDie);
+//#endregion
+//#region src/RunRecord.ts
+/** The key of the record in the stage output document. */
+const RUN_RECORD_KEY = "samebase.run";
+/** The name of the stack file. Alchemy resolves `--config` against the working directory and does not expose it to a state layer, so the record assumes the default name. */
+const STACK_FILE_NAME = "alchemy.run.ts";
+var RunRecordError = class extends Schema.TaggedError()("RunRecordError", { reason: Schema.String }) {
+	get message() {
+		return `The run record of the stage output cannot be made: ${this.reason}`;
+	}
+};
+/** The part of the GitHub Actions event payload that the record reads. A push event has no `pull_request`. */
+const EventPayload = Schema.Struct({ pull_request: Schema.optionalKey(Schema.Struct({
+	number: Schema.Number,
+	head: Schema.Struct({ sha: Schema.String })
+})) });
+/** `owner/name` of an https, ssh, or scp-like git URL with a host. A local path is not one. */
+const REMOTE_URL = /^(?:[a-z+]+:\/\/[^/]+\/|[^/@:]+@[^:/]+:)([^/]+)\/([^/]+?)(?:\.git)?\/?$/;
+const execFileAsync = promisify(execFile);
+const now = Clock.currentTimeMillis.pipe(Effect.map((millis) => new Date(millis).toISOString()));
+const git = (cwd, args) => Effect.tryPromise({
+	try: async () => (await execFileAsync("git", [
+		"-C",
+		cwd,
+		...args
+	], { encoding: "utf8" })).stdout.trim(),
+	catch: (error) => new RunRecordError({ reason: `git ${args.join(" ")} failed in ${cwd} (${error instanceof Error ? error.message.split("\n")[0] : String(error)})` })
+});
+/** The stack file from the repository root: the working directory below the git top level, plus {@link STACK_FILE_NAME}. */
+const stackFileOf = (cwd) => Effect.gen(function* () {
+	const top = yield* git(cwd, ["rev-parse", "--show-toplevel"]);
+	const [realTop, realCwd] = yield* Effect.tryPromise({
+		try: () => Promise.all([realpath(top), realpath(cwd)]),
+		catch: () => new RunRecordError({ reason: `${cwd} is gone` })
+	});
+	return [...relative(realTop, realCwd).split(sep).filter((part) => part !== ""), STACK_FILE_NAME].join("/");
+});
+const variable = (env, name) => Effect.suspend(() => {
+	const value = env[name];
+	return value === void 0 || value === "" ? Effect.fail(new RunRecordError({ reason: `GITHUB_ACTIONS is true, and ${name} is not set` })) : Effect.succeed(value);
+});
+const fromGitHubActions = (where) => Effect.gen(function* () {
+	const { env } = where;
+	const repository = yield* variable(env, "GITHUB_REPOSITORY");
+	const refName = yield* variable(env, "GITHUB_REF_NAME");
+	const sha = yield* variable(env, "GITHUB_SHA");
+	const serverUrl = yield* variable(env, "GITHUB_SERVER_URL");
+	const runId = yield* variable(env, "GITHUB_RUN_ID");
+	const runAttempt = yield* variable(env, "GITHUB_RUN_ATTEMPT");
+	const eventPath = env["GITHUB_EVENT_PATH"];
+	const pullRequest = (eventPath === void 0 || eventPath === "" ? void 0 : yield* Effect.tryPromise({
+		try: () => readFile(eventPath, "utf8"),
+		catch: () => new RunRecordError({ reason: `GITHUB_EVENT_PATH ${eventPath} cannot be read` })
+	}).pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(EventPayload))), Effect.mapError((error) => error instanceof RunRecordError ? error : new RunRecordError({ reason: `GITHUB_EVENT_PATH ${eventPath} is not an event payload` }))))?.pull_request;
+	const headCommit = pullRequest?.head.sha ?? sha;
+	const headRef = env["GITHUB_HEAD_REF"];
+	const mergeRef = /^refs\/pull\/(\d+)\/merge$/.exec(env["GITHUB_REF"] ?? "");
+	return {
+		version: 1,
+		repository,
+		stackFile: yield* stackFileOf(where.cwd),
+		branch: headRef === void 0 || headRef === "" ? refName : headRef,
+		pullRequest: pullRequest?.number ?? (mergeRef === null ? null : Number(mergeRef[1])),
+		headCommit,
+		runUrl: `${serverUrl}/${repository}/actions/runs/${runId}/attempts/${runAttempt}`,
+		source: "github-actions",
+		recordedAt: yield* now
+	};
+});
+const fromGit = (where) => Effect.gen(function* () {
+	const { cwd } = where;
+	const origin = yield* git(cwd, [
+		"remote",
+		"get-url",
+		"origin"
+	]);
+	const match = REMOTE_URL.exec(origin);
+	if (match === null) return yield* new RunRecordError({ reason: `the origin remote of ${cwd} is not a git URL with a host and owner/name: ${origin}` });
+	const branch = yield* git(cwd, [
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	]);
+	if (branch === "HEAD") return yield* new RunRecordError({ reason: `the checkout at ${cwd} is on no branch (detached HEAD)` });
+	return {
+		version: 1,
+		repository: `${match[1]}/${match[2]}`,
+		stackFile: yield* stackFileOf(cwd),
+		branch,
+		pullRequest: null,
+		headCommit: yield* git(cwd, ["rev-parse", "HEAD"]),
+		runUrl: null,
+		source: "laptop",
+		recordedAt: yield* now
+	};
+});
+/**
+* The record of this run: from the GitHub Actions variables and the event
+* payload when GITHUB_ACTIONS is `true`, else from git in `cwd`, which needs
+* a branch and an `origin` remote with `owner/name`. Fails when a value is
+* missing; nothing is guessed.
+*/
+const runRecord = (where) => where.env["GITHUB_ACTIONS"] === "true" ? fromGitHubActions(where) : fromGit(where);
+/** A plain object, which a spread keeps whole. A Date, a Duration, or a Redacted value is an object too, and a spread loses it. */
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+/**
+* The output document of a stage: the stack's output plus the record under
+* {@link RUN_RECORD_KEY}, or undefined for an output with no place for the
+* key: a string, an array, null, or an object that is not plain, such as a
+* Date. A value that the stack itself put under the key stays.
+*/
+const withRunRecord = (output, record) => isPlainObject(output) ? "samebase.run" in output ? output : {
+	...output,
+	[RUN_RECORD_KEY]: record
+} : void 0;
 //#endregion
 //#region src/State.ts
 /** The name of the state project in each team. */
@@ -1449,10 +1618,11 @@ const storeDirectory = () => join(dirname(fileURLToPath(import.meta.url)), "..",
 */
 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* Effect.logInfo(`Convex state: pushing the store version 2 to ${deployment.name}`);
 	yield* withPushKey(options.api, deployment.name, PUSH_KEY_ACTIONS, (key) => push(options.spawner, key, {
 		deployment: deployment.name,
 		url: deployment.deploymentUrl,
+		rootDir: join(options.store, ".."),
 		source: {
 			path: options.store,
 			command: [
@@ -1512,16 +1682,31 @@ const makeConvexState = (options) => Effect.gen(function* () {
 		return next.call(path, args);
 	})))) };
 	const version = yield* storeVersion(functions);
-	if (version === void 0 || version < 1) {
+	if (version === void 0 || version < 2) {
 		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) {
+		if (now === void 0 || now < 2) {
 			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.`);
+			if (pushed === void 0 || pushed < 2) return yield* failure(`${deployment.name} answers store version ${pushed ?? "none"} after the push of version 2.`);
 		}
-	} 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.`);
+	} else if (version > 2) yield* Effect.logInfo(`Convex state: the store of team ${team} is version ${version}, newer than version 2 of this package, and it stays.`);
 	const remote = remoteOf(functions);
+	/** The stack's output plus the record, when the run has one and the output has a place for it. */
+	const documentOf = (request) => Effect.gen(function* () {
+		const { run } = options;
+		if (run === void 0) return request.value;
+		const recordedAt = new Date(yield* Clock.currentTimeMillis).toISOString();
+		const document = withRunRecord(request.value, {
+			...run,
+			recordedAt
+		});
+		if (document === void 0) {
+			yield* Effect.logWarning(`Convex state: the output of ${request.stack}/${request.stage} is not a plain object, so it carries no run record.`);
+			return request.value;
+		}
+		return document;
+	});
 	return {
 		id: "convex",
 		getVersion: () => Effect.succeed(STATE_STORE_VERSION),
@@ -1534,7 +1719,15 @@ const makeConvexState = (options) => Effect.gen(function* () {
 		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))
+		setOutput: (request) => Effect.gen(function* () {
+			const value = yield* documentOf(request);
+			yield* remote.setOutput({
+				stack: request.stack,
+				stage: request.stage,
+				value
+			});
+			return value;
+		})
 	};
 });
 /**
@@ -1551,16 +1744,21 @@ const state = (options = {}) => Layer.effect(State, Effect.gen(function* () {
 	const context = yield* Effect.context();
 	return yield* Effect.cached(Effect.gen(function* () {
 		const api = yield* ManagementApi.pipe(Effect.provide(ManagementApiLive().pipe(Layer.provide(fromConfig()))));
+		const run = yield* runRecord({
+			cwd: process.cwd(),
+			env: process.env
+		}).pipe(Effect.catch((error) => Effect.logWarning(`Convex state: the stage outputs of this run carry no record. ${error.message}`).pipe(Effect.as(void 0))));
 		return yield* makeConvexState({
 			team: options.team,
 			api,
 			spawner,
 			scope,
-			store: storeDirectory()
+			store: storeDirectory(),
+			run
 		});
 	}).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 };
+export { ACCESS_TOKEN_ENV, AbsoluteRootDir, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectNotFound, ProjectTeamChange, Providers, PushTargetMismatch, RUN_RECORD_KEY, RunRecordError, STORE_PROJECT_NAME, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers, runRecord, state, withRunRecord };
 
 //# sourceMappingURL=index.js.map