@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/core/scheduler/evaluator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Next-fire-time computation for cron schedules in a job's IANA timezone.
+ *
+ * Search happens in wall-clock space with field-level skipping (month → day
+ * → hour → minute), so even sparse schedules (e.g. Feb 29) resolve in a
+ * handful of iterations. DST edge cases:
+ * - spring-forward gap: the wall time doesn't exist → round-trip check fails
+ *   → the minute is skipped;
+ * - fall-back ambiguity: the offset iteration in `wallToUtcMs` resolves to
+ *   the first occurrence.
+ */
+import { type CronSchedule } from './cron.js';
+/**
+ * Cheap static unsatisfiability pre-check (SECURITY FIX: unsatisfiable-cron
+ * CPU burn, medium).
+ *
+ * Rejects schedules whose day-of-month can never occur in any selected month
+ * (e.g. `0 0 30 2 *`, `0 0 31 4 *`) WITHOUT running the multi-million-step
+ * search in `computeNextFire`. Before this check, `create()` burned ~2s of
+ * event-loop CPU per hostile spec — and the burn happened BEFORE the
+ * per-principal quota check, so even a quota-exhausted attacker could
+ * trigger it repeatedly (CPU-exhaustion DoS in the management plane).
+ *
+ * Soundness: the check only applies when day-of-week is unrestricted (`*`).
+ * A restricted DOW can match days via Vixie OR-semantics even when DOM never
+ * matches (see `dayMatches` in cron.ts), so those schedules fall through to
+ * the bounded search in `computeNextFire` instead.
+ */
+export declare function isUnsatisfiableCron(schedule: CronSchedule): boolean;
+/**
+ * Earliest UTC instant strictly after `afterMs` matching `schedule` in
+ * `timeZone`. Returns `undefined` when nothing matches within the horizon
+ * (e.g. Feb 30 — rejected earlier by day-range validation, so this is a
+ * safety net for truly unsatisfiable combinations).
+ */
+export declare function computeNextFire(schedule: CronSchedule, afterMs: number, timeZone: string): number | undefined;
+export type MisfireClass = 'on_time' | 'misfired';
+/**
+ * Classify whether `nextRunAt` is merely due or has misfired.
+ * Wall-clock only, per spec 04.
+ */
+export declare function classifyMisfire(nextRunAtMs: number, nowMs: number, misfireGraceMs: number): MisfireClass;

package/dist/node_modules/@boombot/core/scheduler/evaluator.js

