@zintrust/core 0.1.41 → 0.1.43

package/src/scheduler/ScheduleHttpGateway.js

@@ -0,0 +1,196 @@
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { Router } from '../routes/Router.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { SchedulerRuntime } from './SchedulerRuntime.js';
+import { SignedRequest } from '../security/SignedRequest.js';
+const nonces = new Map();
+const nowMs = () => Date.now();
+const normalizePath = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '/api/_sys/schedule/rpc';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+const parseMiddleware = (value) => value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+const readSettings = () => {
+    const configuredSecret = Env.get('SCHEDULE_HTTP_PROXY_KEY', '').trim();
+    const secret = configuredSecret === '' ? Env.APP_KEY : configuredSecret;
+    return {
+        basePath: normalizePath(Env.get('SCHEDULE_HTTP_PROXY_PATH', '/api/_sys/schedule/rpc')),
+        keyId: Env.get('SCHEDULE_HTTP_PROXY_KEY_ID', Env.APP_NAME || 'zintrust').trim(),
+        secret,
+        signingWindowMs: Env.getInt('SCHEDULE_HTTP_PROXY_MAX_SKEW_MS', 60000),
+        nonceTtlMs: Env.getInt('SCHEDULE_HTTP_PROXY_NONCE_TTL_MS', 120000),
+        middleware: parseMiddleware(Env.get('SCHEDULE_HTTP_PROXY_MIDDLEWARE', '')),
+    };
+};
+const cleanupExpiredNonces = () => {
+    const current = nowMs();
+    for (const [nonceKey, expiresAt] of nonces.entries()) {
+        if (expiresAt <= current)
+            nonces.delete(nonceKey);
+    }
+};
+// eslint-disable-next-line @typescript-eslint/require-await
+const storeNonce = async (keyId, nonce, ttlMs) => {
+    cleanupExpiredNonces();
+    const nonceKey = `${keyId}:${nonce}`;
+    if (nonces.has(nonceKey))
+        return false;
+    nonces.set(nonceKey, nowMs() + Math.max(ttlMs, 1));
+    return true;
+};
+const getBodyRecord = (req) => {
+    const body = req.getBody?.() ?? req.body;
+    if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+        return body;
+    }
+    return {};
+};
+const getRawBody = (req) => {
+    const rawText = req.context?.['rawBodyText'];
+    if (typeof rawText === 'string')
+        return rawText;
+    return JSON.stringify(getBodyRecord(req));
+};
+const toIncomingHeaders = (req) => {
+    const headers = req.getHeaders();
+    const normalize = (value) => {
+        if (Array.isArray(value))
+            return value.join(',');
+        return value;
+    };
+    return {
+        'x-zt-key-id': normalize(headers['x-zt-key-id']),
+        'x-zt-nonce': normalize(headers['x-zt-nonce']),
+        'x-zt-timestamp': normalize(headers['x-zt-timestamp']),
+        'x-zt-body-sha256': normalize(headers['x-zt-body-sha256']),
+        'x-zt-signature': normalize(headers['x-zt-signature']),
+        'content-type': normalize(headers['content-type']),
+    };
+};
+const parseRequest = (req) => {
+    const body = getBodyRecord(req);
+    const action = String(body['action'] ?? '')
+        .trim()
+        .toLowerCase();
+    const requestId = String(body['requestId'] ?? '').trim();
+    if (requestId.length === 0) {
+        throw ErrorFactory.createValidationError('requestId is required');
+    }
+    if (action !== 'list' && action !== 'run') {
+        throw ErrorFactory.createValidationError('Invalid action');
+    }
+    const payload = typeof body['payload'] === 'object' && body['payload'] !== null
+        ? body['payload']
+        : undefined;
+    return {
+        action: action,
+        requestId,
+        payload,
+    };
+};
+const ok = (requestId, result) => ({
+    ok: true,
+    requestId,
+    result,
+    error: null,
+});
+const fail = (requestId, code, message, details) => ({
+    ok: false,
+    requestId,
+    result: null,
+    error: { code, message, details },
+});
+const listSchedules = async () => {
+    const rows = await SchedulerRuntime.listWithState();
+    return rows.map(({ schedule, state }) => ({
+        name: schedule.name,
+        intervalMs: schedule.intervalMs,
+        cron: schedule.cron,
+        timezone: schedule.timezone,
+        enabled: schedule.enabled,
+        runOnStart: schedule.runOnStart,
+        state,
+    }));
+};
+const verifyRequest = async (req, bodyText, settings) => {
+    if (settings.keyId.trim() === '' || settings.secret.trim() === '') {
+        return {
+            ok: false,
+            status: 500,
+            code: 'CONFIG_ERROR',
+            message: 'Schedule HTTP gateway signing credentials are not configured',
+        };
+    }
+    const url = new URL(req.getPath(), 'http://localhost');
+    const verifyResult = await SignedRequest.verify({
+        method: req.getMethod(),
+        url,
+        body: bodyText,
+        headers: toIncomingHeaders(req),
+        nowMs: nowMs(),
+        windowMs: settings.signingWindowMs,
+        verifyNonce: async (keyId, nonce) => storeNonce(keyId, nonce, settings.nonceTtlMs),
+        getSecretForKeyId: (keyId) => {
+            if (keyId === settings.keyId)
+                return settings.secret;
+            return undefined;
+        },
+    });
+    if (verifyResult.ok === true)
+        return { ok: true };
+    const errorCode = 'code' in verifyResult ? verifyResult.code : 'INVALID_SIGNATURE';
+    const errorMessage = 'message' in verifyResult ? verifyResult.message : 'Invalid signature';
+    const status = errorCode === 'EXPIRED' || errorCode === 'REPLAYED' ? 401 : 403;
+    return { ok: false, status, code: errorCode, message: errorMessage };
+};
+const handleRpc = async (req, res) => {
+    const settings = readSettings();
+    const rawBody = getRawBody(req);
+    const body = getBodyRecord(req);
+    const requestId = typeof body['requestId'] === 'string' && String(body['requestId']).trim() !== ''
+        ? String(body['requestId'])
+        : 'unknown';
+    const auth = await verifyRequest(req, rawBody, settings);
+    if (auth.ok === false) {
+        res.status(auth.status).json(fail(requestId, auth.code, auth.message));
+        return;
+    }
+    const parsed = parseRequest(req);
+    try {
+        if (parsed.action === 'list') {
+            res.json(ok(parsed.requestId, await listSchedules()));
+            return;
+        }
+        const name = String(parsed.payload?.name ?? '').trim();
+        if (name.length === 0) {
+            res.status(400).json(fail(parsed.requestId, 'VALIDATION_ERROR', 'payload.name is required'));
+            return;
+        }
+        await SchedulerRuntime.runOnce(name);
+        res.json(ok(parsed.requestId, { ran: true, name }));
+    }
+    catch (error) {
+        Logger.error('Schedule RPC failed', error);
+        res.status(500).json(fail(parsed.requestId, 'INTERNAL_ERROR', 'Schedule RPC failed', {
+            message: error instanceof Error ? error.message : String(error),
+        }));
+    }
+};
+export const ScheduleHttpGateway = Object.freeze({
+    create() {
+        const settings = readSettings();
+        const options = settings.middleware.length > 0 ? { middleware: settings.middleware } : undefined;
+        return Object.freeze({
+            registerRoutes(router) {
+                Router.post(router, settings.basePath, handleRpc, options);
+            },
+        });
+    },
+});
+export default ScheduleHttpGateway;

