/**
 * Orchestrator scheduled-job wrapper.
 *
 * Mirrors `packages/platform/src/queue/scheduled-job.ts` in observable
 * surface (5 Prometheus metrics + structured logs + audit row on
 * failure) but uses `setInterval` instead of pg-boss — the orchestrator
 * has no pg-boss dependency and we're not adding one.
 *
 * All future orchestrator periodic jobs MUST use this wrapper — per
 * CLAUDE.md "no workarounds", the legacy setInterval call sites in
 * queue/cleanup.ts and secrets/cleanup.ts migrate in the same phase
 * they'd otherwise be updated.
 *
 * `triggerNow()` on the returned handle forces one off-cadence tick
 * (used by the admin `/api/v1/admin/scheduled-jobs/:name/trigger`
 * endpoint and by E2E harnesses). It does NOT reset the interval
 * timer — a real tick still fires at the scheduled cadence after.
 */
import { z } from 'zod';
import type { Kysely } from 'kysely';
import type { Database } from '../db/types.js';
/**
 * All registered orchestrator scheduled-job names. Adding a new
 * periodic job MUST add its name here before it can register.
 */
export declare const OrchestratorScheduledJobName: z.ZodEnum<{
    cleanup: "cleanup";
    "orphan-secret-cleanup": "orphan-secret-cleanup";
    "token-cleanup": "token-cleanup";
    "cold-store-archive": "cold-store-archive";
    "cold-store-purge": "cold-store-purge";
}>;
export type OrchestratorScheduledJobName = z.infer<typeof OrchestratorScheduledJobName>;
/** Access-log action for a manually triggered off-cadence tick. */
export declare const ACCESS_LOG_ACTION_TRIGGER = "scheduled_job.trigger";
export interface OrchestratorScheduledJobOptions {
    name: OrchestratorScheduledJobName;
    /** Tick cadence. Must be > 0. */
    intervalMs: number;
    /** Handler called per tick. Exceptions are caught and metered. */
    handler: () => Promise<void>;
    /**
     * Orchestrator instance ID — appears on failure access-log rows as
     * `actor_id` alongside `actor_type='system'`.
     */
    instanceId: string;
    /** DB used for failure audit rows. If omitted, failures are logs-only. */
    db?: Kysely<Database>;
    /** Routing key for failure access-log partitioning (null = not scoped). */
    routingKey?: string;
    /** Fire one tick immediately on register. Defaults to false. */
    runOnStart?: boolean;
    /** `timer.unref()` — allows process exit while scheduled. Defaults to true. */
    unref?: boolean;
}
export interface OrchestratorScheduledJobHandle {
    readonly name: OrchestratorScheduledJobName;
    /** Clears the interval. Safe to call multiple times. */
    stop(): void;
    /**
     * Force one off-cadence tick and await it (success or failure).
     * Returns the tick's outcome so E2E and admin routes can report it.
     */
    triggerNow(): Promise<{
        ok: boolean;
        durationMs: number;
        error?: string;
    }>;
}
/**
 * Readonly snapshot of per-job metric state. Used by the admin
 * `/api/v1/admin/scheduled-jobs` route to surface last-run info.
 */
export declare function getOrchestratorJobMetricState(): ReadonlyMap<string, {
    consecutiveFailures: number;
    lastSuccessAt: Date | null;
    lastFailureAt: Date | null;
}>;
/**
 * Look up a registered scheduled job's handle by name. Returns
 * `undefined` if the job isn't registered on this instance. Used by
 * the admin trigger-now endpoint.
 */
export declare function findOrchestratorScheduledJob(name: OrchestratorScheduledJobName): OrchestratorScheduledJobHandle | undefined;
/**
 * Clear the scheduled-job registry. Intended for tests only —
 * production code should keep a stable set of registered jobs.
 */
export declare function __resetOrchestratorScheduledJobsForTesting(): void;
export declare function registerOrchestratorScheduledJob(opts: OrchestratorScheduledJobOptions): OrchestratorScheduledJobHandle;
//# sourceMappingURL=scheduled-job.d.ts.map