convex 1.45.0 → 1.47.0

package/src/server/api.ts

@@ -42,6 +42,9 @@ export type FunctionType = "query" | "mutation" | "action";
  * const result = useQuery(api.myModule.myFunction);
  * ```
  *
+ * If you want to accept a `FunctionReference` as a callback argument, prefer
+ * typing the callback parameter as {@link FunctionReference_future}.
+ *
  * @typeParam Type - The type of the function ("query", "mutation", or "action").
  * @typeParam Visibility - The visibility of the function ("public" or "internal").
  * @typeParam Args - The arguments to this function. This is an object mapping
@@ -58,9 +61,179 @@ export type FunctionReference<
 > = {
   _type: Type;
   _visibility: Visibility;
+  /**
+   * To read the arguments for a `FunctionReference`, prefer
+   * {@link FunctionArgs}.
+   *
+   * This slot will be removed in a future version.
+   *
+   * @deprecated
+   */
   _args: Args;
+  /**
+   * To read the return type of a `FunctionReference`, prefer
+   * {@link FunctionReturnType}.
+   *
+   * This slot will be removed in a future version.
+   *
+   * @deprecated
+   */
   _returnType: ReturnType;
   _componentPath: ComponentPath;
+  /**
+   * To read the arguments or return type of a `FunctionReference`, prefer
+   * {@link FunctionArgs} and {@link FunctionReturnType}.
+   */
+  // This phantom slot exists so that a `FunctionReference` can be checked
+  // against a `FunctionReference_future`. It changes nothing about how two
+  // `FunctionReference`s compare with each other.
+  //
+  // The slot models the function itself: it puts `Args` in a contravariant
+  // position and `ReturnType` in a covariant one, so the slot alone is enough
+  // to compare a reference the way TypeScript compares two functions.
+  //
+  // In that comparison the `keys` parameter has an important role. It carries
+  // the keys of `Args`, so that checking a `FunctionReference` against a
+  // `FunctionReference_future` also checks that every key the consumer passes
+  // is a key the function declares. TypeScript treats a surplus property as
+  // harmless, but a Convex argument validator rejects it, so this is what
+  // makes the comparison match the runtime. See `FunctionReferenceArgKeys`.
+  _fn?(args: Args, keys: FunctionReferenceArgKeys<Args>): ReturnType;
+};
+
+/**
+ * The keys of a reference's arguments.
+ *
+ * `0 extends 1 & Args` holds only when `Args` is `any`. That maps to `any`
+ * rather than `keyof any` so that an untyped reference neither imposes nor
+ * fails the key check in either direction. Arguments with an index signature,
+ * such as `EmptyObject` and `DefaultFunctionArgs`, map to `string`, which
+ * accepts every key and leaves the decision to the first parameter.
+ */
+type ArgKeys<Args> = 0 extends 1 & Args ? any : keyof Args;
+
+/**
+ * The second parameter of `FunctionReference._fn`.
+ *
+ * Wrapping the keys in a function of a function puts them two parameters deep,
+ * so comparing this parameter contravariantly checks that every key the
+ * consumer passes is one the function declares. That is the check a Convex
+ * argument validator performs and an ordinary function-type comparison skips.
+ *
+ * The union with {@link UncheckedArgKeys} is what keeps two
+ * `FunctionReference`s comparing as they did before this slot existed. Every
+ * `FunctionReferenceArgKeys` is assignable to `UncheckedArgKeys`, so between
+ * two `FunctionReference`s the keys always relate and only `_args` decides.
+ * {@link FunctionReference_futureArgKeys} is not assignable to it, so a
+ * `FunctionReference` compared against a `FunctionReference_future` has to
+ * satisfy the real check.
+ */
+type FunctionReferenceArgKeys<Args> = 0 extends 1 & Args
+  ? any
+  : ((keys: (key: ArgKeys<Args>) => void) => void) | UncheckedArgKeys;
+
+/**
+ * A keys parameter that every {@link FunctionReferenceArgKeys} is assignable
+ * to, and that no {@link FunctionReference_futureArgKeys} is: `unknown` for
+ * the second parameter accepts the former's missing parameter and rejects the
+ * latter's `never`.
+ */
+type UncheckedArgKeys = (keys: never, unchecked?: unknown) => void;
+
+/**
+ * The second parameter of `FunctionReference_future._fn`. The same shape as
+ * {@link FunctionReferenceArgKeys} plus a `guard` parameter that keeps it out
+ * of {@link UncheckedArgKeys}.
+ */
+type FunctionReference_futureArgKeys<Args> = 0 extends 1 & Args
+  ? any
+  : (keys: (key: ArgKeys<Args>) => void, guard?: never) => void;
+
+/**
+ * A reference to a Convex function whose arguments are checked closer to the
+ * way Convex checks them at runtime.
+ *
+ * Use this instead of {@link FunctionReference} when you accept someone else's
+ * Convex function as a callback and know which arguments you will pass it.
+ *
+ * A plain `FunctionReference` gets a couple things backwards: it accepts a
+ * function requiring arguments you never pass, and rejects a function
+ * accepting broader values than you pass. An ordinary TypeScript function type
+ * doesn't map perfectly either: it treats a surplus argument as harmless,
+ * where a Convex validator rejects it.
+ *
+ * This type melds regular TypeScript function reference behavior with top
+ * level checking of arguments to prevent surplus arguments from hitting
+ * runtime validation errors. The caveat: a surplus key inside a nested object,
+ * an array element, or one arm of a union passes the type check and fails the
+ * validator at runtime.
+ *
+ * ```ts
+ * import { FunctionReference_future } from "convex/server";
+ *
+ * declare function onComplete(
+ *   fn: FunctionReference_future<
+ *     "mutation",
+ *     "internal",
+ *     { taskId: string; force: boolean },
+ *     null
+ *   >,
+ * ): void;
+ *
+ * // Takes exactly `{ taskId: string; force: boolean }`.
+ * onComplete(internal.tasks.finish);
+ * // Takes `{ taskId: string | number; force?: boolean }`: calling it is safe.
+ * onComplete(internal.tasks.finishLoosely);
+ * // Requires a `reason` argument that `onComplete` never passes.
+ * onComplete(internal.tasks.finishWithReason);
+ * //          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ rejected
+ * // Takes only `{ taskId: string }`: its validator would reject `force`.
+ * onComplete(internal.tasks.finishById);
+ * //          ~~~~~~~~~~~~~~~~~~~~~~~~ rejected
+ * ```
+ *
+ * A value of this type is usable with `ctx.runMutation`,
+ * `ctx.scheduler.runAfter`, `createFunctionHandle`, and everything else in
+ * this package that takes a reference, all of which accept either kind.
+ *
+ * It is *not* assignable to a plain `FunctionReference`. Code that wants to
+ * accept both kinds should take
+ * `FunctionReference<...> | FunctionReference_future<...>` and read arguments
+ * and return types through {@link FunctionArgs} and {@link FunctionReturnType}.
+ *
+ * Argument checking here relies on `strictFunctionTypes` (implied by `strict`)
+ * and is skipped for projects that disable it. Everything else about the
+ * reference is compared exactly as `FunctionReference` compares it.
+ *
+ * @typeParam Type - The type of the function ("query", "mutation", or "action").
+ * @typeParam Visibility - The visibility of the function ("public" or "internal").
+ * @typeParam Args - The arguments the consumer of the reference will pass.
+ * @typeParam ReturnType - The return type of this function.
+ * @public
+ */
+export type FunctionReference_future<
+  Type extends FunctionType,
+  Visibility extends FunctionVisibility = "public",
+  Args extends DefaultFunctionArgs = any,
+  ReturnType = any,
+  ComponentPath = string | undefined,
+> = {
+  _type: Type;
+  _visibility: Visibility;
+  _componentPath: ComponentPath;
+  // Declared as a *property* rather than a method: TypeScript compares method
+  // parameters bivariantly and would not check anything. The explicit
+  // `| undefined` is needed because an optional method on the source side
+  // (`FunctionReference._fn`) carries a real `undefined` in its type, which
+  // `exactOptionalPropertyTypes` would otherwise reject.
+  //
+  // Both parameters are compared contravariantly: the first checks that the
+  // consumer's arguments satisfy the function's, the second that the consumer
+  // passes no key the function does not declare. See
+  // `FunctionReference_futureArgKeys`.
+  _fn?:
+    | ((args: Args, keys: FunctionReference_futureArgKeys<Args>) => ReturnType)
+    | undefined;
 };
 
 /**
@@ -76,7 +249,9 @@ export type FunctionReference<
  * @public
  */
 export function getFunctionName(
-  functionReference: AnyFunctionReference,
+  functionReference:
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
 ): string {
   const address = getFunctionAddress(functionReference);
 
@@ -431,13 +606,33 @@ export type PartialApi<API> = {
 export const anyApi: AnyApi = createApi() as any;
 
 /**
- * Given a {@link FunctionReference}, get the return type of the function.
+ * Given a {@link FunctionReference} or {@link FunctionReference_future}, get
+ * the arguments of the function.
  *
  * This is represented as an object mapping argument names to values.
+ *
  * @public
  */
-export type FunctionArgs<FuncRef extends AnyFunctionReference> =
-  FuncRef["_args"];
+export type FunctionArgs<
+  FuncRef extends
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
+> = ExtractSignature<FuncRef>["args"];
+
+// The arguments and return type a reference declares. A `FunctionReference`
+// declares them in `_args` and `_returnType`, a `FunctionReference_future`
+// only in its `_fn` slot. Reading the named slots first also covers a
+// reference typed by an older copy of this package, which has no `_fn`.
+type ExtractSignature<FuncRef> = FuncRef extends {
+  _args: infer Args;
+  _returnType: infer R;
+}
+  ? { args: Args; returnType: R }
+  : FuncRef extends {
+        _fn?: ((args: infer Args, keys: never) => infer R) | undefined;
+      }
+    ? { args: Args; returnType: R }
+    : { args: any; returnType: any };
 
 /**
  * A tuple type of the (maybe optional) arguments to `FuncRef`.
@@ -447,10 +642,14 @@ export type FunctionArgs<FuncRef extends AnyFunctionReference> =
  *
  * @public
  */
-export type OptionalRestArgs<FuncRef extends AnyFunctionReference> =
-  FuncRef["_args"] extends EmptyObject
+export type OptionalRestArgs<
+  FuncRef extends
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
+> =
+  FunctionArgs<FuncRef> extends EmptyObject
     ? [args?: EmptyObject]
-    : [args: FuncRef["_args"]];
+    : [args: FunctionArgs<FuncRef>];
 
 /**
  * A tuple type of the (maybe optional) arguments to `FuncRef`, followed by an options
@@ -462,19 +661,26 @@ export type OptionalRestArgs<FuncRef extends AnyFunctionReference> =
  * @public
  */
 export type ArgsAndOptions<
-  FuncRef extends AnyFunctionReference,
+  FuncRef extends
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
   Options,
-> = FuncRef["_args"] extends EmptyObject
-  ? [args?: EmptyObject, options?: Options]
-  : [args: FuncRef["_args"], options?: Options];
+> =
+  FunctionArgs<FuncRef> extends EmptyObject
+    ? [args?: EmptyObject, options?: Options]
+    : [args: FunctionArgs<FuncRef>, options?: Options];
 
 /**
- * Given a {@link FunctionReference}, get the return type of the function.
+ * Given a {@link FunctionReference} or {@link FunctionReference_future}, get
+ * the return type of the function.
  *
  * @public
  */
-export type FunctionReturnType<FuncRef extends AnyFunctionReference> =
-  FuncRef["_returnType"];
+export type FunctionReturnType<
+  FuncRef extends
+    | FunctionReference<any, any>
+    | FunctionReference_future<any, any>,
+> = ExtractSignature<FuncRef>["returnType"];
 
 type UndefinedToNull<T> = T extends void ? null : T;
 

package/src/server/components/index.ts

@@ -3,6 +3,7 @@ import { version } from "../../index.js";
 import {
   AnyFunctionReference,
   FunctionReference,
+  FunctionReference_future,
   FunctionType,
 } from "../api.js";
 import { performAsyncSyscall } from "../impl/syscall.js";
@@ -66,12 +67,9 @@ export async function createFunctionHandle<
   Args extends DefaultFunctionArgs,
   ReturnType,
 >(
-  functionReference: FunctionReference<
-    Type,
-    "public" | "internal",
-    Args,
-    ReturnType
-  >,
+  functionReference:
+    | FunctionReference<Type, "public" | "internal", Args, ReturnType>
+    | FunctionReference_future<Type, "public" | "internal", Args, ReturnType>,
 ): Promise<FunctionHandle<Type, Args, ReturnType>> {
   const address = getFunctionAddress(functionReference);
   return await performAsyncSyscall("1.0/createFunctionHandle", {

package/src/server/cron.ts

@@ -1,9 +1,19 @@
-import { getFunctionName, OptionalRestArgs } from "../server/api.js";
+import {
+  FunctionReference_future,
+  getFunctionName,
+  OptionalRestArgs,
+} from "../server/api.js";
 import { parseArgs } from "../common/index.js";
 import { convexToJson, JSONValue, Value } from "../values/index.js";
 import { getFunctionAddress } from "./components/paths.js";
 import { SchedulableFunctionReference } from "./scheduler.js";
 
+// Mirrors the constraint on `Scheduler.runAfter` and `Scheduler.runAt`, which
+// is module-local to `scheduler.ts`.
+type SchedulableFunctionReferenceCompat =
+  | SchedulableFunctionReference
+  | FunctionReference_future<"mutation" | "action", "public" | "internal">;
+
 type CronSchedule = {
   type: "cron";
   cron: string;
@@ -238,8 +248,8 @@ function validatedOptionalMinuteOfHour(n: number | undefined) {
 // call shapes apart by whether the second argument resolves to a function
 // reference (the way the scheduler syscalls do) rather than a schedule object.
 function isSchedulableFunctionReference(
-  arg: Hourly | SchedulableFunctionReference,
-): arg is SchedulableFunctionReference {
+  arg: Hourly | SchedulableFunctionReferenceCompat,
+): arg is SchedulableFunctionReferenceCompat {
   try {
     getFunctionAddress(arg);
     return true;
@@ -280,7 +290,7 @@ export class Crons {
   schedule(
     cronIdentifier: string,
     schedule: Schedule,
-    functionReference: SchedulableFunctionReference,
+    functionReference: SchedulableFunctionReferenceCompat,
     args?: Record<string, Value>,
   ) {
     const cronArgs = parseArgs(args);
@@ -304,11 +314,11 @@ export class Crons {
    *
    * @param identifier - A unique name for this scheduled job.
    * @param schedule - The time between runs for this scheduled job.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    * @param args - The arguments to the function.
    */
-  interval<FuncRef extends SchedulableFunctionReference>(
+  interval<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Interval,
     functionReference: FuncRef,
@@ -353,22 +363,22 @@ export class Crons {
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param schedule - What minute (UTC) of each hour to run this function. May
    * be omitted to let Convex pick a minute and spread runs across the hour.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    * @param args - The arguments to the function.
    */
-  hourly<FuncRef extends SchedulableFunctionReference>(
+  hourly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     functionReference: FuncRef,
     ...args: OptionalRestArgs<FuncRef>
   ): void;
-  hourly<FuncRef extends SchedulableFunctionReference>(
+  hourly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Hourly,
     functionReference: FuncRef,
     ...args: OptionalRestArgs<FuncRef>
   ): void;
-  hourly<FuncRef extends SchedulableFunctionReference>(
+  hourly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     scheduleOrFunctionReference: Hourly | FuncRef,
     functionReferenceOrArg?: FuncRef | Record<string, Value>,
@@ -414,11 +424,11 @@ export class Crons {
    *
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param schedule - What time (UTC) each day to run this function.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    * @param args - The arguments to the function.
    */
-  daily<FuncRef extends SchedulableFunctionReference>(
+  daily<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Daily,
     functionReference: FuncRef,
@@ -453,10 +463,10 @@ export class Crons {
    *
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param schedule - What day and time (UTC) each week to run this function.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    */
-  weekly<FuncRef extends SchedulableFunctionReference>(
+  weekly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Weekly,
     functionReference: FuncRef,
@@ -495,11 +505,11 @@ export class Crons {
    *
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param schedule - What day and time (UTC) each month to run this function.
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    * @param args - The arguments to the function.
    */
-  monthly<FuncRef extends SchedulableFunctionReference>(
+  monthly<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     schedule: Monthly,
     functionReference: FuncRef,
@@ -534,11 +544,11 @@ export class Crons {
    *
    * @param cronIdentifier - A unique name for this scheduled job.
    * @param cron - Cron string like `"15 7 * * *"` (Every day at 7:15 UTC)
-   * @param functionReference - A {@link FunctionReference} for the function
-   * to schedule.
+   * @param functionReference - A {@link FunctionReference} or
+   * {@link FunctionReference_future} for the function to schedule.
    * @param args - The arguments to the function.
    */
-  cron<FuncRef extends SchedulableFunctionReference>(
+  cron<FuncRef extends SchedulableFunctionReferenceCompat>(
     cronIdentifier: string,
     cron: CronString,
     functionReference: FuncRef,

package/src/server/impl/actions_impl.ts

@@ -2,7 +2,10 @@ import { convexToJson, jsonToConvex, Value } from "../../values/index.js";
 import { version } from "../../index.js";
 import { performAsyncSyscall } from "./syscall.js";
 import { parseArgs } from "../../common/index.js";
-import { FunctionReference } from "../../server/api.js";
+import {
+  FunctionReference,
+  FunctionReference_future,
+} from "../../server/api.js";
 import { getFunctionAddress } from "../components/paths.js";
 import { validateArg } from "./validate.js";
 
@@ -23,7 +26,9 @@ function syscallArgs(
 export function setupActionCalls(requestId: string) {
   return {
     runQuery: async (
-      query: FunctionReference<"query", "public" | "internal">,
+      query:
+        | FunctionReference<"query", "public" | "internal">
+        | FunctionReference_future<"query", "public" | "internal">,
       args?: Record<string, Value>,
     ): Promise<any> => {
       const result = await performAsyncSyscall(
@@ -33,7 +38,9 @@ export function setupActionCalls(requestId: string) {
       return jsonToConvex(result);
     },
     runMutation: async (
-      mutation: FunctionReference<"mutation", "public" | "internal">,
+      mutation:
+        | FunctionReference<"mutation", "public" | "internal">
+        | FunctionReference_future<"mutation", "public" | "internal">,
       args?: Record<string, Value>,
     ): Promise<any> => {
       const result = await performAsyncSyscall(
@@ -43,7 +50,9 @@ export function setupActionCalls(requestId: string) {
       return jsonToConvex(result);
     },
     runAction: async (
-      action: FunctionReference<"action", "public" | "internal">,
+      action:
+        | FunctionReference<"action", "public" | "internal">
+        | FunctionReference_future<"action", "public" | "internal">,
       args?: Record<string, Value>,
     ): Promise<any> => {
       const result = await performAsyncSyscall(
@@ -55,26 +64,46 @@ export function setupActionCalls(requestId: string) {
   };
 }
 
+/**
+ * A Convex-managed service. The backend decides which names it accepts; this
+ * type lists the ones the current release knows about.
+ */
+export type ServiceName = "ai-gateway";
+
 /**
  * Get a short-lived credential for calling a Convex-managed service.
  *
  * This function can only be called while an action is running. The credential
  * is scoped to the current deployment and should be sent as a bearer token.
- * Repeated calls in the same action reuse one token; a failed mint is not
- * cached, so a later call retries.
+ * The action runtime caches and refreshes credentials as needed, so call
+ * this function whenever making a service request.
  *
  * @param service - The service the credential may access.
  * @returns A JWT to send as `Authorization: Bearer <token>`. Keep it inside
  * the action: don't return it to clients or store it in environment
  * variables.
  */
-export async function getServiceToken(service: "ai-gateway"): Promise<string> {
+export async function getServiceToken(service: ServiceName): Promise<string> {
   validateArg(service, 1, "getServiceToken", "service");
-  if (service !== "ai-gateway") {
-    throw new Error(`Unsupported service "${String(service)}"`);
-  }
   return await performAsyncSyscall("1.0/createServiceToken", {
     service,
     version,
   });
 }
+
+/**
+ * Get the base URL of a Convex-managed service.
+ *
+ * This function can only be called while an action is running. Pair it with
+ * {@link getServiceToken} to reach the service.
+ *
+ * @param service - The service to address.
+ * @returns The service's origin, without a trailing slash.
+ */
+export async function getServiceUrl(service: ServiceName): Promise<string> {
+  validateArg(service, 1, "getServiceUrl", "service");
+  return await performAsyncSyscall("1.0/getServiceUrl", {
+    service,
+    version,
+  });
+}

package/src/server/impl/meta_impl.ts

@@ -8,7 +8,7 @@ import {
   TransactionMetrics,
   DeploymentMetadata,
 } from "../meta.js";
-import { performAsyncSyscall } from "./syscall.js";
+import { performAsyncSyscall, performSyscall } from "./syscall.js";
 
 async function getTransactionMetrics(): Promise<TransactionMetrics> {
   let syscallJSON;
@@ -53,6 +53,11 @@ async function getDeploymentMetadata(): Promise<DeploymentMetadata> {
   };
 }
 
+function getSnapshotTs(): bigint {
+  const syscallJSON = performSyscall("1.0/getSnapshotTs", {});
+  return jsonToConvex(syscallJSON) as bigint;
+}
+
 async function getRequestMetadata(): Promise<RequestMetadata> {
   const { ip, userAgent, requestId, scheduledFunctionId, authToken } =
     await performAsyncSyscall("1.0/getRequestMetadata", {});
@@ -70,6 +75,7 @@ export function setupQueryMeta(
     }),
     getTransactionMetrics,
     getDeploymentMetadata,
+    getSnapshotTs,
   };
 }
 
@@ -85,6 +91,7 @@ export function setupMutationMeta(
     getTransactionMetrics,
     getDeploymentMetadata,
     getRequestMetadata,
+    getSnapshotTs,
   };
 }
 

package/src/server/impl/scheduler_impl.ts

@@ -3,15 +3,22 @@ import { version } from "../../index.js";
 import { performAsyncSyscall } from "./syscall.js";
 import { parseArgs } from "../../common/index.js";
 import { SchedulableFunctionReference, Scheduler } from "../scheduler.js";
+import { FunctionReference_future } from "../api.js";
 import { Id } from "../../values/value.js";
 import { validateArg } from "./validate.js";
 import { getFunctionAddress } from "../components/paths.js";
 
+// Mirrors the constraint on `Scheduler.runAfter` and `Scheduler.runAt`, which
+// is module-local to `scheduler.ts`.
+type SchedulableFunctionReferenceCompat =
+  | SchedulableFunctionReference
+  | FunctionReference_future<"mutation" | "action", "public" | "internal">;
+
 export function setupMutationScheduler(): Scheduler {
   return {
     runAfter: async (
       delayMs: number,
-      functionReference: SchedulableFunctionReference,
+      functionReference: SchedulableFunctionReferenceCompat,
       args?: Record<string, Value>,
     ) => {
       const syscallArgs = runAfterSyscallArgs(delayMs, functionReference, args);
@@ -19,7 +26,7 @@ export function setupMutationScheduler(): Scheduler {
     },
     runAt: async (
       ms_since_epoch_or_date: number | Date,
-      functionReference: SchedulableFunctionReference,
+      functionReference: SchedulableFunctionReferenceCompat,
       args?: Record<string, Value>,
     ) => {
       const syscallArgs = runAtSyscallArgs(
@@ -41,7 +48,7 @@ export function setupActionScheduler(requestId: string): Scheduler {
   return {
     runAfter: async (
       delayMs: number,
-      functionReference: SchedulableFunctionReference,
+      functionReference: SchedulableFunctionReferenceCompat,
       args?: Record<string, Value>,
     ) => {
       const syscallArgs = {
@@ -52,7 +59,7 @@ export function setupActionScheduler(requestId: string): Scheduler {
     },
     runAt: async (
       ms_since_epoch_or_date: number | Date,
-      functionReference: SchedulableFunctionReference,
+      functionReference: SchedulableFunctionReferenceCompat,
       args?: Record<string, Value>,
     ) => {
       const syscallArgs = {
@@ -74,7 +81,7 @@ export function setupActionScheduler(requestId: string): Scheduler {
 
 function runAfterSyscallArgs(
   delayMs: number,
-  functionReference: SchedulableFunctionReference,
+  functionReference: SchedulableFunctionReferenceCompat,
   args?: Record<string, Value>,
 ) {
   if (typeof delayMs !== "number") {
@@ -100,7 +107,7 @@ function runAfterSyscallArgs(
 
 function runAtSyscallArgs(
   ms_since_epoch_or_date: number | Date,
-  functionReference: SchedulableFunctionReference,
+  functionReference: SchedulableFunctionReferenceCompat,
   args?: Record<string, Value>,
 ) {
   let ts;