@gnldev/scheduler 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Karaca Yılmaz (https://gnl.dev)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,110 @@
+# @gnldev/scheduler
+
+Cron, interval and one-shot triggers for durable workflows. Several workers can poll the same
+schedule: a run-lock picks one winner per fire and every write to the trigger's state is CAS-fenced,
+so a slot is never double-advanced or rolled back — see [the lock section](#lock-ttl-and-what-once-covers)
+for what that does and does not promise about the workflow body.
+
+## Install
+
+> Install: `pnpm add @gnldev/scheduler` — or use it from a [repo clone](https://github.com/Karaca7/gnldev): `pnpm install && pnpm -r build`.
+
+```bash
+npm i @gnldev/scheduler
+```
+
+## Schedule something
+
+```ts
+import { scheduleWorkflow, createScheduler, pollScheduler } from '@gnldev/scheduler';
+
+await scheduleWorkflow(journal, {
+  id: 'nightly-invoices',
+  cron: '0 3 * * *',
+  name: 'invoices',          // the workflow name handed to runner.runWorkflow
+});
+
+// in your worker loop. The runner is an object with runWorkflow — createGnl() is one.
+setInterval(() => pollScheduler(journal, gnl), 30_000);
+```
+
+## Lock TTL and what "once" covers
+
+Two workers polling at the same moment do not both fire the trigger: `acquireRunLock` picks one
+winner on `<runId>:fire`, and every write to the trigger's state is a CAS against the record that
+winner read when the fire began. `fireCount`, `nextRunAt` and `attempts` can therefore only be advanced by the poller that
+actually owns the fire — a poller that lost the lock cannot roll them back or resurrect a stale
+attempt count. The property comes from the journal rather than from careful timing.
+
+`lockTtlMs` (default **60 s**, on both `pollScheduler` and `createScheduler`) is how long that lock is
+held. It is renewed every `lockTtlMs / 3` for as long as the workflow is in flight, so a run that
+takes longer than the TTL keeps its lock. That renewal is not cosmetic: the TTL used to be fixed and
+never renewed, so *any* workflow running longer than 60 s let its lock expire and a second poller
+re-fired the same trigger. Raise `lockTtlMs` if your triggers are long and your journal is slow;
+lowering it makes a genuinely dead worker's fire reclaimable sooner.
+
+**Known limit — the fencing covers the state write, not the execution.** A `renew` that fails is
+logged and nothing else; `pollScheduler` does not abort the workflow it already started. So if the
+lock does expire anyway — a stalled or paused process, a clock jump, a journal outage that outlasts
+the TTL — a second poller can take the fire over and call `runner.runWorkflow` with the **same**
+`runId` while the first is still inside it. The CAS then discards the loser's state write, so the
+schedule stays correct; it does not undo what the loser's workflow did. This is measured, not
+theoretical: in `test/scheduler-lock-fence.test.ts` both pollers run `sched:<id>:<fireCount>`.
+
+What keeps that from becoming a duplicated side effect is the run, not the scheduler. Because both
+attempts share one `runId`, each workflow step reads its output from the journal first and only the
+first writer's result is kept (`claim`), so the two attempts converge on one recorded result — and a
+step built on `runDurable`/`durableTool` gets the real [at-most-once guarantee](../durable/README.md#what-never-charged-twice-actually-means). A plain step's body, however, still
+executes in both pollers. Read the guarantee as *"the schedule advances once and the journal records
+one result"*, not as *"two workers can never run the same job at the same time"*, and write steps that
+touch the outside world to be idempotent — the same rule `@gnldev/queue` and `@gnldev/events` state.
+
+### The fire lock is not the run's lock
+
+`<runId>:fire`, not `<runId>`, and the distinction is load-bearing. The two locks answer different
+questions — *"is another poller firing this occurrence?"* versus *"is this run executing anywhere?"* —
+and for a while they were the same key. That was invisible until a run started taking its own lock:
+under `preset: 'critical'`, `runWorkflow` locks `<runId>` too, so the poller was refusing its own run.
+Measured in production on a five-minute health trigger — five polls, five `RunBusyError`s, `status:
+'failed'`, and not one step ever executed. Nothing raced; it simply could not work. The two locks now
+nest instead of competing.
+
+One upgrade note: during a rolling deploy across this change, an old poller and a new one hold
+*different* fire-lock keys for the same occurrence, so both can start the fire. Under the `critical`
+preset the run's own lock refuses the second executor; without it, a side-effecting workflow can run
+once per poller in that window. If that matters to the workflow, drain the pollers over the upgrade.
+
+### A busy run is a deferral, not an attempt
+
+If `runWorkflow` refuses at lock acquisition (`RunBusyError` with `atLockAcquisition` — somebody else
+is already running this exact `runId`), the trigger is **deferred by `retryMs`**: `attempts` is not
+incremented, `status` stays `'pending'`, nothing is written to `sched:fail:<id>`, and `PollResult.skipped`
+counts it. Nothing was tried and nothing went wrong, so spending retry budget on it is how a busy
+minute turns into a permanently dead trigger.
+
+Deferrals are counted in `sched:busy-skip:<id>` and surfaced on `listTriggers()` as `deferrals` /
+`lastDeferralAt`, because a deferred trigger otherwise reads exactly like a healthy one. If that
+number climbs while `fireCount` does not, the trigger is being refused, not waiting. A **mid-flight**
+`RunBusyError` (this poller got in and was fenced out later) is still an ordinary failure — something
+did happen there.
+
+## Time is data
+
+A trigger's next fire time is **resolved and then frozen** into the journal, not recomputed on each
+poll. A worker that wakes up late fires the run it owed rather than silently skipping it, and a
+replay sees the same schedule the original run saw.
+
+## Exports
+
+| Export | What it is |
+|---|---|
+| `scheduleWorkflow` | Registers a cron / interval / `at` trigger |
+| `pollScheduler` | Fires whatever is due; call it from a loop or a cron container |
+| `listTriggers` | Everything currently registered |
+| `createScheduler` | The stateful wrapper, if you would rather hold an object than call functions |
+| `nextCronTime`, `parseField` | The cron arithmetic, exported for testing and for building your own UI |
+| `createWorkflowWaker` | Wakes a suspended workflow when its sleep or wait elapses |
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/cron.d.ts

@@ -0,0 +1,7 @@
+/** Converts a cron field into the set of allowed values within [min,max]. */
+export declare function parseField(field: string, min: number, max: number): Set<number>;
+/**
+ * Returns the first cron match (epoch ms, minute boundary) AFTER the `after` (epoch ms) time.
+ * 5 fields: minute hour day-of-month month day-of-week (0=Sunday). UTC. Minute-by-minute scan, 366-day cap.
+ */
+export declare function nextCronTime(expr: string, after: number): number;

package/dist/cron.js

@@ -0,0 +1,66 @@
+// Minimal 5-field cron (minute resolution, UTC). Supports '*', list ',', range '-', step '/'.
+// dom/dow POSIX OR semantics: if both are restricted, "day-of-month OR day-of-week"; if one is '*', the other decides.
+/** Converts a cron field into the set of allowed values within [min,max]. */
+export function parseField(field, min, max) {
+    const out = new Set();
+    for (const part of field.split(',')) {
+        const [rangeRaw, stepRaw] = part.split('/');
+        const step = stepRaw !== undefined ? parseInt(stepRaw, 10) : 1;
+        if (!Number.isFinite(step) || step < 1)
+            throw new Error(`cron: invalid step '${part}'`);
+        let lo;
+        let hi;
+        if (rangeRaw === '*' || rangeRaw === '') {
+            lo = min;
+            hi = max;
+        }
+        else if (rangeRaw.includes('-')) {
+            const [a, b] = rangeRaw.split('-').map((x) => parseInt(x, 10));
+            lo = a;
+            hi = b;
+        }
+        else {
+            lo = hi = parseInt(rangeRaw, 10);
+        }
+        if (!Number.isFinite(lo) || !Number.isFinite(hi) || lo < min || hi > max || lo > hi) {
+            throw new Error(`cron: invalid range '${part}' (expected ${min}-${max})`);
+        }
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+/**
+ * Returns the first cron match (epoch ms, minute boundary) AFTER the `after` (epoch ms) time.
+ * 5 fields: minute hour day-of-month month day-of-week (0=Sunday). UTC. Minute-by-minute scan, 366-day cap.
+ */
+export function nextCronTime(expr, after) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5)
+        throw new Error(`cron expects 5 fields (min hour day month weekday): '${expr}'`);
+    const min = parseField(fields[0], 0, 59);
+    const hour = parseField(fields[1], 0, 23);
+    const dom = parseField(fields[2], 1, 31);
+    const mon = parseField(fields[3], 1, 12);
+    const dow = parseField(fields[4], 0, 6);
+    const domRestricted = fields[2] !== '*';
+    const dowRestricted = fields[4] !== '*';
+    let t = Math.ceil((after + 1) / 60000) * 60000; // next minute boundary
+    const limit = 366 * 24 * 60;
+    for (let i = 0; i < limit; i++, t += 60000) {
+        const d = new Date(t);
+        if (!min.has(d.getUTCMinutes()))
+            continue;
+        if (!hour.has(d.getUTCHours()))
+            continue;
+        if (!mon.has(d.getUTCMonth() + 1))
+            continue;
+        const domOk = dom.has(d.getUTCDate());
+        const dowOk = dow.has(d.getUTCDay());
+        const dayOk = domRestricted && dowRestricted ? domOk || dowOk : domOk && dowOk;
+        if (dayOk)
+            return t;
+    }
+    throw new Error(`cron: no match within 1 year: '${expr}'`);
+}
+//# sourceMappingURL=cron.js.map

package/dist/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"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","sourcesContent":["// Minimal 5-field cron (minute resolution, UTC). Supports '*', list ',', range '-', step '/'.\n// dom/dow POSIX OR semantics: if both are restricted, \"day-of-month OR day-of-week\"; if one is '*', the other decides.\n\n/** Converts a cron field into the set of allowed values within [min,max]. */\nexport function parseField(field: string, min: number, max: number): Set<number> {\n  const out = new Set<number>();\n  for (const part of field.split(',')) {\n    const [rangeRaw, stepRaw] = part.split('/');\n    const step = stepRaw !== undefined ? parseInt(stepRaw, 10) : 1;\n    if (!Number.isFinite(step) || step < 1) throw new Error(`cron: invalid step '${part}'`);\n    let lo: number;\n    let hi: number;\n    if (rangeRaw === '*' || rangeRaw === '') {\n      lo = min;\n      hi = max;\n    } else if (rangeRaw.includes('-')) {\n      const [a, b] = rangeRaw.split('-').map((x) => parseInt(x, 10));\n      lo = a!;\n      hi = b!;\n    } else {\n      lo = hi = parseInt(rangeRaw, 10);\n    }\n    if (!Number.isFinite(lo) || !Number.isFinite(hi) || lo < min || hi > max || lo > hi) {\n      throw new Error(`cron: invalid range '${part}' (expected ${min}-${max})`);\n    }\n    for (let v = lo; v <= hi; v += step) out.add(v);\n  }\n  return out;\n}\n\n/**\n * Returns the first cron match (epoch ms, minute boundary) AFTER the `after` (epoch ms) time.\n * 5 fields: minute hour day-of-month month day-of-week (0=Sunday). UTC. Minute-by-minute scan, 366-day cap.\n */\nexport function nextCronTime(expr: string, after: number): number {\n  const fields = expr.trim().split(/\\s+/);\n  if (fields.length !== 5) throw new Error(`cron expects 5 fields (min hour day month weekday): '${expr}'`);\n  const min = parseField(fields[0]!, 0, 59);\n  const hour = parseField(fields[1]!, 0, 23);\n  const dom = parseField(fields[2]!, 1, 31);\n  const mon = parseField(fields[3]!, 1, 12);\n  const dow = parseField(fields[4]!, 0, 6);\n  const domRestricted = fields[2] !== '*';\n  const dowRestricted = fields[4] !== '*';\n\n  let t = Math.ceil((after + 1) / 60000) * 60000; // next minute boundary\n  const limit = 366 * 24 * 60;\n  for (let i = 0; i < limit; i++, t += 60000) {\n    const d = new Date(t);\n    if (!min.has(d.getUTCMinutes())) continue;\n    if (!hour.has(d.getUTCHours())) continue;\n    if (!mon.has(d.getUTCMonth() + 1)) continue;\n    const domOk = dom.has(d.getUTCDate());\n    const dowOk = dow.has(d.getUTCDay());\n    const dayOk = domRestricted && dowRestricted ? domOk || dowOk : domOk && dowOk;\n    if (dayOk) return t;\n  }\n  throw new Error(`cron: no match within 1 year: '${expr}'`);\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+import type { Journal } from '@gnldev/durable';
+export { nextCronTime, parseField } from './cron.js';
+export { createWorkflowWaker } from './workflow-waker.js';
+export type { WorkflowWaker, WorkflowWakerOptions, WorkflowWakerTickResult } from './workflow-waker.js';
+/** Structurally compatible with what createGnl returns — no hard dependency. */
+export interface WorkflowRunner {
+    runWorkflow(name: string, input: unknown, opts?: {
+        runId?: string;
+    }): Promise<{
+        runId: string;
+        suspended?: boolean;
+        output?: unknown;
+    }>;
+}
+export interface ScheduleSpec {
+    /** Trigger id (idempotent record; `name` is used if not given). */
+    id?: string;
+    /** Workflow name to run (passed to runner.runWorkflow). */
+    name: string;
+    input?: unknown;
+    /** Absolute time (epoch ms) — one-shot. */
+    at?: number;
+    /** Period (ms) — repeats every interval. */
+    every?: number;
+    /** 5-field cron (UTC, minute resolution) — repeats on every match. */
+    cron?: string;
+    /** Max attempts on failure (default 5). */
+    maxAttempts?: number;
+    /**
+     * Policy for missed (misfire) fires — only meaningful for every/cron:
+     * 'skip'    (default) — skip missed fires, jump to the next slot aligned to the planned grid (no drift accumulates).
+     * 'catchup' — fire each missed occurrence in sequence (one per poll), none are skipped.
+     */
+    misfire?: MisfirePolicy;
+}
+export type Kind = 'at' | 'every' | 'cron';
+export type MisfirePolicy = 'skip' | 'catchup';
+/**
+ * 1.4: optional budget/quota hook — called BEFORE the trigger starts (before runner.runWorkflow is
+ * CALLED). Throws on overage (typically `@gnldev/durable`'s `assertBudget` — `BudgetExceededError`);
+ * `pollScheduler` does NOT RUN this trigger (skip + records/logs to `sched:budget-skip:<id>`,
+ * `out.skipped` increments), state is DEFERRED to retry after `retryMs` but `attempts` DOES NOT
+ * increase (a budget overage isn't the workflow's fault → doesn't count toward maxAttempts, `status`
+ * stays 'pending'). IF NOT GIVEN (default) behavior is UNCHANGED — no quota check (backward compat).
+ * Typical host usage:
+ *   budgetGuard: () => assertBudget(journal, { orgId, fallback })
+ * Kept simple: the scheduler does NOT EMBED quota logic itself, the host injects it (same pattern as limits/guard).
+ */
+export type BudgetGuard = (ctx: {
+    triggerId: string;
+    workflowName: string;
+    input: unknown;
+    now: number;
+}) => Promise<unknown> | unknown;
+/** Schedules a workflow (at | every | cron). Idempotent: repeating with the same id = no-op. Returns the id. */
+export declare function scheduleWorkflow(journal: Journal, spec: ScheduleSpec, now?: number): Promise<string>;
+export interface PollResult {
+    fired: number;
+    rescheduled: number;
+    failed: number;
+    /**
+     * Triggers that were NOT RUN and are NOT a failure — the three deferral reasons, counted together
+     * because they mean the same thing to a caller ("nothing happened, come back later"):
+     *   - another poller holds the fire lock for this occurrence (no record; the lock IS the record),
+     *   - `budgetGuard` was given and threw on overage (`sched:budget-skip:<id>`),
+     *   - the run is already in flight elsewhere (`sched:busy-skip:<id>`).
+     * None of them consume an attempt. Without a guard and without contention this stays 0.
+     */
+    skipped: number;
+}
+/**
+ * Fires triggers that are due ('pending' && now≥nextRunAt). Double-firing is prevented via the run-lock;
+ * the real exactly-once guarantee comes from the durable workflow run (per-fireCount runId).
+ *
+ * Y2: the lock is kept alive by a heartbeat while the workflow runs (`lockTtlMs`, default 60s, renewed
+ * every ttl/3) — a long workflow no longer lets a second poller take the fire over. And EVERY state
+ * write is a CAS (`putIfMatch`) against the state read at the start of the fire, so even if a takeover
+ * does happen the late poller cannot write its stale result back.
+ */
+export declare function pollScheduler(journal: Journal, runner: WorkflowRunner, now?: number, opts?: {
+    owner?: string;
+    retryMs?: number;
+    budgetGuard?: BudgetGuard;
+    lockTtlMs?: number;
+}): Promise<PollResult>;
+/** Introspection view of a single trigger (for the Studio Scheduler view). */
+export interface TriggerInfo {
+    id: string;
+    name: string;
+    kind: Kind;
+    /** kind='at' → absolute time (epoch ms); kind='every' → period (ms); kind='cron' → 5-field cron expression. */
+    value: number | string;
+    input?: unknown;
+    /** Next (planned) fire time, epoch ms — if in the past, the trigger is due/overdue. */
+    nextRunAt: number;
+    attempts: number;
+    maxAttempts: number;
+    fireCount: number;
+    status: 'pending' | 'done' | 'failed';
+    misfire: MisfirePolicy;
+    /** Last error if status='failed' (if any, from `sched:fail:<id>`). */
+    lastError?: string;
+    lastErrorAt?: number;
+    /**
+     * How many times this trigger was DEFERRED because the run was already in flight elsewhere
+     * (`sched:busy-skip:<id>`, lifetime total). Absent when it has never happened.
+     *
+     * On this list a deferred trigger is otherwise indistinguishable from a healthy one — 'pending',
+     * with a nextRunAt in the near future, forever. That is the shape of a trigger that has not run in
+     * a week and looks fine, so the count is here rather than only in the journal. Compare it against
+     * `fireCount`: a number that keeps climbing while fireCount does not is a trigger that is being
+     * refused, not one that is waiting.
+     */
+    deferrals?: number;
+    lastDeferralAt?: number;
+}
+/**
+ * READ-ONLY trigger listing from the journal, WITHOUT needing a scheduler INSTANCE or a runner (for
+ * Studio introspection). Reads the SAME `sched:def:`/`sched:state:` keys (+ `sched:fail:` for 'failed')
+ * as `pollScheduler`; does NOT change any state, does not take a lock, does not run a workflow. Returns
+ * results sorted alphabetically by id (stable list order).
+ */
+export declare function listTriggers(journal: Journal): Promise<TriggerInfo[]>;
+export interface Scheduler {
+    poll(now?: number): Promise<PollResult>;
+    start(): void;
+    stop(): void;
+}
+/**
+ * Scheduler that manages the poll loop (a self-rescheduling setTimeout chain) — the same pattern as
+ * @gnldev/queue's createWorker. `backoff` (default OFF — timing is the scheduler's core contract, see the
+ * trade-off below): IF ENABLED, when a poll fires NO triggers at all (`fired === 0`) the next poll
+ * interval grows ×2 (cap: `maxPollMs ?? pollMs*32`) → prevents tens of thousands of empty queries per
+ * second (poll storm) on an empty schedule table; the interval resets to `pollMs` once a trigger fires.
+ * Trade-off: `backoff: true` cuts idle poll load by ~32x but can delay a trigger that becomes due after
+ * a quiet period by up to `maxPollMs` — for timing-critical use (e.g. minute-level cron) the default
+ * should stay OFF; only enable it for deployments with many idle-poller instances that can tolerate delay.
+ */
+export declare function createScheduler(journal: Journal, runner: WorkflowRunner, opts?: {
+    pollMs?: number;
+    owner?: string;
+    retryMs?: number;
+    backoff?: boolean;
+    maxPollMs?: number;
+    budgetGuard?: BudgetGuard;
+    lockTtlMs?: number;
+}): Scheduler;