@procedures/schedule 0.0.0-stage → 0.2.3

package/src/scheduler.ts

@@ -0,0 +1,331 @@
+/**
+ * The scheduler: a host starts it, and it starts the stored programs of the schedules at their
+ * times (roadmap R46).
+ *
+ * - It wakes at each minute (the unit of cron), reads the schedules of its store, and starts each
+ *   schedule whose time came. A schedule that a procedure adds or removes counts at the next minute.
+ * - A run goes through the registry, with the capability of the host narrowed by the capability
+ *   of the caller that added the schedule. The expose rule, the call rule, the interceptors and
+ *   the resources of the host policy apply too.
+ * - A schedule has at most one run at a time. A time that comes during a run does not start a
+ *   second run: the store counts it as skipped.
+ * - The store records the last run of each schedule: its start, its time and its outcome.
+ * - A run that passes `runTimeoutMs` gets the abort of its signal and the outcome `TIMEOUT`. The
+ *   schedule stays busy until the handler ends: a handler that does not stop blocks only its own
+ *   schedule.
+ * - The scheduler does not run the times that it missed while it was stopped. Times that it
+ *   missed during a run or a slow minute give one run, not one for each time.
+ * - The timers use an injectable `Clock` (`after` and `now`), and the calendar uses an injectable
+ *   wall clock (`now`, default `Date.now`). A test gives `fakeClock` of `@mark1russell7/service/testing`.
+ */
+
+import {
+  InvocationError,
+  PROCEDURE_REGISTRY,
+  invokePath,
+  invokeProcedure,
+  isRuntimeDefined,
+  keyToPath,
+  narrowCapability,
+  outputValue,
+  realClock,
+  type Cancel,
+  type Capability,
+  type Clock,
+  type HostPolicy,
+  type InvokeOptions,
+  type ProcedureRegistry,
+} from "@procedures/client";
+import { nextTime, parseCron } from "./cron.js";
+import { ScheduleError } from "./errors.js";
+import { findProgram } from "./programs.js";
+import { defaultScheduleStore, type ScheduleStore } from "./store.js";
+import type { Schedule, ScheduleRun } from "./types.js";
+
+/** The default time limit of a run: 10 minutes. */
+export const DEFAULT_RUN_TIMEOUT_MS = 600_000;
+
+/** What a host gets after each run and each skipped time. */
+export interface ScheduleRunEvent {
+  readonly id: string;
+  readonly program: string;
+  readonly outcome: "success" | "failure" | "skipped";
+  /** The wall time of the start, in milliseconds since 1970. */
+  readonly startedAt: number;
+  readonly durationMs: number;
+  readonly error?: { readonly code?: string | undefined; readonly message: string } | undefined;
+}
+
+/** The options of a `Scheduler`. */
+export interface SchedulerOptions {
+  /** The registry of the programs. The default is the global registry. */
+  readonly registry?: ProcedureRegistry | undefined;
+  /** The store of the schedules: the store of the module of the procedures. The default is `defaultScheduleStore`. */
+  readonly store?: ScheduleStore | undefined;
+  /** The capability of the host for each run. The default is the capability of `policy`, else no limits. */
+  readonly capability?: Capability | undefined;
+  /** The policy of the host: its expose rule, call rule, interceptors, clearance order, resources and capability. */
+  readonly policy?: HostPolicy | undefined;
+  /** The clock of the timers and of the durations. The default is `realClock`. */
+  readonly clock?: Clock | undefined;
+  /** The wall time, in milliseconds since 1970. The default is `Date.now`. */
+  readonly now?: (() => number) | undefined;
+  /** The time limit of a run, in milliseconds. 0: no limit. The default is 10 minutes. */
+  readonly runTimeoutMs?: number | undefined;
+  /** This function gets each run and each skipped time. */
+  readonly onRun?: ((event: ScheduleRunEvent) => void) | undefined;
+  /** This function gets an error of the scheduler itself: a store that cannot be read, for example. */
+  readonly onError?: ((error: unknown) => void) | undefined;
+}
+
+/** The next time of one schedule, for the version of the schedule that it came from. */
+interface Due {
+  readonly version: string;
+  at: number | undefined;
+}
+
+const versionOf = (schedule: Schedule): string => `${schedule.createdAt}|${schedule.cron}|${schedule.timeZone}`;
+
+/** The code and the message of an error. */
+function errorInfo(error: unknown): { code?: string; message: string } {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = (error as { code?: unknown } | null)?.code;
+  return typeof code === "string" ? { code, message } : { message };
+}
+
+/** The next time of a schedule after a time, or undefined for an expression that is not correct. */
+function nextOf(schedule: Schedule, after: number): number | undefined {
+  try {
+    return nextTime(parseCron(schedule.cron), after, schedule.timeZone);
+  } catch {
+    return undefined;
+  }
+}
+
+/** A scheduler of the stored programs. See the comment of the file. */
+export class Scheduler {
+  private readonly registry: ProcedureRegistry;
+  private readonly store: ScheduleStore;
+  private readonly clock: Clock;
+  private readonly now: () => number;
+  private readonly runTimeoutMs: number;
+  private readonly options: SchedulerOptions;
+  private readonly due = new Map<string, Due>();
+  private readonly runs = new Map<string, { promise: Promise<void>; controller: AbortController }>();
+  private startedAt: number | undefined;
+  private cancel: Cancel | undefined;
+  private ticking: Promise<void> | undefined;
+
+  constructor(options: SchedulerOptions = {}) {
+    this.options = options;
+    this.registry = options.registry ?? PROCEDURE_REGISTRY;
+    this.store = options.store ?? defaultScheduleStore;
+    this.clock = options.clock ?? realClock;
+    this.now = options.now ?? (() => Date.now());
+    this.runTimeoutMs = options.runTimeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+    if (!(this.runTimeoutMs >= 0)) throw new TypeError("Scheduler: runTimeoutMs must be 0 or more");
+  }
+
+  /** True after `start()` and before `stop()`. */
+  get started(): boolean {
+    return this.startedAt !== undefined;
+  }
+
+  /** The names of the schedules with a run that has not ended. */
+  get active(): string[] {
+    return [...this.runs.keys()].sort();
+  }
+
+  /** This method starts the scheduler: the first times come after now. It gives the end of the first examination. */
+  async start(): Promise<void> {
+    if (this.startedAt !== undefined) return;
+    this.startedAt = this.now();
+    await this.tick();
+  }
+
+  /** This method stops the timer, aborts the runs, and gives the end of the runs. */
+  async stop(): Promise<void> {
+    this.startedAt = undefined;
+    this.cancel?.();
+    this.cancel = undefined;
+    this.due.clear();
+    for (const run of this.runs.values()) run.controller.abort(new Error("The scheduler stopped"));
+    await this.settled();
+  }
+
+  /** This method gives the end of the examination in progress and of the runs in progress. */
+  async settled(): Promise<void> {
+    await this.ticking;
+    await Promise.all([...this.runs.values()].map((run) => run.promise));
+  }
+
+  /**
+   * This method examines the schedules now and starts each one whose time came. It does not wait
+   * for the runs. A second call during an examination gives the same examination.
+   */
+  tick(): Promise<void> {
+    this.ticking ??= this.examine().finally(() => {
+      this.ticking = undefined;
+      this.arm();
+    });
+    return this.ticking;
+  }
+
+  /** This method starts one run of a schedule now, unless it has a run in progress. It gives the event of the run. */
+  async runNow(id: string): Promise<ScheduleRunEvent> {
+    const schedule = await this.store.get(id);
+    if (schedule === undefined) throw new ScheduleError("NOT_FOUND", `No schedule is named ${id}`);
+    return new Promise<ScheduleRunEvent>((resolve) => {
+      if (!this.launch(schedule, this.now(), resolve)) resolve(this.skip(schedule, this.now()));
+    });
+  }
+
+  private async examine(): Promise<void> {
+    if (this.startedAt === undefined) return;
+    const now = this.now();
+    let schedules: Schedule[];
+    try {
+      schedules = await this.store.list();
+    } catch (error) {
+      this.options.onError?.(error);
+      return;
+    }
+    const ids = new Set(schedules.map((schedule) => schedule.id));
+    for (const id of this.due.keys()) if (!ids.has(id)) this.due.delete(id);
+    for (const schedule of schedules) {
+      // A stop during the read of the store starts nothing
+      if (this.startedAt === undefined) return;
+      const version = versionOf(schedule);
+      let due = this.due.get(schedule.id);
+      if (due === undefined || due.version !== version) {
+        // A new or a changed schedule: its first time is after it was added, and after the start
+        due = { version, at: nextOf(schedule, Math.max(schedule.createdAt, this.startedAt) - 1) };
+        this.due.set(schedule.id, due);
+      }
+      if (due.at === undefined || due.at > now) continue;
+      // The times that passed give one run: the next time comes after now
+      due.at = nextOf(schedule, now);
+      if (!this.launch(schedule, now)) void this.skip(schedule, now);
+    }
+  }
+
+  /** This method arms the timer for the next minute, or for an earlier time that is due. */
+  private arm(): void {
+    if (this.startedAt === undefined) return;
+    this.cancel?.();
+    const now = this.now();
+    let wake = Math.floor(now / 60_000) * 60_000 + 60_000;
+    for (const due of this.due.values()) if (due.at !== undefined && due.at < wake) wake = due.at;
+    this.cancel = this.clock.after(Math.max(0, wake - now), () => {
+      this.cancel = undefined;
+      void this.tick();
+    });
+  }
+
+  /** This method gives an event to `onRun`. An error of `onRun` goes to `onError`, not to the scheduler. */
+  private report(event: ScheduleRunEvent): void {
+    try {
+      this.options.onRun?.(event);
+    } catch (error) {
+      this.options.onError?.(error);
+    }
+  }
+
+  /** This method records a time that came during a run of the same schedule. */
+  private skip(schedule: Schedule, now: number): ScheduleRunEvent {
+    const event: ScheduleRunEvent = { id: schedule.id, program: schedule.program, outcome: "skipped", startedAt: now, durationMs: 0 };
+    void this.store
+      .update(schedule.id, (current) => (current.createdAt === schedule.createdAt ? { ...current, skipped: current.skipped + 1 } : undefined))
+      .catch((error: unknown) => this.options.onError?.(error));
+    this.report(event);
+    return event;
+  }
+
+  /** This method starts a run, unless the schedule has one. It gives false for a schedule with a run. */
+  private launch(schedule: Schedule, startedAt: number, done?: (event: ScheduleRunEvent) => void): boolean {
+    if (this.runs.has(schedule.id)) return false;
+    const controller = new AbortController();
+    const promise = this.run(schedule, startedAt, controller).then((event) => {
+      this.runs.delete(schedule.id);
+      this.report(event);
+      done?.(event);
+    });
+    this.runs.set(schedule.id, { promise, controller });
+    return true;
+  }
+
+  /** One run: the program through the registry, then its record. */
+  private async run(schedule: Schedule, startedAt: number, controller: AbortController): Promise<ScheduleRunEvent> {
+    const start = this.clock.now();
+    let timedOut = false;
+    const stopTimer =
+      this.runTimeoutMs > 0
+        ? this.clock.after(this.runTimeoutMs, () => {
+            timedOut = true;
+            controller.abort(new Error(`The run of ${schedule.id} passed its time limit of ${this.runTimeoutMs} ms`));
+          })
+        : undefined;
+    let error: { code?: string; message: string } | undefined;
+    try {
+      await this.invoke(schedule, controller.signal);
+    } catch (caught) {
+      error = errorInfo(caught);
+    } finally {
+      stopTimer?.();
+    }
+    if (timedOut) error = { code: "TIMEOUT", message: `The run passed its time limit of ${this.runTimeoutMs} ms${error ? `: ${error.message}` : ""}` };
+    const run: ScheduleRun = {
+      startedAt,
+      durationMs: Math.max(0, this.clock.now() - start),
+      outcome: error === undefined ? "success" : "failure",
+      ...(error !== undefined ? { error } : {}),
+    };
+    try {
+      await this.store.update(schedule.id, (current) =>
+        current.createdAt === schedule.createdAt
+          ? { ...current, lastRun: run, runs: current.runs + 1, failures: current.failures + (error === undefined ? 0 : 1) }
+          : undefined,
+      );
+    } catch (caught) {
+      this.options.onError?.(caught);
+    }
+    return { id: schedule.id, program: schedule.program, outcome: run.outcome, startedAt, durationMs: run.durationMs, ...(error !== undefined ? { error } : {}) };
+  }
+
+  /** The options of an invocation: the policy of the host, a capability and the signal of the run. */
+  private invokeOptions(capability: Capability | undefined, signal: AbortSignal): InvokeOptions {
+    const policy = this.options.policy;
+    return {
+      registry: this.registry,
+      signal,
+      ...(capability !== undefined ? { capability } : {}),
+      ...(policy?.expose ? { expose: policy.expose } : {}),
+      ...(policy?.strictCalls ? { strictCalls: true } : {}),
+      ...(policy && policy.interceptors.length > 0 ? { interceptors: policy.interceptors } : {}),
+      ...(policy?.clearanceOrder ? { clearanceOrder: policy.clearanceOrder } : {}),
+      ...(policy?.resources ? { resources: policy.resources } : {}),
+    };
+  }
+
+  /** The program of a schedule through the registry, after a load from the program store when the registry does not have it. */
+  private async invoke(schedule: Schedule, signal: AbortSignal): Promise<void> {
+    const path = keyToPath(schedule.program);
+    const host = this.options.capability ?? this.options.policy?.capabilityOf?.();
+    if ((await findProgram(this.registry, schedule.program)) === "store") {
+      // The load defines the program: a step of the host, with the capability of the host
+      await outputValue(await invokePath(["procedure", "load"], { path }, this.invokeOptions(host, signal)), ["procedure", "load"]);
+    }
+    const procedure = this.registry.get(path);
+    if (procedure === undefined || !isRuntimeDefined(procedure)) {
+      throw new ScheduleError("NOT_FOUND", `The program ${schedule.program} is not in the registry after its load`);
+    }
+    const capability = schedule.capability === undefined ? host : narrowCapability(host, schedule.capability, this.options.policy?.clearanceOrder);
+    if (signal.aborted) throw new InvocationError("ABORTED", `The run of ${schedule.id} was aborted before its start`, path);
+    const output = await invokeProcedure(procedure, schedule.input ?? {}, this.invokeOptions(capability, signal));
+    if (output.kind === "stream") {
+      for await (const _item of output.items) {
+        // A program that gives a stream runs to its end
+      }
+    }
+  }
+}