@@ -0,0 +1,148 @@
+/**
+ * Next-fire-time computation for cron schedules in a job's IANA timezone.
+ *
+ * Search happens in wall-clock space with field-level skipping (month → day
+ * → hour → minute), so even sparse schedules (e.g. Feb 29) resolve in a
+ * handful of iterations. DST edge cases:
+ * - spring-forward gap: the wall time doesn't exist → round-trip check fails
+ *   → the minute is skipped;
+ * - fall-back ambiguity: the offset iteration in `wallToUtcMs` resolves to
+ *   the first occurrence.
+ */
+import { matchesCron } from './cron.js';
+import { toWallParts, wallRoundTrips, wallToUtcMs, } from './timezone.js';
+/**
+ * Search horizon: ~8.2 years of minutes. Covers the longest legitimate gap
+ * (Feb 29 across a skipped century leap year, e.g. 2096 -> 2104). Field-level
+ * skipping means this loop almost never runs hot — the bound is a safety net
+ * for unsatisfiable combinations like Feb 30.
+ */
+const MAX_ITERATIONS = 4_300_000;
+function daysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+/**
+ * Max days per month index (1-based). February counts 29 — leap years exist —
+ * so this check is conservative: it only rejects combinations that can NEVER
+ * fire in any year.
+ */
+const MONTH_MAX_DAYS = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/**
+ * Cheap static unsatisfiability pre-check (SECURITY FIX: unsatisfiable-cron
+ * CPU burn, medium).
+ *
+ * Rejects schedules whose day-of-month can never occur in any selected month
+ * (e.g. `0 0 30 2 *`, `0 0 31 4 *`) WITHOUT running the multi-million-step
+ * search in `computeNextFire`. Before this check, `create()` burned ~2s of
+ * event-loop CPU per hostile spec — and the burn happened BEFORE the
+ * per-principal quota check, so even a quota-exhausted attacker could
+ * trigger it repeatedly (CPU-exhaustion DoS in the management plane).
+ *
+ * Soundness: the check only applies when day-of-week is unrestricted (`*`).
+ * A restricted DOW can match days via Vixie OR-semantics even when DOM never
+ * matches (see `dayMatches` in cron.ts), so those schedules fall through to
+ * the bounded search in `computeNextFire` instead.
+ */
+export function isUnsatisfiableCron(schedule) {
+    if (!schedule.dayOfWeekIsStar)
+        return false;
+    let maxDom = 0;
+    for (const day of schedule.dayOfMonth) {
+        if (day > maxDom)
+            maxDom = day;
+    }
+    let maxMonthDays = 0;
+    for (const month of schedule.month) {
+        const days = MONTH_MAX_DAYS[month] ?? 0;
+        if (days > maxMonthDays)
+            maxMonthDays = days;
+    }
+    return maxDom > maxMonthDays;
+}
+function withWeekday(parts) {
+    return {
+        ...parts,
+        weekday: new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay(),
+    };
+}
+function advanceMonth(parts) {
+    const month = parts.month === 12 ? 1 : parts.month + 1;
+    const year = parts.month === 12 ? parts.year + 1 : parts.year;
+    return withWeekday({ year, month, day: 1, hour: 0, minute: 0 });
+}
+function advanceDay(parts) {
+    const dim = daysInMonth(parts.year, parts.month);
+    if (parts.day < dim) {
+        return withWeekday({ ...parts, day: parts.day + 1, hour: 0, minute: 0 });
+    }
+    return advanceMonth(parts);
+}
+function advanceHour(parts) {
+    if (parts.hour < 23)
+        return withWeekday({ ...parts, hour: parts.hour + 1, minute: 0 });
+    return advanceDay(parts);
+}
+function advanceMinute(parts) {
+    if (parts.minute < 59)
+        return withWeekday({ ...parts, minute: parts.minute + 1 });
+    return advanceHour(parts);
+}
+/**
+ * Earliest UTC instant strictly after `afterMs` matching `schedule` in
+ * `timeZone`. Returns `undefined` when nothing matches within the horizon
+ * (e.g. Feb 30 — rejected earlier by day-range validation, so this is a
+ * safety net for truly unsatisfiable combinations).
+ */
+export function computeNextFire(schedule, afterMs, timeZone) {
+    // Start at the next whole minute after `afterMs` (exclusive).
+    const startWall = toWallParts(Math.floor(afterMs / 60000) * 60000 + 60000, timeZone);
+    let wall = startWall;
+    for (let i = 0; i < MAX_ITERATIONS; i += 1) {
+        if (!schedule.month.has(wall.month)) {
+            wall = advanceMonth(wall);
+            continue;
+        }
+        // Day check needs DOM/DOW OR-semantics; reuse matchesCron on a probe.
+        if (!daySatisfied(schedule, wall)) {
+            wall = advanceDay(wall);
+            continue;
+        }
+        if (!schedule.hour.has(wall.hour)) {
+            wall = advanceHour(wall);
+            continue;
+        }
+        if (!schedule.minute.has(wall.minute)) {
+            wall = advanceMinute(wall);
+            continue;
+        }
+        const candidate = wallToUtcMs(wall, timeZone);
+        // Skip wall times that don't exist (spring-forward gap).
+        if (!wallRoundTrips(wall, candidate, timeZone)) {
+            wall = advanceMinute(wall);
+            continue;
+        }
+        if (candidate > afterMs)
+            return candidate;
+        wall = advanceMinute(wall);
+    }
+    return undefined;
+}
+function daySatisfied(schedule, wall) {
+    // Probe with a synthetic full match on the other fields.
+    return matchesCron({
+        minute: new Set([wall.minute]),
+        hour: new Set([wall.hour]),
+        dayOfMonth: schedule.dayOfMonth,
+        month: new Set([wall.month]),
+        dayOfWeek: schedule.dayOfWeek,
+        dayOfMonthIsStar: schedule.dayOfMonthIsStar,
+        dayOfWeekIsStar: schedule.dayOfWeekIsStar,
+    }, wall);
+}
+/**
+ * Classify whether `nextRunAt` is merely due or has misfired.
+ * Wall-clock only, per spec 04.
+ */
+export function classifyMisfire(nextRunAtMs, nowMs, misfireGraceMs) {
+    return nowMs - nextRunAtMs > misfireGraceMs ? 'misfired' : 'on_time';
+}

