@helipod/scheduler 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,711 @@
+import { Driver, ComponentDefinition } from '@helipod/component';
+import * as _helipod_values from '@helipod/values';
+import { JSONValue } from '@helipod/values';
+import { GuestDatabaseWriter, ActionApi } from '@helipod/executor';
+
+/**
+ * A function reference as produced by codegen's `api`/`internal` proxy (see
+ * `@helipod/client`'s `FunctionReference`/`getFunctionPath`). Replicated here (rather than
+ * depending on `@helipod/client`, a client-facing SDK package) since a server component
+ * needs only this one-field shape.
+ */
+interface FunctionReference {
+    readonly __path: string;
+}
+type FnRef = FunctionReference | string;
+/** Resolve a `fnRef` (string path or codegen ref) to its string path. Mirrors `@helipod/client`'s `getFunctionPath`. */
+declare function getFunctionPath(ref: FnRef): string;
+/**
+ * Task 4 design note — `parentId` threading (cascading cancel):
+ *
+ * The original design was for the driver to set an ambient "current job id" while running a job,
+ * so a job scheduling a child (`ctx.scheduler.runAfter(...)` called from inside a driver-run job)
+ * would have that child's `parentId` populated automatically via `currentJobId()` below. That
+ * requires the ambient to survive from `driver.ts`'s `runPass()` — which only has the string
+ * `fnPath`/`jobId`, and calls `ctx.runFunction(claimed.fnPath, claimed.args)` — through
+ * `DriverContext.runFunction` → `InlineUdfExecutor.run` → this component's `context` builder,
+ * none of which currently carry a "who's calling" field. Wiring it soundly means extending
+ * `DriverContext.runFunction`'s signature, `RunOptions` (`packages/executor/src/executor.ts`),
+ * and `ComponentContext` (used by every `context:` facade, not just this one) — a cross-package
+ * change well outside `components/scheduler/*` with blast radius on every component, for a single
+ * driver's benefit.
+ *
+ * Chosen instead: cascading cancel is implemented generically over whatever `parentId` a job
+ * happens to have (`cancel()` below walks `by_parent` regardless of how `parentId` got set), and
+ * `currentJobId()` stays a stub returning `undefined`. Known limitation: a child scheduled from
+ * *inside* a driver-run job today gets `parentId: undefined` (not chained) — cascading cancel
+ * only reaches jobs whose `parentId` was set explicitly. The test suite (`test/reliability.test.ts`)
+ * exercises the cascade via the test-only `_system:insertJob` escape hatch, which sets `parentId`
+ * directly. Revisit if/when a later slice needs real parent/child chaining from driver-run jobs.
+ */
+type JobState = "pending" | "inProgress" | "success" | "failed" | "canceled";
+interface EnqueueOpts {
+    /** Relative delay in ms from the enqueueing call's `now()`. `runAt` wins when both are set. */
+    runAfter?: number;
+    /** Absolute due time (epoch ms). Takes precedence over `runAfter`. */
+    runAt?: number;
+    retry?: {
+        maxFailures: number;
+    };
+    name?: string;
+    onComplete?: string;
+    context?: JSONValue;
+    idempotencyKey?: string;
+}
+interface SchedulerContext {
+    runAfter(delayMs: number, fnRef: FnRef, args: JSONValue): Promise<string>;
+    runAt(ts: number | Date, fnRef: FnRef, args: JSONValue): Promise<string>;
+    cancel(id: string): Promise<void>;
+    /** Internal: the general enqueue path (workflow-style callers pass `opts` directly). */
+    enqueue(fnRef: FnRef, args: JSONValue, opts?: EnqueueOpts): Promise<string>;
+}
+/**
+ * The two `jobs`/`job_args` table names `enqueueInternal` writes to — bare (`"jobs"`) when
+ * called from this file's own namespaced `ctx.scheduler` facade, or fully qualified
+ * (`"scheduler/jobs"`) when called from a privileged context (`_cronTick` in `./modules.ts`, and
+ * the boot-time cron reconciler in `./crons.ts`) that bypasses namespace prefixing entirely —
+ * see `./modules.ts`'s module doc comment for why those callers must use fully-qualified names.
+ */
+interface EnqueueTables {
+    jobs: string;
+    jobArgs: string;
+}
+/**
+ * The shared enqueue path: inserts a `pending` `jobs` row (+ `job_args`), honoring the
+ * born-canceled check and, since Task 5, an idempotent insert-or-noop on `opts.idempotencyKey`
+ * (looked up via `by_idempotency`) — if a job with that key already exists, its id is returned
+ * unchanged and nothing new is inserted. This dedup is what makes the cron cadence's occurrence
+ * key (`${cronName}:${fireTs}`, `_cronTick` in `./modules.ts`) safe to call more than once for
+ * the same occurrence (e.g. a reclaim-driven re-run of a cadence job).
+ *
+ * Factored out of `schedulerContext` (which calls it with bare table names, scoped to the calling
+ * mutation's own transaction via `db`) so `_cronTick` and the boot-time cron reconciler — both of
+ * which write with fully-qualified table names outside a normal namespaced call — can reuse the
+ * exact same logic rather than a parallel reimplementation drifting out of sync.
+ */
+declare function enqueueInternal(db: GuestDatabaseWriter, now: () => number, tables: EnqueueTables, fnRef: FnRef, args: JSONValue, opts: EnqueueOpts, 
+/**
+ * Resolves the target's real kind for the job's `kind` column. Defaults to always-"mutation"
+ * — correct for every caller EXCEPT `schedulerContext`'s facade methods below, which pass a
+ * closure over `cctx.functionKind` (the only caller whose target might actually be an action;
+ * `_cronTick`'s cadence/work jobs and `fireOnComplete`'s callback are always mutations).
+ */
+kindOf?: (fnPath: string) => "mutation" | "action"): Promise<string>;
+/**
+ * The terminal outcome an `onComplete` callback is invoked with — a strict superset of
+ * `./modules.ts`'s `JobResult` (which only ever carries `success`/`failed`, the two outcomes
+ * `_complete` itself produces) plus `canceled`, produced by `cancel()` below. Defined here (not
+ * `./modules.ts`) so `./modules.ts` — which already imports from this file — can reuse it without
+ * a circular import back the other way.
+ */
+type OnCompleteResult = {
+    kind: "success";
+    value: unknown;
+} | {
+    kind: "failed";
+    error: string;
+} | {
+    kind: "canceled";
+};
+/**
+ * Task 6 — the workflow-ready `onComplete`/`context` round-trip: if `job.onComplete` (a mutation
+ * path) is set, enqueue it with `{ jobId, context, result }`, where `context` is `job_args`'s
+ * `context` for THIS job read back verbatim (opaque to the scheduler — never interpreted, just
+ * round-tripped) and `result` is the terminal outcome. Enqueued via `runAt: now()` (the `runAfter:
+ * 0` semantics) so it's immediately due — the reactive wake picks it up on the very next
+ * commit-driven iteration, no extra latency beyond one dispatch pass.
+ *
+ * A no-op when `onComplete` is `undefined` (the common case — most jobs don't register a
+ * completion callback). Called from exactly two terminal transitions, never a retry:
+ *  - `./modules.ts`'s `_complete`, on `state:"success"` and on dead-lettered `state:"failed"`
+ *    (NOT on the back-to-`"pending"` retry branch — the job isn't actually done yet).
+ *  - `cancel()` below, for both the directly-canceled job and any cascaded-canceled descendant.
+ */
+declare function fireOnComplete(db: GuestDatabaseWriter, now: () => number, tables: EnqueueTables, jobId: string, onComplete: string | undefined, result: OnCompleteResult): Promise<void>;
+/**
+ * The action-mode counterpart to `SchedulerContext` — same `runAfter`/`runAt`/`cancel` method
+ * signatures (so a function body scheduling work is portable between a mutation and an action),
+ * minus `enqueue` (the general opts-carrying path stays a mutation-only internal primitive; no
+ * action caller needs it yet). Deliberately NOT structurally assignable to `SchedulerContext` as a
+ * type (no `enqueue`) even though the three shared methods match exactly.
+ */
+interface SchedulerActionContext {
+    runAfter(delayMs: number, fnRef: FnRef, args: JSONValue): Promise<string>;
+    runAt(ts: number | Date, fnRef: FnRef, args: JSONValue): Promise<string>;
+    cancel(id: string): Promise<void>;
+}
+/**
+ * Builds the action-mode `ctx.scheduler` — wired as `defineScheduler()`'s `buildAction` (see
+ * `./index.ts`). An action has no `db`, so `runAfter`/`runAt`/`cancel` can't write a `jobs` row
+ * directly the way `schedulerContext` above does; instead each delegates to `api.runMutation` of
+ * the internal `scheduler:_enqueue`/`scheduler:_cancel` mutations (`./modules.ts`), which run the
+ * SAME `enqueueInternal`/`cancel` logic inside their own fresh top-level transaction.
+ *
+ * `Date.now()` below (converting `runAfter`'s relative `delayMs` to an absolute `runAtMs`) is fine
+ * here even though queries/mutations must stay deterministic: an action is non-deterministic by
+ * design (see `ActionCtx`'s doc comment in `@helipod/executor`), and the scheduler never
+ * recomputes anything from this timestamp — `scheduler:_enqueue` just stores it as `nextTs`.
+ */
+declare function schedulerActionContext(api: ActionApi): SchedulerActionContext;
+
+type CatchUpPolicy = "skip" | "fireOnce" | "fireAll";
+/** The two spec shapes `computeNextRun` understands. Stored on the `crons` row JSON-serialized (`spec: v.string()`). */
+type CronSpec = {
+    kind: "interval";
+    ms: number;
+} | {
+    kind: "cron";
+    expr: string;
+};
+interface CronRegistryEntry {
+    name: string;
+    spec: CronSpec;
+    tz: string;
+    catchUp: CatchUpPolicy;
+    workFnPath: string;
+    workArgs: JSONValue;
+}
+interface IntervalPeriod {
+    seconds?: number;
+    minutes?: number;
+    hours?: number;
+}
+interface DailyAt {
+    hourUTC: number;
+    minuteUTC: number;
+}
+interface HourlyAt {
+    minuteUTC: number;
+}
+type DayOfWeek = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+interface WeeklyAt {
+    dayOfWeek: DayOfWeek;
+    hourUTC: number;
+    minuteUTC: number;
+}
+interface MonthlyAt {
+    day: number;
+    hourUTC: number;
+    minuteUTC: number;
+}
+/** `tz`/`catchUp` are additive Helipod extensions (absent on Convex) — see the design spec §5.2. */
+interface CronOpts {
+    tz?: string;
+    catchUp?: CatchUpPolicy;
+}
+/** `.daily`/`.hourly`/`.weekly`/`.monthly` take *UTC fields by name — `tz` isn't accepted (it'd be ambiguous which field it applies to); only `catchUp` is overridable. */
+type CronUtcOpts = Pick<CronOpts, "catchUp">;
+interface CronJobs {
+    interval(name: string, period: IntervalPeriod, fnRef: FnRef, args: JSONValue, opts?: CronOpts): void;
+    cron(name: string, expr: string, fnRef: FnRef, args: JSONValue, opts?: CronOpts): void;
+    daily(name: string, at: DailyAt, fnRef: FnRef, args: JSONValue, opts?: CronUtcOpts): void;
+    hourly(name: string, at: HourlyAt, fnRef: FnRef, args: JSONValue, opts?: CronUtcOpts): void;
+    weekly(name: string, at: WeeklyAt, fnRef: FnRef, args: JSONValue, opts?: CronUtcOpts): void;
+    monthly(name: string, at: MonthlyAt, fnRef: FnRef, args: JSONValue, opts?: CronUtcOpts): void;
+    /** Boot-reconciliation seam — not part of the public Convex-parity surface. */
+    __entries(): CronRegistryEntry[];
+}
+/** `cronJobs()` — see this file's module doc comment for the full `crons.ts` shape. */
+declare function cronJobs(): CronJobs;
+/**
+ * Computes the next fire time strictly AFTER `afterTs`, per `spec`. For `{kind:"interval"}`
+ * that's plain arithmetic; for `{kind:"cron"}` it's `cron-parser`'s `parseExpression(...).next()`
+ * against `afterTs` as `currentDate` in the given IANA `tz` — verified to return a date strictly
+ * greater than `afterTs` even when `afterTs` itself exactly matches the pattern (i.e. calling
+ * this again with the returned value as the new `afterTs` always advances — no infinite loop,
+ * no repeat).
+ */
+declare function computeNextRun(spec: CronSpec, tz: string, afterTs: number): number;
+/**
+ * Computes the LAST fire time AT-OR-BEFORE `atOrBeforeTs`, per `spec` — the mirror of
+ * `computeNextRun`, used only by `_cronTick`'s bounded catch-up path (`./modules.ts`, the
+ * unbounded-catch-up-loop fix) to find the single most recent missed occurrence in O(1) without
+ * stepping through a potentially enormous backlog. Only meaningful for `{kind:"cron"}` — an
+ * interval spec's "previous occurrence" is plain reverse arithmetic from its own numeric anchor,
+ * which `_cronTick` computes inline without a cron-parser round-trip, so this throws for
+ * `{kind:"interval"}` rather than silently doing the wrong thing.
+ *
+ * Implemented via `cron-parser`'s `.prev()`, called with `currentDate` one ms PAST
+ * `atOrBeforeTs` so an occurrence landing EXACTLY on `atOrBeforeTs` is still included —
+ * `cron-parser`'s `.next()`/`.prev()` are both strictly exclusive of `currentDate` itself
+ * (verified empirically, matching `computeNextRun`'s own "strictly after" contract on the other
+ * side).
+ */
+declare function computePrevRun(spec: CronSpec, tz: string, atOrBeforeTs: number): number;
+/**
+ * Enqueues (or re-enqueues) a cron's CADENCE job, embedding the resulting job's own id into its
+ * args (`{cronName, jobId}`) — the duplicate-cadence-chain fix's belt-and-braces half: a future
+ * `_cronTick` invocation can then recognize whether it's still the CURRENT canonical chain for
+ * this cron (by comparing its own `args.jobId` against `crons.cadenceJobId`) and self-terminate
+ * without rescheduling if not — see `_cronTick`'s doc comment in `./modules.ts`. This convergence
+ * check is a backstop even if `hasLiveCadence` (below) somehow still let two chains coexist.
+ *
+ * Two writes (insert, then patch `job_args`) rather than one, because the job's id isn't known
+ * until after the insert — self-referential args can't be supplied up front. This runs at most
+ * once per cadence tick (or once per boot-time reconcile), so the extra write is negligible.
+ */
+declare function enqueueCadenceJob(db: GuestDatabaseWriter, now: () => number, tables: EnqueueTables, cronName: string, runAt: number): Promise<string>;
+
+/**
+ * The `@helipod/scheduler` component schema (namespaced `scheduler/*` when composed).
+ *
+ * - `jobs` / `job_args`: split so a job's identity/state (small, hot — scanned by the driver's
+ *   `by_next_ts` index) never carries the (possibly large) `args`/`context` payload.
+ * - `crons`: declared here for the schema to be stable across Task 2→5; only Task 5's cron
+ *   scheduler reads/writes it (`cadenceJobId` links a cron to its currently-pending job).
+ */
+declare const schedulerSchema: _helipod_values.SchemaDefinition<{
+    jobs: _helipod_values.TableDefinition<{
+        fnPath: {
+            readonly kind: "string";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string;
+            readonly isOptional: "required";
+        };
+        kind: {
+            readonly kind: "union";
+            readonly members: [{
+                readonly value: "mutation";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "mutation";
+                readonly isOptional: "required";
+            }, {
+                readonly value: "action";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "action";
+                readonly isOptional: "required";
+            }];
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: "mutation" | "action";
+            readonly isOptional: "required";
+        };
+        state: {
+            readonly kind: "union";
+            readonly members: [{
+                readonly value: "pending";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "pending";
+                readonly isOptional: "required";
+            }, {
+                readonly value: "inProgress";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "inProgress";
+                readonly isOptional: "required";
+            }, {
+                readonly value: "success";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "success";
+                readonly isOptional: "required";
+            }, {
+                readonly value: "failed";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "failed";
+                readonly isOptional: "required";
+            }, {
+                readonly value: "canceled";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "canceled";
+                readonly isOptional: "required";
+            }];
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: "pending" | "inProgress" | "success" | "failed" | "canceled";
+            readonly isOptional: "required";
+        };
+        nextTs: {
+            readonly kind: "number";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: number;
+            readonly isOptional: "required";
+        };
+        attempts: {
+            readonly kind: "number";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: number;
+            readonly isOptional: "required";
+        };
+        maxFailures: {
+            readonly kind: "number";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: number;
+            readonly isOptional: "required";
+        };
+        leaseHolder: {
+            readonly inner: _helipod_values.Validator<string, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string | undefined;
+            readonly isOptional: "optional";
+        };
+        leaseExpiresAt: {
+            readonly inner: _helipod_values.Validator<number, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: number | undefined;
+            readonly isOptional: "optional";
+        };
+        idempotencyKey: {
+            readonly inner: _helipod_values.Validator<string, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string | undefined;
+            readonly isOptional: "optional";
+        };
+        appVersion: {
+            readonly inner: _helipod_values.Validator<string, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string | undefined;
+            readonly isOptional: "optional";
+        };
+        name: {
+            readonly inner: _helipod_values.Validator<string, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string | undefined;
+            readonly isOptional: "optional";
+        };
+        hasArgs: {
+            readonly kind: "boolean";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: boolean;
+            readonly isOptional: "required";
+        };
+        onComplete: {
+            readonly inner: _helipod_values.Validator<string, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string | undefined;
+            readonly isOptional: "optional";
+        };
+        parentId: {
+            readonly inner: _helipod_values.Validator<string, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string | undefined;
+            readonly isOptional: "optional";
+        };
+        completedTs: {
+            readonly inner: _helipod_values.Validator<number, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: number | undefined;
+            readonly isOptional: "optional";
+        };
+        /** The most recent failure's `String(error)` — set on retry AND on dead-letter (Task 4). */
+        lastError: {
+            readonly inner: _helipod_values.Validator<string, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string | undefined;
+            readonly isOptional: "optional";
+        };
+    }>;
+    job_args: _helipod_values.TableDefinition<{
+        jobId: {
+            readonly kind: "string";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string;
+            readonly isOptional: "required";
+        };
+        args: {
+            readonly kind: "any";
+            check(): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: any;
+            readonly isOptional: "required";
+        };
+        context: {
+            readonly inner: _helipod_values.Validator<any, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: any;
+            readonly isOptional: "optional";
+        };
+    }>;
+    crons: _helipod_values.TableDefinition<{
+        name: {
+            readonly kind: "string";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string;
+            readonly isOptional: "required";
+        };
+        spec: {
+            readonly kind: "string";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string;
+            readonly isOptional: "required";
+        };
+        tz: {
+            readonly kind: "string";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string;
+            readonly isOptional: "required";
+        };
+        catchUp: {
+            readonly kind: "union";
+            readonly members: [{
+                readonly value: "skip";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "skip";
+                readonly isOptional: "required";
+            }, {
+                readonly value: "fireOnce";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "fireOnce";
+                readonly isOptional: "required";
+            }, {
+                readonly value: "fireAll";
+                readonly kind: "literal";
+                check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+                toJSON(): _helipod_values.ValidatorJSON;
+                readonly _output: "fireAll";
+                readonly isOptional: "required";
+            }];
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: "skip" | "fireOnce" | "fireAll";
+            readonly isOptional: "required";
+        };
+        lastScheduledTs: {
+            readonly inner: _helipod_values.Validator<number, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: number | undefined;
+            readonly isOptional: "optional";
+        };
+        workFnPath: {
+            readonly kind: "string";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string;
+            readonly isOptional: "required";
+        };
+        workArgs: {
+            readonly kind: "any";
+            check(): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: any;
+            readonly isOptional: "required";
+        };
+        cadenceJobId: {
+            readonly inner: _helipod_values.Validator<string, _helipod_values.OptionalProperty>;
+            readonly kind: "optional";
+            check(value: _helipod_values.Value, path: string, out: _helipod_values.ValidationFailure[]): void;
+            toJSON(): _helipod_values.ValidatorJSON;
+            readonly _output: string | undefined;
+            readonly isOptional: "optional";
+        };
+    }>;
+}>;
+
+/**
+ * Internal modules for `@helipod/scheduler` — registered on `defineScheduler()`'s `modules` map
+ * (so they're reachable as `scheduler:_peekDue` / `scheduler:_claim` / `scheduler:_complete`),
+ * consumed ONLY by the Task 3 driver loop (`./driver.ts`) via `DriverContext.runFunction`, which
+ * always calls privileged (`runtime-embedded/src/runtime.ts`'s `driverCtx.runFunction` sets
+ * `privileged: true`). Privileged calls bypass namespace prefixing entirely (`kernel.ts`'s
+ * `requireTable`), so — unlike `facade.ts`, which runs namespaced and uses bare table names
+ * (`"jobs"`, `"job_args"`) — these modules must use the fully-qualified names
+ * (`"scheduler/jobs"`, `"scheduler/job_args"`).
+ *
+ * `_peekDue`/`_claim`/`_complete` are internal by convention (the `_` prefix + being paired only
+ * with the driver), not by enforced access control — see Task 3's research notes. That's an
+ * accepted gap for this slice (nothing else in the codebase enforces "driver-only" beyond
+ * `_system:*`/`_admin:*`'s separate privileged registries).
+ */
+/** Cap on how many due jobs a single `_peekDue` batch returns, so one loop iteration can't run unbounded. */
+declare const BATCH_CAP = 64;
+/**
+ * Hard ceiling on how many missed occurrences `_cronTick`'s `catchUp:"fireAll"` path will
+ * materialize (and fire a work job for) in a single tick — see `_cronTick`'s doc comment. Without
+ * this, a `"fireAll"` cron down for a long time on a fast interval could try to enqueue an
+ * unbounded number of work jobs synchronously inside one mutation. Occurrences beyond the cap are
+ * discarded (logged), not deferred to a later tick — the cron's cadence always re-anchors past
+ * the ENTIRE true backlog on the SAME tick, regardless of how much of it actually got fired.
+ */
+declare const CATCHUP_CAP = 1000;
+/** How long a claim's lease is valid before it could be reclaimed by the sweep below. */
+declare const LEASE_MS = 30000;
+/**
+ * The driver's ONLY periodic timer: how often `scheduler:_reclaim` runs to sweep `inProgress`
+ * jobs whose lease has expired (an infra kill mid-run — the process that claimed the job died
+ * before completing it). Normal dispatch stays fully reactive/event-driven; this is a backstop.
+ */
+declare const SWEEP_MS = 30000;
+interface DueJob {
+    _id: string;
+    fnPath: string;
+    kind: "mutation" | "action";
+    state: JobState;
+    nextTs: number;
+    [key: string]: unknown;
+}
+interface PeekDueResult {
+    due: DueJob[];
+    earliestFutureTs: number | null;
+}
+interface ClaimResult {
+    jobId: string;
+    fnPath: string;
+    kind: "mutation" | "action";
+    args: JSONValue;
+    context: JSONValue | undefined;
+    onComplete: string | undefined;
+}
+type JobResult = {
+    kind: "success";
+    value: unknown;
+} | {
+    kind: "failed";
+    error: string;
+    retryable?: boolean;
+};
+
+/**
+ * A `schedulerDriver()` also exposes:
+ *  - `__tick`: a deterministic test seam for one loop iteration (no real timers).
+ *  - `__wake`: the same fire-and-forget signal `DriverContext.onCommit`/timers use internally,
+ *    exposed so a test can simulate a commit notification landing at a precise moment (e.g. from
+ *    inside a job's own mutation body, to interleave with an in-flight `__tick()`) — the reactive
+ *    `onCommit` path itself can't be driven precisely from a test, since it fires off the real
+ *    commit fan-out on whatever schedule the runtime gives it.
+ *  - `__sweep`: runs the lease-reclaim sweep (`scheduler:_reclaim`) exactly once, without arming
+ *    (or waiting on) the real `SWEEP_MS`-interval timer — the deterministic test seam for Task 4's
+ *    infra-kill reclaim path.
+ */
+interface SchedulerDriver extends Driver {
+    __tick: () => Promise<void>;
+    __wake: () => void;
+    __sweep: () => Promise<void>;
+}
+/**
+ * `@helipod/scheduler`'s driver — the event-driven loop that actually RUNS due jobs.
+ *
+ * Two wake sources, NO fixed-interval polling:
+ *  - **Reactive**: taps the runtime's commit fan-out (`DriverContext.onCommit`) and re-runs
+ *    `iterate()` whenever a commit touches any `scheduler/*` table (an `enqueue`/`cancel`/
+ *    `complete` write) — so a freshly-enqueued due job gets picked up with ~0 latency.
+ *  - **Timer**: re-arms a single wall-clock timer to `earliestFutureTs` (the soonest still-pending
+ *    job) after every iteration, so a job scheduled for later still fires once its time arrives
+ *    without anything scanning `jobs` in between.
+ *
+ * Single-owner: an in-process `running` flag collapses overlapping wake-ups (two commits, or a
+ * commit racing a timer) into a single iteration at a time. Because `running` is set
+ * synchronously — before the first `await` — two `iterate()` calls issued back-to-back in the
+ * same synchronous turn can never both proceed; the second observes `running === true` and
+ * returns immediately. That said, the in-process flag is only a throughput optimization, NOT the
+ * correctness guarantee: the AUTHORITATIVE double-run guard is `scheduler:_claim`'s snapshot-read
+ * + exact `state === "pending"` check (`./modules.ts`), serialized by the single-writer OCC
+ * transactor — even if two iterations somehow ran concurrently (e.g. two runtimes sharing a
+ * store), at most one `_claim` call per job ever observes `"pending"`.
+ *
+ * A wake that arrives while `running` is already true is NOT dropped: it sets a coalesced
+ * `pendingWake` bit that the in-flight iteration checks at the end of every pass, looping for one
+ * more fresh peek/claim/complete pass instead of exiting. Without this, a commit that lands
+ * mid-iteration (an app mutation enqueuing a due-now job between the loop's awaits) would be
+ * silently swallowed — the timer re-arm at the end of the pass would use the `earliestFutureTs`
+ * that pass captured, which doesn't account for the new job, and the job would sit `pending`
+ * until some unrelated future wake.
+ *
+ * A job that throws while running is caught per-job (not allowed to escape the loop), so one bad
+ * job can't wedge the whole batch or leave `running` stuck `true` — `_complete` is always called
+ * (with a `failed` result) and the outer `try/finally` always clears `running`.
+ *
+ * `iterate()` always returns a promise that settles when the due set it's responsible for has
+ * actually been drained — including a coalesced call. A caller that arrives while a pass is
+ * already in flight (setting `pendingWake` per above) gets back the SAME promise as the in-flight
+ * pass, not an already-resolved one: with the reactive `onCommit` wake now real (not dead code —
+ * see `packages/runtime-embedded/src/runtime.ts`), a test's `__tick()` frequently races an
+ * app-mutation's own commit, which fires `wake()` before `__tick()` gets a turn. If `__tick()`
+ * merely no-op'd on a coalesced call, tests would observe results before the real work finished.
+ * `wake()`'s callers (reactive `onCommit`/timer) never await this return value, so they're
+ * unaffected — this only changes behavior for synchronous callers like `__tick()`.
+ */
+declare function schedulerDriver(): SchedulerDriver;
+
+/**
+ * Exponential backoff (with jitter) for a scheduler job's Nth failure. Pure and side-effect-free
+ * so it's trivially unit-testable and safe to call from a deterministic mutation (`_complete` in
+ * `./modules.ts`) — it takes its randomness as an injected `rng`, never touching `Math.random`
+ * directly unless the caller passes none (the default, for callers outside a UDF's determinism
+ * boundary — there are none in this codebase yet, but this keeps the function usable standalone).
+ *
+ * `_complete` passes `ctx.random` (the query/mutation guest ctx's seeded PRNG — see
+ * `@helipod/executor`'s `seeded-random.ts`), which is what actually gives the retry jitter its
+ * determinism-for-replay property: a mutation and its OCC-conflict replay call `ctx.random()` in
+ * the same sequence and get the same numbers, and tests get a computable, non-flaky result.
+ */
+interface BackoffOptions {
+    /** Backoff for the first retry (attempts=1), before jitter. */
+    initialBackoffMs: number;
+    /** Multiplier applied per additional attempt. */
+    base: number;
+}
+declare const DEFAULT_BACKOFF_OPTIONS: BackoffOptions;
+/**
+ * `attempts` is the failure count AFTER this failure is recorded (i.e. call with the
+ * already-incremented `attempts`, not the pre-failure count) — so the first retry (attempts=1)
+ * backs off `initialBackoffMs * base^2`, jittered to 50–100% of that.
+ */
+declare function computeBackoff(attempts: number, rng?: () => number, o?: BackoffOptions): number;
+
+/**
+ * `defineScheduler()` — the `@helipod/scheduler` component: the `jobs`/`job_args`/`crons`
+ * schema, the `ctx.scheduler` facade (`runAfter`/`runAt`/`cancel`/`enqueue`), the
+ * internal `_peekDue`/`_claim`/`_complete`/`_cronTick` modules, and the `schedulerDriver`
+ * event-loop that actually RUNS due jobs — reactive on commits touching `scheduler/*` plus a
+ * wall-clock timer re-armed to the earliest future job (see `./driver.ts`).
+ *
+ * `contextWrite: true` is load-bearing: it's what lets the facade write (via the calling
+ * mutation's own transaction) instead of only reading — see `schedulerContext` in `./facade.ts`
+ * and the `ContextProvider.write` opt-in on `@helipod/executor`.
+ *
+ * `opts.crons` — an app's `crons.ts` (`export default crons` from `cronJobs()` + `.interval()`/
+ * `.cron()`/etc.) — is reconciled into the `crons` table once at boot (`reconcileCrons`, see its
+ * doc comment in `./crons.ts` for why this is a config value rather than file-discovery magic).
+ */
+declare function defineScheduler(opts?: {
+    crons?: CronJobs;
+}): ComponentDefinition;
+
+export { BATCH_CAP, type BackoffOptions, CATCHUP_CAP, type CatchUpPolicy, type ClaimResult, type CronJobs, type CronOpts, type CronRegistryEntry, type CronSpec, type CronUtcOpts, DEFAULT_BACKOFF_OPTIONS, type DailyAt, type DayOfWeek, type DueJob, type EnqueueOpts, type EnqueueTables, type FnRef, type FunctionReference, type HourlyAt, type IntervalPeriod, type JobResult, type JobState, LEASE_MS, type MonthlyAt, type OnCompleteResult, type PeekDueResult, SWEEP_MS, type SchedulerActionContext, type SchedulerContext, type SchedulerDriver, type WeeklyAt, computeBackoff, computeNextRun, computePrevRun, cronJobs, defineScheduler, enqueueCadenceJob, enqueueInternal, fireOnComplete, getFunctionPath, schedulerActionContext, schedulerDriver, schedulerSchema };