@gaganref/confect-test 10.3.1-fork.86 → 10.3.1-fork.88

package/dist/internal/Invocation.d.ts

@@ -0,0 +1,57 @@
+import type { RequestMetadata } from "convex/server";
+import type * as Context from "effect/Context";
+/**
+ * Four re-executions after the first try. A conflict on attempt 5 exhausts.
+ */
+export type Attempt = 1 | 2 | 3 | 4 | 5;
+/**
+ * One test backend. Its `services`, `clock` and `random` reach every invocation
+ * it starts on its own, such as a scheduled job.
+ */
+export interface World {
+    readonly name: string;
+    readonly services: Context.Context<never>;
+    /**
+     * The world's controlled clock in epoch milliseconds. An invocation the world
+     * starts on its own pins its start time from one reading. A bound action's
+     * `Date` reads it live.
+     */
+    readonly clock: () => number;
+    /**
+     * The random stream, uniform on [0, 1), that an invocation the world starts
+     * on its own draws from.
+     */
+    readonly random: () => number;
+}
+export interface Invocation {
+    readonly world: World;
+    readonly componentPath: string;
+    readonly attempt: Attempt;
+    readonly request: Omit<RequestMetadata, "authToken">;
+    readonly services: Context.Context<never>;
+    /**
+     * The start time in epoch milliseconds. Every query or mutation of the
+     * invocation reads it from `Date.now()` and `new Date()`, so Effect's default
+     * `Clock` reads it too. An action reads its world's clock instead, as it
+     * runs, and a query or mutation an action calls starts at the action's time
+     * then.
+     */
+    readonly startedAt: number;
+    /**
+     * The random stream, uniform on [0, 1). Every handler of the invocation draws
+     * from it through `Math.random` and `crypto.getRandomValues`, so Effect's
+     * default `Random` draws from it too.
+     */
+    readonly random: () => number;
+}
+/**
+ * Run `start` with `invocation` bound. Every registered handler it reaches
+ * through convex-test runs with the invocation's services, clock and random
+ * stream.
+ */
+export declare const bind: <A>(invocation: Invocation, start: () => Promise<A>) => Promise<A>;
+/**
+ * The invocation the calling handler runs under, if one is bound.
+ */
+export declare const current: () => Invocation | undefined;
+//# sourceMappingURL=Invocation.d.ts.map

package/dist/internal/Invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Invocation.d.ts","sourceRoot":"","sources":["../../src/internal/Invocation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;CAC/B;AA+ND;;;;GAIG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,cACR,UAAU,SACf,MAAM,OAAO,CAAC,CAAC,CAAC,KACtB,OAAO,CAAC,CAAC,CAIT,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,OAAO,QAAO,UAAU,GAAG,SACQ,CAAC"}

package/dist/internal/Invocation.js