package/dist/node_modules/@boombot/core/scheduler/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @boombot/core — durable cron/heartbeat scheduling for the
+ * BoomBot harness layer.
+ *
+ * Public surface: registry (management plane), runner (execution plane),
+ * cron parser/evaluator, SQLite store, and the narrow ports the host must
+ * wire (`SchedulerAuthorizer`, `TurnSubmitter`).
+ */
+export { parseCron, validateCronExpression, matchesCron, MAX_CRON_LENGTH, type CronSchedule, } from './cron.js';
+export { computeNextFire, isUnsatisfiableCron, classifyMisfire, type MisfireClass, } from './evaluator.js';
+export { toWallParts, wallToUtcMs, wallRoundTrips, tzOffsetMs, isValidTimeZone, type WallParts, } from './timezone.js';
+export { ScheduleStore, SCHEDULER_SCHEMA_SQL, newJobId, newRunId, idempotencyKeyFor, type SchedulerRunRecord, type SchedulerDeliveryRecord, type DeliveryOutcome, type ClaimFire, type ClaimResult, } from './store.js';
+export { ScheduleRegistry, validateSpec, buildClaimFires, MAX_SCHEDULES_PER_PRINCIPAL, MAX_NAME_LENGTH, MAX_PROMPT_LENGTH, type ValidatedSpec, type RegistryOptions, } from './registry.js';
+export { SchedulerRunner, type RunnerOptions, type TickStats, } from './runner.js';
+export { SchedulerError, createAuthenticatedContext, assertAuthenticatedContext, unauthorized, invalidSpec, notFound, limitExceeded, invalidState, storageError, type AuthenticatedContext, type ConcurrencyPolicy, type MissedRunPolicy, type RunStatus, type SchedulerJob, type ScheduleSpec, type SchedulerAuthorizer, type TurnSubmitter, type WallClock, type SchedulerErrorCode, } from './types.js';

package/dist/node_modules/@boombot/core/scheduler/index.js

@@ -0,0 +1,15 @@
+/**
+ * @boombot/core — durable cron/heartbeat scheduling for the
+ * BoomBot harness layer.
+ *
+ * Public surface: registry (management plane), runner (execution plane),
+ * cron parser/evaluator, SQLite store, and the narrow ports the host must
+ * wire (`SchedulerAuthorizer`, `TurnSubmitter`).
+ */
+export { parseCron, validateCronExpression, matchesCron, MAX_CRON_LENGTH, } from './cron.js';
+export { computeNextFire, isUnsatisfiableCron, classifyMisfire, } from './evaluator.js';
+export { toWallParts, wallToUtcMs, wallRoundTrips, tzOffsetMs, isValidTimeZone, } from './timezone.js';
+export { ScheduleStore, SCHEDULER_SCHEMA_SQL, newJobId, newRunId, idempotencyKeyFor, } from './store.js';
+export { ScheduleRegistry, validateSpec, buildClaimFires, MAX_SCHEDULES_PER_PRINCIPAL, MAX_NAME_LENGTH, MAX_PROMPT_LENGTH, } from './registry.js';
+export { SchedulerRunner, } from './runner.js';
+export { SchedulerError, createAuthenticatedContext, assertAuthenticatedContext, unauthorized, invalidSpec, notFound, limitExceeded, invalidState, storageError, } from './types.js';

package/dist/node_modules/@boombot/core/scheduler/registry.d.ts

