@samebase/alchemy-convex 0.7.0 → 0.9.0

package/README.md

@@ -69,6 +69,28 @@ deployment if it has code, only with `--adopt`.
 it stays until Convex deletes it at expiry (14 days by default).
 [`examples/app/alchemy.run.ts`](examples/app/alchemy.run.ts) is the same stack.
 
+### The stack file at the repository root
+
+`rootDir` is the app directory, relative to the directory where `alchemy deploy` runs, which is
+the directory of the stack file. The default is `"."`. The push runs in `rootDir`, and `source` is
+relative to it:
+
+```ts
+Effect.gen(function* () {
+  const project = yield* Convex.Project("Project", { team: "my-team", slug: "my-app" });
+  const backend = yield* Convex.Deployment("Backend", {
+    project,
+    type: "prod",
+    rootDir: "apps/web", // the Convex app, with its package.json
+    source: "./convex", // apps/web/convex
+  });
+  return { convexUrl: backend.url };
+});
+```
+
+State always holds `rootDir`, `"."` included, so a reader of the state finds the app directory of
+each deployment.
+
 ## Credentials
 
 Credentials are a layer, never props, so they do not go into Alchemy state. `Convex.providers()`
@@ -113,11 +135,20 @@ is set must be the slug of that team, checked against its projects, and a token
 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
+newer store when it finds an older one. A store that is newer than the package fails the run with
+both versions, so the repositories of a team upgrade the package together. 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.
+The store and its readers (Samebase) are released and upgraded together.
+
+Store version 3 supports native subscriptions. A trusted server checks repository access, then
+calls internal `reader:authorize({ repository, subject })` with a deployment credential. It gives
+the returned token to a separate `ConvexClient` connected to the state deployment. The client
+subscribes to `reader:repository({})`; the verified token selects the repository. The token has a
+five-minute lifetime and permits redacted reads only. The server checks access again on renewal.
+The store uses its own native signing key and JWKS, so no extra signing secret is required.
+See [the reader contract](docs/design/convex-state.md#repository-subscriptions-090).
 
 ### What the output records about a run
 
@@ -160,25 +191,29 @@ call.
   taken over with `--adopt`; it never creates or renames a project. Outputs `projectId`, `slug`,
   `name`, `teamId`, `prodDeploymentName`, `prodDeploymentUrl`.
 - `Convex.Deployment`: `{ project, type: "prod" }` or `{ project, type: "dev" | "preview", name }`,
-  each with optional `source` and `env`. Outputs `name` (such as `happy-animal-123`), `url`,
-  `siteUrl`, `type`, `projectId`, `reference`, `previewName`, `hash`, and `envNames`.
+  each with optional `rootDir`, `source`, and `env`. Outputs `name` (such as `happy-animal-123`),
+  `url`, `siteUrl`, `type`, `projectId`, `reference`, `previewName`, `hash`, and `envNames`.
   - `prod` is the project's default production deployment (with a deploy key: the key's
     production deployment). The resource never creates or deletes one. A production deployment
     with code that is not in state is taken over only with `--adopt`.
   - `dev` creates a dev deployment with `name` as its reference; `preview` creates a preview
     deployment with `name` as its preview name. An expired preview is created again on the next
     deploy.
-  - `source` is the Convex functions directory: `convex/`, or the `functions` field of
-    convex.json (`SourceMismatch`). The CLI runs in the nearest directory above it with a
-    package.json, with the Node.js that runs Alchemy, and is never downloaded (`ConvexCliNotFound`).
-  - The content identity is a hash of every file of that app directory that git does not ignore,
-    the nearest lockfile, the deployment name, and `env`. The same hash is a no-op. Otherwise the
-    update sets `env`, then pushes. A failed push sets the changed variables back, and deletes a
-    dev or preview deployment that the same run created.
+  - `rootDir` is the app directory, relative to the directory where the deploy runs, `"."` by
+    default. It must be relative (`AbsoluteRootDir`) and have a package.json (`ConvexAppNotFound`).
+    There is no search in the directories above it. When convex.json puts the functions outside
+    `rootDir`, the hash covers them too.
+  - `source` is the Convex functions directory relative to `rootDir`: `convex/`, or the `functions`
+    field of convex.json (`SourceMismatch`). The CLI runs in `rootDir`, with the Node.js that runs
+    Alchemy, and is never downloaded (`ConvexCliNotFound`).
+  - The content identity is a hash of every file of `rootDir` that git does not ignore, the nearest
+    lockfile, the deployment name, and `env`. The same hash is a no-op. Otherwise the update sets
+    `env`, then pushes. A failed push sets the changed variables back, and deletes a dev or preview
+    deployment that the same run created.
   - `env` values are strings or secrets such as `Config.Redacted("AUTH_SECRET")`. A name that
     leaves `env` is removed from the deployment.
