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

package/dist/internal/Scheduling.d.ts

@@ -0,0 +1,71 @@
+import type { Value } from "convex/values";
+import type * as Invocation from "./Invocation.js";
+import type * as Kernel from "./Kernel.js";
+import type { DocumentId, FunctionPath, StoredDocument } from "./KernelValues.js";
+/**
+ * Convex's system table of scheduled functions. Each component has its own.
+ */
+export declare const table = "_scheduled_functions";
+export type JobState = {
+    readonly kind: "pending";
+} | {
+    readonly kind: "inProgress";
+} | {
+    readonly kind: "success";
+} | {
+    readonly kind: "failed";
+    readonly error: string;
+} | {
+    readonly kind: "canceled";
+};
+/**
+ * What the kernel keeps beside a job's row: the function it calls, which a
+ * handle may place in another component, whether a standing source owns the
+ * job, and the test world whose invocation scheduled it. The row holds only
+ * what Convex's system table holds.
+ */
+export interface Target {
+    readonly functionPath: FunctionPath;
+    readonly standing: boolean;
+    /**
+     * The job runs as a fresh invocation of this world, with its services, or
+     * unbound when no invocation was bound as it was scheduled.
+     */
+    readonly world: Invocation.World | undefined;
+}
+/**
+ * A pending job as a driver sees it.
+ */
+export interface Job {
+    readonly id: DocumentId;
+    readonly componentPath: string;
+    readonly name: string;
+    readonly scheduledTime: number;
+    /**
+     * A standing job is never drain work. Time reaches it through `advance`.
+     */
+    readonly standing: boolean;
+}
+/**
+ * A pending job with what running it needs.
+ */
+export interface Due extends Job {
+    readonly target: FunctionPath;
+    readonly args: Value;
+    readonly world: Invocation.World | undefined;
+}
+export declare const row: (id: DocumentId, creationTime: number, name: string, args: Value, scheduledTime: number) => StoredDocument;
+export declare const stateOf: (doc: StoredDocument) => JobState;
+/**
+ * Every committed pending job of every component, earliest deadline first. Jobs
+ * that share a deadline run in the order they were scheduled.
+ */
+export declare const pending: (state: Kernel.State, targets: ReadonlyMap<DocumentId, Target>) => Array<Due>;
+/**
+ * The distinct functions of `jobs`, for a refusal that names what is left.
+ */
+export declare const functions: (jobs: ReadonlyArray<Job>) => Array<{
+    readonly componentPath: string;
+    readonly name: string;
+}>;
+//# sourceMappingURL=Scheduling.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Scheduling.d.ts","sourceRoot":"","sources":["../../src/internal/Scheduling.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,KAAK,UAAU,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,KAAK,yBAAyB,CAAC;AAE5C,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAElC;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,GAAI,SAAQ,GAAG;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;CAC9C;AAED,eAAO,MAAM,GAAG,OACV,UAAU,gBACA,MAAM,QACd,MAAM,QACN,KAAK,iBACI,MAAM,KACpB,cAOD,CAAC;AAEH,eAAO,MAAM,OAAO,QAAS,cAAc,KAAG,QACpB,CAAC;AAK3B;;;GAGG;AACH,eAAO,MAAM,OAAO,UACX,MAAM,CAAC,KAAK,WACV,WAAW,CAAC,UAAU,EAAE,MAAM,CAAC,KACvC,KAAK,CAAC,GAAG,CAwBX,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,SACd,aAAa,CAAC,GAAG,CAAC,KACvB,KAAK,CAAC;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMjE,CAAC"}

package/dist/internal/Scheduling.js