@@ -0,0 +1,145 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/internal/Invocation.ts
+const key = Symbol.for("@confect/test/Invocation");
+/**
+* The invocation a function of `functionType` called from `running` joins. A
+* query or mutation an action calls is a transaction of its own, so it starts
+* at the world's time when it begins. Any other call shares its caller's
+* start.
+*/
+const caller = (running, functionType) => running.functionType === "action" && functionType !== "action" ? {
+	...running.invocation,
+	startedAt: running.invocation.world.clock()
+} : running.invocation;
+/**
+* The invocation a handler runs under. A call nested in the bound request joins
+* it at the callee's component path. A job Convex started from a timer set
+* inside the bound request is a request of its own: its scheduled function ID
+* differs, so it gets a fresh record with the world's services, clock and
+* random stream.
+*/
+const resolve = (bound, componentPath, request) => {
+	if (request !== void 0 && request.scheduledFunctionId !== bound.request.scheduledFunctionId) {
+		const { ip, userAgent, requestId, scheduledFunctionId } = request;
+		return {
+			world: bound.world,
+			componentPath,
+			attempt: 1,
+			request: {
+				ip,
+				userAgent,
+				requestId,
+				scheduledFunctionId
+			},
+			services: bound.world.services,
+			startedAt: bound.world.clock(),
+			random: bound.world.random
+		};
+	}
+	return componentPath === bound.componentPath ? bound : {
+		...bound,
+		componentPath
+	};
+};
+/**
+* What `Date` answers for a function of `functionType` under `invocation`: a
+* query's or mutation's start, or the world's clock as it runs in an action.
+*/
+const clockOf = (invocation, functionType) => functionType === "action" ? invocation.world.clock : () => invocation.startedAt;
+const pinnedDate = (base, now) => new Proxy(base, {
+	get: (target, property, receiver) => property === "now" ? now : Reflect.get(target, property, receiver),
+	construct: (target, args, newTarget) => Reflect.construct(target, args.length === 0 ? [now()] : args, newTarget),
+	apply: () => new base(now()).toString()
+});
+const drawingMath = (base, random) => new Proxy(base, { get: (target, property, receiver) => property === "random" ? random : Reflect.get(target, property, receiver) });
+const drawingCrypto = (base, random) => {
+	function getRandomValues(array) {
+		Reflect.apply(base.getRandomValues, this === drawing ? base : this, [array]);
+		if (array === null) return array;
+		const bytes = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+		for (let index = 0; index < bytes.length; index++) bytes[index] = Math.floor(random() * 256);
+		return array;
+	}
+	const drawing = new Proxy(base, { get: (target, property) => {
+		if (property === "getRandomValues") return getRandomValues;
+		const value = Reflect.get(target, property, target);
+		return typeof value === "function" ? value.bind(target) : value;
+	} });
+	return drawing;
+};
+/**
+* Point the calling handler's `Date`, `Math` and `crypto` at `invocation`, its
+* `Date` through {@link clockOf}. convex-test gives each handler call its own
+* copy of these globals, and an assignment inside a handler lands in that copy
+* only, so overlapping handlers and the handler's own nested calls keep
+* theirs.
+*
+* `outside` reads in the test's own async context. Where the handler has no
+* copy, an assignment either throws or reaches test code, so `pin` puts back
+* each global that reached it and throws.
+*/
+const pin = (invocation, functionType, outside) => {
+	const host = globalThis;
+	const previous = {
+		Date: host.Date,
+		Math: host.Math,
+		crypto: host.crypto
+	};
+	const pinned = {
+		Date: pinnedDate(previous.Date, clockOf(invocation, functionType)),
+		Math: drawingMath(previous.Math, invocation.random),
+		crypto: drawingCrypto(previous.crypto, invocation.random)
+	};
+	try {
+		host.Date = pinned.Date;
+		host.Math = pinned.Math;
+		host.crypto = pinned.crypto;
+	} catch {}
+	const reached = outside(() => ({
+		Date: host.Date === pinned.Date,
+		Math: host.Math === pinned.Math,
+		crypto: host.crypto === pinned.crypto
+	}));
+	if (host.Date === pinned.Date && host.Math === pinned.Math && host.crypto === pinned.crypto && !reached.Date && !reached.Math && !reached.crypto) return;
+	if (reached.Date) host.Date = previous.Date;
+	if (reached.Math) host.Math = previous.Math;
+	if (reached.crypto) host.crypto = previous.crypto;
+	throw new Error("@confect/test cannot pin this handler's Date, Math and crypto: it runs without convex-test's per-handler globals, so pinning would change them for every caller");
+};
+const make = () => {
+	const storage = new AsyncLocalStorage();
+	const outside = AsyncLocalStorage.snapshot();
+	return {
+		storage,
+		start: (meta, run, functionType) => {
+			const running = storage.getStore();
+			if (running === void 0) return void 0;
+			return Promise.all([meta.getFunctionMetadata(), meta.getRequestMetadata?.()]).then(([{ componentPath }, request]) => {
+				const invocation = resolve(caller(running, functionType), componentPath, request);
+				pin(invocation, functionType, outside);
+				return storage.run({
+					invocation,
+					functionType
+				}, () => run(invocation.services));
+			});
+		}
+	};
+};
+const installed = globalThis;
+/**
+* Run `start` with `invocation` bound. Every registered handler it reaches
+* through convex-test runs with the invocation's services, clock and random
+* stream.
+*/
+const bind = (invocation, start) => (installed[key] ??= make()).storage.run({
+	invocation,
+	functionType: void 0
+}, start);
+/**
+* The invocation the calling handler runs under, if one is bound.
+*/
+const current = () => installed[key]?.storage.getStore()?.invocation;
+//#endregion
+export { bind, current };
+
+//# sourceMappingURL=Invocation.js.map