-  - `source: { path, command?, include? }` replaces `convex deploy` with `command`, run in the app
-    directory with the push key in `CONVEX_DEPLOY_KEY`, such as
+  - `source: { path, command?, include? }` replaces `convex deploy` with `command`, run in `rootDir`
+    with the push key in `CONVEX_DEPLOY_KEY`, such as
     `["node_modules/.bin/convex-hosting", "deploy", "--build", "node_modules/.bin/vp build", "--dist", "dist/client"]`.
     The command must push with `convex deploy` (convex-hosting does, through `--cmd`). `include`
     narrows the hash to `path`, package.json, convex.json, the lockfile, and the listed globs, such
@@ -215,8 +250,8 @@ call.
 
 - `env` values are props, so Alchemy state holds them. Keep `.alchemy/` git-ignored, and use an
   encrypted state store, such as `Cloudflare.state()`, in CI.
-- The hash does not see a change in a workspace package outside the app directory, or a push from
-  outside Alchemy. Change a file of the app to push again.
+- The hash does not see a change in a workspace package outside `rootDir`, or a push from outside
+  Alchemy. Change a file of the app to push again.
 - With a deploy key, the provider reaches the deployment at `https://<name>.convex.cloud`, so the
   deployment must answer there.
 - A run that stops between a deployment create and the state write leaves a deployment that state

package/lib/index.d.ts

@@ -9,6 +9,7 @@ import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
 import "effect/Scope";
 import { State, StateStoreError } from "alchemy/State";
+import { InputProps } from "alchemy/Input";
 import { components } from "@convex-dev/platform/managementApi";
 //#region src/Credentials.d.ts
 interface ResolvedCredentials {
@@ -117,11 +118,12 @@ export declare const providers: (credentials?: Layer.Layer<Credentials>) => Laye
 /** A value of the `env` prop: a string, or a secret such as `Config.Redacted("AUTH_SECRET")`. */
 type EnvValue = string | Redacted.Redacted<string>;
 /**
- * The `source` prop: the Convex functions directory, such as `./convex`, or
- * that directory with a push command and more files for the content identity.
+ * The `source` prop: the Convex functions directory relative to the app
+ * directory (`rootDir`), such as `./convex`, or that directory with a push
+ * command and more files for the content identity.
  */
 type Source = string | {
-  /** The Convex functions directory, such as `./convex`. */
+  /** The Convex functions directory relative to the app directory, such as `./convex`. */
   readonly path: string;
   /**
    * Replaces `convex deploy`: a program and its arguments, run in the app
@@ -147,9 +149,10 @@ export declare class ConvexCliNotFound extends ConvexCliNotFound_base {
   get message(): string;
 }
 declare const ConvexAppNotFound_base: Schema.Class<ConvexAppNotFound, Schema.TaggedStruct<"ConvexAppNotFound", {
-  readonly source: Schema.String;
+  /** The app directory, resolved against the working directory of the deploy. */
+  readonly rootDir: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-/** No directory at or above the parent of `source` has a package.json. */
+/** The app directory (`rootDir`) has no package.json. */
 export declare class ConvexAppNotFound extends ConvexAppNotFound_base {
   get message(): string;
 }
@@ -199,10 +202,16 @@ interface DeploymentInputs {
     readonly projectId: number;
   };
   /**
-   * The Convex functions directory, such as `./convex`, or that directory
-   * with a push command and more hashed files. The push runs in the nearest
-   * directory above it with a package.json. Without `source`, the resource
-   * pushes nothing.
+   * The app directory, relative to the directory where the deploy runs (the
+   * directory of the stack file), such as `apps/web`. Default ".". It must
+   * have a package.json. The push runs in it, and `source` is relative to
+   * it. State from 0.7 has no `rootDir`.
+   */
+  readonly rootDir?: string;
+  /**
+   * The Convex functions directory relative to `rootDir`, such as
+   * `./convex`, or that directory with a push command and more hashed
+   * files. Without `source`, the resource pushes nothing.
    */
   readonly source?: Source;
   /** Environment variables to set on the deployment before the push. */
@@ -242,7 +251,36 @@ interface DeploymentAttributes extends DeploymentTarget {
   readonly envNames: readonly string[];
 }
 export type Deployment = Resource<"Convex.Deployment", DeploymentProps, DeploymentAttributes, never, Providers>;
-export declare const Deployment: import("alchemy").ResourceClass<Deployment>;
+/** The props of a `Convex.Deployment` call: Alchemy inputs, with `rootDir` a plain string. */
+type DeploymentInput = DeploymentProps extends (infer P) ? P extends DeploymentProps ? InputProps<P, "rootDir"> : never : never;
+declare const AbsoluteRootDir_base: Schema.Class<AbsoluteRootDir, Schema.TaggedStruct<"AbsoluteRootDir", {
+  readonly rootDir: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** `rootDir` is an absolute path. The declaration stops with it as a defect, before the plan. */
+export declare class AbsoluteRootDir extends AbsoluteRootDir_base {
+  get message(): string;
+}
+/**
+ * `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`.
+ */
+export declare const Deployment: ((id: string, props: DeploymentInput) => Effect.Effect<Deployment, never, Providers>) & {
+  Type: "Convex.Deployment";
+  Props: DeploymentProps;
+  Self: import("alchemy/Self").Self<Deployment>;
+  Provider: Provider.Provider<Deployment>;
+  Aliases: readonly string[] | undefined;
+  ref: (id: string, options?: {
+    stage?: string;
+    stack?: string;
+  }) => Effect.Effect<Deployment, never, never>;
+};
 declare const DeploymentIdentityChange_base: Schema.Class<DeploymentIdentityChange, Schema.TaggedStruct<"DeploymentIdentityChange", {
   /** Name of the deployment in state, such as `happy-animal-123`. */
   readonly deployment: Schema.String;
@@ -410,5 +448,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, RunRecord, Source };
+export type { DeploymentAttributes, DeploymentInput, 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/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"}
+{"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":"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"}

package/lib/index.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { access, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, relative, resolve, sep } 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";
@@ -282,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. */
@@ -372,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) });
@@ -402,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
 	});
 });