@@ -0,0 +1,60 @@
+//#region src/internal/Scheduling.ts
+/**
+* Convex's system table of scheduled functions. Each component has its own.
+*/
+const table = "_scheduled_functions";
+const row = (id, creationTime, name, args, scheduledTime) => ({
+	_id: id,
+	_creationTime: creationTime,
+	name,
+	args: [args],
+	scheduledTime,
+	state: { kind: "pending" }
+});
+const stateOf = (doc) => doc["state"];
+const byDeadline = (a, b) => a.scheduledTime - b.scheduledTime || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+* Every committed pending job of every component, earliest deadline first. Jobs
+* that share a deadline run in the order they were scheduled.
+*/
+const pending = (state, targets) => {
+	const due = [];
+	for (const [componentPath, tables] of state.tables) for (const { doc } of tables.get("_scheduled_functions")?.values() ?? []) {
+		if (stateOf(doc).kind !== "pending") continue;
+		const name = doc["name"];
+		const target = targets.get(doc._id) ?? {
+			functionPath: {
+				componentPath,
+				udfPath: name
+			},
+			standing: false,
+			world: void 0
+		};
+		due.push({
+			id: doc._id,
+			componentPath,
+			name,
+			scheduledTime: doc["scheduledTime"],
+			standing: target.standing,
+			target: target.functionPath,
+			args: doc["args"][0],
+			world: target.world
+		});
+	}
+	return due.sort(byDeadline);
+};
+/**
+* The distinct functions of `jobs`, for a refusal that names what is left.
+*/
+const functions = (jobs) => {
+	const seen = /* @__PURE__ */ new Map();
+	for (const { componentPath, name } of jobs) seen.set(`${componentPath}\u0000${name}`, {
+		componentPath,
+		name
+	});
+	return [...seen.values()];
+};
+//#endregion
+export { functions, pending, row, stateOf, table };
+
+//# sourceMappingURL=Scheduling.js.map