package/dist/internal/Invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Invocation.js","names":[],"sources":["../../src/internal/Invocation.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { FunctionMetadata, RequestMetadata } from \"convex/server\";\nimport type * as Context from \"effect/Context\";\n\n/**\n * Four re-executions after the first try. A conflict on attempt 5 exhausts.\n */\nexport type Attempt = 1 | 2 | 3 | 4 | 5;\n\n/**\n * One test backend. Its `services`, `clock` and `random` reach every invocation\n * it starts on its own, such as a scheduled job.\n */\nexport interface World {\n  readonly name: string;\n  readonly services: Context.Context<never>;\n  /**\n   * The world's controlled clock in epoch milliseconds. An invocation the world\n   * starts on its own pins its start time from one reading. A bound action's\n   * `Date` reads it live.\n   */\n  readonly clock: () => number;\n  /**\n   * The random stream, uniform on [0, 1), that an invocation the world starts\n   * on its own draws from.\n   */\n  readonly random: () => number;\n}\n\nexport interface Invocation {\n  readonly world: World;\n  readonly componentPath: string;\n  readonly attempt: Attempt;\n  readonly request: Omit<RequestMetadata, \"authToken\">;\n  readonly services: Context.Context<never>;\n  /**\n   * The start time in epoch milliseconds. Every query or mutation of the\n   * invocation reads it from `Date.now()` and `new Date()`, so Effect's default\n   * `Clock` reads it too. An action reads its world's clock instead, as it\n   * runs, and a query or mutation an action calls starts at the action's time\n   * then.\n   */\n  readonly startedAt: number;\n  /**\n   * The random stream, uniform on [0, 1). Every handler of the invocation draws\n   * from it through `Math.random` and `crypto.getRandomValues`, so Effect's\n   * default `Random` draws from it too.\n   */\n  readonly random: () => number;\n}\n\ntype FunctionType = \"query\" | \"mutation\" | \"action\";\n\n/**\n * The invocation a handler runs under, and the type of the function it runs.\n * Test code that binds an invocation runs no function, so it has no type.\n */\ninterface Running {\n  readonly invocation: Invocation;\n  readonly functionType: FunctionType | undefined;\n}\n\n/**\n * What `runHandlerPromise` in `@confect/server` reads from `globalThis` under\n * the same key. `start` answers `undefined` when no invocation is bound.\n */\ninterface Bridge {\n  readonly storage: AsyncLocalStorage<Running>;\n  readonly start: <A>(\n    meta: {\n      readonly getFunctionMetadata: () => Promise<FunctionMetadata>;\n      readonly getRequestMetadata?: () => Promise<RequestMetadata>;\n    },\n    run: (services: Context.Context<never>) => Promise<A>,\n    functionType: FunctionType,\n  ) => Promise<A> | undefined;\n}\n\nconst key = Symbol.for(\"@confect/test/Invocation\");\n\n/**\n * The invocation a function of `functionType` called from `running` joins. A\n * query or mutation an action calls is a transaction of its own, so it starts\n * at the world's time when it begins. Any other call shares its caller's\n * start.\n */\nconst caller = (running: Running, functionType: FunctionType): Invocation =>\n  running.functionType === \"action\" && functionType !== \"action\"\n    ? { ...running.invocation, startedAt: running.invocation.world.clock() }\n    : running.invocation;\n\n/**\n * The invocation a handler runs under. A call nested in the bound request joins\n * it at the callee's component path. A job Convex started from a timer set\n * inside the bound request is a request of its own: its scheduled function ID\n * differs, so it gets a fresh record with the world's services, clock and\n * random stream.\n */\nconst resolve = (\n  bound: Invocation,\n  componentPath: string,\n  request: RequestMetadata | undefined,\n): Invocation => {\n  if (\n    request !== undefined &&\n    request.scheduledFunctionId !== bound.request.scheduledFunctionId\n  ) {\n    const { ip, userAgent, requestId, scheduledFunctionId } = request;\n    return {\n      world: bound.world,\n      componentPath,\n      attempt: 1,\n      request: { ip, userAgent, requestId, scheduledFunctionId },\n      services: bound.world.services,\n      startedAt: bound.world.clock(),\n      random: bound.world.random,\n    };\n  }\n  return componentPath === bound.componentPath\n    ? bound\n    : { ...bound, componentPath };\n};\n\n/**\n * What `Date` answers for a function of `functionType` under `invocation`: a\n * query's or mutation's start, or the world's clock as it runs in an action.\n */\nconst clockOf = (\n  invocation: Invocation,\n  functionType: FunctionType,\n): (() => number) =>\n  functionType === \"action\"\n    ? invocation.world.clock\n    : () => invocation.startedAt;\n\nconst pinnedDate = (\n  base: DateConstructor,\n  now: () => number,\n): DateConstructor =>\n  new Proxy(base, {\n    get: (target, property, receiver) =>\n      property === \"now\" ? now : Reflect.get(target, property, receiver),\n    construct: (target, args, newTarget) =>\n      Reflect.construct(target, args.length === 0 ? [now()] : args, newTarget),\n    apply: () => new base(now()).toString(),\n  });\n\nconst drawingMath = (base: Math, random: () => number): Math =>\n  new Proxy(base, {\n    get: (target, property, receiver) =>\n      property === \"random\" ? random : Reflect.get(target, property, receiver),\n  });\n\nconst drawingCrypto = (base: Crypto, random: () => number): Crypto => {\n  function getRandomValues<T extends Parameters<Crypto[\"getRandomValues\"]>[0]>(\n    this: unknown,\n    array: T,\n  ): T {\n    // The host call checks the receiver and the argument and throws the host's\n    // errors, so a detached call fails as it does in production.\n    // oxlint-disable-next-line typescript/unbound-method -- Applied with the caller's receiver.\n    Reflect.apply(base.getRandomValues, this === drawing ? base : this, [\n      array,\n    ]);\n    if (array === null) return array;\n    const bytes = new Uint8Array(\n      array.buffer,\n      array.byteOffset,\n      array.byteLength,\n    );\n    for (let index = 0; index < bytes.length; index++) {\n      bytes[index] = Math.floor(random() * 256);\n    }\n    return array;\n  }\n  const drawing: Crypto = new Proxy(base, {\n    get: (target, property) => {\n      if (property === \"getRandomValues\") return getRandomValues;\n      // Crypto's methods and getters need the host object as `this`.\n      const value: unknown = Reflect.get(target, property, target);\n      return typeof value === \"function\" ? value.bind(target) : value;\n    },\n  });\n  return drawing;\n};\n\n/**\n * Point the calling handler's `Date`, `Math` and `crypto` at `invocation`, its\n * `Date` through {@link clockOf}. convex-test gives each handler call its own\n * copy of these globals, and an assignment inside a handler lands in that copy\n * only, so overlapping handlers and the handler's own nested calls keep\n * theirs.\n *\n * `outside` reads in the test's own async context. Where the handler has no\n * copy, an assignment either throws or reaches test code, so `pin` puts back\n * each global that reached it and throws.\n */\nconst pin = (\n  invocation: Invocation,\n  functionType: FunctionType,\n  outside: <R>(read: () => R) => R,\n): void => {\n  const host = globalThis;\n  const previous = { Date: host.Date, Math: host.Math, crypto: host.crypto };\n  const pinned = {\n    Date: pinnedDate(previous.Date, clockOf(invocation, functionType)),\n    Math: drawingMath(previous.Math, invocation.random),\n    crypto: drawingCrypto(previous.crypto, invocation.random),\n  };\n  try {\n    host.Date = pinned.Date;\n    host.Math = pinned.Math;\n    host.crypto = pinned.crypto;\n  } catch {\n    // A global without a per-handler copy can be read-only. The check below\n    // refuses the handler.\n  }\n  const reached = outside(() => ({\n    Date: host.Date === pinned.Date,\n    Math: host.Math === pinned.Math,\n    crypto: host.crypto === pinned.crypto,\n  }));\n  if (\n    host.Date === pinned.Date &&\n    host.Math === pinned.Math &&\n    host.crypto === pinned.crypto &&\n    !reached.Date &&\n    !reached.Math &&\n    !reached.crypto\n  ) {\n    return;\n  }\n  if (reached.Date) host.Date = previous.Date;\n  if (reached.Math) host.Math = previous.Math;\n  if (reached.crypto) host.crypto = previous.crypto;\n  throw new Error(\n    \"@confect/test cannot pin this handler's Date, Math and crypto: it runs without convex-test's per-handler globals, so pinning would change them for every caller\",\n  );\n};\n\nconst make = (): Bridge => {\n  const storage = new AsyncLocalStorage<Running>();\n  // Taken at the first `bind`, which test code calls outside any handler, so\n  // it reads the test environment's globals.\n  const outside = AsyncLocalStorage.snapshot();\n  return {\n    storage,\n    start: (meta, run, functionType) => {\n      const running = storage.getStore();\n      if (running === undefined) return undefined;\n      return Promise.all([\n        meta.getFunctionMetadata(),\n        meta.getRequestMetadata?.(),\n      ]).then(([{ componentPath }, request]) => {\n        const invocation = resolve(\n          caller(running, functionType),\n          componentPath,\n          request,\n        );\n        pin(invocation, functionType, outside);\n        return storage.run({ invocation, functionType }, () =>\n          run(invocation.services),\n        );\n      });\n    },\n  };\n};\n\n// One bridge per test runtime, so every copy of this module that a test loads\n// binds through the store `runHandlerPromise` reads.\nconst installed = globalThis as { [key]?: Bridge };\n\n/**\n * Run `start` with `invocation` bound. Every registered handler it reaches\n * through convex-test runs with the invocation's services, clock and random\n * stream.\n */\nexport const bind = <A>(\n  invocation: Invocation,\n  start: () => Promise<A>,\n): Promise<A> =>\n  (installed[key] ??= make()).storage.run(\n    { invocation, functionType: undefined },\n    start,\n  );\n\n/**\n * The invocation the calling handler runs under, if one is bound.\n */\nexport const current = (): Invocation | undefined =>\n  installed[key]?.storage.getStore()?.invocation;\n"],"mappings":"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"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@gaganref/confect-test",
-  "version": "10.3.1-fork.86",
+  "version": "10.3.1-fork.88",
   "peerDependencies": {
-    "@confect/core": "npm:@gaganref/confect-core@10.3.1-fork.86",
-    "@confect/server": "npm:@gaganref/confect-server@10.3.1-fork.86",
+    "@confect/core": "npm:@gaganref/confect-core@10.3.1-fork.88",
+    "@confect/server": "npm:@gaganref/confect-server@10.3.1-fork.88",
     "convex": "^1.32.0",
     "convex-test": ">=0.0.65 <0.1.0",
     "effect": ">=4.0.0 <4.1.0"

package/src/internal/Invocation.ts

@@ -0,0 +1,291 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { FunctionMetadata, RequestMetadata } from "convex/server";
+import type * as Context from "effect/Context";
+
+/**
+ * Four re-executions after the first try. A conflict on attempt 5 exhausts.
+ */
+export type Attempt = 1 | 2 | 3 | 4 | 5;
+
+/**
+ * One test backend. Its `services`, `clock` and `random` reach every invocation
+ * it starts on its own, such as a scheduled job.
+ */
+export interface World {
+  readonly name: string;
+  readonly services: Context.Context<never>;
+  /**
+   * The world's controlled clock in epoch milliseconds. An invocation the world
+   * starts on its own pins its start time from one reading. A bound action's
+   * `Date` reads it live.
+   */
+  readonly clock: () => number;
+  /**
+   * The random stream, uniform on [0, 1), that an invocation the world starts
+   * on its own draws from.
+   */
+  readonly random: () => number;
+}
+
+export interface Invocation {
+  readonly world: World;
+  readonly componentPath: string;
+  readonly attempt: Attempt;
+  readonly request: Omit<RequestMetadata, "authToken">;
+  readonly services: Context.Context<never>;
+  /**
+   * The start time in epoch milliseconds. Every query or mutation of the
+   * invocation reads it from `Date.now()` and `new Date()`, so Effect's default
+   * `Clock` reads it too. An action reads its world's clock instead, as it
+   * runs, and a query or mutation an action calls starts at the action's time
+   * then.
+   */
+  readonly startedAt: number;
+  /**
+   * The random stream, uniform on [0, 1). Every handler of the invocation draws
+   * from it through `Math.random` and `crypto.getRandomValues`, so Effect's
+   * default `Random` draws from it too.
+   */
+  readonly random: () => number;
+}
+
+type FunctionType = "query" | "mutation" | "action";
+
+/**
+ * The invocation a handler runs under, and the type of the function it runs.
+ * Test code that binds an invocation runs no function, so it has no type.
+ */
+interface Running {
+  readonly invocation: Invocation;
+  readonly functionType: FunctionType | undefined;
+}
+
+/**
+ * What `runHandlerPromise` in `@confect/server` reads from `globalThis` under
+ * the same key. `start` answers `undefined` when no invocation is bound.
+ */
+interface Bridge {
+  readonly storage: AsyncLocalStorage<Running>;
+  readonly start: <A>(
+    meta: {
+      readonly getFunctionMetadata: () => Promise<FunctionMetadata>;
+      readonly getRequestMetadata?: () => Promise<RequestMetadata>;
+    },
+    run: (services: Context.Context<never>) => Promise<A>,
+    functionType: FunctionType,
+  ) => Promise<A> | undefined;
+}
+
+const key = Symbol.for("@confect/test/Invocation");
+
+/**
+ * The invocation a function of `functionType` called from `running` joins. A
+ * query or mutation an action calls is a transaction of its own, so it starts
+ * at the world's time when it begins. Any other call shares its caller's
+ * start.
+ */
+const caller = (running: Running, functionType: FunctionType): Invocation =>
+  running.functionType === "action" && functionType !== "action"
+    ? { ...running.invocation, startedAt: running.invocation.world.clock() }
+    : running.invocation;
+
+/**
+ * The invocation a handler runs under. A call nested in the bound request joins
+ * it at the callee's component path. A job Convex started from a timer set
+ * inside the bound request is a request of its own: its scheduled function ID
+ * differs, so it gets a fresh record with the world's services, clock and
+ * random stream.
+ */
+const resolve = (
+  bound: Invocation,
+  componentPath: string,
+  request: RequestMetadata | undefined,
+): Invocation => {
+  if (
+    request !== undefined &&
+    request.scheduledFunctionId !== bound.request.scheduledFunctionId
+  ) {
+    const { ip, userAgent, requestId, scheduledFunctionId } = request;
+    return {
+      world: bound.world,
+      componentPath,
+      attempt: 1,
+      request: { ip, userAgent, requestId, scheduledFunctionId },
+      services: bound.world.services,
+      startedAt: bound.world.clock(),
+      random: bound.world.random,
+    };
+  }
+  return componentPath === bound.componentPath
+    ? bound
+    : { ...bound, componentPath };
+};
+
+/**
+ * What `Date` answers for a function of `functionType` under `invocation`: a
+ * query's or mutation's start, or the world's clock as it runs in an action.
+ */
+const clockOf = (
+  invocation: Invocation,
+  functionType: FunctionType,
+): (() => number) =>
+  functionType === "action"
+    ? invocation.world.clock
+    : () => invocation.startedAt;
+
+const pinnedDate = (
+  base: DateConstructor,
+  now: () => number,
+): DateConstructor =>
+  new Proxy(base, {
+    get: (target, property, receiver) =>
+      property === "now" ? now : Reflect.get(target, property, receiver),
+    construct: (target, args, newTarget) =>
+      Reflect.construct(target, args.length === 0 ? [now()] : args, newTarget),
+    apply: () => new base(now()).toString(),
+  });
+
+const drawingMath = (base: Math, random: () => number): Math =>
+  new Proxy(base, {
+    get: (target, property, receiver) =>
+      property === "random" ? random : Reflect.get(target, property, receiver),
+  });
+
+const drawingCrypto = (base: Crypto, random: () => number): Crypto => {
+  function getRandomValues<T extends Parameters<Crypto["getRandomValues"]>[0]>(
+    this: unknown,
+    array: T,
+  ): T {
+    // The host call checks the receiver and the argument and throws the host's
+    // errors, so a detached call fails as it does in production.
+    // oxlint-disable-next-line typescript/unbound-method -- Applied with the caller's receiver.
+    Reflect.apply(base.getRandomValues, this === drawing ? base : this, [
+      array,
+    ]);
+    if (array === null) return array;
+    const bytes = new Uint8Array(
+      array.buffer,
+      array.byteOffset,
+      array.byteLength,
+    );
+    for (let index = 0; index < bytes.length; index++) {
+      bytes[index] = Math.floor(random() * 256);
+    }
+    return array;
+  }
+  const drawing: Crypto = new Proxy(base, {
+    get: (target, property) => {
+      if (property === "getRandomValues") return getRandomValues;
+      // Crypto's methods and getters need the host object as `this`.
+      const value: unknown = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+  return drawing;
+};
+
+/**
+ * Point the calling handler's `Date`, `Math` and `crypto` at `invocation`, its
+ * `Date` through {@link clockOf}. convex-test gives each handler call its own
+ * copy of these globals, and an assignment inside a handler lands in that copy
+ * only, so overlapping handlers and the handler's own nested calls keep
+ * theirs.
+ *
+ * `outside` reads in the test's own async context. Where the handler has no
+ * copy, an assignment either throws or reaches test code, so `pin` puts back
+ * each global that reached it and throws.
+ */
+const pin = (
+  invocation: Invocation,
+  functionType: FunctionType,
+  outside: <R>(read: () => R) => R,
+): void => {
+  const host = globalThis;
+  const previous = { Date: host.Date, Math: host.Math, crypto: host.crypto };
+  const pinned = {
+    Date: pinnedDate(previous.Date, clockOf(invocation, functionType)),
+    Math: drawingMath(previous.Math, invocation.random),
+    crypto: drawingCrypto(previous.crypto, invocation.random),
+  };
+  try {
+    host.Date = pinned.Date;
+    host.Math = pinned.Math;
+    host.crypto = pinned.crypto;
+  } catch {
+    // A global without a per-handler copy can be read-only. The check below
+    // refuses the handler.
+  }
+  const reached = outside(() => ({
+    Date: host.Date === pinned.Date,
+    Math: host.Math === pinned.Math,
+    crypto: host.crypto === pinned.crypto,
+  }));
+  if (
+    host.Date === pinned.Date &&
+    host.Math === pinned.Math &&
+    host.crypto === pinned.crypto &&
+    !reached.Date &&
+    !reached.Math &&
+    !reached.crypto
+  ) {
+    return;
+  }
+  if (reached.Date) host.Date = previous.Date;
+  if (reached.Math) host.Math = previous.Math;
+  if (reached.crypto) host.crypto = previous.crypto;
+  throw new Error(
+    "@confect/test cannot pin this handler's Date, Math and crypto: it runs without convex-test's per-handler globals, so pinning would change them for every caller",
+  );
+};
+
+const make = (): Bridge => {
+  const storage = new AsyncLocalStorage<Running>();
+  // Taken at the first `bind`, which test code calls outside any handler, so
+  // it reads the test environment's globals.
+  const outside = AsyncLocalStorage.snapshot();
+  return {
+    storage,
+    start: (meta, run, functionType) => {
+      const running = storage.getStore();
+      if (running === undefined) return undefined;
+      return Promise.all([
+        meta.getFunctionMetadata(),
+        meta.getRequestMetadata?.(),
+      ]).then(([{ componentPath }, request]) => {
+        const invocation = resolve(
+          caller(running, functionType),
+          componentPath,
+          request,
+        );
+        pin(invocation, functionType, outside);
+        return storage.run({ invocation, functionType }, () =>
+          run(invocation.services),
+        );
+      });
+    },
+  };
+};
+
+// One bridge per test runtime, so every copy of this module that a test loads
+// binds through the store `runHandlerPromise` reads.
+const installed = globalThis as { [key]?: Bridge };
+
+/**
+ * Run `start` with `invocation` bound. Every registered handler it reaches
+ * through convex-test runs with the invocation's services, clock and random
+ * stream.
+ */
+export const bind = <A>(
+  invocation: Invocation,
+  start: () => Promise<A>,
+): Promise<A> =>
+  (installed[key] ??= make()).storage.run(
+    { invocation, functionType: undefined },
+    start,
+  );
+
+/**
+ * The invocation the calling handler runs under, if one is bound.
+ */
+export const current = (): Invocation | undefined =>
+  installed[key]?.storage.getStore()?.invocation;