@namzu/sdk 44.3.0 → 45.1.0

package/src/schedules/index.ts

@@ -0,0 +1,18 @@
+export { parseCronExpression } from './cron.js'
+export { describeSchedule } from './describe.js'
+export type { DescribeScheduleOptions } from './describe.js'
+export { ScheduleValidationError } from './errors.js'
+export {
+	SCHEDULE_CATCH_UP_WINDOW_MS,
+	SCHEDULE_LATE_GRACE_MS,
+	evaluateJob,
+} from './evaluate.js'
+export {
+	countOccurrences,
+	nextFireTime,
+	previousFireTime,
+} from './next-fire.js'
+export { parseDuration, parseScheduleSpec, upcomingFireTimes } from './spec.js'
+export type { ParseScheduleOptions } from './spec.js'
+export { hostTimeZone, validateTimeZone } from './tz.js'
+export type * from './types.js'

package/src/schedules/next-fire.ts

@@ -0,0 +1,257 @@
+/**
+ * When a spec fires: the next instant, the previous one, and how many fall
+ * in a window.
+ *
+ * Cron is walked a local DAY at a time — never a minute at a time over years
+ * — and a day with no DST change is computed arithmetically from one offset.
+ * Only a day whose offset changes is examined slot by slot, and that is where
+ * cronie's rule is applied:
+ *
+ * - a fixed-time expression (`30 2 * * *`) whose time falls in a
+ *   spring-forward gap fires once, at the first instant after the gap;
+ *   whose time is repeated by a fall-back fires once, at the first of the two;
+ * - a wildcard or step expression (`0 * * * *`, `*\/15 * * * *`) fires at
+ *   every instant whose wall time matches: the repeated hour runs twice and
+ *   slots inside the gap do not exist.
+ */
+
+import { cronMatchesDay, parseCronExpression } from './cron.js'
+import { ScheduleValidationError } from './errors.js'
+import type { CronExpression, OccurrenceCount, ScheduleSpec } from './types.js'
+import { civil, firstInstantAfterGap, instantsForWall, offsetAt, validateTimeZone } from './tz.js'
+
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+/** How far ahead a cron search looks before deciding the expression never fires. */
+export const CRON_HORIZON_DAYS = 366 * 5 + 2
+/**
+ * Occurrence counts stop here. Counting a day without a DST change costs one
+ * multiplication, so the cap bounds the pathological case (a years-long gap
+ * on a per-minute job) rather than the ordinary one.
+ */
+export const OCCURRENCE_COUNT_CAP = 100_000
+
+const parsedCache = new Map<string, CronExpression>()
+
+function cronOf(expr: string): CronExpression {
+	let parsed = parsedCache.get(expr)
+	if (!parsed) {
+		parsed = parseCronExpression(expr)
+		if (parsedCache.size > 256) parsedCache.clear()
+		parsedCache.set(expr, parsed)
+	}
+	return parsed
+}
+
+/** The local-midnight wall value of the day containing `wall`. */
+function dayStart(wall: number): number {
+	return Math.floor(wall / DAY) * DAY
+}
+
+/**
+ * Every instant the expression fires on one local day (`dayWall` is that
+ * day's midnight as a wall value), ascending.
+ */
+export function cronInstantsOnDay(expr: CronExpression, tz: string, dayWall: number): number[] {
+	const c = civil(dayWall)
+	if (!cronMatchesDay(expr, c.month, c.day, c.weekday)) return []
+	const before = offsetAt(dayWall - 14 * HOUR, tz)
+	const after = offsetAt(dayWall + DAY + 14 * HOUR, tz)
+	const out: number[] = []
+	if (before === after) {
+		for (const h of expr.hours)
+			for (const m of expr.minutes) out.push(dayWall + h * HOUR + m * MINUTE - before)
+		return out
+	}
+	// A day the offset changes on (or next to): slot by slot.
+	const seen = new Set<number>()
+	for (const h of expr.hours) {
+		for (const m of expr.minutes) {
+			const wall = dayWall + h * HOUR + m * MINUTE
+			const instants = instantsForWall(wall, tz)
+			if (instants.length === 0) {
+				if (expr.fixedTime) {
+					const shifted = firstInstantAfterGap(wall, tz)
+					if (!seen.has(shifted)) {
+						seen.add(shifted)
+						out.push(shifted)
+					}
+				}
+				continue
+			}
+			const chosen = expr.fixedTime ? instants.slice(0, 1) : instants
+			for (const t of chosen) {
+				if (seen.has(t)) continue
+				seen.add(t)
+				out.push(t)
+			}
+		}
+	}
+	return out.sort((a, b) => a - b)
+}
+
+function validEvery(spec: { everyMs: number; anchorAt: string }): number {
+	const anchor = Date.parse(spec.anchorAt)
+	if (!Number.isFinite(anchor)) {
+		throw new ScheduleValidationError(`anchor "${spec.anchorAt}" is not a date`, spec.anchorAt)
+	}
+	if (!Number.isSafeInteger(spec.everyMs) || spec.everyMs < MINUTE || spec.everyMs % MINUTE !== 0) {
+		throw new ScheduleValidationError(
+			'an interval must be a whole number of minutes, at least one',
+			String(spec.everyMs),
+		)
+	}
+	return anchor
+}
+
+/**
+ * The first instant strictly after `afterExclusive` at which `spec` fires,
+ * or `null` when there is none (a past `at`, or a cron expression with no
+ * occurrence in the next five years).
+ */
+export function nextFireTime(spec: ScheduleSpec, afterExclusive: Date): Date | null {
+	const after = afterExclusive.getTime()
+	switch (spec.kind) {
+		case 'at': {
+			const at = Date.parse(spec.at)
+			return Number.isFinite(at) && at > after ? new Date(at) : null
+		}
+		case 'every': {
+			const anchor = validEvery(spec)
+			const k = after < anchor ? 1 : Math.floor((after - anchor) / spec.everyMs) + 1
+			return new Date(anchor + Math.max(1, k) * spec.everyMs)
+		}
+		case 'cron': {
+			const expr = cronOf(spec.expr)
+			const tz = spec.tz
+			// A day early: a gap-shifted or offset-crossing instant of the
+			// previous local day can still lie after `after`.
+			let day = dayStart(after + offsetAt(after, tz)) - DAY
+			for (let i = 0; i <= CRON_HORIZON_DAYS; i++, day += DAY) {
+				for (const t of cronInstantsOnDay(expr, tz, day)) if (t > after) return new Date(t)
+			}
+			return null
+		}
+	}
+}
+
+/**
+ * The last instant at or before `atOrBefore` at which `spec` fired, or
+ * `null` if none within the horizon (or before the anchor / the `at`).
+ */
+export function previousFireTime(spec: ScheduleSpec, atOrBefore: Date): Date | null {
+	const before = atOrBefore.getTime()
+	switch (spec.kind) {
+		case 'at': {
+			const at = Date.parse(spec.at)
+			return Number.isFinite(at) && at <= before ? new Date(at) : null
+		}
+		case 'every': {
+			const anchor = validEvery(spec)
+			const k = Math.floor((before - anchor) / spec.everyMs)
+			return k >= 1 ? new Date(anchor + k * spec.everyMs) : null
+		}
+		case 'cron': {
+			const expr = cronOf(spec.expr)
+			const tz = spec.tz
+			let day = dayStart(before + offsetAt(before, tz)) + DAY
+			for (let i = 0; i <= CRON_HORIZON_DAYS; i++, day -= DAY) {
+				const instants = cronInstantsOnDay(expr, tz, day)
+				for (let j = instants.length - 1; j >= 0; j--) {
+					const t = instants[j] as number
+					if (t <= before) return new Date(t)
+				}
+			}
+			return null
+		}
+	}
+}
+
+/**
+ * How many times `spec` fires in `(fromExclusive, toInclusive]`, with the
+ * first and latest of them. Stops counting at `cap` (default 100 000) and
+ * says so, without enumerating beyond it; the latest is exact either way.
+ */
+export function countOccurrences(
+	spec: ScheduleSpec,
+	fromExclusive: Date,
+	toInclusive: Date,
+	cap: number = OCCURRENCE_COUNT_CAP,
+): OccurrenceCount {
+	const from = fromExclusive.getTime()
+	const to = toInclusive.getTime()
+	if (to <= from) return { count: 0, capped: false }
+	switch (spec.kind) {
+		case 'at': {
+			const at = Date.parse(spec.at)
+			return at > from && at <= to
+				? { count: 1, capped: false, first: new Date(at), latest: new Date(at) }
+				: { count: 0, capped: false }
+		}
+		case 'every': {
+			const anchor = validEvery(spec)
+			const firstK = from < anchor ? 1 : Math.floor((from - anchor) / spec.everyMs) + 1
+			const lastK = Math.floor((to - anchor) / spec.everyMs)
+			if (lastK < Math.max(1, firstK)) return { count: 0, capped: false }
+			const k0 = Math.max(1, firstK)
+			const total = lastK - k0 + 1
+			return {
+				count: Math.min(total, cap),
+				capped: total > cap,
+				first: new Date(anchor + k0 * spec.everyMs),
+				latest: new Date(anchor + lastK * spec.everyMs),
+			}
+		}
+		case 'cron': {
+			const expr = cronOf(spec.expr)
+			const tz = spec.tz
+			const latest = previousFireTime(spec, toInclusive)
+			if (!latest || latest.getTime() <= from) return { count: 0, capped: false }
+			const perUniformDay = expr.hours.length * expr.minutes.length
+			let count = 0
+			let first: number | undefined
+			const lastDay = dayStart(to + offsetAt(to, tz)) + DAY
+			for (let day = dayStart(from + offsetAt(from, tz)) - DAY; day <= lastDay; day += DAY) {
+				const c = civil(day)
+				if (!cronMatchesDay(expr, c.month, c.day, c.weekday)) continue
+				const o1 = offsetAt(day - 14 * HOUR, tz)
+				const o2 = offsetAt(day + DAY + 14 * HOUR, tz)
+				const dayFirst = day - o1
+				const dayLast = day + DAY - o1
+				if (first !== undefined && o1 === o2 && dayFirst > from && dayLast <= to) {
+					count += perUniformDay
+				} else {
+					for (const t of cronInstantsOnDay(expr, tz, day)) {
+						if (t <= from || t > to) continue
+						if (first === undefined) first = t
+						count++
+					}
+				}
+				if (count > cap) break
+			}
+			return {
+				count: Math.min(count, cap),
+				capped: count > cap,
+				...(first !== undefined ? { first: new Date(first) } : {}),
+				latest,
+			}
+		}
+	}
+}
+
+/** Validate a spec as a whole: its zone, its expression, and that it can ever fire after `now`. */
+export function assertSpecFires(spec: ScheduleSpec, now: Date): void {
+	if (spec.kind === 'cron') {
+		validateTimeZone(spec.tz)
+		cronOf(spec.expr)
+	}
+	if (nextFireTime(spec, now) === null) {
+		throw new ScheduleValidationError(
+			spec.kind === 'at'
+				? `${spec.at} is in the past`
+				: `"${spec.kind === 'cron' ? spec.expr : ''}" never fires in the next five years`,
+			spec.kind === 'cron' ? spec.expr : spec.kind === 'at' ? spec.at : undefined,
+		)
+	}
+}

