@gaganref/confect-test 10.3.1-fork.9 → 10.3.1-fork.90

package/dist/internal/Execution.js

@@ -0,0 +1,1024 @@
+import { own } from "./Globals.js";
+import { install } from "./Clock.js";
+import { createFunctionHandle, createTestJwt, deserializeConvexErrorData, evaluateValue, hasPendingValues, parseArgs, parseFunctionHandle, resolveCommittedValues, simpleHash, tableNameFromId, validateFunctionArgs, validateReturnValue } from "./KernelValues.js";
+import { apply, conflict, empty, wallClock } from "./Kernel.js";
+import { KernelAttempt } from "./Attempt.js";
+import { bind, current as current$1, fresh, unbound } from "./Invocation.js";
+import { ClosedAttempt, CommitTsNotIncreasing, DrainBudgetExceeded, OptimisticConcurrencyControlFailure, RegisteredAfterOpen, StaleAttempt, UnknownStandingSource, requiresBinary, rowPending } from "./KernelRefusal.js";
+import { exportSchema, paginate, stream, validateDocument } from "./KernelQuery.js";
+import { functions, pending, row, stateOf, table } from "./Scheduling.js";
+import { actionGeneric, getFunctionAddress, mutationGeneric, queryGeneric } from "convex/server";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { convexToJson, jsonToConvex } from "convex/values";
+//#region src/internal/Execution.ts
+const ROOT = "";
+const TYPICAL_CONVEX_ID_LENGTH = 32;
+const anonymous = {
+	identity: null,
+	token: null,
+	ip: null,
+	userAgent: null
+};
+const withIdentity = (caller, identity) => {
+	const subject = identity.subject ?? "" + simpleHash(JSON.stringify(identity));
+	const issuer = identity.issuer ?? "https://convex.test";
+	const tokenIdentifier = identity.tokenIdentifier ?? `${issuer}|${subject}`;
+	const full = {
+		...identity,
+		subject,
+		issuer,
+		tokenIdentifier
+	};
+	return {
+		...caller,
+		identity: full,
+		token: createTestJwt(full)
+	};
+};
+const lastAttempt = 5;
+const tagOf = (error) => {
+	const tagged = (value) => typeof value === "object" && value !== null && typeof value._tag === "string";
+	const data = error?.data;
+	if (tagged(data)) return data._tag;
+	if (tagged(error)) return error._tag;
+	return error instanceof Error ? error.name : "Error";
+};
+/**
+* A queue that runs one task at a time, in the order they were taken.
+*/
+var Turn = class {
+	tail = Promise.resolve();
+	take(task) {
+		const result = this.tail.then(task);
+		this.tail = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	/**
+	* Resolves once every task taken so far has settled, including the tasks
+	* taken while waiting.
+	*/
+	idle() {
+		const tail = this.tail;
+		return tail.then(() => this.tail === tail ? void 0 : this.idle());
+	}
+};
+/**
+* A function's invocation finishes once its handler returned and every syscall
+* it started has run. On the binary a query or mutation keeps running the
+* syscalls in its queue after its promise resolves, then returns (`run_inner`
+* in `crates/isolate/src/environment/udf/mod.rs`, 1.49), so an unawaited write
+* still lands in its own transaction.
+*/
+const settled = (execution, result) => execution.turn.idle().then(() => result);
+const executions = new AsyncLocalStorage();
+/**
+* Run a function's code as `execution`, with its own copy of the globals a test
+* invocation pins.
+*/
+const enter = (execution, run) => {
+	installConvexGlobal();
+	return own(() => executions.run(execution, run));
+};
+const kernelBrand = Symbol.for("@confect/test/Kernel");
+/**
+* The time `Date` answers inside a kernel invocation: a query's or mutation's
+* start, or the clock as it runs in an action. Outside one, none.
+*/
+const pinnedTime = () => {
+	const execution = executions.getStore();
+	if (execution === void 0) return void 0;
+	return execution.udfType === "action" ? execution.world.now() : execution.startTime;
+};
+/**
+* How many jobs one drain or advance runs before it gives up, as convex-test's
+* `finishAllScheduledFunctions` defaults to.
+*/
+const defaultBudget = 100;
+const current = () => {
+	const execution = executions.getStore();
+	if (execution === void 0) throw new Error("A Convex syscall ran outside any function the test kernel started.");
+	return execution;
+};
+let nextRequestId = 0;
+const newRequest = (caller) => ({
+	ip: caller.ip,
+	userAgent: caller.userAgent,
+	requestId: `kernel-request-${nextRequestId++}`,
+	scheduledFunctionId: null,
+	authToken: caller.token
+});
+/**
+* A scheduled call is a request of its own: no caller's attributes, and its
+* job's ID.
+*/
+const jobRequest = (jobId) => ({
+	...newRequest(anonymous),
+	scheduledFunctionId: jobId
+});
+const findModulesRoot = (paths) => {
+	const generated = paths.find((path) => path.includes("_generated"));
+	if (generated === void 0) throw new Error("Could not find the \"_generated\" directory, make sure to run `npx convex dev` or `npx convex codegen`. Make sure your `import.meta.glob` includes the files in the \"_generated\" directory");
+	return generated.split("_generated", 2)[0];
+};
+const makeComponent = (path, schema, modules, standing = []) => {
+	const root = findModulesRoot(Object.keys(modules));
+	const relative = Object.entries(modules).filter(([key]) => key.startsWith(root)).map(([key, load]) => [key.slice(root.length), load]);
+	const nested = relative.map(([file]) => file).filter((file) => file.endsWith("/convex.config.ts")).map((file) => file.slice(0, -16));
+	return {
+		path,
+		schema: exportSchema(schema),
+		loaders: new Map(relative.filter(([file]) => isFunctionModule(file) && !nested.some((dir) => file.startsWith(dir))).map(([file, load]) => [file.replace(/\.[^.]+$/, ""), load])),
+		loaded: /* @__PURE__ */ new Map(),
+		standing: new Set(standing)
+	};
+};
+const entryExtensions = [
+	".js",
+	".mjs",
+	".cjs",
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".jsx"
+];
+/**
+* Whether Convex's bundler deploys this file as a function module, by the rule
+* `entryPoints` applies in `convex/src/bundler/index.ts` (1.49). A test file, a
+* schema, a config and `_generated` never reach the binary, so the kernel
+* neither loads them nor resolves a function in them.
+*/
+const isFunctionModule = (file) => {
+	const base = file.split("/").pop();
+	return entryExtensions.some((extension) => file.endsWith(extension)) && !file.startsWith("_generated/") && !base.startsWith(".") && !base.startsWith("#") && base !== "schema.ts" && base !== "schema.js" && (base.match(/\./g) ?? []).length <= 1 && !file.includes(" ");
+};
+const unregistered = (world, componentPath) => {
+	const registered = [...world.components.keys()].filter((p) => p !== ROOT);
+	return /* @__PURE__ */ new Error(`Component "${componentPath}" is not registered on this test backend. ` + (registered.length === 0 ? "No components have been registered." : `Registered components: ${registered.map((p) => `"${p}"`).join(", ")}.`));
+};
+/**
+* Where an address points, read from the calling component.
+*/
+const functionPathOf = (address, from) => {
+	if (address.functionHandle !== void 0) return parseFunctionHandle(address.functionHandle);
+	if (address.name !== void 0) return {
+		udfPath: address.name,
+		componentPath: from
+	};
+	if (address.reference !== void 0) {
+		const parts = address.reference.split("/");
+		const child = parts[2];
+		const rest = parts.slice(3);
+		return {
+			componentPath: from.length > 0 ? `${from}/${child}` : child,
+			udfPath: `${rest.slice(0, -1).join("/")}:${rest[rest.length - 1]}`
+		};
+	}
+	throw new Error("Function address not supported");
+};
+const pathOfReference = (reference, from) => functionPathOf(getFunctionAddress(reference), from);
+const kindCheck = {
+	query: "isQuery",
+	mutation: "isMutation",
+	action: "isAction"
+};
+/**
+* A test backend: its registered components and the kernel state they share.
+*/
+var World = class {
+	runtime;
+	components = /* @__PURE__ */ new Map();
+	state = empty;
+	opened;
+	nextDocId = 1e4;
+	lastCreationTime = 0;
+	nextQueryId = 1;
+	queries = /* @__PURE__ */ new Map();
+	holding = /* @__PURE__ */ new Map();
+	nextAttemptId = 1;
+	/**
+	* The latest deadline time has been advanced to. The clock never reads
+	* earlier.
+	*/
+	floor = Number.NEGATIVE_INFINITY;
+	targets = /* @__PURE__ */ new Map();
+	constructor(schema, modules, runtime = wallClock()) {
+		this.runtime = runtime;
+		installConvexGlobal();
+		install(pinnedTime, () => executions.getStore() !== void 0);
+		this.components.set(ROOT, makeComponent(ROOT, schema, modules));
+	}
+	register(componentPath, schema, modules, standing = []) {
+		if (this.opened !== void 0) throw new RegisteredAfterOpen({
+			componentPath,
+			message: `Component "${componentPath}" was registered after the test backend opened. Register every component before the first call.`
+		});
+		this.components.set(componentPath, makeComponent(componentPath, schema, modules, standing));
+	}
+	/**
+	* Load every registered module of every component, once, before any function
+	* runs, then check that each standing source names an exported function.
+	*/
+	open() {
+		this.opened ??= Promise.all(Array.from(this.components.values(), (component) => Promise.all(Array.from(component.loaders, ([path, load]) => load().then((module) => component.loaded.set(path, module)))))).then(() => this.checkStanding());
+		return this.opened;
+	}
+	/**
+	* Refuse a standing source no module of its component exports.
+	*/
+	checkStanding() {
+		for (const component of this.components.values()) for (const name of component.standing) {
+			const [modulePath, exportName = "default"] = name.split(":");
+			const func = component.loaded.get(modulePath)?.[exportName];
+			if (func?.isMutation !== true && func?.isAction !== true) throw new UnknownStandingSource({
+				componentPath: component.path,
+				name,
+				message: `Component "${component.path}" declares "${name}" standing, but exports no mutation or action by that name. Name the self-rescheduling function as module:export.`
+			});
+		}
+	}
+	/**
+	* The kernel's time: the runtime's, never earlier than the latest deadline
+	* time was advanced to.
+	*/
+	now() {
+		return Math.max(this.runtime.now(), this.floor);
+	}
+	component(componentPath) {
+		const component = this.components.get(componentPath);
+		if (component === void 0) throw unregistered(this, componentPath);
+		return component;
+	}
+	resolve(functionPath, kind) {
+		const [modulePath, maybeExport] = functionPath.udfPath.split(":");
+		const exportName = maybeExport ?? "default";
+		const module = this.component(functionPath.componentPath).loaded.get(modulePath);
+		if (module === void 0) throw new Error(`Could not find module for: "${modulePath}"`);
+		const func = module[exportName];
+		if (func === void 0) throw new Error(`Expected a Convex function exported from module "${modulePath}" as \`${exportName}\`, but there is no such export.`);
+		const handler = "_handler" in func ? func._handler : func;
+		if (typeof handler !== "function") throw new Error(`Expected a Convex function exported from module "${modulePath}" as \`${exportName}\`, but got: ${func}`);
+		if (kind !== "any" && !func[kindCheck[kind]]) throw new Error(`Expected a ${kind} function, but the function exported from module "${modulePath}" as \`${exportName}\` is not a ${kind}.`);
+		const args = JSON.parse(func.exportArgs());
+		if (args.type !== "object" && args.type !== "any") throw new Error(`Invalid JSON returned from ${modulePath}.js:${exportName}.exportArgs(): Args validator must be an object or any`);
+		return {
+			func,
+			handler,
+			args,
+			returns: JSON.parse(func.exportReturns())
+		};
+	}
+	query(caller, reference, args) {
+		return this.open().then(() => {
+			const from = {
+				caller,
+				request: newRequest(caller)
+			};
+			return typeof reference === "function" ? this.runQuery({
+				componentPath: ROOT,
+				udfPath: "inline"
+			}, {
+				handler: reference,
+				args: { type: "any" },
+				returns: null
+			}, args ?? {}, from) : this.queryAt(pathOfReference(reference, ROOT), args, from);
+		});
+	}
+	mutation(caller, reference, args) {
+		return this.open().then(() => {
+			const from = {
+				caller,
+				request: newRequest(caller)
+			};
+			return typeof reference === "function" ? this.runMutation({
+				componentPath: ROOT,
+				udfPath: "inline"
+			}, {
+				handler: reference,
+				args: { type: "any" },
+				returns: null
+			}, args ?? {}, from) : this.mutationAt(pathOfReference(reference, ROOT), args, from);
+		});
+	}
+	action(caller, reference, args) {
+		return this.open().then(() => {
+			const from = {
+				caller,
+				request: newRequest(caller)
+			};
+			return typeof reference === "function" ? this.runAction({
+				componentPath: ROOT,
+				udfPath: "inline"
+			}, {
+				handler: reference,
+				args: { type: "any" },
+				returns: null
+			}, args ?? {}, from) : this.actionAt(pathOfReference(reference, ROOT), args, from);
+		});
+	}
+	run(caller, componentPath, handler) {
+		return this.open().then(() => {
+			this.component(componentPath);
+			return this.runMutation({
+				componentPath,
+				udfPath: "custom"
+			}, {
+				handler,
+				args: { type: "any" },
+				returns: null
+			}, {}, {
+				caller,
+				request: newRequest(caller)
+			});
+		});
+	}
+	/**
+	* Run a mutation to its commit point and hold it as attempt 1.
+	*/
+	prepare(caller, reference, args) {
+		return this.open().then(() => {
+			const functionPath = pathOfReference(reference, ROOT);
+			const resolved = this.resolve(functionPath, "mutation");
+			validateFunctionArgs(resolved.args, args ?? {}, functionPath, false);
+			return this.prepareMutation(functionPath, resolved, args, {
+				caller,
+				request: newRequest(caller)
+			}, 1, current$1()).then((held) => held.view);
+		});
+	}
+	apply(id) {
+		const held = this.holding.get(id);
+		return held === void 0 ? Promise.reject(new StaleAttempt({
+			id,
+			message: `The test kernel holds no attempt "${id}". It was already applied, or never prepared.`
+		})) : this.applyHeld(held);
+	}
+	/**
+	* The held attempts, oldest first.
+	*/
+	held() {
+		return Array.from(this.holding.values(), (held) => held.view);
+	}
+	/**
+	* The committed pending jobs, earliest deadline first.
+	*/
+	jobs() {
+		return pending(this.state, this.targets).map(({ id, componentPath, name, scheduledTime, standing }) => ({
+			id,
+			componentPath,
+			name,
+			scheduledTime,
+			standing
+		}));
+	}
+	/**
+	* Move the clock forward `ms`, running every job whose deadline falls on the
+	* way, in deadline order, each starting at its deadline. Jobs those jobs
+	* schedule inside the window run too. `advance(0)` runs what is due now and
+	* crosses no future deadline.
+	*/
+	advance(ms, budget = defaultBudget) {
+		return this.open().then(() => {
+			const until = this.now() + ms;
+			return this.walk((pending) => pending.filter((job) => job.scheduledTime <= until), budget).then(() => this.raiseFloor(until));
+		});
+	}
+	/**
+	* Run jobs, earliest deadline first and each at its deadline, until only
+	* standing jobs are pending. Every job run counts against `budget`.
+	*/
+	drain(budget = defaultBudget) {
+		return this.open().then(() => this.walk((pending) => pending.filter((job) => !job.standing), budget));
+	}
+	/**
+	* Run the first of `select(pending)` until it is empty, moving the clock to
+	* each job's deadline as it starts.
+	*/
+	walk(select, budget) {
+		const step = (ran) => {
+			const left = select(pending(this.state, this.targets));
+			const next = left[0];
+			if (next === void 0) return Promise.resolve();
+			if (ran === budget) {
+				const pending = functions(left);
+				return Promise.reject(new DrainBudgetExceeded({
+					budget,
+					pending,
+					message: `Scheduled functions ran ${budget} jobs and work remains: ${pending.map(({ componentPath, name }) => componentPath === ROOT ? name : `${name} in "${componentPath}"`).join(", ")}. A function that schedules its own next run never lets the drain end, so its kit declares it with registerComponent's \`standing\` option.`
+				}));
+			}
+			this.raiseFloor(next.scheduledTime);
+			return this.runJob(next).then(() => step(ran + 1));
+		};
+		return step(0);
+	}
+	raiseFloor(to) {
+		this.floor = Math.max(this.floor, to);
+	}
+	/**
+	* Run one pending job as its own request, moving its row through in progress
+	* to success or failed. `walk` picks it from the committed pending jobs and
+	* starts it in the same turn, so no cancel can land in between. The job runs
+	* as a fresh invocation of the world that scheduled it, whatever invocation
+	* the drain itself runs under.
+	*/
+	runJob(job) {
+		this.commitNow((attempt) => {
+			const doc = attempt.get(job.componentPath, job.id);
+			attempt.write(job.componentPath, job.id, {
+				...doc,
+				state: { kind: "inProgress" }
+			});
+		});
+		const request = jobRequest(job.id);
+		const from = {
+			caller: anonymous,
+			request
+		};
+		const run = () => Promise.resolve().then(() => {
+			const { func } = this.resolve(job.target, "any");
+			return func.isQuery ? this.queryAt(job.target, job.args, from) : func.isMutation ? this.mutationAt(job.target, job.args, from) : this.actionAt(job.target, job.args, from);
+		});
+		return (job.world === void 0 ? unbound(run) : bind(fresh(job.world, job.target.componentPath, request), run)).then(() => ({ kind: "success" }), (error) => ({
+			kind: "failed",
+			error: error instanceof Error ? error.message : String(error)
+		})).then((state) => this.commitNow((attempt) => {
+			const doc = attempt.get(job.componentPath, job.id);
+			if (doc === null || stateOf(doc).kind !== "inProgress") return;
+			attempt.write(job.componentPath, job.id, {
+				...doc,
+				state,
+				completedTime: this.now()
+			});
+		}));
+	}
+	/**
+	* Write through a fresh attempt and publish it at once, as the scheduler does
+	* for an action's schedule and a job's state. Nothing runs between the
+	* snapshot and the commit, so no other commit can conflict with it.
+	*/
+	commitNow(write) {
+		const attempt = new KernelAttempt(this.state);
+		const result = write(attempt);
+		this.publishWrites(attempt.writes());
+		return result;
+	}
+	/**
+	* Publish `writes` as the next commit, at the runtime's timestamp for it. No
+	* writes publish nothing and ask the runtime for no timestamp, which answers
+	* the latest commit's.
+	*/
+	publishWrites(writes) {
+		if (writes.length === 0) return this.state.commitTs;
+		const commitTs = this.runtime.commitTs(this.state.version + 1);
+		if (commitTs <= this.state.commitTs) throw new CommitTsNotIncreasing({
+			version: this.state.version + 1,
+			previous: this.state.commitTs,
+			commitTs,
+			message: `The runtime answered commit timestamp ${commitTs} for version ${this.state.version + 1}, which is not greater than the previous commit's ${this.state.commitTs}.`
+		});
+		this.state = apply(this.state, writes, commitTs);
+		return commitTs;
+	}
+	/**
+	* Write a pending job into `attempt`, so the job exists only once that
+	* attempt publishes. A job that a standing function schedules, or that runs
+	* one, is standing.
+	*/
+	scheduleJob(attempt, execution, args) {
+		const target = functionPathOf(args, execution.componentPath);
+		this.component(target.componentPath);
+		const jobArgs = jsonToConvex(args.args);
+		if (hasPendingValues(jobArgs)) throw new Error(`Invalid arguments for "${target.udfPath}": a scheduled function cannot take an unresolved placeholder value.`);
+		const id = this.generateId(table);
+		attempt.write(execution.componentPath, id, row(id, this.creationTime(execution.startTime), target.udfPath, jobArgs, args.ts * 1e3));
+		this.targets.set(id, {
+			functionPath: target,
+			standing: this.isStanding({
+				componentPath: execution.componentPath,
+				udfPath: execution.udfPath
+			}) || this.isStanding(target),
+			world: current$1()?.world
+		});
+		return id;
+	}
+	/**
+	* Cancel a job that has not finished. A finished job stays as it ended.
+	*/
+	cancelJob(attempt, componentPath, id) {
+		validateId(table, id);
+		attempt.readDocument(componentPath, id);
+		const doc = attempt.get(componentPath, id);
+		if (doc === null) throw new Error(`Patch on non-existent document with ID "${id}"`);
+		const { kind } = stateOf(doc);
+		if (kind === "pending" || kind === "inProgress") attempt.write(componentPath, id, {
+			...doc,
+			state: { kind: "canceled" }
+		});
+	}
+	isStanding({ componentPath, udfPath }) {
+		return this.components.get(componentPath)?.standing.has(udfPath) ?? false;
+	}
+	queryAt(functionPath, args, from, snapshotOnly = false) {
+		const resolved = this.resolve(functionPath, "query");
+		validateFunctionArgs(resolved.args, args ?? {}, functionPath, from.parent?.attempt !== void 0);
+		return this.runQuery(functionPath, resolved, args, from, snapshotOnly);
+	}
+	mutationAt(functionPath, args, from) {
+		const resolved = this.resolve(functionPath, "mutation");
+		validateFunctionArgs(resolved.args, args ?? {}, functionPath, from.parent?.attempt !== void 0);
+		return this.runMutation(functionPath, resolved, args, from);
+	}
+	actionAt(functionPath, args, from) {
+		const resolved = this.resolve(functionPath, "action");
+		validateFunctionArgs(resolved.args, args ?? {}, functionPath, false);
+		return this.runAction(functionPath, resolved, args, from);
+	}
+	execution(functionPath, udfType, attempt, from, pagination) {
+		const identity = functionPath.componentPath !== ROOT ? null : from.parent !== void 0 ? from.parent.identity : from.caller.identity;
+		return {
+			world: this,
+			componentPath: functionPath.componentPath,
+			udfPath: functionPath.udfPath,
+			udfType,
+			attempt,
+			identity,
+			request: from.request,
+			startTime: from.parent !== void 0 && from.parent.udfType !== "action" ? from.parent.startTime : this.now(),
+			pagination,
+			turn: new Turn()
+		};
+	}
+	runQuery(functionPath, resolved, args, from, snapshotOnly = false) {
+		const parentAttempt = from.parent?.attempt;
+		const isNested = parentAttempt !== void 0;
+		const attempt = parentAttempt === void 0 ? new KernelAttempt(this.state) : snapshotOnly ? new KernelAttempt(parentAttempt.snapshot) : parentAttempt;
+		const execution = this.execution(functionPath, "query", attempt, from, isNested && from.parent?.pagination || { calls: 0 });
+		const q = queryGeneric({ handler: (ctx, a) => resolved.handler({
+			...ctx,
+			auth: queryAuth(execution)
+		}, a) });
+		return enter(execution, () => q.invokeQuery(JSON.stringify(convexToJson([parseArgs(args)])))).then((raw) => settled(execution, raw)).then((raw) => {
+			const result = jsonToConvex(JSON.parse(raw));
+			if (!isNested && hasPendingValues(result)) throw new Error(`Function ${functionPath.udfPath} return value invalid: queries cannot return an unresolved placeholder value.`);
+			validateReturnValue(resolved.returns, result, "query", functionPath);
+			return result;
+		}).catch((error) => {
+			throw deserializeConvexErrorData(error);
+		});
+	}
+	invokeMutation(execution, resolved, args) {
+		const m = mutationGeneric({ handler: (ctx, a) => resolved.handler({
+			...ctx,
+			auth: mutationAuth(execution)
+		}, a) });
+		return enter(execution, () => m.invokeMutation(JSON.stringify(convexToJson([parseArgs(args)])))).then((raw) => settled(execution, raw)).then((raw) => {
+			const result = jsonToConvex(JSON.parse(raw));
+			validateReturnValue(resolved.returns, result, "mutation", {
+				componentPath: execution.componentPath,
+				udfPath: execution.udfPath
+			});
+			return result;
+		});
+	}
+	runMutation(functionPath, resolved, args, from) {
+		const parentAttempt = from.parent?.attempt;
+		if (parentAttempt !== void 0) {
+			const frame = parentAttempt.child();
+			const execution = this.execution(functionPath, "mutation", frame, from, void 0);
+			return this.invokeMutation(execution, resolved, args).then((result) => frame.drained().then(() => {
+				frame.close();
+				frame.merge();
+				return result;
+			}), (error) => {
+				frame.close();
+				throw deserializeConvexErrorData(error);
+			});
+		}
+		return this.prepareMutation(functionPath, resolved, args, from, 1, current$1()).then((held) => this.publish(held));
+	}
+	/**
+	* Run one attempt of a top-level mutation against the latest commit, then
+	* hold it. The commit point is once the function has returned and every
+	* syscall it started has settled. A test invocation bound when the mutation
+	* was first called reaches each attempt's handler with that attempt's
+	* number.
+	*/
+	prepareMutation(functionPath, resolved, args, from, number, bound) {
+		const attempt = new KernelAttempt(this.state, number);
+		const execution = this.execution(functionPath, "mutation", attempt, from, void 0);
+		const run = () => this.invokeMutation(execution, resolved, args);
+		return (bound === void 0 ? run() : bind({
+			...bound,
+			attempt: number
+		}, run)).then((value) => attempt.drained().then(() => ({
+			_tag: "returned",
+			value
+		})), (error) => ({
+			_tag: "failed",
+			error: deserializeConvexErrorData(error)
+		})).then((outcome) => {
+			attempt.close();
+			const held = {
+				view: {
+					id: `attempt-${this.nextAttemptId++}`,
+					request: from.request.requestId,
+					number,
+					snapshot: attempt.snapshot.version,
+					reads: attempt.reads,
+					outcome
+				},
+				attempt,
+				again: (next) => this.prepareMutation(functionPath, resolved, args, from, next, bound)
+			};
+			this.holding.set(held.view.id, held);
+			return held;
+		});
+	}
+	/**
+	* Validate a held attempt's reads against every commit since its snapshot,
+	* then publish its writes or prepare its next attempt. An attempt that wrote
+	* nothing publishes nothing and has nothing to validate. It answers its
+	* snapshot's version and commit timestamp.
+	*/
+	applyHeld({ view, attempt, again }) {
+		this.holding.delete(view.id);
+		const { outcome } = view;
+		if (outcome._tag === "failed") return Promise.resolve({
+			kind: "refused",
+			tag: tagOf(outcome.error),
+			error: outcome.error
+		});
+		const writes = attempt.writes();
+		if (writes.length === 0) {
+			const { version, commitTs } = attempt.snapshot;
+			return Promise.resolve({
+				kind: "applied",
+				version,
+				commitTs,
+				result: resolveCommittedValues(outcome.value, commitTs)
+			});
+		}
+		if (conflict(this.state, view.snapshot, attempt.reads) !== void 0) {
+			if (view.number === lastAttempt) return Promise.resolve({
+				kind: "exhausted",
+				error: new OptimisticConcurrencyControlFailure({
+					attempts: lastAttempt,
+					message: `Documents read by the mutation changed before each of its ${lastAttempt} attempts could commit.`
+				})
+			});
+			return again(view.number + 1).then((next) => ({
+				kind: "conflict",
+				next: next.view
+			}));
+		}
+		let commitTs;
+		try {
+			commitTs = this.publishWrites(writes);
+		} catch (error) {
+			return Promise.reject(error);
+		}
+		return Promise.resolve({
+			kind: "applied",
+			version: this.state.version,
+			commitTs,
+			result: resolveCommittedValues(outcome.value, commitTs)
+		});
+	}
+	/**
+	* Apply until the mutation publishes, is refused or is exhausted, as the
+	* binary retries a mutation that conflicts.
+	*/
+	publish(held) {
+		return this.applyHeld(held).then((applied) => {
+			if (applied.kind === "applied") return applied.result;
+			if (applied.kind === "conflict") return this.publish(this.holding.get(applied.next.id));
+			throw applied.error;
+		});
+	}
+	runAction(functionPath, resolved, args, from) {
+		const execution = this.execution(functionPath, "action", void 0, from, void 0);
+		const inner = {
+			request: from.request,
+			parent: execution
+		};
+		const a = actionGeneric({ handler: (ctx, innerArgs) => resolved.handler({
+			...ctx,
+			runQuery: (reference, queryArgs) => this.queryAt(pathOfReference(reference, functionPath.componentPath), queryArgs, inner),
+			runMutation: (reference, mutationArgs) => this.mutationAt(pathOfReference(reference, functionPath.componentPath), mutationArgs, inner),
+			runAction: (reference, actionArgs) => this.actionAt(pathOfReference(reference, functionPath.componentPath), actionArgs, inner),
+			auth: queryAuth(execution)
+		}, innerArgs) });
+		const run = () => enter(execution, () => a.invokeAction(from.request.requestId, JSON.stringify(convexToJson([parseArgs(args)]))));
+		const bound = from.parent === void 0 ? void 0 : current$1();
+		return (bound === void 0 ? run() : bind(fresh(bound.world, functionPath.componentPath, from.request), run)).then((raw) => {
+			const result = jsonToConvex(JSON.parse(raw));
+			validateReturnValue(resolved.returns, result, "action", functionPath);
+			return result;
+		}).catch((error) => {
+			throw deserializeConvexErrorData(error);
+		});
+	}
+	schema(componentPath) {
+		return this.component(componentPath).schema;
+	}
+	view(execution) {
+		const attempt = transaction(execution);
+		return {
+			schema: this.schema(execution.componentPath),
+			scan: (tableName) => attempt.scan(execution.componentPath, tableName),
+			read: (interval, after) => attempt.readInterval({
+				...interval,
+				componentPath: execution.componentPath,
+				after
+			})
+		};
+	}
+	generateId(table) {
+		return String(this.nextDocId++).padStart(TYPICAL_CONVEX_ID_LENGTH - table.length, "0") + table;
+	}
+	syscall(op, jsonArgs) {
+		const args = JSON.parse(jsonArgs);
+		const execution = current();
+		if (execution.attempt?.closed === true) throw closed(execution, op);
+		switch (op) {
+			case "1.0/getSnapshotTs": return JSON.stringify(convexToJson(transaction(execution).snapshot.commitTs));
+			case "1.0/queryStream": {
+				const queryId = this.nextQueryId++;
+				const view = this.view(execution);
+				let results;
+				this.queries.set(queryId, { next: () => (results ??= stream(view, args.query)).next() });
+				return JSON.stringify({ queryId });
+			}
+			case "1.0/queryCleanup":
+				this.queries.delete(args.queryId);
+				return JSON.stringify({});
+			case "1.0/db/normalizeId": {
+				const tableName = tableNameFromId(args.idString);
+				return JSON.stringify({ id: tableName === args.table ? args.idString : null });
+			}
+			default: throw new Error(`The test kernel does not support syscall: "${op}"`);
+		}
+	}
+	/**
+	* The binary queues a query's or mutation's async syscalls and runs them one
+	* at a time, oldest first (`start_async_syscall` and `run_inner` in
+	* `crates/isolate/src/environment/udf/mod.rs`, 1.49). A write and a nested
+	* call never share a batch (`AsyncSyscallBatch::can_push` in
+	* `async_syscall.rs`), and a nested call holds the queue until it has
+	* committed or rolled back its subtransaction (`run_udf` in
+	* `async_syscall.rs`). So a caller's write made after its nested call runs
+	* after that call, and a nested mutation sees every write made before it. An
+	* action's calls run side by side.
+	*/
+	asyncSyscall(op, jsonArgs) {
+		const execution = current();
+		const attempt = execution.attempt;
+		if (attempt === void 0) return Promise.resolve().then(() => this.dispatchAsync(op, JSON.parse(jsonArgs), execution));
+		if (attempt.closed) return Promise.reject(closed(execution, op));
+		const end = attempt.begin();
+		return execution.turn.take(() => this.dispatchAsync(op, JSON.parse(jsonArgs), execution)).finally(end);
+	}
+	dispatchAsync(op, args, execution) {
+		switch (op) {
+			case "1.0/get": {
+				const { table, id } = args;
+				return JSON.stringify(convexToJson(this.get(execution, table, id)));
+			}
+			case "1.0/queryStreamNext": {
+				const results = this.queries.get(args.queryId);
+				if (results === void 0) throw new Error("Bad queryId");
+				const { value, done } = results.next();
+				return JSON.stringify(convexToJson(done ? {
+					value: null,
+					done: true
+				} : {
+					value,
+					done: false
+				}));
+			}
+			case "1.0/queryPage": {
+				const pagination = execution.pagination;
+				if (pagination) {
+					pagination.calls += 1;
+					if (pagination.calls > 1) throw new Error("Only a single paginated query (`.paginate()`) is allowed per query, including nested query calls and component calls. This is a Convex limit: https://docs.convex.dev/database/pagination");
+				}
+				return JSON.stringify(convexToJson(paginate(this.view(execution), args)));
+			}
+			case "1.0/insert": return JSON.stringify({ _id: this.insert(execution, args.table, jsonToConvex(args.value)) });
+			case "1.0/shallowMerge":
+				this.patch(execution, args.table, args.id, args.value);
+				return JSON.stringify({});
+			case "1.0/replace":
+				this.replace(execution, args.table, args.id, args.value);
+				return JSON.stringify({});
+			case "1.0/remove":
+				this.remove(execution, args.table, args.id);
+				return JSON.stringify({});
+			case "1.0/count": {
+				const attempt = transaction(execution);
+				attempt.readInterval({
+					kind: "interval",
+					componentPath: execution.componentPath,
+					table: args.table,
+					fields: ["_creationTime", "_id"],
+					order: "asc",
+					range: [],
+					after: null
+				})("end");
+				return JSON.stringify(attempt.scan(execution.componentPath, args.table).length);
+			}
+			case "1.0/getFunctionMetadata": return JSON.stringify(convexToJson({
+				name: execution.udfPath,
+				componentPath: execution.componentPath
+			}));
+			case "1.0/getRequestMetadata":
+				if (execution.udfType === "query") throw new Error("getRequestMetadata() can only be called from a mutation, action or HTTP action. It is not available in queries.");
+				return JSON.stringify(convexToJson(execution.request));
+			case "1.0/getDeploymentMetadata": return JSON.stringify(convexToJson({
+				name: "test",
+				region: null,
+				class: "s16"
+			}));
+			case "1.0/actions/query":
+			case "1.0/actions/mutation":
+			case "1.0/actions/action": {
+				const from = {
+					request: execution.request,
+					parent: execution
+				};
+				const functionPath = functionPathOf(args, execution.componentPath);
+				return (op === "1.0/actions/query" ? this.queryAt(functionPath, args.args, from) : op === "1.0/actions/mutation" ? this.mutationAt(functionPath, args.args, from) : this.actionAt(functionPath, args.args, from)).then((value) => JSON.stringify(convexToJson(value)));
+			}
+			case "1.0/runUdf": {
+				const { udfType, args: udfArgs } = args;
+				const from = {
+					request: execution.request,
+					parent: execution
+				};
+				const functionPath = functionPathOf(args, execution.componentPath);
+				const value = jsonToConvex(udfArgs);
+				return (udfType === "query" ? this.queryAt(functionPath, value, from) : udfType === "snapshotQuery" ? this.queryAt(functionPath, value, from, true) : udfType === "mutation" ? this.mutationAt(functionPath, value, from) : Promise.reject(/* @__PURE__ */ new Error(`The test kernel does not support udf type: "${udfType}"`))).then((result) => JSON.stringify(convexToJson(result)));
+			}
+			case "1.0/createFunctionHandle": {
+				const functionPath = functionPathOf(args, execution.componentPath);
+				this.component(functionPath.componentPath);
+				return JSON.stringify(createFunctionHandle(functionPath));
+			}
+			case "1.0/auditLog": return JSON.stringify(null);
+			case "1.0/schedule": return JSON.stringify(convexToJson(this.scheduleJob(transaction(execution), execution, args)));
+			case "1.0/actions/schedule": return JSON.stringify(convexToJson(this.commitNow((attempt) => this.scheduleJob(attempt, execution, args))));
+			case "1.0/cancel_job":
+				this.cancelJob(transaction(execution), execution.componentPath, args.id);
+				return JSON.stringify({});
+			case "1.0/actions/cancel_job":
+				this.commitNow((attempt) => this.cancelJob(attempt, execution.componentPath, args.id));
+				return JSON.stringify({});
+			case "1.0/storageDelete":
+			case "1.0/storageGetUrl":
+			case "1.0/storageGenerateUploadUrl": throw rowPending("storage", 6);
+			case "1.0/getTransactionMetrics": throw rowPending("transaction limits", 6);
+			case "1.0/actions/vectorSearch": throw requiresBinary("vectorSearch");
+			default: throw new Error(`The test kernel does not support async syscall: "${op}"`);
+		}
+	}
+	jsSyscall(op) {
+		return Promise.reject(op.startsWith("storage/") ? rowPending("storage", 6) : /* @__PURE__ */ new Error(`The test kernel does not support js syscall: "${op}"`));
+	}
+	get(execution, tableName, id) {
+		validateId(tableName, id);
+		const attempt = transaction(execution);
+		attempt.readDocument(execution.componentPath, id);
+		return attempt.get(execution.componentPath, id);
+	}
+	insert(execution, table, value) {
+		const attempt = transaction(execution);
+		validateDocument(this.schema(execution.componentPath), table, value);
+		const _id = this.generateId(table);
+		attempt.write(execution.componentPath, _id, {
+			...value,
+			_id,
+			_creationTime: this.creationTime(execution.startTime)
+		});
+		return _id;
+	}
+	/**
+	* A new document's creation time: `at`, or just past the latest one, so no
+	* two documents share one.
+	*/
+	creationTime(at) {
+		const time = at <= this.lastCreationTime ? this.lastCreationTime + .001 : at;
+		this.lastCreationTime = time;
+		return time;
+	}
+	existing(execution, tableName, id, write, value) {
+		validateId(tableName, id);
+		if (value !== void 0 && typeof value !== "object") throw new Error(`Invalid argument \`value\` in \`db.${write}\`, expected object but got '${typeof value}': ${value}`);
+		const attempt = transaction(execution);
+		attempt.readDocument(execution.componentPath, id);
+		const document = attempt.get(execution.componentPath, id);
+		if (document === null) throw new Error(write === "delete" ? "Delete on non-existent doc" : `${write === "patch" ? "Patch" : "Replace"} on non-existent document with ID "${id}"`);
+		return document;
+	}
+	fields(document, value) {
+		if (value._id !== void 0 && value._id !== document._id) throw new Error(`Provided \`_id\` field value "${value._id}" does not match the document ID "${document._id}"`);
+		if (value._creationTime !== void 0 && value._creationTime !== document._creationTime) throw new Error(`Provided \`_creationTime\` field value ${value._creationTime} does not match the document's creation time ${document._creationTime}`);
+		const convexValue = {};
+		for (const [key, v] of Object.entries(value)) if (key !== "_id" && key !== "_creationTime") convexValue[key] = evaluateValue(v);
+		return convexValue;
+	}
+	patch(execution, tableName, id, value) {
+		const document = this.existing(execution, tableName, id, "patch", value);
+		const { _id, _creationTime, ...fields } = document;
+		const merged = {
+			...fields,
+			...this.fields(document, value)
+		};
+		validateDocument(this.schema(execution.componentPath), tableNameFromId(_id), merged);
+		transaction(execution).write(execution.componentPath, _id, {
+			_id,
+			_creationTime,
+			...merged
+		});
+	}
+	replace(execution, tableName, id, value) {
+		const document = this.existing(execution, tableName, id, "replace", value);
+		const fields = this.fields(document, value);
+		validateDocument(this.schema(execution.componentPath), tableNameFromId(document._id), fields);
+		transaction(execution).write(execution.componentPath, document._id, {
+			...fields,
+			_id: document._id,
+			_creationTime: document._creationTime
+		});
+	}
+	remove(execution, tableName, id) {
+		const document = this.existing(execution, tableName, id, "delete", void 0);
+		transaction(execution).write(execution.componentPath, document._id, null);
+	}
+};
+const closed = (execution, operation) => new ClosedAttempt({
+	operation,
+	message: `"${operation}" reached mutation ${execution.udfPath} after it returned and its syscalls settled. Await every read and write inside the handler.`
+});
+const transaction = (execution) => {
+	if (execution.attempt === void 0) throw new Error("The database is only available in queries and mutations. An action reads and writes through `ctx.runQuery` and `ctx.runMutation`.");
+	return execution.attempt;
+};
+const queryAuth = (execution) => ({ getUserIdentity: () => Promise.resolve(execution.identity) });
+const mutationAuth = (execution) => ({
+	...queryAuth(execution),
+	signJwt: () => Promise.reject(rowPending("JWT signing", 6))
+});
+function validateId(expectedTableName, id) {
+	if (typeof id !== "string") throw new Error(`Invalid argument \`id\`, expected string but got '${typeof id}': ${id}`);
+	if (expectedTableName === void 0) return;
+	if (typeof expectedTableName !== "string") throw new Error(`Invalid argument \`tableName\`, expected string but got '${typeof expectedTableName}': ${expectedTableName}`);
+	const actualTableName = tableNameFromId(id);
+	if (actualTableName === null) throw new Error(`Invalid argument \`id\`, expected ID value but got '${id}'`);
+	if (actualTableName !== expectedTableName) throw new Error(`Invalid argument \`id\`, expected ID in table '${expectedTableName}' but got ID in table '${actualTableName}'`);
+}
+/**
+* The backend another library installed as `globalThis.Convex`, which answers
+* every syscall made outside a kernel function.
+*/
+let forwarded;
+const backend = () => executions.getStore()?.world ?? forwarded ?? current().world;
+const dispatcher = {
+	[kernelBrand]: true,
+	syscall: (op, args) => backend().syscall(op, args),
+	asyncSyscall: (op, args) => backend().asyncSyscall(op, args),
+	jsSyscall: (op, args) => backend().jsSyscall(op, args)
+};
+/**
+* Convex's server library reaches the backend through `globalThis.Convex`, one
+* global for the whole test runtime. convex-test 0.0.65 assigns its own the
+* first time it builds a world (its `dist/index.js:1936-1951`), whenever that
+* is. The kernel keeps the global an accessor that always reads its dispatcher,
+* and takes an assignment, or the global it found, as the backend for syscalls
+* made outside a kernel function. So a kernel world and a convex-test world
+* stay live together, whichever was built first, and no world restores the
+* global when it ends. A test that redefines the global removes the accessor,
+* so every kernel function installs it again over what the test left.
+*/
+const installConvexGlobal = () => {
+	const found = globalThis.Convex;
+	if (found?.[kernelBrand] === true) return;
+	forwarded = found;
+	Object.defineProperty(globalThis, "Convex", {
+		get: () => dispatcher,
+		set: (value) => {
+			if (value?.[kernelBrand] !== true) forwarded = value;
+		},
+		configurable: true,
+		enumerable: true
+	});
+};
+/**
+* Whether `globalThis.Convex` is the kernel's, and no other backend installed
+* one behind it.
+*/
+const ownsConvexGlobal = () => globalThis.Convex?.[kernelBrand] === true && forwarded === void 0;
+//#endregion
+export { World, anonymous, ownsConvexGlobal, withIdentity };
+
+//# sourceMappingURL=Execution.js.map