@samebase/alchemy-convex 0.6.1 → 0.7.0

package/README.md

@@ -119,6 +119,39 @@ the end. Rows are in the tables `resources` and `outputs` in the dashboard, unde
 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.
 
+### What the output records about a run
+
+Alchemy state holds no time, commit, branch, or run. `Convex.state()` adds them to the stage output:
+the document that `setOutput` stores is the stack's output plus the key `samebase.run`. On GitHub
+Actions the record comes from the run's variables and the event payload; on a laptop from git, which
+needs a branch and an `origin` remote. It holds no secret.
+
+```json
+{
+  "convexUrl": "https://modest-guanaco-252.convex.cloud",
+  "samebase.run": {
+    "version": 1,
+    "repository": "samebase/base-alchemy",
+    "stackFile": "alchemy.run.ts",
+    "branch": "feature",
+    "pullRequest": 42,
+    "headCommit": "8af3c5b7932c528939cbc7aa0597b1fc36c8dc83",
+    "runUrl": "https://github.com/samebase/base-alchemy/actions/runs/12345678901/attempts/1",
+    "source": "github-actions",
+    "recordedAt": "2026-10-21T10:00:00.000Z"
+  }
+}
+```
+
+`stackFile` is the working directory of the run below the repository root plus `alchemy.run.ts`.
+`pullRequest` and `runUrl` are `null` for a push and for a laptop, where `source` is `laptop`. A
+value that the stack itself returns under `samebase.run` stays. A checkout that gives no record,
+such as a tarball without git or a detached HEAD, writes its outputs without one, and the log says
+why. Alchemy writes the output once after a full successful deploy, so a failed deploy leaves the
+previous record, and a deploy of selected resources writes none. A reader gets every stage of a
+stack, with its resources and output, from the store function `state:readStack({ stack })` in one
+call.
+
 ## Resources
 
 - `Convex.Project`: `{ team, name, deploymentRegion?, deploymentType? }` creates a project with its

package/lib/index.d.ts

@@ -347,6 +347,54 @@ export declare class ProjectNotFound extends ProjectNotFound_base {
   get message(): string;
 }
 //#endregion
+//#region src/RunRecord.d.ts
+/** The key of the record in the stage output document. */
+export declare const RUN_RECORD_KEY = "samebase.run";
+/** Version 1 of the record. A reader validates `version` first. */
+interface RunRecord {
+  readonly version: 1;
+  /** GitHub `owner/name`. */
+  readonly repository: string;
+  /** Path of the stack file from the repository root, POSIX separators, such as `apps/samebase/alchemy.run.ts`. */
+  readonly stackFile: string;
+  /** The branch that was deployed: the head branch of a pull request, else the pushed branch. */
+  readonly branch: string;
+  /** The pull request whose head was deployed, or null for a push and for a laptop. */
+  readonly pullRequest: number | null;
+  /** The commit that was deployed: the head of the pull request, else GITHUB_SHA, else git HEAD. */
+  readonly headCommit: string;
+  /** The GitHub Actions run and attempt, or null for a laptop. */
+  readonly runUrl: string | null;
+  readonly source: "github-actions" | "laptop";
+  /** ISO 8601, when the record was written. */
+  readonly recordedAt: string;
+}
+declare const RunRecordError_base: Schema.Class<RunRecordError, Schema.TaggedStruct<"RunRecordError", {
+  readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class RunRecordError extends RunRecordError_base {
+  get message(): string;
+}
+/** Where the run happens: the working directory of the stack and the process environment. */
+interface RunEnvironment {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * 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.
+ */
+export declare const runRecord: (where: RunEnvironment) => Effect.Effect<RunRecord, RunRecordError>;
+/**
+ * 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.
+ */
+export declare const withRunRecord: (output: unknown, record: RunRecord) => object | undefined;
+//#endregion
 //#region src/State.d.ts
 /** The name of the state project in each team. */
 export declare const STORE_PROJECT_NAME = "alchemy-state";
@@ -362,5 +410,5 @@ 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 };
+export type { DeploymentAttributes, DeploymentProps, DeploymentRegion, EnvValue, ProjectAttributes, ProjectProps, RunRecord, 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","../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;;;;;;;;WAQb,gBACP,sCACG,OAAO,eAAe;;;;;;;;WAQlB,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBC1FtB,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;;;;;;;;;qBAiVA,QACX;WAAoB;MACnB,MAAM,MAAM,cAAc,oBAAoB"}
+{"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/RunRecord.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;;;;;;;;WAQb,gBACP,sCACG,OAAO,eAAe;;;;;;;;WAQlB,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBC1FtB,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;;;;;qBC5GF;;UAMI;WACN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;WACA;;WAEA;;;;;qBAGE,uBAAuB;MAGrB;;;UAME;WACN;WACA,KAAK,SAAS;;;;;;;;qBAuIZ,YAAa,OAAO,mBAAiB,OAAO,OAAO,WAAW;;;;;;;qBAgB9D,gBAAiB,iBAAiB,QAAQ;;;;qBCxH1C;;;;;;;;;qBAwWA,QACX;WAAoB;MACnB,MAAM,MAAM,cAAc,oBAAoB"}

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, relative, resolve, sep } 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";
@@ -1329,6 +1330,125 @@ 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
+//#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. */
 const STORE_PROJECT_NAME = "alchemy-state";
@@ -1449,7 +1569,7 @@ 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,
@@ -1512,16 +1632,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 +1669,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 +1694,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, 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