package/src/scheduler/ScheduleRunner.d.ts

@@ -2,6 +2,7 @@
  * ScheduleRunner
  * Lightweight, zero-dependency schedule runner for long-running runtimes
  */
+import { type ScheduleRunState } from './state/ScheduleStateStore';
 import type { ISchedule, IScheduleKernel } from './types';
 type ScheduleRunner = {
     register: (schedule: ISchedule) => void;
@@ -9,6 +10,11 @@ type ScheduleRunner = {
     stop: (timeoutMs?: number) => Promise<void>;
     list: () => ISchedule[];
     runOnce: (name: string, kernel?: IScheduleKernel) => Promise<void>;
+    getState: (name: string) => Promise<ScheduleRunState | null>;
+    listStates: () => Promise<Array<{
+        name: string;
+        state: ScheduleRunState;
+    }>>;
 };
 export declare const create: () => Readonly<ScheduleRunner>;
 declare const _default: {

package/src/scheduler/ScheduleRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScheduleRunner.d.ts","sourceRoot":"","sources":["../../../src/scheduler/ScheduleRunner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAgBnE,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,SAAS,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE,CAAC;AAoKF,eAAO,MAAM,MAAM,QAAO,QAAQ,CAAC,cAAc,CAuBhD,CAAC;;kBAvBwB,QAAQ,CAAC,cAAc,CAAC;;AAyBlD,wBAA0B"}
+{"version":3,"file":"ScheduleRunner.d.ts","sourceRoot":"","sources":["../../../src/scheduler/ScheduleRunner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAkBnE,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,SAAS,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC7D,UAAU,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAAC,CAAC;CAC7E,CAAC;AA6VF,eAAO,MAAM,MAAM,QAAO,QAAQ,CAAC,cAAc,CA6BhD,CAAC;;kBA7BwB,QAAQ,CAAC,cAAc,CAAC;;AA+BlD,wBAA0B"}

package/src/scheduler/ScheduleRunner.js

@@ -4,45 +4,184 @@
  */
 import { Logger } from '../config/logger.js';
 import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { Cron } from './cron/Cron.js';
+import { InMemoryScheduleStateStore, } from './state/ScheduleStateStore.js';
+const nowMs = () => Date.now();
+const randomInt = (min, maxInclusive) => {
+    if (!Number.isFinite(min) || !Number.isFinite(maxInclusive))
+        return 0;
+    if (maxInclusive <= min)
+        return Math.floor(min);
+    return Math.floor(min + Math.random() * (maxInclusive - min + 1)); //NOSONAR
+};
+const resolveBackoffDelayMs = (state) => {
+    const policy = state.schedule.backoff;
+    if (!policy)
+        return 0;
+    const initialMs = Number.isFinite(policy.initialMs)
+        ? Math.max(0, Math.floor(policy.initialMs))
+        : 0;
+    const maxMs = Number.isFinite(policy.maxMs) ? Math.max(0, Math.floor(policy.maxMs)) : 0;
+    if (initialMs <= 0 || maxMs <= 0)
+        return 0;
+    const factor = policy.factor === undefined || !Number.isFinite(policy.factor) || policy.factor <= 1
+        ? 2
+        : policy.factor;
+    const power = Math.max(0, state.consecutiveFailures - 1);
+    const raw = initialMs * Math.pow(factor, power);
+    return Math.min(maxMs, Math.floor(raw));
+};
+const resolveJitterMs = (jitterMs) => {
+    return typeof jitterMs === 'number' && jitterMs > 0 ? randomInt(0, Math.floor(jitterMs)) : 0;
+};
+const computeBackoffDelay = (state) => {
+    if (state.schedule.enabled === false)
+        return null;
+    const backoffDelayMs = resolveBackoffDelayMs(state);
+    if (backoffDelayMs > 0) {
+        const jitter = resolveJitterMs(state.schedule.jitterMs);
+        return backoffDelayMs + jitter;
+    }
+    return null;
+};
+const computeCronDelay = (schedule) => {
+    if (typeof schedule.cron !== 'string' || schedule.cron.trim().length === 0) {
+        return null;
+    }
+    const tz = typeof schedule.timezone === 'string' && schedule.timezone.trim().length > 0
+        ? schedule.timezone
+        : 'UTC';
+    const nextAt = Cron.nextRunAtMs(nowMs(), schedule.cron, tz);
+    const baseDelay = Math.max(0, nextAt - nowMs());
+    const jitter = resolveJitterMs(schedule.jitterMs);
+    return baseDelay + jitter;
+};
+const computeIntervalDelay = (schedule) => {
+    if (typeof schedule.intervalMs !== 'number' || schedule.intervalMs <= 0) {
+        return null;
+    }
+    const base = Math.floor(schedule.intervalMs);
+    const jitter = resolveJitterMs(schedule.jitterMs);
+    return base + jitter;
+};
+const computeNextDelayMs = (state, outcome) => {
+    const schedule = state.schedule;
+    if (schedule.enabled === false)
+        return null;
+    if (outcome === 'failure') {
+        const backoffDelay = computeBackoffDelay(state);
+        if (backoffDelay !== null)
+            return backoffDelay;
+    }
+    const cronDelay = computeCronDelay(schedule);
+    if (cronDelay !== null)
+        return cronDelay;
+    const intervalDelay = computeIntervalDelay(schedule);
+    if (intervalDelay !== null)
+        return intervalDelay;
+    return null;
+};
+const clearTimer = (state) => {
+    if (state.timeoutId !== undefined) {
+        globalThis.clearTimeout(state.timeoutId);
+        state.timeoutId = undefined;
+    }
+};
+const scheduleNext = (state, kernel, invoke, outcome, store) => {
+    clearTimer(state);
+    const delay = computeNextDelayMs(state, outcome);
+    if (delay === null)
+        return;
+    const nextRunAt = nowMs() + delay;
+    void store.set(state.schedule.name, {
+        nextRunAt,
+        consecutiveFailures: state.consecutiveFailures,
+    });
+    state.timeoutId = globalThis.setTimeout(() => {
+        void runOnceAndReschedule(state, kernel, invoke, store);
+    }, delay);
+};
+const runOnceAndReschedule = async (state, kernel, invoke, store) => {
+    const outcome = await invoke(state, kernel);
+    scheduleNext(state, kernel, invoke, outcome, store);
+};
 const createRegister = (runner, invokeHandler) => (schedule) => {
-    if (runner.schedules.has(schedule.name)) {
+    const existing = runner.schedules.get(schedule.name);
+    if (existing !== undefined) {
         Logger.warn(`Schedule replaced: ${schedule.name}`);
+        // Reuse the same internal state to avoid leaving old timers/reschedule loops behind.
+        existing.schedule = schedule;
+        // If disabled, ensure any pending timer is cleared.
+        if (schedule.enabled === false) {
+            clearTimer(existing);
+            return;
+        }
+        // If a run is currently in progress, let it finish and reschedule naturally.
+        if (existing.isRunning) {
+            return;
+        }
+        // If schedules are already started, apply the new schedule immediately.
+        if (runner.started) {
+            if (schedule.runOnStart === true) {
+                void runOnceAndReschedule(existing, runner.kernel, invokeHandler, runner.store);
+                return;
+            }
+            scheduleNext(existing, runner.kernel, invokeHandler, 'success', runner.store);
+        }
+        return;
     }
     const state = {
         schedule,
         isRunning: false,
+        consecutiveFailures: 0,
     };
     runner.schedules.set(schedule.name, state);
     // If schedules are already started, register should take effect immediately.
     if (runner.started && schedule.enabled !== false) {
         if (schedule.runOnStart === true) {
-            void invokeHandler(state, runner.kernel);
-        }
-        if (typeof schedule.intervalMs === 'number' && schedule.intervalMs > 0) {
-            state.intervalId = globalThis.setInterval(() => {
-                void invokeHandler(state, runner.kernel);
-            }, schedule.intervalMs);
+            void runOnceAndReschedule(state, runner.kernel, invokeHandler, runner.store);
+            return;
         }
+        // Auto scheduling
+        scheduleNext(state, runner.kernel, invokeHandler, 'success', runner.store);
     }
 };
-const createInvokeHandler = () => async (state, kernel) => {
+const createInvokeHandler = (store) => async (state, kernel) => {
     if (state.isRunning) {
         Logger.info(`Skipping overlapping run for schedule: ${state.schedule.name}`);
-        return;
+        return 'failure';
     }
     state.isRunning = true;
     try {
         const handlerPromise = Promise.resolve()
             .then(async () => state.schedule.handler(kernel))
             .then(() => {
-            state.lastRunAt = Date.now();
+            state.lastRunAt = nowMs();
+            state.consecutiveFailures = 0;
+            void store.set(state.schedule.name, {
+                lastRunAt: state.lastRunAt,
+                lastSuccessAt: state.lastRunAt,
+                lastErrorAt: undefined,
+                lastErrorMessage: undefined,
+                consecutiveFailures: state.consecutiveFailures,
+            });
+            return 'success';
         })
             .catch((error) => {
+            state.consecutiveFailures = Math.min(1_000_000, state.consecutiveFailures + 1);
+            const errMsg = error instanceof Error ? error.message : String(error);
+            const at = nowMs();
+            void store.set(state.schedule.name, {
+                lastRunAt: at,
+                lastErrorAt: at,
+                lastErrorMessage: errMsg,
+                consecutiveFailures: state.consecutiveFailures,
+            });
             Logger.error(`Schedule '${state.schedule.name}' failed:`, error);
-        })
-            .then(() => undefined);
-        state.runningPromise = handlerPromise;
-        await handlerPromise;
+            return 'failure';
+        });
+        state.runningPromise = handlerPromise.then(() => undefined);
+        return await handlerPromise;
     }
     finally {
         state.isRunning = false;
@@ -59,16 +198,12 @@ const createStart = (runner, invokeHandler) => (kernel) => {
         if (schedule.enabled === false)
             continue;
         if (schedule.runOnStart === true) {
-            // fire-and-forget (handled by invokeHandler which logs errors)
-            void invokeHandler(state, kernel);
-        }
-        if (typeof schedule.intervalMs === 'number' && schedule.intervalMs > 0) {
-            const id = globalThis.setInterval(() => {
-                // fire and forget invocation; overlapping runs are protected inside
-                void invokeHandler(state, kernel);
-            }, schedule.intervalMs);
-            state.intervalId = id;
+            // fire-and-forget; next scheduling happens after the handler completes
+            void runOnceAndReschedule(state, kernel, invokeHandler, runner.store);
+            continue;
         }
+        // Auto scheduling
+        scheduleNext(state, kernel, invokeHandler, 'success', runner.store);
     }
 };
 const createStop = (runner) => async () => {
@@ -76,12 +211,9 @@ const createStop = (runner) => async () => {
         return;
     runner.started = false;
     runner.kernel = undefined;
-    // Clear intervals
+    // Clear timers
     for (const [, state] of runner.schedules) {
-        if (state.intervalId !== undefined) {
-            globalThis.clearInterval(state.intervalId);
-            state.intervalId = undefined;
-        }
+        clearTimer(state);
     }
     // Await running handlers (runningPromise is guaranteed not to reject)
     const running = [];
@@ -136,20 +268,25 @@ export const create = () => {
         schedules: new Map(),
         started: false,
         kernel: undefined,
+        store: InMemoryScheduleStateStore.create(),
     };
-    const invokeHandler = createInvokeHandler();
+    const invokeHandler = createInvokeHandler(runner.store);
     const register = createRegister(runner, invokeHandler);
     const start = createStart(runner, invokeHandler);
     const stopRaw = createStop(runner);
     const stop = createStopWithTimeout(stopRaw);
     const list = createList(runner);
     const runOnce = createRunOnce(runner, invokeHandler);
+    const getState = async (name) => runner.store.get(name);
+    const listStates = async () => runner.store.list();
     return Object.freeze({
         register,
         start,
         stop,
         list,
         runOnce,
+        getState,
+        listStates,
     });
 };
 export default { create };

package/src/scheduler/SchedulerRuntime.d.ts

@@ -0,0 +1,15 @@
+import type { ScheduleRunState } from './state/ScheduleStateStore';
+import type { ISchedule, IScheduleKernel } from './types';
+export declare const SchedulerRuntime: Readonly<{
+    registerMany: (schedules: ReadonlyArray<ISchedule>, source?: "core" | "app") => void;
+    start(kernel?: IScheduleKernel): void;
+    stop(timeoutMs?: number): Promise<void>;
+    list(): ISchedule[];
+    listWithState(): Promise<Array<{
+        schedule: ISchedule;
+        state: ScheduleRunState | null;
+    }>>;
+    runOnce(name: string, kernel?: IScheduleKernel): Promise<void>;
+}>;
+export default SchedulerRuntime;
+//# sourceMappingURL=SchedulerRuntime.d.ts.map

package/src/scheduler/SchedulerRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchedulerRuntime.d.ts","sourceRoot":"","sources":["../../../src/scheduler/SchedulerRuntime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAmDnE,eAAO,MAAM,gBAAgB;8BAzBhB,aAAa,CAAC,SAAS,CAAC,WAC3B,MAAM,GAAG,KAAK,KACrB,IAAI;mBAyBU,eAAe,GAAG,IAAI;qBAqBd,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAOrC,SAAS,EAAE;qBAGI,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;kBAkB1E,MAAM,WAAW,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;EAGtC,CAAC;AAEjC,eAAe,gBAAgB,CAAC"}

package/src/scheduler/SchedulerRuntime.js

@@ -0,0 +1,79 @@
+import { Logger } from '../config/logger.js';
+import { createScheduleRunner } from './index.js';
+import { SchedulerLeader } from './leader/SchedulerLeader.js';
+const state = {
+    runner: createScheduleRunner(),
+    registered: new Map(),
+    leader: SchedulerLeader.create(),
+    leaderStarted: false,
+};
+const registerMany = (schedules, source = 'core') => {
+    for (const schedule of schedules) {
+        if (schedule === undefined || schedule === null || typeof schedule.name !== 'string')
+            continue;
+        const name = schedule.name.trim();
+        if (name.length === 0)
+            continue;
+        const existing = state.registered.get(name);
+        // If app already registered, it always wins.
+        if (existing === 'app')
+            continue;
+        // Prevent repeated registrations from the same source.
+        if (existing === source)
+            continue;
+        if (existing === 'core' && source === 'app') {
+            Logger.info('Schedule overridden by app/Schedules', { name });
+        }
+        state.registered.set(name, source);
+        state.runner.register(schedule);
+    }
+};
+export const SchedulerRuntime = Object.freeze({
+    registerMany,
+    start(kernel) {
+        // If leader mode is enabled, only the leader instance starts timers.
+        if (state.leader.isEnabled()) {
+            if (state.leaderStarted)
+                return;
+            state.leaderStarted = true;
+            state.leader.start({
+                onBecameLeader: () => {
+                    state.runner.start(kernel);
+                },
+                onLostLeadership: () => {
+                    // Best-effort stop; leadership transitions should not crash the process.
+                    void state.runner.stop();
+                },
+            });
+            return;
+        }
+        state.runner.start(kernel);
+    },
+    async stop(timeoutMs) {
+        if (state.leaderStarted) {
+            state.leaderStarted = false;
+            await state.leader.stop();
+        }
+        await state.runner.stop(timeoutMs);
+    },
+    list() {
+        return state.runner.list();
+    },
+    async listWithState() {
+        const schedules = state.runner.list();
+        const getState = state.runner
+            .getState;
+        if (typeof getState !== 'function') {
+            return schedules.map((schedule) => ({ schedule, state: null }));
+        }
+        const rows = await Promise.all(schedules.map(async (schedule) => {
+            const stateRow = (await getState(schedule.name));
+            return { schedule, state: stateRow };
+        }));
+        return rows;
+    },
+    async runOnce(name, kernel) {
+        await state.runner.runOnce(name, kernel);
+    },
+});
+export default SchedulerRuntime;

package/src/scheduler/cron/Cron.d.ts

@@ -0,0 +1,19 @@
+type CronAllowed = Readonly<{
+    any: true;
+}> | Readonly<{
+    any: false;
+    values: ReadonlySet<number>;
+}>;
+export type CronSpec = Readonly<{
+    minute: CronAllowed;
+    hour: CronAllowed;
+    dayOfMonth: CronAllowed;
+    month: CronAllowed;
+    dayOfWeek: CronAllowed;
+}>;
+export declare const Cron: Readonly<{
+    parse(expr: string): CronSpec;
+    nextRunAtMs(nowMs: number, expr: string, timeZone?: string): number;
+}>;
+export default Cron;
+//# sourceMappingURL=Cron.d.ts.map

package/src/scheduler/cron/Cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cron.d.ts","sourceRoot":"","sources":["../../../../src/scheduler/cron/Cron.ts"],"names":[],"mappings":"AAEA,KAAK,WAAW,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,CAAC,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAC;AAEnG,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC9B,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,WAAW,CAAC;IACxB,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,WAAW,CAAC;CACxB,CAAC,CAAC;AA0LH,eAAO,MAAM,IAAI;gBACH,MAAM,GAAG,QAAQ;uBA+BV,MAAM,QAAQ,MAAM,aAAY,MAAM,GAAW,MAAM;EAoB1E,CAAC;AAEH,eAAe,IAAI,CAAC"}