package/src/schedules/spec.ts

@@ -0,0 +1,210 @@
+/**
+ * The words an operator or a model types for a schedule, turned into a spec.
+ *
+ * | Input | Spec |
+ * |---|---|
+ * | `at 2026-09-24T09:00`, `at 2026-09-24 09:00`, `at 09:00`, `in 30m` | `at` |
+ * | an ISO instant with `Z` or an offset, with or without `at` | `at` |
+ * | `every 30m`, `every 2h`, `every 1d`, `every 90m` | `every` |
+ * | five-field cron, `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly` | `cron` |
+ *
+ * A local time is read in `tz`. Nothing is rounded silently: `every 30s` is
+ * refused and the refusal names the nearest interval that is allowed.
+ */
+
+import { parseCronExpression } from './cron.js'
+import { ScheduleValidationError } from './errors.js'
+import { assertSpecFires, nextFireTime } from './next-fire.js'
+import type { ScheduleSpec } from './types.js'
+import { civil, hostTimeZone, instantsForWall, validateTimeZone, wallOf } from './tz.js'
+
+const MINUTE = 60_000
+const UNIT_MS: Readonly<Record<string, number>> = {
+	s: 1_000,
+	sec: 1_000,
+	secs: 1_000,
+	second: 1_000,
+	seconds: 1_000,
+	m: MINUTE,
+	min: MINUTE,
+	mins: MINUTE,
+	minute: MINUTE,
+	minutes: MINUTE,
+	h: 60 * MINUTE,
+	hr: 60 * MINUTE,
+	hrs: 60 * MINUTE,
+	hour: 60 * MINUTE,
+	hours: 60 * MINUTE,
+	d: 24 * 60 * MINUTE,
+	day: 24 * 60 * MINUTE,
+	days: 24 * 60 * MINUTE,
+	w: 7 * 24 * 60 * MINUTE,
+	week: 7 * 24 * 60 * MINUTE,
+	weeks: 7 * 24 * 60 * MINUTE,
+}
+
+export interface ParseScheduleOptions {
+	/** "Now", for `in …`, `at HH:MM` and the anchor of `every`. Default: the clock. */
+	readonly now?: Date
+	/** Zone a local time and a cron expression are read in. Default: the host's. */
+	readonly tz?: string
+}
+
+/** `90m` → 5 400 000. Throws on anything else. */
+export function parseDuration(text: string): number {
+	const match = /^(\d+)\s*([a-z]+)$/i.exec(text.trim())
+	const unit = match ? UNIT_MS[(match[2] ?? '').toLowerCase()] : undefined
+	if (!match || unit === undefined) {
+		throw new ScheduleValidationError(
+			`"${text}" is not a duration (write it like 30m, 2h, 1d)`,
+			text,
+		)
+	}
+	return Number(match[1]) * unit
+}
+
+function formatInterval(ms: number): string {
+	if (ms % (24 * 60 * MINUTE) === 0) return `${ms / (24 * 60 * MINUTE)}d`
+	if (ms % (60 * MINUTE) === 0) return `${ms / (60 * MINUTE)}h`
+	return `${ms / MINUTE}m`
+}
+
+function everySpec(text: string, now: Date): ScheduleSpec {
+	const ms = parseDuration(text)
+	if (ms < MINUTE) {
+		throw new ScheduleValidationError(
+			`every ${text} is shorter than the minimum interval; the nearest allowed is every 1m`,
+			text,
+		)
+	}
+	if (ms % MINUTE !== 0) {
+		const down = Math.floor(ms / MINUTE) * MINUTE
+		const up = down + MINUTE
+		throw new ScheduleValidationError(
+			`every ${text} is not a whole number of minutes; the nearest allowed are every ${formatInterval(down)} and every ${formatInterval(up)}`,
+			text,
+		)
+	}
+	const anchor = new Date(Math.floor(now.getTime() / MINUTE) * MINUTE)
+	return { kind: 'every', everyMs: ms, anchorAt: anchor.toISOString() }
+}
+
+/** Resolve a local `YYYY-MM-DD HH:MM` in `tz` to one instant (the earlier of two). */
+function localToInstant(
+	y: number,
+	mo: number,
+	d: number,
+	h: number,
+	mi: number,
+	tz: string,
+	token: string,
+): number {
+	const wall = Date.UTC(y, mo - 1, d, h, mi)
+	const c = civil(wall)
+	if (c.year !== y || c.month !== mo || c.day !== d || h > 23 || mi > 59) {
+		throw new ScheduleValidationError(`"${token}" is not a real date and time`, token)
+	}
+	const instants = instantsForWall(wall, tz)
+	if (instants.length === 0) {
+		throw new ScheduleValidationError(
+			`"${token}" does not exist in ${tz} (the clocks skip it); pick a time outside the change`,
+			token,
+		)
+	}
+	return instants[0] as number
+}
+
+function atSpec(text: string, now: Date, tz: string): ScheduleSpec {
+	const t = text.trim()
+	// An instant with its own offset: taken as written.
+	if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/i.test(t)) {
+		const at = Date.parse(t)
+		if (!Number.isFinite(at)) throw new ScheduleValidationError(`"${t}" is not a date`, t)
+		return { kind: 'at', at: new Date(at).toISOString() }
+	}
+	const full = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{1,2}):(\d{2})$/.exec(t)
+	if (full) {
+		const [, y, mo, d, h, mi] = full.map(Number) as number[]
+		const at = localToInstant(
+			y as number,
+			mo as number,
+			d as number,
+			h as number,
+			mi as number,
+			tz,
+			t,
+		)
+		return { kind: 'at', at: new Date(at).toISOString() }
+	}
+	const clock = /^(\d{1,2}):(\d{2})$/.exec(t)
+	if (clock) {
+		const h = Number(clock[1])
+		const mi = Number(clock[2])
+		if (h > 23 || mi > 59) throw new ScheduleValidationError(`"${t}" is not a time of day`, t)
+		// The next time the wall clock reads HH:MM, today or tomorrow.
+		const today = civil(wallOf(now.getTime(), tz))
+		for (let add = 0; add < 3; add++) {
+			const day = new Date(Date.UTC(today.year, today.month - 1, today.day + add))
+			const instants = instantsForWall(
+				Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate(), h, mi),
+				tz,
+			)
+			const first = instants.find((i) => i > now.getTime())
+			if (first !== undefined) return { kind: 'at', at: new Date(first).toISOString() }
+		}
+		throw new ScheduleValidationError(`"${t}" does not occur in ${tz} in the next two days`, t)
+	}
+	throw new ScheduleValidationError(
+		`"${t}" is not a time (write 2026-09-24 09:00, 09:00, or an ISO instant)`,
+		t,
+	)
+}
+
+/**
+ * Parse schedule words into a spec, validated: the zone exists, the
+ * expression parses, and the spec fires at least once after `now`.
+ */
+export function parseScheduleSpec(input: string, options: ParseScheduleOptions = {}): ScheduleSpec {
+	const now = options.now ?? new Date()
+	const tz = validateTimeZone(options.tz ?? hostTimeZone())
+	const text = input.trim()
+	if (text === '') throw new ScheduleValidationError('a schedule is required', '')
+	let spec: ScheduleSpec
+	const lower = text.toLowerCase()
+	if (lower.startsWith('every ')) {
+		spec = everySpec(text.slice(6).trim(), now)
+	} else if (lower.startsWith('in ')) {
+		const ms = parseDuration(text.slice(3).trim())
+		if (ms < MINUTE) {
+			throw new ScheduleValidationError(
+				`in ${text.slice(3).trim()} is less than a minute away; the nearest allowed is in 1m`,
+				text.slice(3).trim(),
+			)
+		}
+		spec = { kind: 'at', at: new Date(now.getTime() + ms).toISOString() }
+	} else if (lower.startsWith('at ')) {
+		spec = atSpec(text.slice(3), now, tz)
+	} else if (/^\d{4}-\d{2}-\d{2}T/i.test(text)) {
+		spec = atSpec(text, now, tz)
+	} else if (lower === '@reboot') {
+		throw new ScheduleValidationError('@reboot is not supported: a job runs on a schedule', text)
+	} else {
+		const expr = parseCronExpression(text)
+		spec = { kind: 'cron', expr: expr.source, tz }
+	}
+	assertSpecFires(spec, now)
+	return spec
+}
+
+/** The next `count` fire times after `after`. */
+export function upcomingFireTimes(spec: ScheduleSpec, after: Date, count = 3): Date[] {
+	const out: Date[] = []
+	let cursor = after
+	for (let i = 0; i < count; i++) {
+		const next = nextFireTime(spec, cursor)
+		if (!next) break
+		out.push(next)
+		cursor = next
+	}
+	return out
+}