package/dist/internal/Scheduling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scheduling.js","names":[],"sources":["../../src/internal/Scheduling.ts"],"sourcesContent":["import type { Value } from \"convex/values\";\nimport type * as Invocation from \"./Invocation.js\";\nimport type * as Kernel from \"./Kernel.js\";\nimport type {\n  DocumentId,\n  FunctionPath,\n  StoredDocument,\n} from \"./KernelValues.js\";\n\n/**\n * Convex's system table of scheduled functions. Each component has its own.\n */\nexport const table = \"_scheduled_functions\";\n\nexport type JobState =\n  | { readonly kind: \"pending\" }\n  | { readonly kind: \"inProgress\" }\n  | { readonly kind: \"success\" }\n  | { readonly kind: \"failed\"; readonly error: string }\n  | { readonly kind: \"canceled\" };\n\n/**\n * What the kernel keeps beside a job's row: the function it calls, which a\n * handle may place in another component, whether a standing source owns the\n * job, and the test world whose invocation scheduled it. The row holds only\n * what Convex's system table holds.\n */\nexport interface Target {\n  readonly functionPath: FunctionPath;\n  readonly standing: boolean;\n  /**\n   * The job runs as a fresh invocation of this world, with its services, or\n   * unbound when no invocation was bound as it was scheduled.\n   */\n  readonly world: Invocation.World | undefined;\n}\n\n/**\n * A pending job as a driver sees it.\n */\nexport interface Job {\n  readonly id: DocumentId;\n  readonly componentPath: string;\n  readonly name: string;\n  readonly scheduledTime: number;\n  /**\n   * A standing job is never drain work. Time reaches it through `advance`.\n   */\n  readonly standing: boolean;\n}\n\n/**\n * A pending job with what running it needs.\n */\nexport interface Due extends Job {\n  readonly target: FunctionPath;\n  readonly args: Value;\n  readonly world: Invocation.World | undefined;\n}\n\nexport const row = (\n  id: DocumentId,\n  creationTime: number,\n  name: string,\n  args: Value,\n  scheduledTime: number,\n): StoredDocument => ({\n  _id: id,\n  _creationTime: creationTime,\n  name,\n  args: [args],\n  scheduledTime,\n  state: { kind: \"pending\" },\n});\n\nexport const stateOf = (doc: StoredDocument): JobState =>\n  doc[\"state\"] as JobState;\n\nconst byDeadline = (a: Due, b: Due) =>\n  a.scheduledTime - b.scheduledTime || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);\n\n/**\n * Every committed pending job of every component, earliest deadline first. Jobs\n * that share a deadline run in the order they were scheduled.\n */\nexport const pending = (\n  state: Kernel.State,\n  targets: ReadonlyMap<DocumentId, Target>,\n): Array<Due> => {\n  const due: Array<Due> = [];\n  for (const [componentPath, tables] of state.tables) {\n    for (const { doc } of tables.get(table)?.values() ?? []) {\n      if (stateOf(doc).kind !== \"pending\") continue;\n      const name = doc[\"name\"] as string;\n      const target = targets.get(doc._id) ?? {\n        functionPath: { componentPath, udfPath: name },\n        standing: false,\n        world: undefined,\n      };\n      due.push({\n        id: doc._id,\n        componentPath,\n        name,\n        scheduledTime: doc[\"scheduledTime\"] as number,\n        standing: target.standing,\n        target: target.functionPath,\n        args: (doc[\"args\"] as ReadonlyArray<Value>)[0]!,\n        world: target.world,\n      });\n    }\n  }\n  return due.sort(byDeadline);\n};\n\n/**\n * The distinct functions of `jobs`, for a refusal that names what is left.\n */\nexport const functions = (\n  jobs: ReadonlyArray<Job>,\n): Array<{ readonly componentPath: string; readonly name: string }> => {\n  const seen = new Map<string, { componentPath: string; name: string }>();\n  for (const { componentPath, name } of jobs) {\n    seen.set(`${componentPath}\\u0000${name}`, { componentPath, name });\n  }\n  return [...seen.values()];\n};\n"],"mappings":";;;;AAYA,MAAa,QAAQ;AAgDrB,MAAa,OACX,IACA,cACA,MACA,MACA,mBACoB;CACpB,KAAK;CACL,eAAe;CACf;CACA,MAAM,CAAC,IAAI;CACX;CACA,OAAO,EAAE,MAAM,UAAU;AAC3B;AAEA,MAAa,WAAW,QACtB,IAAI;AAEN,MAAM,cAAc,GAAQ,MAC1B,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI;;;;;AAM7E,MAAa,WACX,OACA,YACe;CACf,MAAM,MAAkB,CAAC;CACzB,KAAK,MAAM,CAAC,eAAe,WAAW,MAAM,QAC1C,KAAK,MAAM,EAAE,SAAS,OAAO,IAAA,sBAAS,CAAC,EAAE,OAAO,KAAK,CAAC,GAAG;EACvD,IAAI,QAAQ,GAAG,CAAC,CAAC,SAAS,WAAW;EACrC,MAAM,OAAO,IAAI;EACjB,MAAM,SAAS,QAAQ,IAAI,IAAI,GAAG,KAAK;GACrC,cAAc;IAAE;IAAe,SAAS;GAAK;GAC7C,UAAU;GACV,OAAO,KAAA;EACT;EACA,IAAI,KAAK;GACP,IAAI,IAAI;GACR;GACA;GACA,eAAe,IAAI;GACnB,UAAU,OAAO;GACjB,QAAQ,OAAO;GACf,MAAO,IAAI,OAAO,CAA0B;GAC5C,OAAO,OAAO;EAChB,CAAC;CACH;CAEF,OAAO,IAAI,KAAK,UAAU;AAC5B;;;;AAKA,MAAa,aACX,SACqE;CACrE,MAAM,uBAAO,IAAI,IAAqD;CACtE,KAAK,MAAM,EAAE,eAAe,UAAU,MACpC,KAAK,IAAI,GAAG,cAAc,QAAQ,QAAQ;EAAE;EAAe;CAAK,CAAC;CAEnE,OAAO,CAAC,GAAG,KAAK,OAAO,CAAC;AAC1B"}