@@ -0,0 +1,81 @@
+import { type ClaimFire, type ClaimResult, type ScheduleStore } from './store.js';
+import { type AuthenticatedContext, type ConcurrencyPolicy, type MissedRunPolicy, type SchedulerAuthorizer, type SchedulerJob, type ScheduleSpec, type WallClock } from './types.js';
+export declare const MAX_SCHEDULES_PER_PRINCIPAL = 100;
+export declare const MAX_NAME_LENGTH = 100;
+export declare const MAX_PROMPT_LENGTH = 4000;
+/** New schedules must fire within this horizon, else the spec is rejected. */
+export declare const MAX_SCHEDULE_HORIZON_MS: number;
+export interface ValidatedSpec {
+    readonly name: string;
+    readonly cronExpr: string;
+    readonly timezone: string;
+    readonly promptText: string;
+    readonly enabled: boolean;
+    readonly concurrencyPolicy: ConcurrencyPolicy;
+    readonly missedRunPolicy: MissedRunPolicy;
+    readonly maxCatchUp: number;
+    readonly maxAttempts: number;
+    readonly baseRetryDelayMs: number;
+    readonly maxRetryDelayMs: number;
+}
+export declare function validateSpec(spec: ScheduleSpec, nowMs: number): ValidatedSpec;
+export interface RegistryOptions {
+    readonly authorizer: SchedulerAuthorizer;
+    readonly clock?: WallClock;
+    readonly maxSchedulesPerPrincipal?: number;
+}
+export declare class ScheduleRegistry {
+    private readonly store;
+    private readonly authorizer;
+    private readonly clock;
+    private readonly maxSchedulesPerPrincipal;
+    constructor(store: ScheduleStore, options: RegistryOptions);
+    private requireCanManage;
+    /**
+     * Resolve the caller: an `AuthenticatedContext` minted by the host authN
+     * layer (preferred), or a raw principal-id string (deprecated escape
+     * hatch — see overload docs).
+     */
+    private callerPrincipalId;
+    /**
+     * @deprecated SECURITY: passing a raw `principalId` string trusts a
+     * caller-supplied principal-id with no binding to the authenticated caller
+     * (confused-deputy gap). Kept for backward compatibility only.
+     *
+     * HOST INTEGRATION (MUST): pass an `AuthenticatedContext` minted via
+     * `createAuthenticatedContext()` from the Gateway's verified session/auth
+     * context instead. The string MUST be the authenticated principal id —
+     * never user input, a request header, or plugin-supplied data.
+     */
+    create(context: AuthenticatedContext | string, spec: ScheduleSpec): Promise<SchedulerJob>;
+    /**
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    update(context: AuthenticatedContext | string, jobId: string, patch: Partial<ScheduleSpec>): Promise<SchedulerJob>;
+    /**
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    remove(context: AuthenticatedContext | string, jobId: string): Promise<void>;
+    /**
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    setEnabled(context: AuthenticatedContext | string, jobId: string, enabled: boolean): Promise<SchedulerJob>;
+    /**
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    get(context: AuthenticatedContext | string, jobId: string): Promise<SchedulerJob>;
+    /**
+     * Lists only the caller's own schedules (least privilege).
+     *
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    list(context: AuthenticatedContext | string): Promise<SchedulerJob[]>;
+}
+/** Build claim fires for a set of fire-time ISO strings. */
+export declare function buildClaimFires(job: SchedulerJob, fireTimesIso: readonly string[]): ClaimFire[];
+export type { ClaimResult };

package/dist/node_modules/@boombot/core/scheduler/registry.js

@@ -0,0 +1,263 @@
+/**
+ * Schedule registry: the management-plane API (`create`/`update`/`remove`/
+ * `enable`/`disable`/`list`). All input is validated here — the trust
+ * boundary — before anything reaches storage.
+ */
+import { parseCron } from './cron.js';
+import { computeNextFire, isUnsatisfiableCron } from './evaluator.js';
+import { idempotencyKeyFor, newJobId, } from './store.js';
+import { isValidTimeZone } from './timezone.js';
+import { assertAuthenticatedContext, invalidSpec, notFound, unauthorized, } from './types.js';
+export const MAX_SCHEDULES_PER_PRINCIPAL = 100;
+export const MAX_NAME_LENGTH = 100;
+export const MAX_PROMPT_LENGTH = 4000;
+/** New schedules must fire within this horizon, else the spec is rejected. */
+export const MAX_SCHEDULE_HORIZON_MS = 9 * 365 * 24 * 60 * 60 * 1000;
+const CONCURRENCY_POLICIES = new Set(['forbid', 'allow', 'replace']);
+const MISSED_RUN_POLICIES = new Set(['skip', 'run_once', 'catch_up_bounded']);
+function asIso(ms) {
+    return new Date(ms).toISOString();
+}
+function validateInt(value, name, min, max, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) {
+        throw invalidSpec(`${name} must be an integer in [${min}, ${max}]`);
+    }
+    return value;
+}
+export function validateSpec(spec, nowMs) {
+    if (typeof spec !== 'object' || spec === null)
+        throw invalidSpec('spec must be an object');
+    const name = spec.name;
+    if (typeof name !== 'string' || name.trim().length === 0 || name.length > MAX_NAME_LENGTH) {
+        throw invalidSpec(`name must be a non-empty string up to ${MAX_NAME_LENGTH} chars`);
+    }
+    if (typeof spec.cron !== 'string')
+        throw invalidSpec('cron must be a string');
+    const schedule = parseCron(spec.cron); // throws invalidSpec
+    // SECURITY FIX (unsatisfiable-cron CPU burn): reject statically-impossible
+    // day-of-month/month combinations BEFORE the expensive next-fire search —
+    // and before the quota check — so a hostile spec costs microseconds, not
+    // ~2s of event-loop CPU.
+    if (isUnsatisfiableCron(schedule)) {
+        throw invalidSpec('cron expression is unsatisfiable: no selected month contains the given day-of-month');
+    }
+    if (typeof spec.timezone !== 'string' || !isValidTimeZone(spec.timezone)) {
+        throw invalidSpec(`unknown IANA timezone: ${String(spec.timezone).slice(0, 64)}`);
+    }
+    if (typeof spec.promptText !== 'string' ||
+        spec.promptText.length === 0 ||
+        spec.promptText.length > MAX_PROMPT_LENGTH) {
+        throw invalidSpec(`promptText must be 1..${MAX_PROMPT_LENGTH} chars`);
+    }
+    const concurrencyPolicy = spec.concurrencyPolicy ?? 'forbid';
+    if (!CONCURRENCY_POLICIES.has(concurrencyPolicy)) {
+        throw invalidSpec(`unknown concurrencyPolicy: ${String(spec.concurrencyPolicy).slice(0, 32)}`);
+    }
+    const missedRunPolicy = spec.missedRunPolicy ?? 'skip';
+    if (!MISSED_RUN_POLICIES.has(missedRunPolicy)) {
+        throw invalidSpec(`unknown missedRunPolicy: ${String(spec.missedRunPolicy).slice(0, 32)}`);
+    }
+    const maxCatchUp = validateInt(spec.maxCatchUp, 'maxCatchUp', 1, 100, 3);
+    const maxAttempts = validateInt(spec.maxAttempts, 'maxAttempts', 1, 10, 3);
+    const baseRetryDelayMs = validateInt(spec.baseRetryDelayMs, 'baseRetryDelayMs', 100, 3600000, 5000);
+    const maxRetryDelayMs = validateInt(spec.maxRetryDelayMs, 'maxRetryDelayMs', 1000, 86400000, 300000);
+    if (maxRetryDelayMs < baseRetryDelayMs) {
+        throw invalidSpec('maxRetryDelayMs must be >= baseRetryDelayMs');
+    }
+    const enabled = spec.enabled ?? true;
+    if (typeof enabled !== 'boolean')
+        throw invalidSpec('enabled must be a boolean');
+    // The schedule must resolve to a fire time within the horizon.
+    const nextFire = computeNextFire(schedule, nowMs, spec.timezone);
+    if (nextFire === undefined || nextFire - nowMs > MAX_SCHEDULE_HORIZON_MS) {
+        throw invalidSpec('cron expression never fires within the supported horizon');
+    }
+    return {
+        name: name.trim(),
+        cronExpr: spec.cron.trim().replace(/\s+/g, ' '),
+        timezone: spec.timezone,
+        promptText: spec.promptText,
+        enabled,
+        concurrencyPolicy: concurrencyPolicy,
+        missedRunPolicy: missedRunPolicy,
+        maxCatchUp,
+        maxAttempts,
+        baseRetryDelayMs,
+        maxRetryDelayMs,
+    };
+}
+function systemClock() {
+    return { now: () => Date.now() };
+}
+export class ScheduleRegistry {
+    store;
+    authorizer;
+    clock;
+    maxSchedulesPerPrincipal;
+    constructor(store, options) {
+        this.store = store;
+        this.authorizer = options.authorizer;
+        this.clock = options.clock ?? systemClock();
+        this.maxSchedulesPerPrincipal = options.maxSchedulesPerPrincipal ?? MAX_SCHEDULES_PER_PRINCIPAL;
+    }
+    async requireCanManage(principalId) {
+        const ok = await this.authorizer.canManage(principalId);
+        if (!ok)
+            throw unauthorized(`principal ${principalId} may not manage schedules`);
+    }
+    /**
+     * Resolve the caller: an `AuthenticatedContext` minted by the host authN
+     * layer (preferred), or a raw principal-id string (deprecated escape
+     * hatch — see overload docs).
+     */
+    callerPrincipalId(context) {
+        if (typeof context === 'string')
+            return context;
+        assertAuthenticatedContext(context);
+        return context.principalId;
+    }
+    /**
+     * @deprecated SECURITY: passing a raw `principalId` string trusts a
+     * caller-supplied principal-id with no binding to the authenticated caller
+     * (confused-deputy gap). Kept for backward compatibility only.
+     *
+     * HOST INTEGRATION (MUST): pass an `AuthenticatedContext` minted via
+     * `createAuthenticatedContext()` from the Gateway's verified session/auth
+     * context instead. The string MUST be the authenticated principal id —
+     * never user input, a request header, or plugin-supplied data.
+     */
+    async create(context, spec) {
+        const principalId = this.callerPrincipalId(context);
+        await this.requireCanManage(principalId);
+        const nowMs = this.clock.now();
+        const validated = validateSpec(spec, nowMs);
+        const schedule = parseCron(validated.cronExpr);
+        const nextRunAt = validated.enabled
+            ? asIso(computeNextFire(schedule, nowMs, validated.timezone))
+            : null;
+        const job = {
+            id: newJobId(),
+            ownerPrincipalId: principalId,
+            ...validated,
+            nextRunAt,
+            createdAt: asIso(nowMs),
+            updatedAt: asIso(nowMs),
+        };
+        // Quota count + insert are one BEGIN IMMEDIATE transaction inside the
+        // store (multi-process check-then-act fix).
+        this.store.insertJobWithQuotaCheck(job, this.maxSchedulesPerPrincipal);
+        return job;
+    }
+    /**
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    async update(context, jobId, patch) {
+        const principalId = this.callerPrincipalId(context);
+        await this.requireCanManage(principalId);
+        const existing = this.store.getJob(jobId);
+        if (existing === undefined)
+            throw notFound(`schedule ${jobId} not found`);
+        if (existing.ownerPrincipalId !== principalId)
+            throw unauthorized('schedule belongs to another principal');
+        const nowMs = this.clock.now();
+        const merged = {
+            name: patch.name ?? existing.name,
+            cron: patch.cron ?? existing.cronExpr,
+            timezone: patch.timezone ?? existing.timezone,
+            promptText: patch.promptText ?? existing.promptText,
+            enabled: patch.enabled ?? existing.enabled,
+            concurrencyPolicy: patch.concurrencyPolicy ?? existing.concurrencyPolicy,
+            missedRunPolicy: patch.missedRunPolicy ?? existing.missedRunPolicy,
+            maxCatchUp: patch.maxCatchUp ?? existing.maxCatchUp,
+            maxAttempts: patch.maxAttempts ?? existing.maxAttempts,
+            baseRetryDelayMs: patch.baseRetryDelayMs ?? existing.baseRetryDelayMs,
+            maxRetryDelayMs: patch.maxRetryDelayMs ?? existing.maxRetryDelayMs,
+        };
+        const validated = validateSpec(merged, nowMs);
+        const scheduleChanged = validated.cronExpr !== existing.cronExpr || validated.timezone !== existing.timezone;
+        const schedule = parseCron(validated.cronExpr);
+        const nextRunAt = scheduleChanged
+            ? validated.enabled
+                ? asIso(computeNextFire(schedule, nowMs, validated.timezone))
+                : null
+            : validated.enabled
+                ? (existing.nextRunAt ?? asIso(computeNextFire(schedule, nowMs, validated.timezone)))
+                : null;
+        const updated = this.store.updateJob(jobId, {
+            name: validated.name,
+            cronExpr: validated.cronExpr,
+            timezone: validated.timezone,
+            promptText: validated.promptText,
+            enabled: validated.enabled,
+            concurrencyPolicy: validated.concurrencyPolicy,
+            missedRunPolicy: validated.missedRunPolicy,
+            maxCatchUp: validated.maxCatchUp,
+            maxAttempts: validated.maxAttempts,
+            baseRetryDelayMs: validated.baseRetryDelayMs,
+            maxRetryDelayMs: validated.maxRetryDelayMs,
+            nextRunAt,
+            updatedAt: asIso(nowMs),
+        });
+        if (updated === undefined)
+            throw notFound(`schedule ${jobId} not found`);
+        return updated;
+    }
+    /**
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    async remove(context, jobId) {
+        const principalId = this.callerPrincipalId(context);
+        await this.requireCanManage(principalId);
+        const existing = this.store.getJob(jobId);
+        if (existing === undefined)
+            throw notFound(`schedule ${jobId} not found`);
+        if (existing.ownerPrincipalId !== principalId)
+            throw unauthorized('schedule belongs to another principal');
+        this.store.deleteJob(jobId); // cascades runs
+    }
+    /**
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    async setEnabled(context, jobId, enabled) {
+        // Resolve once here; update() re-resolves idempotently.
+        return this.update(this.callerPrincipalId(context), jobId, { enabled });
+    }
+    /**
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    async get(context, jobId) {
+        const principalId = this.callerPrincipalId(context);
+        await this.requireCanManage(principalId);
+        const job = this.store.getJob(jobId);
+        if (job === undefined)
+            throw notFound(`schedule ${jobId} not found`);
+        if (job.ownerPrincipalId !== principalId)
+            throw unauthorized('schedule belongs to another principal');
+        return job;
+    }
+    /**
+     * Lists only the caller's own schedules (least privilege).
+     *
+     * @deprecated SECURITY: see `create()` — prefer `AuthenticatedContext`.
+     * The string MUST be the authenticated principal id.
+     */
+    async list(context) {
+        const principalId = this.callerPrincipalId(context);
+        await this.requireCanManage(principalId);
+        return this.store.listByOwner(principalId);
+    }
+}
+/** Build claim fires for a set of fire-time ISO strings. */
+export function buildClaimFires(job, fireTimesIso) {
+    return fireTimesIso.map((scheduledFireAt) => ({
+        runId: `run_${job.id}_${scheduledFireAt}`,
+        idempotencyKey: idempotencyKeyFor(job.id, scheduledFireAt),
+        scheduledFireAt,
+    }));
+}

