@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.24

package/dist/schedules/calendar.js

@@ -0,0 +1,410 @@
+import { scanStep, tickerOf, ticksIn } from "./schedule-math.js";
+/**
+ * The scheduled task calendar (spec 2026-11-12-scheduled-tasks-calendar-design.md §5): recorded
+ * runs and planned occurrences between two instants, dense task-days collapsed, cut at a whole
+ * day when a limit is reached. The assembly here is pure; `ScheduledTasksService.calendar` reads
+ * the rows and decides who sees what.
+ */
+const DAY_MS = 86_400_000;
+/** Planned occurrences reach this far ahead of now (spec §5.2, "about six weeks"). */
+export const CALENDAR_HORIZON_DAYS = 42;
+/** The longest range one request may ask for: a 6-week month grid plus a DST hour (§5.1). */
+export const CALENDAR_RANGE_DAYS = 43;
+/** The longest range with `taskId` (the panel's one-day list, §5.4). */
+export const CALENDAR_TASK_RANGE_DAYS = 2;
+/** A task-day with more items than this is collapsed into one summary (§5.4). */
+export const CALENDAR_COLLAPSE_OVER = 6;
+/**
+ * Ticks taken per request after the first local day, across all tasks (§5.5). One tick costs
+ * about 150-340 µs (cron's `getNextDateFrom`, measured 2026-11-12 with a ticker built once per
+ * task), so 3,000 keeps a worst-case request near one second.
+ */
+export const CALENDAR_TICK_BUDGET = 3_000;
+/** Entries (`items` + `collapsed`) per request after the first local day (§5.5). */
+export const CALENDAR_ITEM_CAP = 3_000;
+/** Run rows read per request after the first local day (§5.5). */
+export const CALENDAR_RUN_ROW_CAP = 20_000;
+/**
+ * The first requested local day is always returned whole, outside the limits above; only these
+ * safety caps stop it (then nothing is returned, `truncated`, `horizon` = `from`).
+ */
+export const CALENDAR_FIRST_DAY_TICK_CAP = 10_000;
+export const CALENDAR_FIRST_DAY_RUN_CAP = 20_000;
+export const CALENDAR_LIMITS = {
+    horizonDays: CALENDAR_HORIZON_DAYS,
+    collapseOver: CALENDAR_COLLAPSE_OVER,
+    tickBudget: CALENDAR_TICK_BUDGET,
+    itemCap: CALENDAR_ITEM_CAP,
+    runRowCap: CALENDAR_RUN_ROW_CAP,
+    firstDayTickCap: CALENDAR_FIRST_DAY_TICK_CAP,
+    firstDayRunCap: CALENDAR_FIRST_DAY_RUN_CAP,
+};
+/** How many run rows the service reads: enough to tell where either run cap cuts. */
+export const calendarRunReadLimit = (limits) => limits.firstDayRunCap + limits.runRowCap + 1;
+/** The calendar answer from the rows (spec §5.2–§5.5). */
+export function assembleCalendar(input, limits = CALENDAR_LIMITS) {
+    const { timeZone, now } = input;
+    const horizonAt = now.getTime() + limits.horizonDays * DAY_MS;
+    const fromMs = input.from.getTime();
+    // `cut`: the exclusive end of what is returned; a limit moves it back to a local day start, and
+    // only a first-day safety cap moves it to `from` (nothing returned)
+    let cut = input.to.getTime();
+    let truncated = false;
+    // the first requested local day is returned whole, outside the budget and the caps
+    const firstDay = dayKey(fromMs, timeZone);
+    const firstDayEnd = Math.min(cut, startOfLocalDay(startOfLocalDay(fromMs, timeZone) + 26 * 3_600_000, timeZone));
+    // the run read is bounded too: past a cap, the range ends at the start of the local day of the
+    // first row over it
+    const firstDayRuns = input.runs.filter((r) => r.scheduledFor.getTime() < firstDayEnd).length;
+    const overRun = input.runs[firstDayRuns + limits.runRowCap];
+    if (firstDayRuns > limits.firstDayRunCap) {
+        cut = fromMs;
+        truncated = true;
+    }
+    else if (overRun !== undefined) {
+        cut = startOfLocalDay(overRun.scheduledFor.getTime(), timeZone);
+        truncated = true;
+    }
+    const planned = input.plan && cut > fromMs
+        ? planOccurrences(input, horizonAt, limits, firstDayEnd, cut)
+        : { ticks: new Map(), cut };
+    if (planned.cut < cut) {
+        cut = planned.cut;
+        truncated = true;
+    }
+    // a tick the scan recorded is shown as its run, never twice
+    const recorded = new Set(input.runs.filter((r) => !r.trial).map((r) => `${r.taskId}|${r.scheduledFor.getTime()}`));
+    const byId = new Map(input.tasks.map((t) => [t.id, t]));
+    const raw = [];
+    for (const r of input.runs) {
+        const own = byId.get(r.taskId)?.accountId === input.viewerAccountId;
+        raw.push({ at: r.scheduledFor.getTime(), taskId: r.taskId, item: runItem(r, own) });
+    }
+    for (const [taskId, ticks] of planned.ticks) {
+        const jitterMs = (byId.get(taskId)?.jitterSeconds ?? 0) * 1000;
+        for (const tick of ticks) {
+            if (recorded.has(`${taskId}|${tick}`))
+                continue;
+            raw.push({
+                at: tick,
+                taskId,
+                item: {
+                    kind: "occurrence",
+                    taskId,
+                    scheduledFor: new Date(tick).toISOString(),
+                    at: new Date(tick + jitterMs).toISOString(),
+                },
+            });
+        }
+    }
+    // group by local day, then by task: a task-day over the threshold becomes one summary
+    const days = new Map();
+    for (const e of raw) {
+        if (e.at >= cut)
+            continue;
+        const day = dayKey(e.at, timeZone);
+        let tasks = days.get(day);
+        if (!tasks) {
+            tasks = new Map();
+            days.set(day, tasks);
+        }
+        const list = tasks.get(e.taskId);
+        if (list)
+            list.push(e);
+        else
+            tasks.set(e.taskId, [e]);
+    }
+    // walk the days in order; a day is added whole or not at all
+    const entries = [];
+    // the first day's entries do not count against the cap (the day is always returned whole)
+    let counted = 0;
+    for (const day of [...days.keys()].sort()) {
+        const dayEntries = [];
+        for (const [taskId, list] of days.get(day) ?? []) {
+            if (input.collapse && list.length > limits.collapseOver) {
+                dayEntries.push({
+                    kind: "collapsed",
+                    at: firstAt(list),
+                    taskId,
+                    collapsed: summarize(taskId, day, list),
+                });
+            }
+            else {
+                for (const e of list)
+                    dayEntries.push({ kind: "item", ...e });
+            }
+        }
+        if (day !== firstDay && counted + dayEntries.length > limits.itemCap) {
+            const start = startOfLocalDay(dayEntries[0]?.at ?? cut, timeZone);
+            if (start < cut) {
+                cut = start;
+                truncated = true;
+            }
+            break;
+        }
+        entries.push(...dayEntries);
+        if (day !== firstDay)
+            counted += dayEntries.length;
+    }
+    const kept = entries.filter((e) => e.at < cut);
+    kept.sort((a, b) => a.at - b.at || cmp(a.taskId, b.taskId) || cmp(entryKey(a), entryKey(b)));
+    const items = [];
+    const collapsed = [];
+    const named = new Set();
+    for (const e of kept) {
+        named.add(e.taskId);
+        if (e.kind === "item")
+            items.push(e.item);
+        else
+            collapsed.push(e.collapsed);
+    }
+    return {
+        tasks: input.tasks.filter((t) => named.has(t.id)).map(calendarTask),
+        items,
+        collapsed,
+        horizon: new Date(Math.max(fromMs, truncated ? Math.min(cut, horizonAt) : horizonAt)).toISOString(),
+        truncated,
+    };
+}
+/** The stream's next tick, or null when it has no more (or its trigger cannot be evaluated). */
+function pull(s) {
+    if (s.after >= s.until)
+        return null;
+    try {
+        const tick = ticksIn(s.ticker, new Date(s.after), new Date(s.until), 1).ticks[0];
+        s.after = tick === undefined ? Number.POSITIVE_INFINITY : tick.getTime();
+        return tick === undefined ? null : s.after;
+    }
+    catch {
+        // a trigger the math cannot evaluate: the scanner pauses the task; nothing to plan
+        s.after = Number.POSITIVE_INFINITY;
+        return null;
+    }
+}
+/**
+ * Each active task's planned ticks in `[from, min(to, horizon, expires_at)]` (spec §5.2), from the
+ * scanner's own math: a task already due (`next_run_at <= now`, not scanned yet) keeps only the
+ * tick the scan will fire (the latest due one inside the catch-up window; the older ones become
+ * one `missed` run), then the ticks after it as the scan continues; a task not due starts at its
+ * due tick, `next_run_at - jitter`.
+ *
+ * The tasks' ticks are taken in time order across all tasks (a merge), each one tick evaluation
+ * on the task's ticker (built once). Ticks of the first local day count against the first day's
+ * safety cap only (past it, nothing is returned: the cut moves to `from`); the first later tick
+ * past the budget cuts the range at the start of its local day, and the ticks already taken on
+ * that day are dropped, so the days before the cut are whole (spec §5.5). The counts are ticks
+ * taken: each stream's lookahead past its `until` and `scanStep`'s doubling search for a task
+ * already due are not counted (at most about 2 × tasks evaluations more).
+ */
+function planOccurrences(input, horizonAt, limits, firstDayEnd, end) {
+    const fromMs = input.from.getTime();
+    const ticks = new Map();
+    const heap = new TickHeap();
+    for (const task of input.tasks) {
+        if (task.status !== "active" || task.nextRunAt === null)
+            continue;
+        const jitterMs = task.jitterSeconds * 1000;
+        const until = Math.min(end - 1, horizonAt, task.expiresAt?.getTime() ?? Number.POSITIVE_INFINITY);
+        if (until < fromMs)
+            continue;
+        let after = task.nextRunAt.getTime() - jitterMs - 1;
+        let first = null;
+        if (task.nextRunAt.getTime() <= input.now.getTime()) {
+            let step;
+            try {
+                step = scanStep({
+                    trigger: task.trigger,
+                    nextRunAt: task.nextRunAt,
+                    jitterSeconds: task.jitterSeconds,
+                    expiresAt: task.expiresAt,
+                }, input.now, input.catchUpWindowMinutes);
+            }
+            catch {
+                continue;
+            }
+            const fire = step.fire?.getTime();
+            if (fire !== undefined && fire >= fromMs && fire <= until)
+                first = fire;
+            after =
+                step.nextRunAt === null
+                    ? Number.POSITIVE_INFINITY
+                    : step.nextRunAt.getTime() - jitterMs - 1;
+        }
+        let ticker;
+        try {
+            ticker = tickerOf(task.trigger);
+        }
+        catch {
+            continue;
+        }
+        const stream = { task, ticker, until, after: Math.max(after, fromMs - 1) };
+        const head = first ?? pull(stream);
+        if (head === null)
+            continue;
+        ticks.set(task.id, []);
+        heap.push({ at: head, stream });
+    }
+    let cut = end;
+    // the first local day has its own safety cap; the budget counts the days after it
+    let used = 0;
+    let firstDayUsed = 0;
+    for (let top = heap.pop(); top !== undefined; top = heap.pop()) {
+        if (top.at < firstDayEnd) {
+            if (firstDayUsed >= limits.firstDayTickCap) {
+                cut = fromMs;
+                break;
+            }
+            firstDayUsed++;
+        }
+        else {
+            if (used >= limits.tickBudget) {
+                cut = startOfLocalDay(top.at, input.timeZone);
+                break;
+            }
+            used++;
+        }
+        ticks.get(top.stream.task.id)?.push(top.at);
+        const next = pull(top.stream);
+        if (next !== null)
+            heap.push({ at: next, stream: top.stream });
+    }
+    if (cut < end) {
+        for (const [id, list] of ticks)
+            ticks.set(id, list.filter((t) => t < cut));
+    }
+    return { ticks, cut };
+}
+/** A binary min-heap of stream heads by tick, then task id (a stable order). */
+class TickHeap {
+    a = [];
+    less(i, j) {
+        const x = this.a[i];
+        const y = this.a[j];
+        return x.at < y.at || (x.at === y.at && x.stream.task.id < y.stream.task.id);
+    }
+    swap(i, j) {
+        const t = this.a[i];
+        this.a[i] = this.a[j];
+        this.a[j] = t;
+    }
+    push(e) {
+        this.a.push(e);
+        for (let i = this.a.length - 1; i > 0;) {
+            const p = (i - 1) >> 1;
+            if (!this.less(i, p))
+                break;
+            this.swap(i, p);
+            i = p;
+        }
+    }
+    pop() {
+        const top = this.a[0];
+        const last = this.a.pop();
+        if (top === undefined || last === undefined || this.a.length === 0)
+            return top;
+        this.a[0] = last;
+        for (let i = 0;;) {
+            const l = 2 * i + 1;
+            const r = l + 1;
+            let m = i;
+            if (l < this.a.length && this.less(l, m))
+                m = l;
+            if (r < this.a.length && this.less(r, m))
+                m = r;
+            if (m === i)
+                break;
+            this.swap(i, m);
+            i = m;
+        }
+        return top;
+    }
+}
+function runItem(r, own) {
+    return {
+        kind: "run",
+        taskId: r.taskId,
+        id: r.id,
+        scheduledFor: r.scheduledFor.toISOString(),
+        firedAt: r.firedAt?.toISOString() ?? null,
+        status: r.status,
+        skipReason: r.skipReason,
+        trial: r.trial,
+        manual: r.manual,
+        conversationId: own ? r.conversationId : null,
+        error: own ? r.error : null,
+        missingGrants: own ? r.missingGrants.length : null,
+    };
+}
+function summarize(taskId, day, list) {
+    const c = {
+        taskId,
+        day,
+        count: list.length,
+        upcoming: 0,
+        running: 0,
+        completed: 0,
+        failed: 0,
+        skipped: 0,
+        first: new Date(firstAt(list)).toISOString(),
+        last: new Date(Math.max(...list.map((e) => e.at))).toISOString(),
+    };
+    for (const { item } of list) {
+        if (item.kind === "occurrence")
+            c.upcoming++;
+        else if (item.status === "pending" || item.status === "running")
+            c.running++;
+        else
+            c[item.status]++;
+    }
+    return c;
+}
+function calendarTask(t) {
+    return {
+        id: t.id,
+        name: t.name,
+        agentId: t.agentId,
+        accountId: t.accountId,
+        status: t.status,
+        pauseReason: t.pauseReason,
+        trigger: t.trigger,
+        mode: t.mode,
+        jitterSeconds: t.jitterSeconds,
+        nextRunAt: t.nextRunAt?.toISOString() ?? null,
+    };
+}
+const firstAt = (list) => Math.min(...list.map((e) => e.at));
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const entryKey = (e) => e.kind === "collapsed" ? "~" : e.item.kind === "run" ? `r${e.item.id}` : "o";
+const dayFormats = new Map();
+/** YYYY-MM-DD of the instant (epoch ms) in `timeZone`. */
+export function dayKey(ms, timeZone) {
+    let f = dayFormats.get(timeZone);
+    if (!f) {
+        f = new Intl.DateTimeFormat("en-CA", {
+            timeZone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+        });
+        dayFormats.set(timeZone, f);
+    }
+    const p = Object.fromEntries(f.formatToParts(new Date(ms)).map((x) => [x.type, x.value]));
+    return `${p.year}-${p.month}-${p.day}`;
+}
+/**
+ * The first instant (epoch ms) of the local day of `ms` in `timeZone`: midnight, or the end of a
+ * DST gap that swallows it. A day is at most 25 hours long, so 27 hours back is an earlier day.
+ */
+export function startOfLocalDay(ms, timeZone) {
+    const day = dayKey(ms, timeZone);
+    let lo = ms - 27 * 3_600_000;
+    let hi = ms;
+    while (lo < hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        if (dayKey(mid, timeZone) < day)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}

package/dist/schedules/fire.d.ts

@@ -9,7 +9,6 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { LockService } from "../infra/lock/lock.service.js";
 import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
-import { RunControl } from "../runtime/run-control.js";
 import { ScheduledTaskRunTracker } from "./run-tracker.js";
 import { ScheduledTaskStore } from "./store.js";
 /** A task run's message client id in a conversation's queue (never read back as "the task's"). */
@@ -49,11 +48,10 @@ export declare class ScheduledTaskFirer {
     private readonly conversations;
     private readonly queue;
     private readonly connections;
-    private readonly runs;
     /** Reads a local device's connection lease (online or not). */
     private readonly locks;
     private readonly log;
-    constructor(kdb: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, store: ScheduledTaskStore, tracker: Pick<ScheduledTaskRunTracker, "inFlightIn" | "failStartIn">, orgLock: Pick<OrgLock, "tryLock">, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, conversations: Pick<ConversationsService, "createWithMessage" | "create">, queue: Pick<ConversationQueue, "add">, connections: Pick<ChannelConnections, "row" | "channel">, runs: Pick<RunControl, "ensureRun">, 
+    constructor(kdb: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, store: ScheduledTaskStore, tracker: Pick<ScheduledTaskRunTracker, "inFlightIn" | "failStartIn">, orgLock: Pick<OrgLock, "tryLock">, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, conversations: Pick<ConversationsService, "createWithMessage" | "create">, queue: Pick<ConversationQueue, "add">, connections: Pick<ChannelConnections, "row" | "channel">, 
     /** Reads a local device's connection lease (online or not). */
     locks: Pick<LockService, "holderOf">, log: Pick<KernelLogger, "warn" | "info">);
     private get db();

package/dist/schedules/fire.js

@@ -27,7 +27,6 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { deviceLeaseKey } from "../local-devices/keys.js";
 import { OrgLock, OrgLockModule } from "../orgs/org-lock.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
-import { RunControl } from "../runtime/run-control.js";
 import { RuntimeModule } from "../runtime/runtime.module.js";
 import { readScheduleSettings } from "./effective-settings.js";
 import { pauseTaskIn } from "./pause.js";
@@ -97,10 +96,9 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
     conversations;
     queue;
     connections;
-    runs;
     locks;
     log;
-    constructor(kdb, txHost, config, store, tracker, orgLock, agents, access, conversations, queue, connections, runs, 
+    constructor(kdb, txHost, config, store, tracker, orgLock, agents, access, conversations, queue, connections, 
     /** Reads a local device's connection lease (online or not). */
     locks, log) {
         this.kdb = kdb;
@@ -114,7 +112,6 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
         this.conversations = conversations;
         this.queue = queue;
         this.connections = connections;
-        this.runs = runs;
         this.locks = locks;
         this.log = log;
     }
@@ -286,10 +283,9 @@ let ScheduledTaskFirer = class ScheduledTaskFirer {
                     ...(task.effort !== null && { effort: task.effort }),
                 };
                 const out = await this.conversations.createWithMessage(task.orgId, task.accountId, task.agentId, { text: task.prompt, clientMessageId: run.id, ...pick }, task.deviceId === null ? {} : { deviceId: task.deviceId }, internal);
+                // a retried start found the conversation made before: `createWithMessage` already asked
+                // for its run (and the first start's message owes the ensure-run backstop)
                 await this.setConversation(run.id, out.conversation.id);
-                // a retried start found the conversation made before: its run may be still to start
-                if (!out.created)
-                    await this.runs.ensureRun(out.conversation.id);
                 return;
             }
             let conversationId;
@@ -593,9 +589,8 @@ ScheduledTaskFirer = __decorate([
     __param(8, Inject(ConversationsService)),
     __param(9, Inject(ConversationQueue)),
     __param(10, Inject(ChannelConnections)),
-    __param(11, Inject(RunControl)),
-    __param(12, Inject(LockService)),
-    __param(13, Inject(KERNEL_LOGGER))
+    __param(11, Inject(LockService)),
+    __param(12, Inject(KERNEL_LOGGER))
 ], ScheduledTaskFirer);
 export { ScheduledTaskFirer };
 /**

package/dist/schedules/run-tracker.d.ts

@@ -59,11 +59,6 @@ export declare class ScheduledTaskRunTracker {
  * sub-agent or wake run inheriting the marker) is left alone.
  */
 export declare function linkStartedRunIn(t: KernelSchemaDb, taskRunId: string, runId: string, conversationId: string): Promise<void>;
-/**
- * A queued run row was taken back before it ran (`RunQueue.deleteQueued`: its job could not be
- * enqueued): the task run it had taken waits for the next run of its message again.
- */
-export declare function unlinkRunIn(t: KernelSchemaDb, taskRunId: string, runId: string): Promise<void>;
 /**
  * A person removed, edited or sent the queued item that carried `schedule` (the item's stored
  * marker, or null): its task run will never run as the task's, so it becomes `skipped`

package/dist/schedules/run-tracker.js

@@ -281,19 +281,6 @@ export async function linkStartedRunIn(t, taskRunId, runId, conversationId) {
         .where("run_id", "is", null)
         .execute();
 }
-/**
- * A queued run row was taken back before it ran (`RunQueue.deleteQueued`: its job could not be
- * enqueued): the task run it had taken waits for the next run of its message again.
- */
-export async function unlinkRunIn(t, taskRunId, runId) {
-    await t
-        .updateTable("scheduled_task_runs")
-        .set({ status: "pending", run_id: null })
-        .where("id", "=", taskRunId)
-        .where("run_id", "=", runId)
-        .where("status", "=", "running")
-        .execute();
-}
 /**
  * A person removed, edited or sent the queued item that carried `schedule` (the item's stored
  * marker, or null): its task run will never run as the task's, so it becomes `skipped`

package/dist/schedules/scan.job.js

@@ -24,7 +24,7 @@ import { readScheduleSettings } from "./effective-settings.js";
 import { SCHED_SCAN_JOB, schedFireJob } from "./job-ids.js";
 import { pauseTaskIn } from "./pause.js";
 import { lockTaskRow, ScheduledTaskRunTracker } from "./run-tracker.js";
-import { dueTicks, nextTick } from "./schedule-math.js";
+import { scanStep } from "./schedule-math.js";
 import { ScheduledTaskStore } from "./store.js";
 /** Due tasks per scan; what is left waits for the next minute. */
 const MAX_TASKS = 2000;
@@ -145,51 +145,46 @@ let ScheduledTaskScanJob = class ScheduledTaskScanJob {
     }
     /** One due task (see the class); returns the id of the run to fire, if any. */
     async advance(t, task, now, catchUpWindowMinutes) {
-        const jitterMs = task.jitterSeconds * 1000;
-        // ticks are before jitter: the due tick is next_run_at - jitter, and a tick is due once
-        // tick + jitter <= now
-        const dueTick = new Date(task.nextRunAt.getTime() - jitterMs);
-        const until = new Date(now.getTime() - jitterMs);
         // the schedule math alone may mark the task broken; database errors fail this pass only
-        let ticks;
-        let next;
+        let step;
         try {
-            ticks = dueTicks(task.trigger, new Date(dueTick.getTime() - 1), until, catchUpWindowMinutes);
-            next = nextTick(task.trigger, until);
+            step = scanStep({
+                trigger: task.trigger,
+                nextRunAt: task.nextRunAt,
+                jitterSeconds: task.jitterSeconds,
+                expiresAt: task.expiresAt,
+            }, now, catchUpWindowMinutes);
         }
         catch (err) {
             throw new TaskScanFailed(task.id, err);
         }
-        const expires = task.expiresAt?.getTime() ?? Number.POSITIVE_INFINITY;
-        const fireAt = ticks.fire !== null && ticks.fire.getTime() <= expires ? ticks.fire : null;
-        const first = ticks.firstMissed;
-        if (first !== null && first.getTime() <= expires) {
+        if (step.missed !== null) {
             await this.store.insertRun(t, {
                 id: randomUUID(),
                 taskId: task.id,
                 orgId: task.orgId,
-                scheduledFor: first,
+                scheduledFor: step.missed,
                 trial: false,
                 status: "skipped",
                 skipReason: "missed",
             });
         }
         let fired = null;
-        if (fireAt !== null) {
+        if (step.fire !== null) {
             const run = await this.store.insertRun(t, {
                 id: randomUUID(),
                 taskId: task.id,
                 orgId: task.orgId,
-                scheduledFor: fireAt,
+                scheduledFor: step.fire,
                 trial: false,
             });
             fired = run?.id ?? null;
         }
-        const patch = next === null
+        const patch = step.end === "done"
             ? { status: "ended", nextRunAt: null }
-            : next.getTime() > expires
+            : step.end === "expired"
                 ? { status: "ended", pauseReason: "expired", nextRunAt: null }
-                : { nextRunAt: new Date(next.getTime() + jitterMs) };
+                : { nextRunAt: step.nextRunAt };
         await this.store.updateTask(t, task.id, patch);
         return fired;
     }

package/dist/schedules/schedule-math.d.ts

@@ -8,6 +8,48 @@ export declare function validateTrigger(t: ScheduleTrigger, now: Date): {
 };
 /** The first tick strictly after `after` (before jitter); null for a past once task. */
 export declare function nextTick(t: ScheduleTrigger, after: Date): Date | null;
+/** The first tick strictly after `after` (before jitter) of one trigger; null when none. */
+export type Ticker = (after: Date) => Date | null;
+/**
+ * The scanner's ticker for one trigger ({@link nextTick} without rebuilding its `CronTime`s per
+ * call), for callers that walk the same trigger many times ({@link ticksIn}).
+ */
+export declare function tickerOf(t: ScheduleTrigger): Ticker;
+/**
+ * The ticks in `(after, until]` (before jitter), at most `max`, from the same ticker
+ * {@link nextTick} and {@link dueTicks} use, so a list of planned runs equals what the scanner
+ * fires (calendar spec §5.2). `exhausted`: `max` ticks were taken before a tick past `until` was
+ * seen, so more may follow. A `once` trigger yields its one tick when it lies in the window.
+ * Costs one tick evaluation per tick returned, plus one when the walk reaches `until`. A caller
+ * that walks one trigger in many windows passes a {@link tickerOf} it built once.
+ */
+export declare function ticksIn(t: ScheduleTrigger | Ticker, after: Date, until: Date, max: number): {
+    ticks: Date[];
+    exhausted: boolean;
+};
+/** What one scan does to a due task (spec §6 step 1), as {@link scanStep} decides it. */
+export interface ScanStep {
+    /** The first missed tick, recorded as one skipped run (`missed`); null when none. */
+    missed: Date | null;
+    /** The tick whose run is recorded and fired; null when none. */
+    fire: Date | null;
+    /** The task's new `next_run_at` (jitter included); null when it ends. */
+    nextRunAt: Date | null;
+    /** Why the task ends: no tick left (`done`) or the next one lies past `expires_at`. */
+    end: "done" | "expired" | null;
+}
+/**
+ * One scan of a due task (`next_run_at <= now`) as of `now`, the schedule math alone: the ticks
+ * are before jitter, so the due tick is `nextRunAt - jitter` and a tick is due once
+ * `tick + jitter <= now`. The scanner applies the result; the calendar's parity test drives it.
+ * Throws when the trigger cannot be evaluated.
+ */
+export declare function scanStep(task: {
+    trigger: ScheduleTrigger;
+    nextRunAt: Date;
+    jitterSeconds: number;
+    expiresAt: Date | null;
+}, now: Date, catchUpWindowMinutes: number): ScanStep;
 /** The smallest gap, in minutes, among the next 50 fire times after `from`; null for once. */
 export declare function minGapMinutes(t: ScheduleTrigger, from: Date): number | null;
 /** A fixed per-task offset: `fnv1a32(id) mod min(floor(10 % of the interval), 300 s)`; once is 0. */