package/package.json

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

package/src/TestConfect.ts

@@ -7,7 +7,6 @@ import type {
 } from "convex-test";
 import { convexTest } from "convex-test";
 import type {
-  GenericDataModel,
   GenericMutationCtx,
   GenericSchema,
   SchemaDefinition,
@@ -18,17 +17,32 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
+import { convexTest as kernelTest } from "./internal/ConvexTest.js";
 import * as MountedHttp from "./internal/MountedHttp.js";
 
 declare const process: { env: Record<string, string | undefined> };
 
+/**
+ * How a kit registers a component beyond its schema and modules.
+ */
+export type RegisterOptions = {
+  /**
+   * The component's functions, as `module:export`, that schedule their own next
+   * run, such as the crons component's `public:rescheduler`. The test kernel
+   * never treats a job that runs one, or that one schedules, as work
+   * `finishAllScheduledFunctions` must finish. convex-test ignores it.
+   */
+  readonly standing?: ReadonlyArray<string>;
+};
+
 /**
  * Register a component's Convex schema and modules at its installation path.
  */
 export type RegisterComponent = (
-  ...args: Parameters<
-    TestConvexForDataModelAndIdentity<GenericDataModel>["registerComponent"]
-  >
+  componentPath: string,
+  schema: SchemaDefinition<GenericSchema, boolean>,
+  modules: Record<string, () => Promise<any>>,
+  options?: RegisterOptions,
 ) => void;
 
 /**
@@ -39,7 +53,22 @@ export type HttpMount = {
   readonly httpPrefix: string;
 };
 
-export type LayerOptions = {
+/**
+ * The in-process backend a test layer runs on.
+ */
+export type Target = "convex-test" | "kernel";
+
+export type TargetOptions = {
+  /**
+   * `"kernel"` runs every function and component the layer registers on
+   * Confect's test kernel, which runs scheduled functions on its own clock and
+   * reads `registerComponent`'s `standing`. Defaults to `"convex-test"`. The
+   * option goes once the kernel replaces convex-test.
+   */
+  readonly target?: Target;
+};
+
+export type LayerOptions = TargetOptions & {
   /**
    * Register component kits synchronously before the test service is available.
    */
@@ -106,6 +135,7 @@ export type TestConfect<ConfectSchema extends DatabaseSchema.AnyWithProps> = {
     componentPath: string,
     schema: SchemaDefinition<GenericSchema, boolean>,
     modules: Record<string, () => Promise<any>>,
+    options?: RegisterOptions,
   ) => Effect.Effect<void>;
   withIdentity: (
     userIdentity: Partial<UserIdentity>,
@@ -261,9 +291,9 @@ class TestConfectImpl<
 
   readonly registerComponent: TestConfect<ConfectSchema>["registerComponent"] =
     Effect.fn("TestConfect.registerComponent")(
-      (componentPath, schema, modules) =>
+      (componentPath, schema, modules, options) =>
         Effect.sync(() =>
-          this.mountedHttp.register(componentPath, schema, modules),
+          this.mountedHttp.register(componentPath, schema, modules, options),
         ),
     );
 
@@ -366,9 +396,12 @@ export type DeclaredApp<DatabaseSchema_ extends DatabaseSchema.AnyWithProps> =
 /**
  * Build a fresh test backend from a declaration and its generated
  * `confect/_generated/testing` registry, without restating component mounts.
+ * Pass `{ target: "kernel" }` to run it on Confect's test kernel instead of
+ * convex-test.
  */
 export function layer<DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   app: DeclaredApp<DatabaseSchema_>,
+  options?: TargetOptions,
 ): Layer.Layer<TestConfect<DatabaseSchema_>>;
 export function layer<
   A extends App.Any,
@@ -383,6 +416,7 @@ export function layer<
       >
     >;
   },
+  options?: TargetOptions,
 ): Layer.Layer<TestConfect<DatabaseSchema_>>;
 export function layer<DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   databaseSchema: DatabaseSchema_,