package/dist/node_modules/@boombot/core/scheduler/runner.d.ts

@@ -0,0 +1,59 @@
+import { type ScheduleStore } from './store.js';
+import { type SchedulerJob, type TurnSubmitter, type WallClock } from './types.js';
+export interface RunnerOptions {
+    readonly store: ScheduleStore;
+    readonly submitter: TurnSubmitter;
+    readonly clock?: WallClock;
+    readonly runnerId?: string;
+    /** Default 1000ms. */
+    readonly tickIntervalMs?: number;
+    /** Default 60s: how late a fire may be before it counts as misfired. */
+    readonly misfireGraceMs?: number;
+    /** Default 60s: claim lease before a crashed runner's runs are recovered. */
+    readonly leaseMs?: number;
+    /** Default 5s: monotonic bound for the drive phase of one tick. */
+    readonly maxTickDurationMs?: number;
+    /** Default 100. */
+    readonly claimBatchSize?: number;
+    /** Jitter source for backoff; injectable for deterministic tests. */
+    readonly jitter?: () => number;
+    readonly onError?: (error: unknown, phase: 'recover' | 'claim' | 'drive') => void;
+}
+export interface TickStats {
+    readonly recovered: number;
+    readonly claimed: number;
+    readonly skippedConcurrency: number;
+    readonly driven: number;
+    readonly completed: number;
+    readonly retried: number;
+    readonly deadLettered: number;
+}
+export declare class SchedulerRunner {
+    private readonly store;
+    private readonly submitter;
+    private readonly clock;
+    private readonly runnerId;
+    private readonly tickIntervalMs;
+    private readonly misfireGraceMs;
+    private readonly leaseMs;
+    private readonly maxTickDurationMs;
+    private readonly claimBatchSize;
+    private readonly jitter;
+    private readonly onError;
+    private timer;
+    private tickInFlight;
+    private stopped;
+    constructor(options: RunnerOptions);
+    get id(): string;
+    /** Start the non-overlapping tick chain. */
+    start(): void;
+    /** Stop ticking; resolves when the in-flight tick (if any) settles. */
+    stop(): Promise<void>;
+    private scheduleNext;
+    /** Run one full tick. Exposed for tests; `start()` uses it internally. */
+    tickOnce(nowMs?: number): Promise<TickStats>;
+    private claimJob;
+    private driveRun;
+    /** Bounded exponential backoff with jitter. */
+    backoffDelay(job: SchedulerJob, attempt: number): number;
+}