@@ -427,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,
@@ -510,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))
@@ -530,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);
@@ -628,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`. */
@@ -750,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;
@@ -843,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 ?? {}
@@ -854,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) {
@@ -897,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 ?? {};
@@ -905,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* () {
@@ -963,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,
@@ -977,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,
@@ -994,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()
 			};
 		}),
@@ -1328,7 +1377,7 @@ 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. */
@@ -1506,8 +1555,18 @@ const makeFunctionApi = (url, key) => ({ call: (path, args) => post(`${url}/api/
 /** 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 remoteOf = (api, record) => {
 	const run = (name, args) => api.call(`state:${name}`, args).pipe(Effect.flatMap(valueOf));
+	const write = (name, args) => Effect.gen(function* () {
+		const currentRun = record === void 0 ? void 0 : {
+			...record,
+			recordedAt: new Date(yield* Clock.currentTimeMillis).toISOString()
+		};
+		return yield* run(name, {
+			...args,
+			run: currentRun
+		});
+	});
 	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));
@@ -1531,13 +1590,13 @@ const remoteOf = (api) => {
 			stack: r.stack,
 			stage: r.stage
 		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
-		set: (r) => run("set", {
+		set: (r) => write("set", {
 			stack: r.stack,
 			stage: r.stage,
 			fqn: r.fqn,
 			value: encode(r.value)
 		}),
-		delete: (r) => run("remove", {
+		delete: (r) => write("remove", {
 			stack: r.stack,
 			stage: r.stage,
 			fqn: r.fqn
@@ -1546,7 +1605,7 @@ const remoteOf = (api) => {
 			stack: r.stack,
 			stage: r.stage
 		}),
-		setOutput: (r) => run("setOutput", {
+		setOutput: (r) => write("setOutput", {
 			stack: r.stack,
 			stage: r.stage,
 			value: encode(r.value)
@@ -1569,10 +1628,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 2 to ${deployment.name}`);
+	yield* Effect.logInfo(`Convex state: pushing the store version 3 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: [
@@ -1631,17 +1691,17 @@ const makeConvexState = (options) => Effect.gen(function* () {
 		current = next;
 		return next.call(path, args);
 	})))) };
-	const version = yield* storeVersion(functions);
-	if (version === void 0 || version < 2) {
+	let version = yield* storeVersion(functions);
+	if (version === void 0 || version < 3) {
 		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 < 2) {
+		version = yield* storeVersion(functions);
+		if (version === void 0 || version < 3) {
 			yield* pushStore(options, deployment);
-			const pushed = yield* storeVersion(functions);
-			if (pushed === void 0 || pushed < 2) return yield* failure(`${deployment.name} answers store version ${pushed ?? "none"} after the push of version 2.`);
+			version = yield* storeVersion(functions);
 		}
-	} 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);
+	}
+	if (version !== 3) return yield* failure(`${deployment.name} answers store version ${version ?? "none"}, and this package needs store version 3.`);
+	const remote = remoteOf(functions, options.run);
 	/** 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;
@@ -1709,6 +1769,6 @@ const state = (options = {}) => Layer.effect(State, Effect.gen(function* () {
 	}).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, RUN_RECORD_KEY, RunRecordError, STORE_PROJECT_NAME, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers, runRecord, state, withRunRecord };
+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