@@ -392,20 +426,22 @@ export function layer<DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
 ): Layer.Layer<TestConfect<DatabaseSchema_>>;
 export function layer<DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   appOrSchema: App.Any | DeclaredApp<DatabaseSchema_> | DatabaseSchema_,
-  registryOrSchema?:
+  second?:
     | Registry<DatabaseSchema_>
-    | SchemaDefinition<GenericSchema, true>,
-  modules?: Record<string, () => Promise<any>>,
+    | SchemaDefinition<GenericSchema, true>
+    | TargetOptions,
+  third?: Record<string, () => Promise<any>> | TargetOptions,
   options: LayerOptions = {},
 ): Layer.Layer<TestConfect<DatabaseSchema_>> {
   if (App.isApp(appOrSchema)) {
-    const registry = registryOrSchema as Registry<DatabaseSchema_>;
+    const registry = second as Registry<DatabaseSchema_>;
     const mounts = App.mounts(appOrSchema);
     return schemaLayer(
       registry.schema,
       registry.convexSchema,
       registry.modules,
       {
+        ...targetOf(third as TargetOptions | undefined),
         httpMounts: mounts.flatMap(({ name, httpPrefix }) =>
           httpPrefix === undefined ? [] : [{ componentPath: name, httpPrefix }],
         ),
@@ -427,6 +463,7 @@ export function layer<DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   if ("httpMounts" in appOrSchema) {
     const app = appOrSchema as DeclaredApp<DatabaseSchema_>;
     return schemaLayer(app.schema, app.convexSchema, app.modules, {
+      ...targetOf(second as TargetOptions | undefined),
       httpMounts: app.httpMounts,
       register: (registerComponent) => {
         for (const [name, component] of Object.entries(app.components)) {
@@ -437,12 +474,15 @@ export function layer<DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   }
   return schemaLayer(
     appOrSchema as DatabaseSchema_,
-    registryOrSchema as SchemaDefinition<GenericSchema, true>,
-    modules!,
+    second as SchemaDefinition<GenericSchema, true>,
+    third as Record<string, () => Promise<any>>,
     options,
   );
 }
 
+const targetOf = (options: TargetOptions | undefined): TargetOptions =>
+  options?.target === undefined ? {} : { target: options.target };
+
 const schemaLayer = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   databaseSchema: DatabaseSchema_,
   convexSchemaDefinition: SchemaDefinition<GenericSchema, true>,
@@ -452,9 +492,16 @@ const schemaLayer = <DatabaseSchema_ extends DatabaseSchema.AnyWithProps>(
   Layer.sync(TestConfect<DatabaseSchema_>(), () => {
     process.env.CONVEX_CLOUD_URL ??= "https://some-deployment.convex.cloud";
     process.env.CONVEX_SITE_URL ??= "https://some.convex.site";
-    const testConvex = convexTest(convexSchemaDefinition, modules);
+    const testConvex = (options.target === "kernel" ? kernelTest : convexTest)(
+      convexSchemaDefinition,
+      modules,
+    );
+    // convex-test takes three arguments and ignores the options. The kernel
+    // reads `standing`.
+    const registerComponent =
+      testConvex.registerComponent as unknown as RegisterComponent;
     const mountedHttp = MountedHttp.make(options.httpMounts ?? [], (...args) =>
-      testConvex.registerComponent(...args),
+      registerComponent(...args),
     );
     options.register?.(mountedHttp.register);
     return new TestConfectImpl(databaseSchema, testConvex as any, mountedHttp);

package/src/internal/Attempt.ts

@@ -1,4 +1,4 @@
-// oxlint-disable-next-line effecttsgo/node-builtin-import -- The drain waits a real turn of the event loop. Fake timers in a test replace the global `setImmediate`, not this one.
+// oxlint-disable-next-line effecttsgo/node-builtin-import, no-restricted-imports -- An attempt's drain waits one real turn of the event loop, which is no deadline. Fake timers in a test replace the global `setImmediate`, not this one.
 import { setImmediate } from "node:timers/promises";
 import type { Attempt as AttemptNumber } from "./Invocation.js";
 import * as Kernel from "./Kernel.js";

package/src/internal/Clock.ts

@@ -0,0 +1,95 @@
+/**
+ * Convex pins `Date` inside a query or mutation to the time it started, and its
+ * scheduler reads `Date.now()` for `runAfter`. The kernel wraps the realm's
+ * `Date` so it answers a kernel invocation's time inside one and the host's
+ * everywhere else. It sets no host timer.
+ */
+
+import * as Globals from "./Globals.js";
+
+type DateConstructor = typeof globalThis.Date;
+
+interface State {
+  /**
+   * Each wrapper the kernel installed, and the `Date` it wraps.
+   */
+  readonly bases: WeakMap<DateConstructor, DateConstructor>;
+  readonly pinned: () => number | undefined;
+  /**
+   * Whether a kernel invocation is running, without reading its time.
+   */
+  readonly inside: () => boolean;
+}
+
+const key = Symbol.for("@confect/test/Clock");
+
+type Global = { [key]?: State; Date: DateConstructor };
+
+const wrap = (
+  base: DateConstructor,
+  pinned: () => number | undefined,
+): DateConstructor => {
+  const proxy: DateConstructor = new Proxy(base, {
+    get: (target, property) =>
+      property === "now"
+        ? () => pinned() ?? target.now()
+        : Reflect.get(target, property, target),
+    construct: (target, args, newTarget) => {
+      const at = args.length === 0 ? pinned() : undefined;
+      return Reflect.construct(
+        target,
+        at === undefined ? args : [at],
+        newTarget === proxy ? target : newTarget,
+      );
+    },
+    apply: (target, self, args) => {
+      const at = pinned();
+      return at === undefined
+        ? Reflect.apply(target, self, args)
+        : new target(at).toString();
+    },
+  });
+  return proxy;
+};
+
+/**
+ * Wrap the realm's current `Date`, unless the kernel already did. `pinned`
+ * answers the running invocation's time, or `undefined` outside one, and
+ * `inside` says whether one is running. The first install's callbacks answer
+ * for every later one, as with `globalThis.Convex`. A test that fakes `Date`
+ * replaces the wrapper while the fake is installed, and the next install wraps
+ * the `Date` the test restores.
+ */
+export const install = (
+  pinned: () => number | undefined,
+  inside: () => boolean,
+) => {
+  const global = globalThis as Global;
+  const state = (global[key] ??= { bases: new WeakMap(), pinned, inside });
+  const current = global.Date;
+  if (state.bases.has(current)) return;
+  const wrapper = wrap(current, () => state.pinned());
+  state.bases.set(wrapper, current);
+  global.Date = wrapper;
+};
+
+/**
+ * Whether `date` is the kernel's wrapper inside a running kernel invocation, so
+ * it already answers that invocation's time on the kernel's clock.
+ */
+export const answersInvocation = (date: DateConstructor): boolean => {
+  const state = (globalThis as Global)[key];
+  return state !== undefined && state.bases.has(date) && state.inside();
+};
+
+/**
+ * The host's time in milliseconds, never a kernel invocation's: the real clock,
+ * or a test's fake one while it is installed. It reads the test environment's
+ * `Date`, never the copy a bound handler pinned.
+ */
+export const hostNow = (): number =>
+  Globals.host(() => {
+    const global = globalThis as Global;
+    const current = global.Date;
+    return (global[key]?.bases.get(current) ?? current).now();
+  });

package/src/internal/ConvexTest.ts

@@ -7,6 +7,7 @@ import { componentsGeneric } from "convex/server";
 import * as Execution from "./Execution.js";
 import type * as Kernel from "./Kernel.js";
 import * as KernelRefusal from "./KernelRefusal.js";
+import type * as Scheduling from "./Scheduling.js";
 
 type Modules = Record<string, () => Promise<any>>;
 
@@ -24,6 +25,40 @@ export interface KernelControls {
   ) => Promise<Execution.HeldAttempt>;
   readonly apply: (id: string) => Promise<Execution.KernelApply>;
   readonly held: () => ReadonlyArray<Execution.HeldAttempt>;
+  /**
+   * Move the kernel's clock forward, running each job due on the way at its
+   * deadline.
+   */
+  readonly advance: (ms: number) => Promise<void>;
+  /**
+   * The pending jobs, earliest deadline first.
+   */
+  readonly jobs: () => ReadonlyArray<Scheduling.Job>;
+  /**
+   * Run the jobs due now. No future deadline is crossed.
+   */
+  readonly finishInProgressScheduledFunctions: () => Promise<void>;
+  /**
+   * Run jobs at their deadlines until only standing jobs remain, or fail with
+   * `DrainBudgetExceeded` after `maxIterations` jobs. The kernel keeps its own
+   * clock, so it never calls `advanceTimers`.
+   */
+  readonly finishAllScheduledFunctions: (
+    advanceTimers?: () => void,
+    maxIterations?: number,
+  ) => Promise<void>;
+}
+
+/**
+ * How a kit registers a component beyond its schema and modules.
+ */
+export interface RegisterOptions {
+  /**
+   * The component's functions, as `module:export`, that schedule their own next
+   * run, such as the crons component's `public:rescheduler`. A job that runs
+   * one, or that one schedules, is never drain work.
+   */
+  readonly standing?: ReadonlyArray<string>;
 }
 
 const isSchemaDefinition = (
@@ -59,10 +94,13 @@ const accessor = (world: Execution.World, caller: Execution.Caller): any => ({
     }),
   fetch: () => Promise.reject(KernelRefusal.rowPending("HTTP routes", 6)),
   jwks: () => Promise.reject(KernelRefusal.rowPending("JWT verification", 6)),
-  finishInProgressScheduledFunctions: () =>
-    Promise.reject(KernelRefusal.rowPending("the scheduler", 5)),
-  finishAllScheduledFunctions: () =>
-    Promise.reject(KernelRefusal.rowPending("the scheduler", 5)),
+  advance: (ms: number) => world.advance(ms),
+  jobs: () => world.jobs(),
+  finishInProgressScheduledFunctions: () => world.advance(0),
+  finishAllScheduledFunctions: (
+    _advanceTimers?: () => void,
+    maxIterations?: number,
+  ) => world.drain(maxIterations),
 });
 
 /**
@@ -73,7 +111,8 @@ const accessor = (world: Execution.World, caller: Execution.Caller): any => ({
  * Beyond convex-test, `prepare` runs a mutation to its commit point and holds
  * it, and `apply` validates and publishes a held attempt. `mutation` applies
  * each attempt it prepares at once and prepares the next on a conflict, up to
- * attempt 5. `runtime` supplies the clock and commit timestamps.
+ * attempt 5. `runtime` supplies the clock and commit timestamps. Scheduled
+ * functions run on the kernel's clock, never on a host timer.
  */
 export function convexTest(
   schemaOrOptions?:
@@ -110,8 +149,14 @@ export function convexTest(
       componentPath: string,
       componentSchema: SchemaDefinition<GenericSchema, boolean>,
       componentModules: Modules,
+      options?: RegisterOptions,
     ) => {
-      world.register(componentPath, componentSchema, componentModules);
+      world.register(
+        componentPath,
+        componentSchema,
+        componentModules,
+        options?.standing,
+      );
       return (componentsGeneric() as any)[componentPath];
     },
   };