@samebase/alchemy-convex 0.6.0 → 0.7.0

package/README.md

@@ -107,8 +107,11 @@ export default Alchemy.Stack(
 );
 ```
 
-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
+Every run needs the team token in `CONVEX_ACCESS_TOKEN`, or the Convex CLI login on a laptop. A
+team access token names its team, so `Convex.state()` needs no `team` with one; a `team` slug that
+is set must be the slug of that team, checked against its projects, and a token of another team
+fails the run. The Convex CLI login needs the slug or the id. 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
@@ -116,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

@@ -78,8 +78,14 @@ interface ManagementApiService {
   readonly requestVoid: (operation: string, run: (client: ManagementClient) => Promise<FetchResult<unknown>>) => Effect.Effect<void, ConvexApiError>;
   /** Run one deployment-scoped call authenticated with a deploy key. */
   readonly deploymentRequest: <T>(operation: string, deploymentUrlOrName: string, deployKey: Redacted.Redacted<string>, run: (client: DeploymentClient) => Promise<FetchResult<T>>) => Effect.Effect<T, ConvexApiError>;
-  /** Team id for a slug or numeric id. */
-  readonly resolveTeamId: (team: string | number) => Effect.Effect<number, ConvexApiError>;
+  /**
+   * Team id for a numeric id, a slug, or nothing. A team access token names
+   * its team (`GET /token_details`); a slug is then checked against the
+   * `teamSlug` of the team's projects, so a token of another team fails. The
+   * Convex CLI login and a personal token answer 403 there, so a slug goes to
+   * the dashboard's team list, and nothing is an error.
+   */
+  readonly resolveTeamId: (team: string | number | undefined) => Effect.Effect<number, ConvexApiError>;
   /**
    * True when a deploy key that Convex returned carries the token of the
    * Management API credential itself. With an OAuth token, create_deploy_key
@@ -341,18 +347,68 @@ 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";
 /**
  * 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.
+ * in CONVEX_ACCESS_TOKEN or the Convex CLI login. A team access token names
+ * its team, so `team` is optional with one; the Convex CLI login needs the
+ * slug or the id. 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;
+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;;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"}
+{"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";
@@ -169,15 +170,54 @@ const TeamRow = Schema.Struct({
 	slug: Schema.String
 });
 const TeamRows = Schema.Array(TeamRow);
+/** The first page of GET /teams/{team_id}/projects: every row carries the slug of the team. */
+const ProjectSlugRows = Schema.Struct({ items: Schema.Array(Schema.Struct({ teamSlug: Schema.String })) });
+/** GET /token_details: the team of a team token, or the project of a project token. */
+const TokenDetails = Schema.Union([Schema.Struct({
+	type: Schema.Literal("teamToken"),
+	teamId: Schema.Number
+}), Schema.Struct({
+	type: Schema.Literal("projectToken"),
+	projectId: Schema.Number
+})]);
 /** The service for one way to get the bearer token. */
 const makeService = (credentials) => {
 	const client = Effect.cached(credentials.pipe(Effect.map((resolved) => createManagementClient(Redacted.value(resolved.accessToken))))).pipe(Effect.flatten);
 	const request = (operation, run) => client.pipe(Effect.flatMap((c) => settle(operation, () => run(c))));
 	const requestVoid = (operation, run) => client.pipe(Effect.flatMap((c) => settleVoid(operation, () => run(c))));
 	const deploymentRequest = (operation, deploymentUrlOrName, deployKey, run) => settle(operation, () => run(createDeploymentClient(deploymentUrlOrName, Redacted.value(deployKey))));
+	const tokenDetails = Effect.runSync(Effect.cached(request("get token details", (c) => c.GET("/token_details")).pipe(Effect.map((body) => Schema.decodeUnknownSync(TokenDetails)(body)), Effect.catchIf((error) => error.status === 403, () => Effect.succeed(void 0)))));
+	/** The slug of the team, from the first project of its listing, or undefined for a team without one. Read once. */
+	const teamSlug = (teamId) => request("list projects", (c) => c.GET("/teams/{team_id}/projects", { params: { path: { team_id: teamId } } })).pipe(Effect.map((body) => Schema.decodeUnknownSync(ProjectSlugRows)(body).items[0]?.teamSlug));
 	const resolveTeamId = (team) => Effect.gen(function* () {
 		if (typeof team === "number") return team;
-		if (/^\d+$/.test(team)) return Number(team);
+		if (team !== void 0 && /^\d+$/.test(team)) return Number(team);
+		const details = yield* tokenDetails;
+		if (details?.type === "teamToken") {
+			if (team === void 0) return details.teamId;
+			const slug = yield* teamSlug(details.teamId);
+			if (slug === void 0) return yield* new ConvexApiError({
+				operation: "resolve team",
+				status: 0,
+				message: `team "${team}" cannot be checked against the access token: team ${details.teamId} has no project yet. Set team to ${details.teamId}, or leave it out.`
+			});
+			if (slug !== team) return yield* new ConvexApiError({
+				operation: "resolve team",
+				status: 403,
+				message: `the access token belongs to team ${details.teamId} ("${slug}"), and team is "${team}". Use a token of "${team}", or set team to ${details.teamId}.`
+			});
+			return details.teamId;
+		}
+		if (details?.type === "projectToken") return yield* new ConvexApiError({
+			operation: "resolve team",
+			status: 403,
+			message: `the access token belongs to project ${details.projectId}, and a project token cannot create projects. Use a team access token.`
+		});
+		if (team === void 0) return yield* new ConvexApiError({
+			operation: "resolve team",
+			status: 0,
+			message: "set team to the slug or the id of the Convex team: this access token does not name a team."
+		});
 		const resolved = yield* credentials;
 		const match = (yield* Effect.tryPromise({
 			try: async () => {
@@ -1290,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";
@@ -1410,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,
@@ -1455,8 +1614,9 @@ const createStoreProject = (api, teamId, team) => Effect.gen(function* () {
 * written with the keys of this run.
 */
 const makeConvexState = (options) => Effect.gen(function* () {
-	const { api, team } = options;
-	const teamId = yield* api.resolveTeamId(team);
+	const { api } = options;
+	const teamId = yield* api.resolveTeamId(options.team);
+	const team = options.team ?? teamId;
 	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 });
@@ -1472,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),
@@ -1494,31 +1669,46 @@ 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;
+		})
 	};
 });
 /**
 * 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.
+* in CONVEX_ACCESS_TOKEN or the Convex CLI login. A team access token names
+* its team, so `team` is optional with one; the Convex CLI login needs the
+* slug or the id. 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 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()))));
+		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