package/src/schedules/types.ts

@@ -0,0 +1,163 @@
+/**
+ * Types of the schedule time engine and evaluator.
+ *
+ * The SDK owns WHEN something is due and nothing about how a host stores a
+ * job or runs it: the CLI keeps its job files, claims and history records to
+ * itself, so its on-disk format is not SDK API. The unions exported here
+ * (`ScheduleDecision`, `ScheduleSkipReason`, `ScheduleMissedReason`) may grow
+ * in a minor release; switch over them with a `default:` branch.
+ */
+
+/** A single instant (ISO-8601 UTC). */
+export interface ScheduleAtSpec {
+	readonly kind: 'at'
+	readonly at: string
+}
+
+/**
+ * Elapsed time from an anchor: `anchorAt + k * everyMs` for k ≥ 1. Pure UTC
+ * arithmetic, so `every 24h` drifts against the wall clock across a DST
+ * change; a cron spec is the way to say "every day at 09:00".
+ */
+export interface ScheduleEverySpec {
+	readonly kind: 'every'
+	/** At least one minute, and a whole number of minutes. */
+	readonly everyMs: number
+	readonly anchorAt: string
+}
+
+/** Five-field cron, evaluated in an IANA time zone the spec carries. */
+export interface ScheduleCronSpec {
+	readonly kind: 'cron'
+	/** Normalised five-field text; macros are expanded. */
+	readonly expr: string
+	readonly tz: string
+}
+
+export type ScheduleSpec = ScheduleAtSpec | ScheduleEverySpec | ScheduleCronSpec
+
+/** A parsed cron expression: each field as the sorted set of values it allows. */
+export interface CronExpression {
+	readonly source: string
+	readonly minutes: readonly number[]
+	readonly hours: readonly number[]
+	readonly daysOfMonth: readonly number[]
+	readonly months: readonly number[]
+	/** 0-6, Sunday = 0 (a written 7 is folded into 0). */
+	readonly daysOfWeek: readonly number[]
+	/** The day-of-month field does not start with `*`. */
+	readonly domRestricted: boolean
+	/** The day-of-week field does not start with `*`. */
+	readonly dowRestricted: boolean
+	/**
+	 * Minute and hour are single values or lists with no `*` or step. Decides
+	 * the DST rule (cronie's): a fixed-time job fires once per day across a
+	 * DST change, a wildcard job fires at every instant whose wall time
+	 * matches.
+	 */
+	readonly fixedTime: boolean
+}
+
+/** Why an occurrence did not run. May grow in a minor release. */
+export type ScheduleSkipReason =
+	| 'previous-run-active'
+	| 'previous-run-awaiting-approval'
+	| 'paused'
+	| 'awaiting-confirmation'
+	| 'beyond-catch-up-window'
+	| 'one-shot-expired'
+	| 'quota-hold'
+
+/** Why occurrences were missed. Best effort; may grow in a minor release. */
+export type ScheduleMissedReason = 'daemon-not-running' | 'machine-asleep' | 'clock-jumped-forward'
+
+/** The lifecycle a job is in, as far as the evaluator cares. */
+export type ScheduleJobLifecycle =
+	| 'pending-confirmation'
+	| 'active'
+	| 'paused'
+	| 'completed'
+	| 'expired'
+
+/** The evaluator's structural view of a job: what it needs and nothing else. */
+export interface ScheduleEvaluationJob {
+	readonly spec: ScheduleSpec
+	readonly state: ScheduleJobLifecycle
+	/** Catch-up window; default {@link SCHEDULE_CATCH_UP_WINDOW_MS}. */
+	readonly catchUp?: { readonly windowMs: number }
+	readonly createdAt: string
+	readonly updatedAt: string
+	/** Bumped on every definition change. */
+	readonly revision: number
+}
+
+/** What the host remembers between evaluations of one job. */
+export interface ScheduleEvaluationState {
+	/** Everything up to and including this instant has been decided. */
+	readonly lastEvaluatedAt?: string
+	/** The job revision `lastEvaluatedAt` was computed under. */
+	readonly jobRevision?: number
+	/** A run of this job that has not finished (or a fire queued but not started). */
+	readonly activeRun?: { readonly status: 'queued' | 'running' | 'awaiting-approval' }
+	/** Provider asked to be left alone until this instant. */
+	readonly quotaHoldUntil?: string
+}
+
+export interface ScheduleObservedGap {
+	readonly from: Date
+	readonly to: Date
+	readonly kind: 'asleep' | 'clock-forward' | 'clock-backward'
+}
+
+export interface ScheduleEvaluationInput {
+	readonly job: ScheduleEvaluationJob
+	readonly state: ScheduleEvaluationState
+	readonly now: Date
+	/** When this daemon instance started, and a gap it observed itself. */
+	readonly daemon: { readonly startedAt: Date; readonly observedGap?: ScheduleObservedGap }
+	/** How late a fire may be and still count as on time; default {@link SCHEDULE_LATE_GRACE_MS}. */
+	readonly lateGraceMs?: number
+	/** Whether an occurrence key was already started (claimed) by someone. */
+	readonly isClaimed?: (key: string) => boolean
+}
+
+export type ScheduleFireTrigger = 'scheduled' | 'late' | 'catch-up'
+
+/** What to do about one job now. May grow in a minor release. */
+export interface ScheduleDecision {
+	readonly fire?: {
+		/** Occurrence key: the scheduled instant in epoch milliseconds. */
+		readonly key: string
+		readonly scheduledFor: Date
+		readonly trigger: ScheduleFireTrigger
+	}
+	/** Occurrences that will not run, collapsed: one entry per reason. */
+	readonly skip: readonly {
+		readonly scheduledFor: Date
+		readonly reason: ScheduleSkipReason
+		readonly count: number
+	}[]
+	readonly missed?: {
+		readonly from: Date
+		readonly to: Date
+		readonly count: number
+		/** The count stopped at the cap; the real number is at least `count`. */
+		readonly capped: boolean
+		readonly reason: ScheduleMissedReason
+	}
+	readonly jobTransition?: 'completed' | 'expired'
+	readonly nextState: {
+		readonly lastEvaluatedAt: Date
+		readonly nextFireAt?: Date
+		readonly jobRevision: number
+	}
+}
+
+/** How occurrences in a window were counted. */
+export interface OccurrenceCount {
+	readonly count: number
+	/** The count stopped at the cap. */
+	readonly capped: boolean
+	readonly first?: Date
+	readonly latest?: Date
+}