@namzu/sdk 44.3.0 → 45.1.0

package/src/runtime/query/resume-pending.ts

@@ -14,6 +14,7 @@ import type { ChatCompletionResponse } from '../../types/provider/index.js'
 import type { ToolExecutionSnapshot } from '../../types/session/tool-execution.js'
 import type { Logger } from '../../utils/logger.js'
 import type { RestoredCheckpoint } from './checkpoint.js'
+import { DECLINED_TOOL_CALL_FEEDBACK } from './declined.js'
 import type { PriorToolResults, ToolCallDenials, ToolExecutor } from './executor.js'
 import { PendingAnswers } from './question-park.js'
 import { readToolExecutions } from './tool-executions.js'
@@ -630,7 +631,7 @@ function derriveDenials(
 			return new Map()
 
 		case 'reject_tools': {
-			const reason = decision.feedback || 'The user rejected this tool call.'
+			const reason = decision.feedback || DECLINED_TOOL_CALL_FEEDBACK
 			return new Map(toolCalls.map((tc) => [tc.id, reason]))
 		}
 
@@ -642,7 +643,7 @@ function derriveDenials(
 			const denials = new Map<string, string>()
 			for (const mod of decision.modifications) {
 				if (mod.action === 'deny') {
-					denials.set(mod.toolCallId, 'The user denied this tool call.')
+					denials.set(mod.toolCallId, DECLINED_TOOL_CALL_FEEDBACK)
 				}
 			}
 			for (const mod of decision.modifications) {

package/src/runtime/query/review-policy.ts

@@ -27,6 +27,7 @@ import type { HITLResumeDecision, ResumeHandler, ToolCallSummary } from '../../t
 import type { ApprovalPolicy } from '../../types/hitl/policy.js'
 import type { SessionId, TurnId } from '../../types/ids/index.js'
 import { PLAN_MODE_REFUSAL } from '../../types/permission/index.js'
+import { DECLINED_TOOL_CALL_FEEDBACK } from './declined.js'
 
 export type ReviewMode =
 	/** Ask a person. The default when a `prompt` is supplied. */
@@ -238,6 +239,33 @@ export interface ReviewPolicyOptions {
 	 * in every mode that does not refuse the call outright.
 	 */
 	readonly unattendedSandboxEscape?: 'refuse' | 'allow'
+	/**
+	 * Whether a skill's `allowed-tools` pre-approval stands in for a person.
+	 *
+	 * `'honour'` (the default) approves a batch without asking when every call
+	 * that would be asked about carries `ToolCallSummary.skillGrant`. `'ignore'`
+	 * asks as though no skill had been loaded — the behaviour before
+	 * `allowed-tools` was read as a pre-approval, for a host that does not want
+	 * repository content to reduce its prompts. `plan` and `strict` refuse
+	 * either way.
+	 */
+	readonly skillGrants?: 'honour' | 'ignore'
+}
+
+/**
+ * Whether a skill's `allowed-tools` grant may stand in for a person on this
+ * call: the kernel marked it, and nothing that outranks a skill is present.
+ * The second half repeats what the kernel checked before marking, so a mark
+ * on a persisted or host-built summary cannot carry more than it should.
+ */
+function isSkillGranted(tc: ToolCallSummary): boolean {
+	return (
+		tc.skillGrant !== undefined &&
+		!tc.authorization?.explicitReview &&
+		tc.authorization?.decision !== 'deny' &&
+		!tc.isDestructive &&
+		tc.escalation === undefined
+	)
 }
 
 /** The handler behind `createReviewPolicy`, for a host that wants only the function. */
@@ -306,7 +334,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			if (answer.kind === 'reject') {
 				return {
 					action: 'reject_tools',
-					feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 				}
 			}
 			// "Approve all" still latches for the calls that follow; it never
@@ -328,7 +356,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			if (answer.kind === 'reject') {
 				return {
 					action: 'reject_tools',
-					feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 				}
 			}
 			// Latches for the ordinary calls that follow, never for the next path.
@@ -338,6 +366,32 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		if (mode === 'auto' || !prompt || remembered.all) {
 			return { action: 'approve_tools' }
 		}
+		// Every call a person would be asked about is one a skill loaded in
+		// this turn pre-approved (`allowed-tools`). Reached only in `prompt`
+		// and `accept-edits`: `plan` and `strict` refused above, so a skill's
+		// word never outranks either, and the kernel only marks a call no
+		// deny, explicit ask, destructive flag or escalation stands behind.
+		// One unmarked call and the whole batch is asked about, as always.
+		const needsPerson = request.toolCalls.filter(
+			(tc) =>
+				tc.authorization?.explicitReview ||
+				tc.isDestructive ||
+				tc.escalation !== undefined ||
+				!(
+					exempt(tc.name, tc.input) ||
+					(mode === 'accept-edits' && ACCEPT_EDITS_TOOLS.has(tc.name))
+				),
+		)
+		if (
+			options.skillGrants !== 'ignore' &&
+			needsPerson.length > 0 &&
+			needsPerson.every(isSkillGranted)
+		) {
+			return {
+				action: 'approve_tools',
+				skillGranted: needsPerson.map((tc) => tc.id),
+			}
+		}
 		const answer = await prompt({
 			sessionId: request.sessionId,
 			turnId: request.turnId,
@@ -352,7 +406,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			case 'reject':
 				return {
 					action: 'reject_tools',
-					feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 				}
 		}
 	}

package/src/runtime/query/tooling.ts

@@ -1,4 +1,5 @@
 import type { AuthorizationGate } from '../../authorization/gate.js'
+import type { SkillGrantSet } from '../../authorization/skill-grant.js'
 import type { PluginLifecycleManager } from '../../plugin/lifecycle.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import type { SessionId, TurnId } from '../../types/ids/index.js'
@@ -67,6 +68,8 @@ export interface ToolingBootstrapConfig {
 	recordAudit?: (input: AuditEventInput) => Promise<unknown>
 	/** Builds the durable-pause seam for one tool call; see ToolContext.requestPause. */
 	toolPause?: (toolUseId: string) => RequestToolPause
+	/** The turn's skill pre-approvals; see the executor's own field. */
+	skillGrants?: SkillGrantSet
 }
 
 export class ToolingBootstrap {
@@ -130,6 +133,7 @@ export class ToolingBootstrap {
 					: {}),
 				...(config.recordAudit !== undefined ? { recordAudit: config.recordAudit } : {}),
 				...(config.toolPause !== undefined ? { toolPause: config.toolPause } : {}),
+				...(config.skillGrants !== undefined ? { skillGrants: config.skillGrants } : {}),
 			},
 			activityStore,
 			emitEvent,

package/src/schedules/cron.ts

@@ -0,0 +1,202 @@
+/**
+ * Five-field cron, parsed into sets.
+ *
+ * Minute, hour, day of month, month, day of week. Lists, ranges, steps and
+ * three-letter names; `0` and `7` are both Sunday. Vixie semantics for the
+ * two day fields: when BOTH are restricted a day matches if EITHER does, which
+ * is what every cron and every existing crontab assumes.
+ *
+ * Refused, each by name: `L`, `W`, `#`, `?`, a sixth (seconds) field and
+ * `@reboot`. A refused token is a better answer than a job that silently
+ * means something the operator did not write.
+ */
+
+import { ScheduleValidationError } from './errors.js'
+import type { CronExpression } from './types.js'
+
+const MACROS: Readonly<Record<string, string>> = {
+	'@yearly': '0 0 1 1 *',
+	'@annually': '0 0 1 1 *',
+	'@monthly': '0 0 1 * *',
+	'@weekly': '0 0 * * 0',
+	'@daily': '0 0 * * *',
+	'@midnight': '0 0 * * *',
+	'@hourly': '0 * * * *',
+}
+
+const MONTH_NAMES = [
+	'jan',
+	'feb',
+	'mar',
+	'apr',
+	'may',
+	'jun',
+	'jul',
+	'aug',
+	'sep',
+	'oct',
+	'nov',
+	'dec',
+]
+const DAY_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat']
+
+interface FieldSpec {
+	readonly label: string
+	readonly min: number
+	readonly max: number
+	readonly names?: readonly string[]
+	/** Where `names[0]` sits in the numeric range. */
+	readonly nameBase?: number
+}
+
+const FIELDS: readonly FieldSpec[] = [
+	{ label: 'minute', min: 0, max: 59 },
+	{ label: 'hour', min: 0, max: 23 },
+	{ label: 'day of month', min: 1, max: 31 },
+	{ label: 'month', min: 1, max: 12, names: MONTH_NAMES, nameBase: 1 },
+	{ label: 'day of week', min: 0, max: 7, names: DAY_NAMES, nameBase: 0 },
+]
+
+function parseValue(raw: string, field: FieldSpec): number {
+	const lower = raw.toLowerCase()
+	if (field.names) {
+		const at = field.names.indexOf(lower)
+		if (at >= 0) return at + (field.nameBase ?? 0)
+	}
+	if (!/^\d+$/.test(raw)) {
+		throw new ScheduleValidationError(`${field.label}: "${raw}" is not a number or a name`, raw)
+	}
+	const n = Number(raw)
+	if (n < field.min || n > field.max) {
+		throw new ScheduleValidationError(
+			`${field.label}: ${n} is outside ${field.min}-${field.max}`,
+			raw,
+		)
+	}
+	return n
+}
+
+function parseField(text: string, field: FieldSpec): number[] {
+	if (text === '') throw new ScheduleValidationError(`${field.label}: empty field`, text)
+	const values = new Set<number>()
+	for (const part of text.split(',')) {
+		if (part === '') throw new ScheduleValidationError(`${field.label}: empty list entry`, text)
+		// Names (`jul`, `wed`) are removed first: they carry the letters the
+		// refused `L` and `W` are spelled with.
+		const withoutNames = part.replace(/[a-z]{3}/gi, (word) =>
+			field.names?.includes(word.toLowerCase()) ? '' : word,
+		)
+		for (const refused of ['L', 'W', '#', '?']) {
+			if (withoutNames.toUpperCase().includes(refused)) {
+				throw new ScheduleValidationError(
+					`${field.label}: "${refused}" is not supported (in "${part}")`,
+					refused,
+				)
+			}
+		}
+		const [rangeText = '', stepText, extra] = part.split('/')
+		if (extra !== undefined) {
+			throw new ScheduleValidationError(`${field.label}: "${part}" has more than one step`, part)
+		}
+		let step = 1
+		if (stepText !== undefined) {
+			if (!/^\d+$/.test(stepText) || Number(stepText) === 0) {
+				throw new ScheduleValidationError(
+					`${field.label}: step "${stepText}" must be a whole number above 0`,
+					part,
+				)
+			}
+			step = Number(stepText)
+		}
+		let lo: number
+		let hi: number
+		if (rangeText === '*') {
+			lo = field.min
+			hi = field.label === 'day of week' ? 6 : field.max
+		} else if (rangeText.includes('-')) {
+			const [a = '', b = '', more] = rangeText.split('-')
+			if (more !== undefined) {
+				throw new ScheduleValidationError(`${field.label}: "${rangeText}" is not a range`, part)
+			}
+			lo = parseValue(a, field)
+			hi = parseValue(b, field)
+			if (hi < lo) {
+				throw new ScheduleValidationError(
+					`${field.label}: range "${rangeText}" runs backwards`,
+					rangeText,
+				)
+			}
+		} else {
+			lo = parseValue(rangeText, field)
+			// `5/15` means "from 5, every 15", as in Vixie cron.
+			hi = stepText !== undefined ? (field.label === 'day of week' ? 6 : field.max) : lo
+		}
+		for (let v = lo; v <= hi; v += step) values.add(v)
+	}
+	return [...values].sort((a, b) => a - b)
+}
+
+/**
+ * Parse a five-field expression or a macro. Throws
+ * {@link ScheduleValidationError} naming the offending token.
+ */
+export function parseCronExpression(input: string): CronExpression {
+	const trimmed = input.trim()
+	if (trimmed === '') throw new ScheduleValidationError('empty cron expression', '')
+	let text = trimmed
+	if (trimmed.startsWith('@')) {
+		const macro = MACROS[trimmed.toLowerCase()]
+		if (!macro) {
+			throw new ScheduleValidationError(`"${trimmed}" is not a supported macro`, trimmed)
+		}
+		text = macro
+	}
+	const fields = text.split(/\s+/)
+	if (fields.length === 6) {
+		throw new ScheduleValidationError(
+			'six fields: a seconds field is not supported; use five fields (minute hour day month weekday)',
+			fields[0],
+		)
+	}
+	if (fields.length !== 5) {
+		throw new ScheduleValidationError(
+			`expected five fields (minute hour day month weekday), got ${fields.length}`,
+			text,
+		)
+	}
+	const [mi = '', ho = '', dom = '', mon = '', dow = ''] = fields
+	const minutes = parseField(mi, FIELDS[0] as FieldSpec)
+	const hours = parseField(ho, FIELDS[1] as FieldSpec)
+	const daysOfMonth = parseField(dom, FIELDS[2] as FieldSpec)
+	const months = parseField(mon, FIELDS[3] as FieldSpec)
+	const weekdays = parseField(dow, FIELDS[4] as FieldSpec)
+	const normalizedWeekdays = [...new Set(weekdays.map((d) => (d === 7 ? 0 : d)))].sort(
+		(a, b) => a - b,
+	)
+	const fixedTime = !/[*/]/.test(mi) && !/[*/]/.test(ho)
+	return {
+		source: fields.join(' '),
+		minutes,
+		hours,
+		daysOfMonth,
+		months,
+		daysOfWeek: normalizedWeekdays,
+		domRestricted: !dom.startsWith('*'),
+		dowRestricted: !dow.startsWith('*'),
+		fixedTime,
+	}
+}
+
+/** Whether the civil date matches the day fields (Vixie OR rule). */
+export function cronMatchesDay(
+	expr: CronExpression,
+	month: number,
+	day: number,
+	weekday: number,
+): boolean {
+	if (!expr.months.includes(month)) return false
+	const domMatch = expr.daysOfMonth.includes(day)
+	const dowMatch = expr.daysOfWeek.includes(weekday)
+	if (expr.domRestricted && expr.dowRestricted) return domMatch || dowMatch
+	return domMatch && dowMatch
+}

package/src/schedules/describe.ts

@@ -0,0 +1,138 @@
+/**
+ * A schedule in words, for a confirmation screen or a listing.
+ *
+ * Covers the common shapes exactly and falls back to the expression itself
+ * for anything else, rather than paraphrasing it wrongly.
+ */
+
+import { parseCronExpression } from './cron.js'
+import type { CronExpression, ScheduleSpec } from './types.js'
+import { formatWall } from './tz.js'
+
+const MINUTE = 60_000
+const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+const MONTH_NAMES = [
+	'January',
+	'February',
+	'March',
+	'April',
+	'May',
+	'June',
+	'July',
+	'August',
+	'September',
+	'October',
+	'November',
+	'December',
+]
+
+export interface DescribeScheduleOptions {
+	/** Zone an `at` or `every` anchor is shown in. Default UTC. */
+	readonly tz?: string
+}
+
+function pad(n: number): string {
+	return String(n).padStart(2, '0')
+}
+
+function plural(n: number, unit: string): string {
+	return `${n} ${unit}${n === 1 ? '' : 's'}`
+}
+
+function describeInterval(ms: number): string {
+	if (ms % (7 * 24 * 60 * MINUTE) === 0) {
+		const w = ms / (7 * 24 * 60 * MINUTE)
+		return w === 1 ? 'every week' : `every ${plural(w, 'week')}`
+	}
+	if (ms % (24 * 60 * MINUTE) === 0) {
+		const d = ms / (24 * 60 * MINUTE)
+		return d === 1 ? 'every 24 hours' : `every ${plural(d, 'day')}`
+	}
+	if (ms % (60 * MINUTE) === 0) {
+		const h = ms / (60 * MINUTE)
+		return h === 1 ? 'every hour' : `every ${plural(h, 'hour')}`
+	}
+	const m = ms / MINUTE
+	return m === 1 ? 'every minute' : `every ${plural(m, 'minute')}`
+}
+
+/** `1,2,3,5` → `1–3, 5`. */
+function ranges(values: readonly number[], name: (n: number) => string): string {
+	const out: string[] = []
+	let i = 0
+	while (i < values.length) {
+		let j = i
+		while (j + 1 < values.length && (values[j + 1] as number) === (values[j] as number) + 1) j++
+		const a = values[i] as number
+		const b = values[j] as number
+		if (j - i >= 2) out.push(`${name(a)} through ${name(b)}`)
+		else for (let k = i; k <= j; k++) out.push(name(values[k] as number))
+		i = j + 1
+	}
+	return out.join(', ')
+}
+
+function isFull(values: readonly number[], min: number, max: number): boolean {
+	return values.length === max - min + 1
+}
+
+function describeDays(e: CronExpression): string {
+	const allDom = !e.domRestricted
+	const allDow = !e.dowRestricted
+	const allMonths = isFull(e.months, 1, 12)
+	let days: string
+	if (allDom && allDow) days = 'every day'
+	else if (allDom) days = `on ${ranges(e.daysOfWeek, (d) => DAY_NAMES[d] ?? String(d))}`
+	else if (allDow) days = `on day ${ranges(e.daysOfMonth, String)} of the month`
+	else
+		days = `on day ${ranges(e.daysOfMonth, String)} of the month and on ${ranges(e.daysOfWeek, (d) => DAY_NAMES[d] ?? String(d))}`
+	if (!allMonths) days += ` in ${ranges(e.months, (m) => MONTH_NAMES[m - 1] ?? String(m))}`
+	return days
+}
+
+function describeTimes(e: CronExpression, source: string): string {
+	const [mi = '', ho = ''] = source.split(' ')
+	const allMinutes = isFull(e.minutes, 0, 59)
+	const allHours = isFull(e.hours, 0, 23)
+	if (allMinutes && allHours) return 'every minute'
+	const stepMinute = /^\*\/(\d+)$/.exec(mi)
+	if (stepMinute && allHours) return `every ${plural(Number(stepMinute[1]), 'minute')}`
+	if (allHours && e.minutes.length <= 4) {
+		return e.minutes.length === 1 && e.minutes[0] === 0
+			? 'every hour, on the hour'
+			: `every hour at minute ${e.minutes.join(', ')}`
+	}
+	const stepHour = /^\*\/(\d+)$/.exec(ho)
+	if (stepHour && e.minutes.length === 1) {
+		return `every ${plural(Number(stepHour[1]), 'hour')} at minute ${e.minutes[0]}`
+	}
+	if (e.hours.length * e.minutes.length <= 6) {
+		const times: string[] = []
+		for (const h of e.hours) for (const m of e.minutes) times.push(`${pad(h)}:${pad(m)}`)
+		return `at ${times.join(', ')}`
+	}
+	return `at minute ${ranges(e.minutes, String)} of hour ${ranges(e.hours, String)}`
+}
+
+/** The schedule in words: `at 03:00 every day (Europe/Istanbul)`. */
+export function describeSchedule(
+	spec: ScheduleSpec,
+	options: DescribeScheduleOptions = {},
+): string {
+	const tz = options.tz ?? 'UTC'
+	switch (spec.kind) {
+		case 'at':
+			return `once at ${formatWall(Date.parse(spec.at), tz)} (${tz})`
+		case 'every':
+			return describeInterval(spec.everyMs)
+		case 'cron': {
+			let e: CronExpression
+			try {
+				e = parseCronExpression(spec.expr)
+			} catch {
+				return `cron "${spec.expr}" (${spec.tz})`
+			}
+			return `${describeTimes(e, e.source)} ${describeDays(e)} (${spec.tz})`
+		}
+	}
+}

package/src/schedules/errors.ts

@@ -0,0 +1,15 @@
+/**
+ * A schedule, cron expression or time zone that cannot be used.
+ *
+ * `token` names the piece of the input that was refused, so a caller can
+ * point at it instead of repeating the whole expression back.
+ */
+export class ScheduleValidationError extends Error {
+	readonly token: string | undefined
+
+	constructor(message: string, token?: string) {
+		super(message)
+		this.name = 'ScheduleValidationError'
+		this.token = token
+	}
+}

package/src/schedules/evaluate.ts

@@ -0,0 +1,178 @@
+/**
+ * What to do about one job now: fire, skip, record a miss, or nothing.
+ *
+ * Pure: no clock, no I/O. The host passes the instant, the state it kept and
+ * whether an occurrence was already claimed, and applies the decision itself
+ * (append history, claim, dispatch). Evaluating the same `(state, now)` twice
+ * gives the same answer, so a host that lost its in-memory queue rebuilds it
+ * by evaluating again; an already-claimed key is never fired twice.
+ *
+ * Rules, in order:
+ *
+ * 1. Occurrences due are those in `(lastEvaluatedAt, now]`, counted with a
+ *    cap and never enumerated. A new job counts from its creation. A changed
+ *    revision counts from the change, so editing `0 3 * * *` into `0 4 * * *`
+ *    does not invent catch-ups for 04:00s that never belonged to the job.
+ * 2. `lastEvaluatedAt` never moves backwards: after a backward clock jump
+ *    nothing is due until the wall clock passes it again.
+ * 3. A job that is not active produces skip records only (paused and
+ *    awaiting-confirmation are collapsed per evaluation). A one-shot whose
+ *    time passed while inactive is expired.
+ * 4. The latest due occurrence fires on time (`scheduled`, or `late` once
+ *    more than five seconds late) within the late grace; within the catch-up
+ *    window it fires once as `catch-up` and everything earlier is one
+ *    `missed` record; older than the window, nothing fires.
+ * 5. An unfinished run of the same job skips what came due meanwhile.
+ * 6. A provider quota hold skips what comes due before the hold ends.
+ */
+
+import { countOccurrences, nextFireTime, previousFireTime } from './next-fire.js'
+import type {
+	ScheduleDecision,
+	ScheduleEvaluationInput,
+	ScheduleMissedReason,
+	ScheduleSkipReason,
+} from './types.js'
+
+/** Default catch-up window: seven days. */
+export const SCHEDULE_CATCH_UP_WINDOW_MS = 7 * 24 * 60 * 60 * 1000
+/** Default grace for a fire to still count as on time: two minutes. */
+export const SCHEDULE_LATE_GRACE_MS = 120_000
+/** A fire later than this is reported `late` rather than `scheduled`. */
+const LATE_THRESHOLD_MS = 5_000
+
+type Skip = ScheduleDecision['skip'][number]
+
+function missedReason(input: ScheduleEvaluationInput, firstMissed: Date): ScheduleMissedReason {
+	const gap = input.daemon.observedGap
+	if (gap && firstMissed.getTime() >= gap.from.getTime()) {
+		if (gap.kind === 'asleep') return 'machine-asleep'
+		if (gap.kind === 'clock-forward') return 'clock-jumped-forward'
+	}
+	return 'daemon-not-running'
+}
+
+/** Evaluate one job at `now`. */
+export function evaluateJob(input: ScheduleEvaluationInput): ScheduleDecision {
+	const { job, state, now } = input
+	const nowMs = now.getTime()
+	const lateGrace = input.lateGraceMs ?? SCHEDULE_LATE_GRACE_MS
+	const windowMs = job.catchUp?.windowMs ?? SCHEDULE_CATCH_UP_WINDOW_MS
+
+	let baseMs = Date.parse(state.lastEvaluatedAt ?? job.createdAt)
+	if (!Number.isFinite(baseMs)) baseMs = Date.parse(job.createdAt)
+	if (state.jobRevision !== undefined && state.jobRevision !== job.revision) {
+		baseMs = Math.max(baseMs, Date.parse(job.updatedAt))
+	}
+	const nextState = (evaluatedMs: number): ScheduleDecision['nextState'] => {
+		const next = nextFireTime(job.spec, new Date(evaluatedMs))
+		return {
+			lastEvaluatedAt: new Date(evaluatedMs),
+			...(next ? { nextFireAt: next } : {}),
+			jobRevision: job.revision,
+		}
+	}
+
+	if (job.state === 'completed' || job.state === 'expired') {
+		return {
+			skip: [],
+			nextState: { lastEvaluatedAt: new Date(Math.max(baseMs, nowMs)), jobRevision: job.revision },
+		}
+	}
+	// Rule 2: a clock that went backwards decides nothing new.
+	if (nowMs <= baseMs) return { skip: [], nextState: nextState(baseMs) }
+
+	const due = countOccurrences(job.spec, new Date(baseMs), now)
+	if (due.count === 0 || !due.latest) {
+		if (job.spec.kind === 'at' && Date.parse(job.spec.at) <= baseMs && job.state !== 'active') {
+			return { skip: [], jobTransition: 'expired', nextState: nextState(nowMs) }
+		}
+		return { skip: [], nextState: nextState(nowMs) }
+	}
+	const latest = due.latest
+
+	const collapsed = (reason: ScheduleSkipReason): Skip[] => [
+		{ scheduledFor: latest, reason, count: due.count },
+	]
+
+	if (job.state === 'paused' || job.state === 'pending-confirmation') {
+		const reason: ScheduleSkipReason = job.state === 'paused' ? 'paused' : 'awaiting-confirmation'
+		return {
+			skip: collapsed(reason),
+			...(job.spec.kind === 'at' ? { jobTransition: 'expired' as const } : {}),
+			nextState: nextState(nowMs),
+		}
+	}
+
+	const hold = state.quotaHoldUntil ? Date.parse(state.quotaHoldUntil) : Number.NaN
+	if (Number.isFinite(hold) && hold > nowMs) {
+		return { skip: collapsed('quota-hold'), nextState: nextState(nowMs) }
+	}
+
+	if (state.activeRun) {
+		return {
+			skip: collapsed(
+				state.activeRun.status === 'awaiting-approval'
+					? 'previous-run-awaiting-approval'
+					: 'previous-run-active',
+			),
+			nextState: nextState(nowMs),
+		}
+	}
+
+	const key = String(latest.getTime())
+	const lateBy = nowMs - latest.getTime()
+	const earlier = due.count - 1
+	const missedBefore = (): ScheduleDecision['missed'] | undefined => {
+		if (earlier <= 0 || !due.first) return undefined
+		// The occurrence just before the fired one.
+		const to = previousFireTime(job.spec, new Date(latest.getTime() - 1)) ?? due.first
+		return {
+			from: due.first,
+			to,
+			count: earlier,
+			capped: due.capped,
+			reason: missedReason(input, due.first),
+		}
+	}
+	const transition = job.spec.kind === 'at' ? { jobTransition: 'completed' as const } : {}
+
+	if (input.isClaimed?.(key)) {
+		// Somebody already started it; nothing to fire, nothing missed.
+		return { skip: [], ...transition, nextState: nextState(nowMs) }
+	}
+
+	if (lateBy <= lateGrace || lateBy <= windowMs) {
+		const trigger =
+			lateBy <= lateGrace ? (lateBy > LATE_THRESHOLD_MS ? 'late' : 'scheduled') : 'catch-up'
+		const missed = missedBefore()
+		return {
+			fire: { key, scheduledFor: latest, trigger },
+			skip: [],
+			...(missed ? { missed } : {}),
+			...transition,
+			nextState: nextState(nowMs),
+		}
+	}
+
+	// Everything due is older than the window.
+	const first = due.first ?? latest
+	return {
+		skip: [
+			{
+				scheduledFor: latest,
+				reason: job.spec.kind === 'at' ? 'one-shot-expired' : 'beyond-catch-up-window',
+				count: 1,
+			},
+		],
+		missed: {
+			from: first,
+			to: latest,
+			count: due.count,
+			capped: due.capped,
+			reason: missedReason(input, first),
+		},
+		...(job.spec.kind === 'at' ? { jobTransition: 'expired' as const } : {}),
+		nextState: nextState(nowMs),
+	}
+}