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

package/src/internal/Invocation.ts

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { FunctionMetadata, RequestMetadata } from "convex/server";
 import type * as Context from "effect/Context";
+import * as Clock from "./Clock.js";
 
 /**
  * Four re-executions after the first try. A conflict on attempt 5 exhausts.
@@ -78,6 +79,25 @@ interface Bridge {
 
 const key = Symbol.for("@confect/test/Invocation");
 
+/**
+ * A fresh invocation of `world` for a request of its own, as an action or a
+ * scheduled job starts: attempt 1, the world's services and random stream, and
+ * a start time read from the world's clock.
+ */
+export const fresh = (
+  world: World,
+  componentPath: string,
+  { ip, userAgent, requestId, scheduledFunctionId }: Invocation["request"],
+): Invocation => ({
+  world,
+  componentPath,
+  attempt: 1,
+  request: { ip, userAgent, requestId, scheduledFunctionId },
+  services: world.services,
+  startedAt: world.clock(),
+  random: world.random,
+});
+
 /**
  * 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
@@ -105,16 +125,7 @@ const resolve = (
     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 fresh(bound.world, componentPath, request);
   }
   return componentPath === bound.componentPath
     ? bound
@@ -202,13 +213,18 @@ const pin = (
 ): void => {
   const host = globalThis;
   const previous = { Date: host.Date, Math: host.Math, crypto: host.crypto };
+  // On the kernel, `Date` already answers the running function's time on the
+  // kernel's clock, so `runAfter` schedules on it. The bridge leaves it there.
+  const kernelDate = Clock.answersInvocation(previous.Date);
   const pinned = {
-    Date: pinnedDate(previous.Date, clockOf(invocation, functionType)),
+    Date: kernelDate
+      ? previous.Date
+      : pinnedDate(previous.Date, clockOf(invocation, functionType)),
     Math: drawingMath(previous.Math, invocation.random),
     crypto: drawingCrypto(previous.crypto, invocation.random),
   };
   try {
-    host.Date = pinned.Date;
+    if (!kernelDate) host.Date = pinned.Date;
     host.Math = pinned.Math;
     host.crypto = pinned.crypto;
   } catch {
@@ -216,7 +232,7 @@ const pin = (
     // refuses the handler.
   }
   const reached = outside(() => ({
-    Date: host.Date === pinned.Date,
+    Date: !kernelDate && host.Date === pinned.Date,
     Math: host.Math === pinned.Math,
     crypto: host.crypto === pinned.crypto,
   }));
@@ -284,6 +300,15 @@ export const bind = <A>(
     start,
   );
 
+/**
+ * Run `start` with no invocation bound, so every registered handler it reaches
+ * keeps its production runtime, whatever the caller has bound.
+ */
+export const unbound = <A>(start: () => Promise<A>): Promise<A> => {
+  const bridge = installed[key];
+  return bridge === undefined ? start() : bridge.storage.exit(start);
+};
+
 /**
  * The invocation the calling handler runs under, if one is bound.
  */

package/src/internal/Kernel.ts

@@ -1,4 +1,4 @@
-import * as Globals from "./Globals.js";
+import * as Clock from "./Clock.js";
 import type { DocumentId, StoredDocument } from "./KernelValues.js";
 import { resolveCommittedValues, tableNameFromId } from "./KernelValues.js";
 import * as ReadSet from "./ReadSet.js";