package/src/store.ts

@@ -0,0 +1,213 @@
+/**
+ * The stores of the schedules: in memory, or in one JSON file.
+ *
+ * A host gives one store to the module of the procedures (`createScheduleModule({ store })`) and
+ * the same store to its `Scheduler`. `update()` changes one schedule in one step, so the record of
+ * a run does not lose a change of `schedule.add` that came at the same time.
+ */
+
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { ScheduleError } from "./errors.js";
+import type { Schedule } from "./types.js";
+
+/** A store of schedules. Each method gives a Promise: a caller cannot tell a local store from a remote one. */
+export interface ScheduleStore {
+  /** The kind of the backend: "memory", "file" or another name. */
+  readonly kind: string;
+  get(id: string): Promise<Schedule | undefined>;
+  /** The schedules, sorted by name. */
+  list(): Promise<Schedule[]>;
+  /** Write a schedule. A schedule of the same name is replaced. */
+  put(schedule: Schedule): Promise<void>;
+  /** Delete a schedule. True when it existed. */
+  delete(id: string): Promise<boolean>;
+  /**
+   * Change one schedule in one step. `change` gets a copy and gives the new schedule, or
+   * undefined for no change. The result is the stored schedule, or undefined when none exists.
+   */
+  update(id: string, change: (schedule: Schedule) => Schedule | undefined): Promise<Schedule | undefined>;
+}
+
+const byId = (a: Schedule, b: Schedule): number => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+const isCount = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+
+/** The schedule of a record that came from a file: its shape is not trusted. */
+export function checkSchedule(value: unknown): Schedule {
+  const record = value as Partial<Schedule> | null;
+  if (record === null || typeof record !== "object") throw new ScheduleError("BAD_STORE", "A stored schedule must be an object");
+  if (typeof record.id !== "string" || record.id === "") throw new ScheduleError("BAD_STORE", "A stored schedule needs an id");
+  if (typeof record.cron !== "string" || typeof record.program !== "string" || record.program === "") {
+    throw new ScheduleError("BAD_STORE", `The schedule ${record.id} needs a cron expression and a program`);
+  }
+  if (record.timeZone !== "utc" && record.timeZone !== "local") throw new ScheduleError("BAD_STORE", `The schedule ${record.id} needs the time zone utc or local`);
+  if (typeof record.createdAt !== "number" || !Number.isFinite(record.createdAt)) throw new ScheduleError("BAD_STORE", `The schedule ${record.id} needs createdAt`);
+  if (!isCount(record.runs) || !isCount(record.failures) || !isCount(record.skipped)) throw new ScheduleError("BAD_STORE", `The schedule ${record.id} needs the counts of its runs`);
+  return record as Schedule;
+}
+
+/** A store in memory: for tests, and for a host that keeps its schedules only while it runs. */
+export class MemoryScheduleStore implements ScheduleStore {
+  readonly kind = "memory";
+  private readonly schedules = new Map<string, Schedule>();
+
+  async get(id: string): Promise<Schedule | undefined> {
+    const schedule = this.schedules.get(id);
+    return schedule ? structuredClone(schedule) : undefined;
+  }
+
+  async list(): Promise<Schedule[]> {
+    return [...this.schedules.values()].map((schedule) => structuredClone(schedule)).sort(byId);
+  }
+
+  async put(schedule: Schedule): Promise<void> {
+    const checked = checkSchedule(structuredClone(schedule));
+    this.schedules.set(checked.id, checked);
+  }
+
+  async delete(id: string): Promise<boolean> {
+    return this.schedules.delete(id);
+  }
+
+  async update(id: string, change: (schedule: Schedule) => Schedule | undefined): Promise<Schedule | undefined> {
+    const current = this.schedules.get(id);
+    if (current === undefined) return undefined;
+    const next = change(structuredClone(current));
+    if (next === undefined) return structuredClone(current);
+    const checked = checkSchedule(structuredClone(next));
+    if (checked.id !== id) throw new ScheduleError("BAD_STORE", "An update cannot change the id of a schedule");
+    this.schedules.set(id, checked);
+    return structuredClone(checked);
+  }
+}
+
+interface ScheduleFile {
+  schemaVersion: 1;
+  schedules: Record<string, Schedule>;
+}
+
+/** True when Windows holds a file for a moment. */
+function isContention(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  return process.platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY");
+}
+
+const pause = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * A store in one JSON file: `{ "schemaVersion": 1, "schedules": { "<id>": <Schedule> } }`. Each
+ * operation reads the file again. A write goes through a temporary file and a rename, so a reader
+ * never sees a part of a write. The writes of this process go one at a time. The store is for
+ * one process: two processes on one file can lose a write.
+ */
+export class FileScheduleStore implements ScheduleStore {
+  readonly kind = "file";
+  private queue: Promise<unknown> = Promise.resolve();
+
+  /** @param path - The JSON file. The store makes it, and its folder, at the first write. */
+  constructor(readonly path: string) {}
+
+  async get(id: string): Promise<Schedule | undefined> {
+    return (await this.read()).schedules[id];
+  }
+
+  async list(): Promise<Schedule[]> {
+    return Object.values((await this.read()).schedules).sort(byId);
+  }
+
+  async put(schedule: Schedule): Promise<void> {
+    const checked = checkSchedule(structuredClone(schedule));
+    await this.change((file) => {
+      file.schedules[checked.id] = checked;
+      return true;
+    });
+  }
+
+  async delete(id: string): Promise<boolean> {
+    let deleted = false;
+    await this.change((file) => {
+      deleted = Object.hasOwn(file.schedules, id);
+      if (deleted) delete file.schedules[id];
+      return deleted;
+    });
+    return deleted;
+  }
+
+  async update(id: string, change: (schedule: Schedule) => Schedule | undefined): Promise<Schedule | undefined> {
+    let result: Schedule | undefined;
+    await this.change((file) => {
+      const current = file.schedules[id];
+      if (current === undefined) return false;
+      const next = change(structuredClone(current));
+      if (next === undefined) {
+        result = current;
+        return false;
+      }
+      const checked = checkSchedule(structuredClone(next));
+      if (checked.id !== id) throw new ScheduleError("BAD_STORE", "An update cannot change the id of a schedule");
+      file.schedules[id] = checked;
+      result = checked;
+      return true;
+    });
+    return result;
+  }
+
+  /** The content of the file. A missing file is an empty store. */
+  private async read(): Promise<ScheduleFile> {
+    let text: string;
+    try {
+      text = await readFile(this.path, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return { schemaVersion: 1, schedules: {} };
+      throw error;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new ScheduleError("BAD_STORE", `The schedule file ${this.path} is not JSON. The store does not write over it.`);
+    }
+    const file = parsed as Partial<ScheduleFile> | null;
+    if (file === null || typeof file !== "object" || file.schemaVersion !== 1 || file.schedules === null || typeof file.schedules !== "object") {
+      throw new ScheduleError("BAD_STORE", `The schedule file ${this.path} does not have schemaVersion 1 and schedules`);
+    }
+    const schedules: Record<string, Schedule> = {};
+    for (const [id, value] of Object.entries(file.schedules)) {
+      const schedule = checkSchedule(value);
+      if (schedule.id !== id) throw new ScheduleError("BAD_STORE", `The schedule file ${this.path} has the schedule ${schedule.id} under the key ${id}`);
+      schedules[id] = schedule;
+    }
+    return { schemaVersion: 1, schedules };
+  }
+
+  /** One change of the file, after the changes before it. `edit` gives false for no change. */
+  private change(edit: (file: ScheduleFile) => boolean): Promise<void> {
+    const run = this.queue.then(async () => {
+      const file = await this.read();
+      if (!edit(file)) return;
+      await mkdir(dirname(this.path), { recursive: true });
+      const temporary = `${this.path}.${randomBytes(6).toString("hex")}.tmp`;
+      await writeFile(temporary, JSON.stringify(file, null, 2) + "\n", "utf8");
+      for (let attempt = 1; ; attempt++) {
+        try {
+          await rename(temporary, this.path);
+          return;
+        } catch (error) {
+          if (attempt >= 20 || !isContention(error)) {
+            await rm(temporary, { force: true });
+            throw error;
+          }
+          await pause(10 * attempt);
+        }
+      }
+    });
+    // A failed change does not stop the next one
+    this.queue = run.catch(() => undefined);
+    return run;
+  }
+}
+
+/** The store of the default module and of a `Scheduler` without a store: in memory, one for the process. */
+export const defaultScheduleStore: ScheduleStore = new MemoryScheduleStore();

package/src/types.ts

@@ -0,0 +1,122 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+
+import type { PermittedEffects } from "@procedures/client";
+
+/** The time zone of a cron expression: the UTC time, or the local time of the host. */
+export type ScheduleTimeZone = "utc" | "local";
+
+/** The last run of a schedule. */
+export interface ScheduleRun {
+  /** The wall time of the start, in milliseconds since 1970. */
+  startedAt: number;
+  /** The time of the run, in milliseconds. */
+  durationMs: number;
+  outcome: "success" | "failure";
+  /** The error of a failure: its code, when it has one, and its message. */
+  error?: { code?: string | undefined; message: string } | undefined;
+}
+
+/** One stored schedule: a cron expression that starts a stored program with an input. */
+export interface Schedule {
+  /** The name of the schedule. */
+  id: string;
+  /** The cron expression: 5 fields, or a name such as `@daily`. */
+  cron: string;
+  /** The dotted key of the stored program: `reports.weekly`. */
+  program: string;
+  /** The input of the program. */
+  input?: unknown;
+  timeZone: ScheduleTimeZone;
+  /** When the schedule was added, in milliseconds since 1970. A schedule starts no run for a time before it. */
+  createdAt: number;
+  /**
+   * The capability of the caller that added the schedule, without its deadline. A run gets the
+   * capability of the host, narrowed by this one: a caller cannot start more than it can do.
+   */
+  capability?: { clearance?: unknown; effects?: PermittedEffects } | undefined;
+  lastRun?: ScheduleRun | undefined;
+  /** The number of runs. */
+  runs: number;
+  /** The number of runs that failed. */
+  failures: number;
+  /** The number of times that came while a run of the schedule was not finished: no second run started. */
+  skipped: number;
+}
+
+/** A schedule as the procedures give it: with its next time. */
+export interface ScheduleView extends Schedule {
+  /** The next time, as an ISO text in the time zone of the schedule, or null when the expression has no next time. */
+  nextRunAt: string | null;
+}
+
+// =============================================================================
+// schedule.add
+// =============================================================================
+
+export interface ScheduleAddInput {
+  /** The name of the schedule. The default is the key of the program. */
+  id?: string | undefined;
+  cron: string;
+  /** The dotted key of the stored program. */
+  program: string;
+  input?: unknown;
+  /** The time zone of the expression. The default is `local`. */
+  timeZone?: ScheduleTimeZone | undefined;
+  /** True: replace a schedule of the same name. The default is false: a second schedule of a name is an error. */
+  replace?: boolean | undefined;
+}
+
+export interface ScheduleAddOutput {
+  schedule: ScheduleView;
+}
+
+// =============================================================================
+// schedule.list
+// =============================================================================
+
+export interface ScheduleListInput {
+  /** Only the schedules of this program. */
+  program?: string | undefined;
+}
+
+export interface ScheduleListOutput {
+  /** The schedules, sorted by name. */
+  schedules: ScheduleView[];
+}
+
+// =============================================================================
+// schedule.remove
+// =============================================================================
+
+export interface ScheduleRemoveInput {
+  id: string;
+}
+
+export interface ScheduleRemoveOutput {
+  /** True when the schedule existed. */
+  removed: boolean;
+}
+
+// =============================================================================
+// schedule.next
+// =============================================================================
+
+export interface ScheduleNextInput {
+  cron: string;
+  /** The number of times: 1 to 100. The default is 5. */
+  count?: number | undefined;
+  /** The times come after this time: an ISO text. The default is now. */
+  after?: string | undefined;
+  /** The time zone of the expression. The default is `local`. */
+  timeZone?: ScheduleTimeZone | undefined;
+}
+
+export interface ScheduleNextOutput {
+  /** The next times, as ISO texts in the time zone of the expression. Fewer than `count` when the expression has fewer times in the next 9 years. */
+  times: string[];
+}