@apisurf/ngn-core 0.4.0 → 0.5.0

package/dist/core.d.ts

@@ -1,9 +1,8 @@
-import { RunStage } from '@apisurf/ngn-schema/describe';
-export { RunStage } from '@apisurf/ngn-schema/describe';
-import { FsNodeFileDescriptor } from '@apisurf/ngn-os';
 import { Client, InArgs, ResultSet, InStatement, InValue } from '@apisurf/ngn-persistence';
 export { initDbFileIfNotExists } from '@apisurf/ngn-persistence';
-import { Cron } from 'croner';
+import { ScheduleFields, ScheduleEventName, TickOrigin, RunStage } from '@apisurf/ngn-schema/describe';
+export { RunStage } from '@apisurf/ngn-schema/describe';
+import { FsNodeFileDescriptor } from '@apisurf/ngn-os';
 
 type CompilerOptions = {
     /** Minify output */
@@ -59,6 +58,95 @@ declare class Compiler {
  */
 declare function executeEsm(code: string): Promise<Record<string, unknown>>;
 
+/**
+ * Named leases in `locks`.
+ *
+ * Taking one is a single upsert that only overwrites a row whose lease has
+ * run out, so two processes on one file cannot both win, and a lease left by
+ * a process that died is free once it expires. Every acquisition gets its own
+ * holder token: two runs of one task in one process are two holders.
+ */
+declare class LockService {
+    private db;
+    constructor(db: Client);
+    /** The holder token on success, null when someone else holds an unexpired lease. */
+    tryAcquire(name: string, ttlMs: number, taskRunId: number | null): Promise<string | null>;
+    /** Push the lease out; false when it was lost (it expired and someone took it). */
+    renew(name: string, holder: string, ttlMs: number): Promise<boolean>;
+    /** Who holds `name`, and until when; null when nobody has it. Expired leases included. */
+    holderOf(name: string): Promise<{
+        holder: string;
+        taskRunId: number | null;
+        expiresAt: number;
+    } | null>;
+    /** Record which run a held lease is working for. */
+    setRun(name: string, holder: string, taskRunId: number): Promise<void>;
+    release(name: string, holder: string): Promise<void>;
+}
+
+/**
+ * A length of time as tasks write it: milliseconds, or a string such as
+ * `"500ms"`, `"30s"`, `"4m"`, `"2h"` or `"1d"`.
+ */
+type Duration = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
+
+type Edge = "leading" | "trailing";
+/** The object form of the `timing` export: a period instead of a cron pattern. */
+interface IntervalTiming {
+    /** How far apart runs are. At least 1s. */
+    every: Duration;
+    /**
+     * `"leading"` (default): a fixed grid, `every` apart from the planned start
+     * of the last run. `"trailing"`: `every` after the last run ended.
+     */
+    edge?: Edge;
+    /** The shortest delay a run may choose. At least 1s; defaults to `every`. */
+    min?: Duration;
+    /** The longest delay anything may choose. Defaults to `every × 32`. */
+    max?: Duration;
+    /**
+     * How failures slow the task down: `every × factor^failedInARow`, capped at
+     * `max`, give or take `jitter` of it. `false` keeps failures on `every`.
+     * Defaults to `{ factor: 2, jitter: 0.1 }`.
+     */
+    backoff?: TimingBackoff | false;
+}
+interface TimingBackoff {
+    /** What each failure in a row multiplies the delay by. At least 1. */
+    factor?: number;
+    /** How far the delay may stray either way, as a fraction of it, from 0 to 1. */
+    jitter?: number;
+}
+/** What a task's `timing` export can be. */
+type TimingExport = string | IntervalTiming;
+type ResolvedTiming = {
+    kind: "cron";
+    pattern: string;
+} | {
+    kind: "interval";
+    everyMs: number;
+    edge: Edge;
+    minMs: number;
+    maxMs: number;
+    backoff: Required<TimingBackoff> | null;
+};
+/**
+ * The `timing` export, checked: a cron pattern, or `{ every, edge, min, max, backoff }`. Throws,
+ * naming the task, on anything else, so a typo fails at schedule time.
+ */
+declare function resolveTiming(value: unknown, taskPath: string): ResolvedTiming;
+/**
+ * The timing `--timing` takes on the command line: a duration (`5m`) is
+ * `{ every }` on the leading edge, anything else a cron pattern. Null when it is
+ * neither.
+ */
+declare function timingFromFlag(flag: string): TimingExport | null;
+/** What the `next` hook chose, checked: a delay in ms or one of the task's own, and why. */
+interface NextChoice {
+    delay: number | "every" | "min" | "max";
+    reason: string | null;
+}
+
 /**
  * A database migration
  */
@@ -130,30 +218,6 @@ declare function closeTaskDatabases(): void;
  */
 declare function releaseTaskDatabases(taskSourcePath: string): void;
 
-/**
- * A length of time as tasks write it: milliseconds, or a string such as
- * `"500ms"`, `"30s"`, `"4m"`, `"2h"` or `"1d"`.
- */
-type Duration = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
-
-/**
- * Named leases in `locks`.
- *
- * Taking one is a single upsert that only overwrites a row whose lease has
- * run out, so two processes on one file cannot both win, and a lease left by
- * a process that died is free once it expires. Every acquisition gets its own
- * holder token: two runs of one task in one process are two holders.
- */
-declare class LockService {
-    private db;
-    constructor(db: Client);
-    /** The holder token on success, null when someone else holds an unexpired lease. */
-    tryAcquire(name: string, ttlMs: number, taskRunId: number | null): Promise<string | null>;
-    /** Push the lease out; false when it was lost (it expired and someone took it). */
-    renew(name: string, holder: string, ttlMs: number): Promise<boolean>;
-    release(name: string, holder: string): Promise<void>;
-}
-
 interface LockOptions {
     /**
      * How long the lease lasts if this process stops renewing it (it dies, or
@@ -451,6 +515,15 @@ declare class Queue<T = unknown> {
     stats(): Promise<QueueStats>;
 }
 
+interface ResolvedRetry {
+    attempts: number;
+    delayMs: number;
+    breaker: {
+        after: number;
+        maxSkip: number;
+    } | null;
+}
+
 /**
  * The run this context belongs to, and how long it has. Times are epoch
  * milliseconds, as everywhere in ngn's database.
@@ -458,9 +531,13 @@ declare class Queue<T = unknown> {
 interface TaskRun {
     /** This run's `task_runs.id`. */
     id: number;
-    /** When the tick that started it fired; null for a run with no schedule. */
+    /** When the tick that started it was planned for; null for a run with no schedule. */
     scheduledAt: number | null;
-    /** When the next tick is due; null for a run with no schedule. */
+    /**
+     * When the next tick is due: the next slot of a cron pattern or the leading
+     * edge. Null on the trailing edge, whose next run depends on when this one
+     * ends, and for a run with no schedule.
+     */
     nextAt: number | null;
     /**
      * When to stop starting new work: shortly before `nextAt`, or sooner with a
@@ -527,11 +604,118 @@ interface TaskContext {
     sqlite: TaskSqlite;
 }
 /**
- * What a scheduled tick does when the task's previous run is still going:
- * `"skip"` records the tick as a skipped run, `"allow"` starts another run
- * beside it.
+ * ngn runs one run of a task at a time, so `"skip"` is the only policy: a run
+ * that comes due while one is going waits for it. `"allow"` fails at schedule
+ * time; it is kept in the type so the message can say why.
  */
 type OverlapPolicy = "skip" | "allow";
+interface NextOutcomeBase {
+    /** Failed ticks in a row, this one included. */
+    failedInARow: number;
+    /** The delay that led to this tick, in ms; null when there was none to measure. */
+    previousDelayMs: number | null;
+    /** The `task_runs.id` of the tick's final run. */
+    runId: number;
+}
+/** What the `next` hook is told about the tick that just ended. */
+type NextOutcome<Result = any> = NextOutcomeBase & ({
+    status: "success";
+    result: Result;
+    error: undefined;
+    skipReason: null;
+} | {
+    status: "failure";
+    result: undefined;
+    error: Error;
+    skipReason: null;
+} | {
+    status: "skipped";
+    result: undefined;
+    error: undefined;
+    /** Why ngn skipped it; null for a skip by the task's own `shouldSkip`. */
+    skipReason: string | null;
+});
+/**
+ * When to run next: a duration from when the tick ended, or the task's own
+ * `every`, `min` or `max`. ngn keeps it within `[min, max]`.
+ */
+type NextDelay = Duration | "every" | "min" | "max";
+/** What the `next` hook returns: undefined leaves it to the default policy. */
+type NextDecision = undefined | void | NextDelay | {
+    in: NextDelay;
+    reason?: string;
+};
+
+interface ScheduleRow extends ScheduleFields {
+    file_task_id: number;
+    updated_at: number;
+}
+/** What a transition writes, besides the state the table gives it. */
+interface Transition {
+    event: ScheduleEventName;
+    at: number;
+    /** Row fields to set; anything left out keeps its value. */
+    set?: Partial<Omit<ScheduleFields, "state">>;
+    origin?: TickOrigin | null;
+    firstRunId?: number | null;
+    runId?: number | null;
+    /** Only apply while the row's holder is this one (a tick's own lease, or none). */
+    holder?: string | null;
+    /** The tick's final run, to record the next run and its reason on. */
+    finalRunId?: number | null;
+    /**
+     * Only apply while the row's pending request is this one, so a request made
+     * after it was read is not lost.
+     */
+    requestIs?: string | null;
+    /**
+     * A second transition to make in the same write, from the state this one
+     * leaves: `paused` after the decision of a tick a pause was requested during.
+     */
+    followedBy?: Omit<Transition, "followedBy" | "holder" | "requestIs" | "finalRunId">;
+}
+/** Why a transition was not applied. */
+type Refusal = {
+    refused: string;
+};
+/**
+ * The schedule rows and their event log. Every change is one write batch: the
+ * row update, conditional on the state the event comes from, then the event,
+ * copied from the row it left, inserted only if the update applied. The row is
+ * therefore always the fold of its events. A write the state table does not
+ * allow, or one that lost a race with another process, is refused and the row
+ * is left as it was.
+ */
+declare class ScheduleStore {
+    private db;
+    constructor(db: Client);
+    read(taskId: number): Promise<ScheduleRow | null>;
+    /**
+     * Apply `change` to the task's schedule, as it stands now. The new row, or
+     * why it was refused.
+     */
+    transition(taskId: number, change: Transition): Promise<ScheduleRow | Refusal>;
+    private insert;
+    /**
+     * The row update, conditional on the state it comes from (and the holder or
+     * request the change names). `after`: the time of the transition this one
+     * follows in the same write, which it applies only on top of.
+     */
+    private update;
+    /** The next run and its reason, on the tick's final run, written only if the event was. */
+    private finalRun;
+    /** The event, copied from the row the update left, written only if it applied. */
+    private event;
+    /**
+     * Close the task's runs that never recorded an end, as failed in
+     * `interrupted` with `why` as the error, in one write. `fromRunId` limits it
+     * to one tick's runs. Returns the ids closed, oldest first.
+     */
+    closeOpenRuns(taskId: number, why: string, { fromRunId, at }: {
+        fromRunId?: number;
+        at: number;
+    }): Promise<number[]>;
+}
 
 interface CompiledTaskCallbacks {
     onTaskLoadComplete?: ({ paths, md5Hash, compiledCode, }: {
@@ -627,13 +811,74 @@ type TaskConfig = {
     env: TaskContext["env"];
     kv: TaskContext["kv"];
     sqlite: TaskContext["sqlite"];
+    /** The run database's schedules and leases, for whatever schedules or starts the task. */
+    scheduling: {
+        store: ScheduleStore;
+        locks: LockService;
+    };
 };
 
+/**
+ * What time it is, and how to wait: the one seam the scheduler takes time
+ * through, so a test can drive grids, sleeps and restarts without patching
+ * global timers (which task code, in its own VM context, never sees anyway).
+ */
+interface Clock {
+    now(): number;
+    /** Resolve after `ms`, or as soon as `signal` aborts. Never rejects. */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+declare const systemClock: Clock;
+
 interface ExecuteSchedule {
     /** When the tick fired, epoch ms. */
     scheduledAt?: number | null;
     /** When the next tick is due, epoch ms. */
     nextAt?: number | null;
+    /**
+     * For a run with no next tick: its deadline when it has no budget, measured
+     * from its start (the trailing edge's `every`).
+     */
+    periodMs?: number | null;
+    /** Where the tick reads the time and waits between retries. */
+    clock?: Clock;
+    /** Aborts every attempt's `ctx.run.signal`: ngn is stopping, or lost the task's lease. */
+    signal?: AbortSignal;
+    /** Told each attempt's run id as its row is opened. */
+    onRunStarted?: (runId: number) => void;
+    /**
+     * Ask the task's `next` hook, if it has one, when to run next, once the
+     * tick has ended: a scheduled tick of an interval task passes this.
+     */
+    next?: {
+        previousDelayMs: number | null;
+        timeoutMs?: number;
+    };
+}
+type TickStatus = "success" | "failure" | "skipped";
+/**
+ * How one tick ended, every way it can: the task ran and returned, it failed
+ * (in any stage, after any retries), or ngn or `shouldSkip` held it back.
+ * Whatever decides when the task runs next reads this.
+ */
+interface TickOutcome {
+    status: TickStatus;
+    /** What the task returned, for a success. */
+    result: unknown;
+    /** What the final attempt threw, for a failure. */
+    error: unknown;
+    /** Why ngn skipped the tick; null for a skip by the task's own `shouldSkip`, or no skip. */
+    skipReason: string | null;
+    /** The `task_runs.id` of the tick's first attempt; null when it failed before a run existed. */
+    firstRunId: number | null;
+    /** The `task_runs.id` of the tick's final attempt; null when it failed before a run existed. */
+    runId: number | null;
+    /** Attempts made, the first included. */
+    attempts: number;
+    /** When the final attempt ended, on the tick's clock. */
+    endedAt: number;
+    /** What the `next` hook chose; null when it was not asked, or left it to the policy. */
+    next: NextChoice | null;
 }
 /** The `task_runs.id` of the run that threw `error`, when a run recorded it. */
 declare function failedRunId(error: unknown): number | null;
@@ -654,10 +899,9 @@ declare class Task {
     private kv;
     private sqlite;
     private meta;
+    private schedulingServices;
     private entry;
     private entryExports;
-    /** Executions started and not yet settled. */
-    private inFlight;
     constructor({ entryParams, buildConfigFn, }: {
         entryParams: EntryParams;
         buildConfigFn: BuildCompiledTaskConfigFn;
@@ -669,25 +913,28 @@ declare class Task {
      */
     get taskPath(): string;
     get codeHash(): string | null;
-    get timingPattern(): string | undefined;
-    /**
-     * The task's `overlap` export, `"skip"` when it has none. Throws on anything
-     * else, naming the task, so a typo fails at schedule time.
-     */
-    get overlapPolicy(): OverlapPolicy;
+    /** The `timing` export, as the latest run (or `loadEntry`) read it. */
+    get timing(): TimingExport | undefined;
+    /** The `next` export, as loaded: unchecked, for whoever schedules the task to check. */
+    get nextHook(): unknown;
     /**
      * Check the exports that shape how the task is scheduled, so a bad value
-     * fails when the task is scheduled rather than on its first tick.
+     * fails when the task is scheduled rather than on its first tick. ngn runs
+     * one run of a task at a time, so `overlap` may only say so.
      */
     validateExports(): void;
-    /** Whether an execution of this task is in progress. */
-    get isRunning(): boolean;
+    /** The `retry` export, checked. */
+    get retryPolicy(): ResolvedRetry;
+    /** The schedule and lease services this task's runs are recorded with. */
+    get scheduling(): {
+        store: ScheduleStore;
+        locks: LockService;
+    };
     /**
-     * Record a run that ngn decided not to start, without loading or calling any
-     * of the task's code. Needs the task to have been registered by an earlier
-     * execution, which is always so for a run skipped because one is in progress.
+     * Load the task file and register it and its version, without running it:
+     * its schedule is kept against the task's id. Returns that id.
      */
-    skip(reason: string): Promise<void>;
+    register(): Promise<number>;
     hasTaskExport(): boolean;
     hasTimingExport(): boolean;
     loadEntry(): Promise<void>;
@@ -712,18 +959,39 @@ declare class Task {
      */
     private runHook;
     /**
-     * Run the task for one tick, retrying as its `retry` export allows. A
-     * scheduled tick passes when it fired and when the next one is due, which
-     * `ctx.run.deadline` and the retry window are worked out from.
+     * Run the task for one tick, retrying as its `retry` export allows, and say
+     * how it ended. A scheduled tick passes when it fired and when the next one
+     * is due, which `ctx.run.deadline` and the retry window are worked out from.
+     * Never throws: a failure is an outcome, its error recorded on its run.
+     */
+    executeTick(schedule?: ExecuteSchedule): Promise<TickOutcome>;
+    /**
+     * One tick, for a caller that wants the task's value: what it returned, or
+     * undefined for a skip. Throws what the tick failed with.
      */
-    execute(schedule?: ExecuteSchedule): Promise<void>;
+    execute(schedule?: ExecuteSchedule): Promise<unknown>;
     private executeWithRetries;
+    /**
+     * Ask the `next` hook when to run next. What it throws, returns that it may
+     * not, or a hook that takes too long, is recorded on the tick's final run in
+     * stage `next`, and leaves the decision to the policy, as does a tick that
+     * never got as far as loading the task's exports.
+     */
+    private askNext;
+    /** The tick's attempts, retrying as `retry` allows, and how the last one ended. */
+    private attempts;
     /**
      * Retry only a run that got as far as running: a module that will not load
      * fails the same way every time. Then it has to fit before the next tick,
      * and the task's `shouldRetry` gets the last word.
      */
     private shouldRetry;
+    /**
+     * The task's latest ticks that failed in a row, from its run history, so a
+     * restart does not reset the count. Ticks closed as interrupted count, since
+     * their runs were closed as failed; skipped ticks neither break nor extend it.
+     */
+    failedInARow(): Promise<number>;
     /**
      * Whether the breaker holds this tick back: after `after` failed ticks in a
      * row it skips 1, 2, 4… ticks (counted since the latest failure), letting
@@ -765,27 +1033,132 @@ declare class TaskLibrary {
         tasksRootDir: string;
         buildConfigFn: BuildCompiledTaskConfigFn;
     }): void;
-    execute(taskPath: string): Promise<void>;
+    execute(taskPath: string): Promise<unknown>;
     getTasks(): Task[];
 }
 
-type Options$1 = {
-    taskLibrary: TaskLibrary;
-    /** Called when a scheduled run throws, with the run it was recorded as when there is one. */
-    onRunError?: (path: string, error: unknown, runId: number | null) => void;
+/**
+ * What `ngn pause`, `ngn resume` and `ngn next` do to a task's schedule, and
+ * what ngnui's buttons do through `ngn run`: each one transition from the
+ * state table, written straight to the database with source `cli`. No live
+ * runtime is needed; a running scheduler sees the changed row within a step.
+ *
+ * | Command  | waiting, blocked | running            | paused              |
+ * | -------- | ---------------- | ------------------ | ------------------- |
+ * | pause    | paused           | pause_requested    | no change           |
+ * | resume   | no change        | no change          | resumed             |
+ * | next     | rescheduled      | override_requested | refused             |
+ *
+ * A request made during a run waits in `schedules.request` for the run to end.
+ */
+
+type ScheduleCommand = {
+    kind: "pause";
+} | {
+    kind: "resume";
+}
+/** `delayMs` from now; 0 for `now`. */
+ | {
+    kind: "next";
+    delayMs: number;
 };
-/** What `runNow()` did: started a run, or why it did not. */
+interface ScheduleControlTarget {
+    store: ScheduleStore;
+    taskId: number;
+    /** The task as the person named it, for the messages. */
+    name: string;
+    /** The task's cron pattern, when it runs on one: resuming it takes the next slot. */
+    pattern: string | null;
+    now: number;
+}
+type ScheduleControlResult = {
+    applied: true;
+    event: ScheduleEventName;
+    row: ScheduleRow;
+    message: string;
+}
+/** `error`: the command could not do what was asked (as opposed to there being nothing to do). */
+ | {
+    applied: false;
+    error: boolean;
+    message: string;
+};
+/**
+ * Apply `command` to the task's schedule as it stands. If the scheduler moves
+ * the row on between the read and the write, the command reads it again and
+ * acts on the new state, once.
+ */
+declare function controlSchedule(target: ScheduleControlTarget, command: ScheduleCommand): Promise<ScheduleControlResult>;
+
+/**
+ * When a task runs next, for each kind of timing. The scheduler's loop is the
+ * same for all of them; only these answers differ.
+ *
+ * The leading edge and cron both run on slots: the leading edge's are `every`
+ * apart from an anchor, a pattern's are wherever it matches. After a tick, the
+ * next run is the first slot that fits: the slot after the tick's planned
+ * time, or, when the run overran it, the first slot after it ended. Missed
+ * slots are never made up with back-to-back runs.
+ */
+
+/** The window a run gets: what `ctx.run` and the retry window are worked out from. */
+interface RunWindow {
+    scheduledAt: number;
+    nextAt: number | null;
+    /** For the trailing edge: the run's deadline when it has no budget. */
+    periodMs: number | null;
+}
+
+/** What Run now did: started a run, or why it did not. */
 type RunNowOutcome = {
     started: true;
 } | {
     started: false;
     reason: string;
 };
-/** What `start()` did with each task: scheduled on its pattern, or left out and why. */
+/** How long `stop()` waits for runs in progress before closing them as interrupted. */
+declare const STOP_GRACE_MS = 10000;
+/** The services a manual run uses, and the task's id they are keyed by. */
+interface ManualRunDeps {
+    task: Task;
+    taskId: number;
+    clock: Clock;
+    leaseTtlMs?: number;
+    /** The run's window, when it has one: Run now's is the schedule's next run. */
+    window?: Pick<RunWindow, "nextAt" | "periodMs">;
+    onProblem: (message: string) => void;
+}
+/**
+ * `ngn run x --once`: one run now, through the task's lease, from a process of
+ * its own. Refused, writing nothing, while another run of the task is going.
+ */
+declare function runOnce(task: Task, { clock, leaseTtlMs, onProblem }: Pick<ManualRunDeps, "clock" | "leaseTtlMs" | "onProblem">): Promise<TickOutcome | {
+    busy: string;
+}>;
+
+type Options$1 = {
+    taskLibrary: TaskLibrary;
+    /** Called when a scheduled run throws, with the run it was recorded as when there is one. */
+    onRunError?: (path: string, error: unknown, runId: number | null) => void;
+    /** Something went wrong with a task's schedule itself (a refused transition, a bad timing change). */
+    onScheduleProblem?: (path: string, message: string) => void;
+    /** Schedule every task on this instead of its own `timing` (`ngn run x --timing`). */
+    timing?: TimingExport;
+    /** Where the scheduler reads the time and waits. Tests pass their own. */
+    clock?: Clock;
+    /** How long a task's lease outlives a process that stopped renewing it. */
+    leaseTtlMs?: number;
+    /** Where backoff's jitter comes from. Tests pass their own. */
+    random?: () => number;
+    /** How long a task's `next` hook may take. Tests pass their own. */
+    nextTimeoutMs?: number;
+};
+
+/** What `start()` did with each task: scheduled on its timing, or left out and why. */
 interface ScheduleReport {
     scheduled: {
         path: string;
-        pattern: string;
+        timing: TimingExport;
     }[];
     failed: {
         path: string;
@@ -794,25 +1167,38 @@ interface ScheduleReport {
 }
 declare class TaskLibraryScheduler {
     private taskLibrary;
-    private onRunError;
+    private options;
     private scheduledTasks;
     constructor(options: Options$1);
     start(): Promise<ScheduleReport>;
-    stop(): Promise<void>;
-    scheduleTask(task: Task): Promise<void>;
-    /**
-     * Start one run of a scheduled task now, outside its schedule, the way a tick
-     * would: retries, budget, locks and hooks all apply, and errors go where a
-     * tick's go. It is not a tick, so the breaker does not hold it back. Resolves
-     * once the run is under way, not when it ends: a run can take longer than
-     * anyone waits on a button.
+    /**
+     * Stop starting runs, and give the runs in progress up to `graceMs` to end
+     * before closing them as interrupted.
+     */
+    stop(options?: {
+        graceMs?: number;
+    }): Promise<void>;
+    /** Stop as a process that died would, writing nothing. For tests standing in for a crash. */
+    abandon(): void;
+    /**
+     * Check a loaded task's exports and start its schedule. The timing it is
+     * scheduled on is returned; anything wrong with the exports is thrown,
+     * naming the task, so it fails now rather than on the first tick.
+     */
+    scheduleTask(task: Task): Promise<TimingExport>;
+    /**
+     * Start one run of a scheduled task now, outside its schedule: retries,
+     * budget, locks and hooks all apply, and errors go where a tick's go. It is
+     * not a tick, so the breaker does not hold it back, and it leaves the next
+     * run where it was. Resolves once the run is under way, not when it ends.
      *
-     * A run still going is reported rather than recorded as a skip, since nothing
-     * was due: the person asking can simply wait.
+     * A run of the task still going, in this process or another, is reported
+     * rather than recorded as a skip: the person asking can simply wait.
      */
-    runNow(taskPath: string): RunNowOutcome;
-    unscheduleTask(task: Task): void;
-    isCronPatternValid(cronPattern: string): boolean;
+    runNow(taskPath: string): Promise<RunNowOutcome>;
+    /** Pause, resume or move a scheduled task's next run, as `ngn pause`, `resume` and `next` do. */
+    control(taskPath: string, command: ScheduleCommand): Promise<ScheduleControlResult>;
+    unscheduleTask(task: Task): Promise<void>;
 }
 
 type Options = {
@@ -825,11 +1211,6 @@ declare class TaskOnceRunner {
 }
 
 declare function isCronPatternValid(pattern: string): boolean;
-/**
- * Schedule a loaded task on `pattern`. The task's exports are checked here, so
- * a bad `overlap` or `budget` fails now rather than on the first tick.
- */
-declare function scheduleTask(task: Task, pattern: string, onError: (error: unknown) => void): Cron<undefined>;
 
 declare function setupDbClient(dbPath: string): Promise<Client>;
 declare function getDbClient(): Client;
@@ -842,4 +1223,4 @@ declare function createControlsGenerator({ dbClient, env, report, }: {
     report?: (problem: RunProblem) => void;
 }): BuildCompiledTaskConfigFn;
 
-export { type AddJob, type Backoff, type ClaimOptions, Compiler, type DBInstance, type Duration, type InitDBOptions, type Job, type JobFilter, type JobStatus, LockBusyError, type LockOptions, type Migration, type OverlapPolicy, Queue, type QueueOptions, type QueueStats, type RunNowOutcome, type RunProblem, type ScheduleReport, Task, type TaskContext, TaskLibrary, TaskLibraryScheduler, TaskOnceRunner, type TaskRun, type TaskSqlite, type WorkHandler, type WorkOptions, type WorkSummary, type WorkerHandle, closeTaskDatabases, createControlsGenerator, executeEsm, failedRunId, getDbClient, isCronPatternValid, releaseTaskDatabases, runFailure, scheduleTask, setupDbClient };
+export { type AddJob, type Backoff, type ClaimOptions, type Clock, Compiler, type DBInstance, type Duration, type Edge, type ExecuteSchedule, type InitDBOptions, type IntervalTiming, type Job, type JobFilter, type JobStatus, LockBusyError, type LockOptions, type Migration, type NextDecision, type NextDelay, type NextOutcome, type OverlapPolicy, Queue, type QueueOptions, type QueueStats, type ResolvedTiming, type RunNowOutcome, type RunProblem, STOP_GRACE_MS, type ScheduleCommand, type ScheduleControlResult, type ScheduleControlTarget, type ScheduleReport, ScheduleStore, Task, type TaskContext, TaskLibrary, TaskLibraryScheduler, TaskOnceRunner, type TaskRun, type TaskSqlite, type TickOutcome, type TickStatus, type TimingBackoff, type TimingExport, type WorkHandler, type WorkOptions, type WorkSummary, type WorkerHandle, closeTaskDatabases, controlSchedule, createControlsGenerator, executeEsm, failedRunId, getDbClient, isCronPatternValid, releaseTaskDatabases, resolveTiming, runFailure, runOnce, setupDbClient, systemClock, timingFromFlag };