@@ -158,7 +158,9 @@ export const conflict = (
  */
 export interface KernelRuntime {
   /**
-   * The time in milliseconds, for each inserted document's creation time.
+   * The time in milliseconds. The kernel's clock never reads earlier than the
+   * latest deadline `advance` reached, so a runtime that stands still still
+   * lets jobs run on time.
    */
   readonly now: () => number;
   /**
@@ -176,9 +178,7 @@ export interface KernelRuntime {
  */
 export const wallClock = (): KernelRuntime => {
   let latest = 0n;
-  // The host's clock, never the copy a bound handler pinned.
-  // oxlint-disable-next-line effecttsgo/global-date -- The default runtime is the wall clock. A driver that replays supplies its own.
-  const now = () => Globals.host(() => Date.now());
+  const now = Clock.hostNow;
   return {
     now,
     commitTs: () => {

package/src/internal/KernelRefusal.ts

@@ -74,6 +74,30 @@ export class CommitTsNotIncreasing extends Schema.TaggedError<CommitTsNotIncreas
   },
 ) {}
 
+/**
+ * Draining scheduled functions ran its budget of jobs and work still remained.
+ * A self-rescheduling function keeps the drain from ending unless its kit
+ * declares it standing.
+ */
+export class DrainBudgetExceeded extends Schema.TaggedError<DrainBudgetExceeded>()(
+  "DrainBudgetExceeded",
+  {
+    budget: Schema.Int,
+    pending: Schema.Array(
+      Schema.Struct({ componentPath: Schema.String, name: Schema.String }),
+    ),
+    message: Schema.String,
+  },
+) {}
+
+/**
+ * A component declared a standing source its modules do not export.
+ */
+export class UnknownStandingSource extends Schema.TaggedError<UnknownStandingSource>()(
+  "UnknownStandingSource",
+  { componentPath: Schema.String, name: Schema.String, message: Schema.String },
+) {}
+
 export const requiresBinary = (operation: RequiresBinary["operation"]) =>
   new RequiresBinary({
     operation,

package/src/internal/KernelValues.ts

@@ -419,6 +419,12 @@ export type ValidatorJSON =
   | { type: "array"; value: ValidatorJSON }
   | { type: "object"; value: Record<string, ObjectFieldType> }
   | { type: "record"; keys: ValidatorJSON; values: ObjectFieldType }
+  | {
+      type: "function";
+      fnType?: string;
+      args?: ValidatorJSON;
+      returns?: ValidatorJSON;
+    }
   | { type: "union"; value: ValidatorJSON[] };
 
 export function validateValidator(validator: ValidatorJSON, value: any) {
@@ -568,6 +574,24 @@ export function validateValidator(validator: ValidatorJSON, value: any) {
       }
       return;
     }
+    case "function": {
+      // The pinned binary, `precompiled-2026-10-28-cccbade`, accepts a string
+      // that parses as a function handle
+      // (`common/src/schemas/validator.rs:156-164`), and its parser requires a
+      // document id after the prefix
+      // (`common/src/bootstrap_model/components/handles.rs:100-112`). The
+      // kernel mints convex-test's handle format instead, so it accepts a
+      // string that parses as that format.
+      if (
+        typeof value !== "string" ||
+        readFunctionHandle(value) === undefined
+      ) {
+        throw new Error(
+          `Validator error: Expected a function handle, got \`${value}\``,
+        );
+      }
+      return;
+    }
     case "record": {
       if (
         value === null ||
@@ -706,13 +730,29 @@ export function validateReturnValue(
   }
 }
 
+const FUNCTION_HANDLE_PREFIX = "function://";
+
 export function createFunctionHandle(functionPath: FunctionPath) {
-  return `function://${functionPath.componentPath};${functionPath.udfPath}`;
+  return `${FUNCTION_HANDLE_PREFIX}${functionPath.componentPath};${functionPath.udfPath}`;
 }
 
-export function parseFunctionHandle(handle: string) {
-  const [componentPath, udfPath] = handle.split("function://")[1].split(";");
-  return { componentPath, udfPath };
+/**
+ * The function a handle the kernel minted names, or `undefined` for a string
+ * that is not `function://<componentPath>;<udfPath>` with a function path.
+ */
+function readFunctionHandle(handle: string): FunctionPath | undefined {
+  if (!handle.startsWith(FUNCTION_HANDLE_PREFIX)) return undefined;
+  const parts = handle.slice(FUNCTION_HANDLE_PREFIX.length).split(";");
+  if (parts.length !== 2 || parts[1] === "") return undefined;
+  return { componentPath: parts[0]!, udfPath: parts[1]! };
+}
+
+export function parseFunctionHandle(handle: string): FunctionPath {
+  const functionPath = readFunctionHandle(handle);
+  if (functionPath === undefined) {
+    throw new Error(`Invalid function handle \`${handle}\``);
+  }
+  return functionPath;
 }
 export function simpleHash(string: string) {
   let hash = 0;

package/src/internal/MountedHttp.ts

@@ -102,11 +102,16 @@ export const make = (
   const registered = new Set<string>();
   let tail = Promise.resolve();
 
-  const register: RegisterComponent = (componentPath, schema, modules) => {
+  const register: RegisterComponent = (
+    componentPath,
+    schema,
+    modules,
+    options,
+  ) => {
     if (
       !normalized.success.some((mount) => mount.componentPath === componentPath)
     ) {
-      registerComponent(componentPath, schema, modules);
+      registerComponent(componentPath, schema, modules, options);
       return;
     }
     const generated = Object.keys(modules).find((key) =>
@@ -188,10 +193,12 @@ export const make = (
         }
       },
     });
-    registerComponent(componentPath, schema, {
-      ...modules,
-      [bridgePath]: () => Promise.resolve({ invoke }),
-    });
+    registerComponent(
+      componentPath,
+      schema,
+      { ...modules, [bridgePath]: () => Promise.resolve({ invoke }) },
+      options,
+    );
     registered.add(componentPath);
   };
 

package/src/internal/Scheduling.ts

@@ -0,0 +1,126 @@
+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 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 const row = (
+  id: DocumentId,
+  creationTime: number,
+  name: string,
+  args: Value,
+  scheduledTime: number,
+): StoredDocument => ({
+  _id: id,
+  _creationTime: creationTime,
+  name,
+  args: [args],
+  scheduledTime,
+  state: { kind: "pending" },
+});
+
+export const stateOf = (doc: StoredDocument): JobState =>
+  doc["state"] as JobState;
+
+const byDeadline = (a: Due, b: Due) =>
+  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.
+ */
+export const pending = (
+  state: Kernel.State,
+  targets: ReadonlyMap<DocumentId, Target>,
+): Array<Due> => {
+  const due: Array<Due> = [];
+  for (const [componentPath, tables] of state.tables) {
+    for (const { doc } of tables.get(table)?.values() ?? []) {
+      if (stateOf(doc).kind !== "pending") continue;
+      const name = doc["name"] as string;
+      const target = targets.get(doc._id) ?? {
+        functionPath: { componentPath, udfPath: name },
+        standing: false,
+        world: undefined,
+      };
+      due.push({
+        id: doc._id,
+        componentPath,
+        name,
+        scheduledTime: doc["scheduledTime"] as number,
+        standing: target.standing,
+        target: target.functionPath,
+        args: (doc["args"] as ReadonlyArray<Value>)[0]!,
+        world: target.world,
+      });
+    }
+  }
+  return due.sort(byDeadline);
+};
+
+/**
+ * The distinct functions of `jobs`, for a refusal that names what is left.
+ */
+export const functions = (
+  jobs: ReadonlyArray<Job>,
+): Array<{ readonly componentPath: string; readonly name: string }> => {
+  const seen = new Map<string, { componentPath: string; name: string }>();
+  for (const { componentPath, name } of jobs) {
+    seen.set(`${componentPath}\u0000${name}`, { componentPath, name });
+  }
+  return [...seen.values()];
+};