@raybase/core 0.0.2 → 0.3.4

package/dist/jobs.d.ts

@@ -0,0 +1,796 @@
+import { z } from "zod";
+import { type ActionPolicyExpression, type RaybaseAction, type RaybaseActionRowAuthorization } from "./actions.js";
+import type { RaybaseAgentInvocationRuntime } from "./agent.js";
+import type { RaybaseAuditContextEvent } from "./audit.js";
+import type { RaybaseActionDataClient } from "./data-client.js";
+import type { RaybaseAI } from "./ai.js";
+import type { RaybaseAuthContextRuntime } from "./auth.js";
+import { type JsonSchemaObject } from "./json-schema.js";
+import type { RaybaseNotificationsRuntime } from "./notifications.js";
+import type { PolicyExpression, RaybaseUser } from "./policies.js";
+import { type RaybaseJobPrincipal } from "./principal.js";
+import type { RaybaseSchema } from "./schema.js";
+import type { RaybaseRuntimeSettings, RaybaseSettingsDefinitions } from "./settings.js";
+export { principalToStored } from "./principal.js";
+export type { RaybaseJobPrincipal, RaybaseStoredPrincipal } from "./principal.js";
+export type JobJsonSchemaObject = JsonSchemaObject;
+export type JobPolicyExpression = PolicyExpression;
+export type JobRetryConfig = {
+    maxAttempts?: number;
+    backoff?: "fixed" | "exponential" | {
+        kind: "fixed" | "exponential";
+        delay?: string | number;
+    };
+    delay?: string | number;
+};
+/**
+ * In-flight bounds enforced when the data Durable Object claims a run. A run
+ * counts while it holds a live lease; a claim over a full limit is deferred,
+ * never failed, and never spends an attempt. The Durable Object parks the
+ * waiting run and wakes it when a run releases a slot it shares.
+ */
+export type JobConcurrencyConfig<Input = unknown> = {
+    /** Most runs of this job name in flight at once in one data Durable Object. */
+    max?: number;
+    /**
+     * Most runs in flight at once per key. The key is computed from the parsed
+     * input at enqueue time and is shared by every job in the data Durable
+     * Object that returns the same string, so namespace it (`site:${id}`).
+     */
+    perKey?: {
+        key: (input: Input) => string;
+        max: number;
+    };
+};
+/** Token bucket over run starts, checked in the same claim as concurrency. */
+export type JobRateLimitConfig<Input = unknown> = {
+    /** Sustained starts per second; fractions allowed (0.5 is one start every two seconds). */
+    perSecond: number;
+    /** Starts allowed back to back after an idle period. Defaults to max(1, ceil(perSecond)). */
+    burst?: number;
+    /** Bucket key computed from the parsed input; shared like `concurrency.perKey.key`. Defaults to one bucket per job name. */
+    key?: (input: Input) => string;
+};
+/** The declared limits a claim enforces, resolved from the job definition by the queue consumer. */
+export type JobRunClaimLimits = {
+    max?: number;
+    perKeyMax?: number;
+    rateLimit?: {
+        perSecond: number;
+        burst: number;
+        keyed: boolean;
+    };
+};
+export type RaybaseJobDeferralReason = "concurrency" | "concurrency-key" | "rate-limit";
+export type RaybaseJobDeferral = {
+    reason: RaybaseJobDeferralReason;
+    /** The full limit: `max`, `perKey.max`, or the rate-limit burst. */
+    limit: number;
+    /** Runs holding a live lease when the claim was deferred (concurrency reasons). */
+    inFlight?: number;
+    /** The concurrency or rate-limit key, when the limit is keyed. */
+    key?: string | null;
+    /** Rate limit only: time until the bucket holds a whole token. */
+    retryAfterMs?: number;
+    /** Total deferrals of this run, including this one. */
+    deferrals: number;
+    /**
+     * The data Durable Object holds the waiting run and sends its message when
+     * a slot frees, so the consumer acknowledges without redelivering it.
+     */
+    parked?: boolean;
+};
+export type JobRetentionConfig = {
+    success?: string | number;
+    failure?: string | number;
+    cancelled?: string | number;
+    events?: string | number;
+};
+export type JobScheduleConfig = {
+    cron: string;
+    timezone?: string;
+    input?: unknown;
+    enabled?: boolean;
+};
+export type RaybaseJobLogger = {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+};
+export type RaybaseJobScheduleContext = {
+    key: string;
+    bookedAt: string;
+    generation: number;
+    late: boolean;
+};
+export type RaybaseJobHandlerContext<Input = unknown> = {
+    input: Input;
+    run: RaybaseJobRun;
+    enqueuedBy: RaybaseJobPrincipal;
+    runAs: RaybaseJobPrincipal;
+    principal: RaybaseJobPrincipal;
+    user?: RaybaseUser;
+    /** Opaque first-party runtime scope metadata; Core leaves this unset. */
+    organizationId?: string;
+    /** Policy-checked app data as the job's runAs principal; `revealSecret()` returns `secret()` plaintext through an audited call. */
+    db: RaybaseActionDataClient;
+    auth: RaybaseAuthContextRuntime;
+    agents: RaybaseAgentInvocationRuntime;
+    ai: RaybaseAI;
+    settings: RaybaseRuntimeSettings<unknown, RaybaseSettingsDefinitions<unknown>>;
+    notifications: RaybaseNotificationsRuntime;
+    jobs: RaybaseJobsRuntime;
+    schedule?: RaybaseJobScheduleContext;
+    /** Present only on a batch continuation run (`onComplete` or `onFailure`). */
+    batch?: RaybaseJobBatchContext;
+    env: unknown;
+    log: RaybaseJobLogger;
+    progress: (patch: Record<string, unknown>) => Promise<void>;
+    signal: AbortSignal;
+    audit?: (event: RaybaseAuditContextEvent) => Promise<void>;
+};
+export type RaybaseJobDefinition<Input = unknown> = {
+    name: string;
+    description?: string;
+    input: z.ZodType<Input> | JobJsonSchemaObject;
+    enqueue: JobPolicyExpression;
+    view?: JobPolicyExpression;
+    cancel?: JobPolicyExpression;
+    retry?: JobPolicyExpression;
+    /** "actor" means run as the principal that enqueued the job. */
+    runAs: "actor" | "system" | {
+        userRef: string;
+    };
+    mode?: "queue" | "workflow";
+    retries?: JobRetryConfig;
+    concurrency?: JobConcurrencyConfig<Input>;
+    rateLimit?: JobRateLimitConfig<Input>;
+    /**
+     * How long a claimed run holds its lease, and so its concurrency slot,
+     * before the stale-lease sweep may fail it. Falls back to
+     * `appConfig.jobs.leaseDuration`, then 5 minutes.
+     */
+    leaseDuration?: string | number;
+    retention?: JobRetentionConfig;
+    schedule?: JobScheduleConfig;
+    handler: (ctx: RaybaseJobHandlerContext<Input>) => Promise<unknown>;
+};
+export type RaybaseActionJobRunAs = RaybaseJobDefinition["runAs"];
+export type RaybaseActionJobOptions<Input = unknown, Output = unknown, Env = unknown, Schema extends RaybaseSchema = RaybaseSchema> = {
+    name?: string;
+    description?: string;
+    enqueue: ActionPolicyExpression;
+    runAs: RaybaseActionJobRunAs;
+    view?: JobPolicyExpression;
+    cancel?: JobPolicyExpression;
+    retry?: JobPolicyExpression;
+    mode?: "queue" | "workflow";
+    retries?: JobRetryConfig;
+    concurrency?: JobConcurrencyConfig<Input>;
+    rateLimit?: JobRateLimitConfig<Input>;
+    leaseDuration?: string | number;
+    retention?: JobRetentionConfig;
+    schedule?: JobScheduleConfig;
+    policy?: ActionPolicyExpression;
+    rowAuthorization?: RaybaseActionRowAuthorization<Input, Env, Schema>;
+};
+export type RaybaseJobDefinitionInput<Input = unknown> = RaybaseJobDefinition<Input>;
+export type RaybaseJobCollectionDefinition<Input = unknown> = Omit<RaybaseJobDefinition<Input>, "name"> & {
+    name?: string;
+};
+export type RaybaseJobs = Record<string, RaybaseJobDefinition<any>>;
+export type RaybaseJobDefinitions = Record<string, RaybaseJobDefinition<any> | RaybaseJobCollectionDefinition<any>>;
+export type RaybaseJobRunStatus = "queued" | "leased" | "running" | "succeeded" | "failed" | "denied" | "cancelled" | "expired";
+export type RaybaseJobRun = {
+    id: string;
+    jobName: string;
+    status: RaybaseJobRunStatus;
+    inputJson: string;
+    inputHash: string | null;
+    idempotencyKey: string | null;
+    actorKind: "user" | "operator" | "service" | "agent";
+    actorId: string | null;
+    runAsKind: "user" | "operator" | "service" | "agent";
+    runAsId: string | null;
+    attempt: number;
+    maxAttempts: number;
+    queueMessageId: string | null;
+    workflowInstanceId: string | null;
+    leaseOwner: string | null;
+    leaseExpiresAt: string | null;
+    createdAt: string;
+    availableAt: string;
+    startedAt: string | null;
+    endedAt: string | null;
+    expiresAt: string | null;
+    progressJson: string | null;
+    resultJson: string | null;
+    errorJson: string | null;
+    artifactJson: string | null;
+    createdBy: string | null;
+    retryOfRunId: string | null;
+    scheduleKey: string | null;
+    scheduleGeneration: number | null;
+    scheduleBookedAt: string | null;
+    /** The batch this run is a child of. */
+    batchId: string | null;
+    /** Enqueue order inside the batch, starting at 1; the children cursor. */
+    batchSeq: number | null;
+    /** The batch whose completion this run continues. */
+    continuationOfBatchId: string | null;
+    /** `concurrency.perKey.key(input)`, computed at enqueue. */
+    concurrencyKey: string | null;
+    /** `rateLimit.key(input)`, computed at enqueue. */
+    rateLimitKey: string | null;
+    /** Claims deferred because a concurrency or rate limit was full. */
+    deferrals: number;
+    deferredAt: string | null;
+    /** Set while a queued run waits on a full limit; cleared when the run is claimed. */
+    deferredReason: RaybaseJobDeferralReason | null;
+    /**
+     * When the data Durable Object last sent a waiting run its wake message.
+     * For the next 30 seconds the run holds the slot that woke it.
+     */
+    wokenAt: string | null;
+};
+export type RaybaseJobEvent = {
+    id: string;
+    runId: string;
+    type: string;
+    level: "debug" | "info" | "warn" | "error";
+    message: string | null;
+    dataJson: string | null;
+    createdAt: string;
+};
+export type RaybaseJobQueueMessage = {
+    kind: "raybase.job.run";
+    version: 1;
+    runId: string;
+    jobName: string;
+    organizationId?: string;
+};
+export type RaybaseJobScheduleDispatchMessage = {
+    kind: "raybase.job.schedule";
+    version: 1;
+    scheduleId: string;
+    key: string;
+    jobName: string;
+    generation: number;
+    bookedAt: string;
+    inputJson: string;
+    service: string;
+    actorKind: "user" | "operator" | "service" | "agent";
+    actorId: string | null;
+    organizationId?: string;
+};
+type CreateJobRunOptionalField = "attempt" | "queueMessageId" | "workflowInstanceId" | "leaseOwner" | "leaseExpiresAt" | "startedAt" | "endedAt" | "resultJson" | "errorJson" | "batchId" | "batchSeq" | "continuationOfBatchId" | "concurrencyKey" | "rateLimitKey" | "deferrals" | "deferredAt" | "deferredReason" | "wokenAt";
+export type CreateJobRunInput = {
+    run: Omit<RaybaseJobRun, CreateJobRunOptionalField> & Partial<Pick<RaybaseJobRun, CreateJobRunOptionalField>>;
+};
+export type CreateJobRunResult = {
+    created: boolean;
+    run: RaybaseJobRun;
+};
+export type ClaimJobRunInput = {
+    runId: string;
+    jobName: string;
+    leaseOwner: string;
+    now: string;
+    wallNow?: string;
+    leaseExpiresAt: string;
+    limits?: JobRunClaimLimits;
+    /** Runtime scope claims the Durable Object attaches to the wake message of a run it parks. */
+    claims?: Record<string, unknown>;
+};
+export type ClaimJobRunResult = {
+    status: "claimed";
+    run: RaybaseJobRun;
+} | {
+    status: "missing";
+} | {
+    status: "terminal";
+    run: RaybaseJobRun;
+} | {
+    status: "not-due";
+    run: RaybaseJobRun;
+} | {
+    status: "leased";
+    run: RaybaseJobRun;
+} | {
+    status: "cancelled";
+    run: RaybaseJobRun;
+} | {
+    status: "deferred";
+    run: RaybaseJobRun;
+    deferral: RaybaseJobDeferral;
+};
+export type CompleteJobRunInput = {
+    runId: string;
+    leaseOwner: string;
+    now: string;
+    expiresAt: string | null;
+    resultJson: string | null;
+    artifactJson?: string | null;
+};
+export type FailJobRunInput = {
+    runId: string;
+    leaseOwner: string;
+    now: string;
+    retry: boolean;
+    availableAt?: string | null;
+    expiresAt?: string | null;
+    errorJson: string;
+};
+export type DenyJobRunInput = {
+    runId: string;
+    leaseOwner?: string | null;
+    now: string;
+    expiresAt: string | null;
+    errorJson: string;
+};
+export type CancelJobRunInput = {
+    runId: string;
+    now: string;
+    actorKind?: string | null;
+    actorId?: string | null;
+    expiresAt?: string | null;
+    reason?: string | null;
+};
+export type CancelJobRunResult = {
+    status: "cancelled";
+    run: RaybaseJobRun;
+} | {
+    status: "already-terminal";
+    run: RaybaseJobRun;
+} | {
+    status: "missing";
+};
+export type AppendJobEventInput = {
+    id?: string;
+    runId: string;
+    type: string;
+    level: "debug" | "info" | "warn" | "error";
+    message?: string | null;
+    dataJson?: string | null;
+    createdAt?: string;
+};
+export type ListDueSchedulesInput = {
+    now: string;
+    limit?: number;
+};
+export type RaybaseJobSchedule = {
+    id: string;
+    jobName: string;
+    key: string;
+    kind: "once" | "cron";
+    status: "pending" | "suspended" | "fired" | "cancelled";
+    inputJson: string;
+    cron: string | null;
+    timezone: string | null;
+    bookedAt: string | null;
+    generation: number;
+    dispatchAttempts: number;
+    dispatchLeaseExpiresAt: string | null;
+    lastDispatchAt: string | null;
+    lastDispatchError: string | null;
+    suspendedAt: string | null;
+    cancelledAt: string | null;
+    cancellationReason: string | null;
+    lastRunAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    createdBy: string | null;
+    service: string | null;
+    actorKind: "user" | "operator" | "service" | "agent";
+    actorId: string | null;
+};
+export type RaybaseJobScheduleCreateOptions = {
+    name: string;
+    key: string;
+    input: unknown;
+    at?: string | number | Date;
+    cron?: string;
+    timezone?: string;
+};
+export type RaybaseJobScheduleReplaceOptions = Omit<RaybaseJobScheduleCreateOptions, "key">;
+export type RaybaseJobScheduleListOptions = {
+    name?: string;
+    prefix?: string;
+    status?: RaybaseJobSchedule["status"];
+    limit?: number;
+};
+export type RaybaseJobScheduleSelection = {
+    prefix: string;
+    keys?: never;
+} | {
+    keys: string[];
+    prefix?: never;
+};
+export type RaybaseJobSchedulesRuntime = {
+    create(options: RaybaseJobScheduleCreateOptions): Promise<RaybaseJobSchedule>;
+    get(key: string): Promise<RaybaseJobSchedule | null>;
+    list(options?: RaybaseJobScheduleListOptions): Promise<RaybaseJobSchedule[]>;
+    replace(key: string, options: RaybaseJobScheduleReplaceOptions): Promise<RaybaseJobSchedule>;
+    cancel(key: string, reason?: string): Promise<RaybaseJobSchedule | null>;
+    suspend(selection: RaybaseJobScheduleSelection): Promise<{
+        count: number;
+        schedules: RaybaseJobSchedule[];
+    }>;
+    resume(selection: RaybaseJobScheduleSelection): Promise<{
+        count: number;
+        schedules: RaybaseJobSchedule[];
+    }>;
+};
+/**
+ * A batch moves `open` → `sealed` → `completed`. It completes, and fires its
+ * one continuation, once it is sealed and every child run is terminal.
+ */
+export type RaybaseJobBatchStatus = "open" | "sealed" | "completed";
+/** Child runs by state; `pending` counts children that are not yet terminal. */
+export type RaybaseJobBatchCounts = {
+    total: number;
+    pending: number;
+    succeeded: number;
+    failed: number;
+    cancelled: number;
+    denied: number;
+    expired: number;
+};
+export type RaybaseJobBatchContinuation = {
+    job: string;
+    input: unknown;
+};
+export type RaybaseJobBatch = {
+    id: string;
+    name: string;
+    key: string;
+    status: RaybaseJobBatchStatus;
+    counts: RaybaseJobBatchCounts;
+    onComplete: RaybaseJobBatchContinuation;
+    onFailure: RaybaseJobBatchContinuation | null;
+    /** The one continuation run, set when the batch completes. */
+    continuationRunId: string | null;
+    continuationJob: string | null;
+    continuationDispatchedAt: string | null;
+    lastDispatchError: string | null;
+    cancelledAt: string | null;
+    cancellationReason: string | null;
+    createdAt: string;
+    updatedAt: string;
+    sealedAt: string | null;
+    completedAt: string | null;
+    /** When the continuation run reached a terminal state. */
+    finishedAt: string | null;
+    expiresAt: string | null;
+    createdBy: string | null;
+    actorKind: "user" | "operator" | "service" | "agent";
+    actorId: string | null;
+};
+export type RaybaseJobBatchCreateOptions = {
+    /** Stable label shown in admin, for example `crawl.pages`. */
+    name: string;
+    /** Unique inside the data Durable Object; creating an existing key returns that batch. */
+    key: string;
+    onComplete: RaybaseJobBatchContinuation;
+    /** Fires instead of `onComplete` when any child did not succeed or the batch was cancelled. */
+    onFailure?: RaybaseJobBatchContinuation;
+};
+export type RaybaseJobBatchEnqueueOptions = Pick<EnqueueJobOptions, "idempotencyKey" | "delay">;
+/** One child for `batches.enqueueMany`: its input plus the options `batches.enqueue` takes. */
+export type RaybaseJobBatchEnqueueItem = RaybaseJobBatchEnqueueOptions & {
+    input: unknown;
+};
+export type RaybaseJobBatchChild = {
+    runId: string;
+    seq: number;
+    jobName: string;
+    status: RaybaseJobRunStatus;
+    /** The key passed to `batches.enqueue`, without the batch scope. */
+    idempotencyKey: string | null;
+    attempt: number;
+    input: unknown;
+    result: unknown;
+    error: unknown;
+    createdAt: string;
+    endedAt: string | null;
+};
+export type RaybaseJobBatchChildrenOptions = {
+    status?: RaybaseJobRunStatus;
+    cursor?: string | null;
+    /** Defaults to 50, at most 100. */
+    limit?: number;
+};
+export type RaybaseJobBatchChildrenPage = {
+    children: RaybaseJobBatchChild[];
+    /** Pass back as `cursor` for the next page; null on the last page. */
+    cursor: string | null;
+};
+export type RaybaseJobBatchesRuntime = {
+    create(options: RaybaseJobBatchCreateOptions): Promise<RaybaseJobBatch>;
+    get(batchId: string): Promise<RaybaseJobBatch | null>;
+    enqueue(batchId: string, jobName: string, input: unknown, options?: RaybaseJobBatchEnqueueOptions): Promise<RaybaseJobRun>;
+    /**
+     * Adds many children of one job, as `enqueue` would one at a time, in one
+     * Durable Object transaction and one queue batch send per 100 items.
+     * Returns the runs in item order.
+     */
+    enqueueMany(batchId: string, jobName: string, items: readonly RaybaseJobBatchEnqueueItem[]): Promise<RaybaseJobRun[]>;
+    seal(batchId: string): Promise<RaybaseJobBatch>;
+    cancel(batchId: string, reason?: string): Promise<RaybaseJobBatch>;
+    children(batchId: string, options?: RaybaseJobBatchChildrenOptions): Promise<RaybaseJobBatchChildrenPage>;
+};
+/** What a continuation handler receives as `ctx.batch`. */
+export type RaybaseJobBatchContext = {
+    id: string;
+    name: string;
+    key: string;
+    counts: RaybaseJobBatchCounts;
+    cancelled: boolean;
+    cancellationReason: string | null;
+    children(options?: RaybaseJobBatchChildrenOptions): Promise<RaybaseJobBatchChildrenPage>;
+};
+export type RaybaseJobsRuntime = {
+    enqueue(jobName: string, input: unknown, options?: EnqueueJobOptions): Promise<RaybaseJobRun>;
+    schedules: RaybaseJobSchedulesRuntime;
+    batches: RaybaseJobBatchesRuntime;
+};
+export declare const unsupportedRaybaseJobsRuntime: RaybaseJobsRuntime;
+/** A continuation prepared and policy-checked when the batch is created. */
+export type RaybaseJobBatchContinuationTemplate = {
+    jobName: string;
+    inputJson: string;
+    inputHash: string | null;
+    runAsKind: "user" | "operator" | "service" | "agent";
+    runAsId: string | null;
+    maxAttempts: number;
+    /** Limit keys computed from the input when the batch was created; absent on templates stored before limits existed. */
+    concurrencyKey?: string | null;
+    rateLimitKey?: string | null;
+};
+export type CreateJobBatchInput = {
+    id: string;
+    name: string;
+    key: string;
+    onComplete: RaybaseJobBatchContinuationTemplate;
+    onFailure: RaybaseJobBatchContinuationTemplate | null;
+    createdBy: string | null;
+    actorKind: "user" | "operator" | "service" | "agent";
+    actorId: string | null;
+    claims?: Record<string, unknown>;
+    now: string;
+};
+export type CreateJobBatchResult = {
+    created: boolean;
+    batch: RaybaseJobBatch;
+};
+/** The `_audit` row values of an audit event, as `recordAudit` would insert them. */
+export type RaybaseJobAuditRow = {
+    actorKind: string | null;
+    actorId: string | null;
+    runAsKind: string | null;
+    runAsId: string | null;
+    action: string;
+    metadata: string | null;
+};
+export type CreateJobBatchChildrenInput = {
+    batchId: string;
+    /** At most 100; each child's enqueue event and audit row are written only when its run is created. */
+    children: Array<{
+        run: CreateJobRunInput["run"];
+        eventDataJson: string | null;
+        audit: RaybaseJobAuditRow;
+    }>;
+    /** The calling run; a live child may add siblings after the batch is sealed. */
+    fromRunId?: string | null;
+    now: string;
+};
+export type CreateJobBatchChildrenResult = {
+    /** In input order; a repeated idempotency key returns the existing run with `created: false`. */
+    children: Array<{
+        created: boolean;
+        run: RaybaseJobRun;
+    }>;
+    batch: RaybaseJobBatch;
+};
+export type SealJobBatchInput = {
+    batchId: string;
+    now: string;
+};
+export type CancelJobBatchInput = {
+    batchId: string;
+    now: string;
+    reason?: string | null;
+    actorKind?: string | null;
+    actorId?: string | null;
+    /** Retention for cancelled children, by job name, falling back to `expiresAt`. */
+    expiresAtByJob?: Record<string, string | null>;
+    expiresAt?: string | null;
+};
+export type ListJobBatchesInput = {
+    status?: RaybaseJobBatchStatus;
+    name?: string;
+    key?: string;
+    limit?: number;
+};
+export type ListJobBatchChildrenInput = RaybaseJobBatchChildrenOptions & {
+    batchId: string;
+};
+export declare function batchChildIdempotencyKey(batchId: string, key: string): string;
+export declare function batchContinuationIdempotencyKey(batchId: string): string;
+export type CreateJobScheduleInput = {
+    id: string;
+    jobName: string;
+    key: string;
+    kind: "once" | "cron";
+    inputJson: string;
+    cron?: string | null;
+    timezone?: string | null;
+    bookedAt: string;
+    createdBy?: string | null;
+    service?: string | null;
+    actorKind?: "user" | "operator" | "service" | "agent";
+    actorId?: string | null;
+    claims?: Record<string, unknown>;
+    now: string;
+};
+export type ListJobSchedulesInput = RaybaseJobScheduleListOptions;
+export type ReplaceJobScheduleInput = Omit<CreateJobScheduleInput, "id" | "key" | "createdBy"> & {
+    key: string;
+    expected?: Omit<RaybaseJobScheduleExpectedCoordinate, "key">;
+};
+export type RaybaseJobScheduleExpectedCoordinate = {
+    key: string;
+    scheduleId: string;
+    generation: number;
+    bookedAt: string | null;
+};
+export type CancelJobScheduleInput = {
+    key: string;
+    reason?: string | null;
+    now: string;
+    expected?: {
+        scheduleId: string;
+        generation: number;
+        bookedAt: string | null;
+    };
+};
+export type MutateJobScheduleSelectionInput = RaybaseJobScheduleSelection & {
+    now: string;
+    expected?: RaybaseJobScheduleExpectedCoordinate[];
+};
+export type FindMaterializedScheduledJobRunInput = {
+    scheduleId: string;
+    key: string;
+    generation: number;
+    bookedAt: string;
+};
+export type ClaimDueJobSchedulesInput = {
+    now: string;
+    wallNow: string;
+    leaseExpiresAt: string;
+    limit?: number;
+};
+export type MaterializeScheduledJobRunInput = {
+    scheduleId: string;
+    key: string;
+    generation: number;
+    bookedAt: string;
+    materializedAt: string;
+    nextBookedAt: string | null;
+    run: CreateJobRunInput["run"];
+};
+export type MaterializeScheduledJobRunResult = {
+    status: "materialized";
+    run: RaybaseJobRun;
+    schedule: RaybaseJobSchedule;
+} | {
+    status: "existing";
+    run: RaybaseJobRun;
+    schedule: RaybaseJobSchedule;
+} | {
+    status: "stale";
+} | {
+    status: "missing";
+};
+export type RaybaseSchedulerState = {
+    nextJobScheduleAt: string | null;
+    pendingJobSchedules: number;
+    leasedJobSchedules: number;
+};
+export type ListDueSchedulesResult = {
+    schedules: RaybaseJobSchedule[];
+};
+export type UpsertJobScheduleInput = {
+    id: string;
+    jobName: string;
+    inputJson: string;
+    cron: string;
+    timezone?: string | null;
+    enabled?: boolean;
+    nextRunAt?: string | null;
+    createdBy?: string | null;
+    service?: string | null;
+    now: string;
+};
+export type AdvanceScheduleInput = {
+    id: string;
+    lastRunAt: string;
+    nextRunAt: string | null;
+    now: string;
+};
+export type CompactJobsInput = {
+    now: string;
+    wallNow?: string;
+    batchSize?: number;
+    staleLeaseBefore?: string;
+    wallClockBudgetMs?: number;
+};
+export type CompactJobsResult = {
+    expiredLeases: number;
+    rolledUpRuns: number;
+    deletedEvents: number;
+    deletedRuns: number;
+    more: boolean;
+};
+export type EnqueueJobOptions = {
+    idempotencyKey?: string;
+    delay?: string | number;
+    runId?: string;
+    createdAt?: string;
+    retryOfRunId?: string;
+};
+export type PreparedJobRun = {
+    run: CreateJobRunInput["run"];
+    message: RaybaseJobQueueMessage;
+    input: unknown;
+};
+export declare function defineJob<Input>(definition: RaybaseJobDefinitionInput<Input>): RaybaseJobDefinition<Input>;
+export declare function jobFromAction<Input, Output, Env, Schema extends RaybaseSchema = RaybaseSchema>(action: RaybaseAction<Input, Output, Env, Schema>, options: RaybaseActionJobOptions<Input, Output, Env, Schema>): RaybaseJobDefinition<Input>;
+export declare function defineJobs<T extends RaybaseJobDefinitions>(jobs: T): RaybaseJobs;
+export declare function normalizeRaybaseJobs(jobs: RaybaseJobDefinitions | undefined): RaybaseJobs;
+export declare function mergeRaybaseJobs(base: RaybaseJobDefinitions | undefined, contribution: RaybaseJobDefinitions | undefined, duplicateMessage?: string): RaybaseJobs;
+export declare function validateJobName(name: string): void;
+export declare function validateJobDefinition(job: RaybaseJobDefinition): void;
+/** The lease a claimed run of `job` holds: the job's own `leaseDuration`, else the app's, else 5 minutes. */
+export declare function jobLeaseDurationMs(job: Pick<RaybaseJobDefinition, "leaseDuration">, appJobs?: {
+    leaseDuration?: string | number;
+}): number;
+/** The limits the queue consumer asks the data Durable Object to enforce when it claims a run of `job`. */
+export declare function jobClaimLimits(job: RaybaseJobDefinition): JobRunClaimLimits | undefined;
+/**
+ * Redelivery delay for a deferred claim: equal-jitter exponential backoff on
+ * the run's deferral count (1s, 2s, 4s ... capped at 30s), never sooner than
+ * the rate limit's next token.
+ */
+export declare function jobDeferralDelaySeconds(deferral: Pick<RaybaseJobDeferral, "deferrals" | "retryAfterMs">, random?: () => number): number;
+export declare function isTerminalJobStatus(status: string): status is RaybaseJobRunStatus;
+export declare function storedPrincipal(kind: string, id: string | null, user?: RaybaseUser | null): RaybaseJobPrincipal;
+export declare function jobPrincipalId(principal: RaybaseJobPrincipal): string | null;
+export declare function evaluateJobPolicy(policy: JobPolicyExpression | undefined, ctx: {
+    principal: RaybaseJobPrincipal;
+    action: "enqueue" | "view" | "cancel" | "retry";
+    run?: RaybaseJobRun | Record<string, unknown> | null;
+}): boolean;
+export declare function validateJobInput<Input>(job: RaybaseJobDefinition<Input>, input: unknown): Input;
+export declare function prepareJobRun(job: RaybaseJobDefinition, input: unknown, principal: RaybaseJobPrincipal, options?: EnqueueJobOptions, extra?: {
+    organizationId?: string;
+    wallNow?: string;
+}): Promise<PreparedJobRun>;
+export declare function jobPrincipalUser(principal: RaybaseJobPrincipal): RaybaseUser;
+export declare function retentionExpiresAt(job: RaybaseJobDefinition | undefined, status: RaybaseJobRunStatus, now: string, defaults?: JobRetentionConfig): string | null;
+export declare function retryAvailableAt(job: RaybaseJobDefinition, attempt: number, now: string): string;
+export declare function addDuration(startIso: string, duration: string | number): string;
+export declare function addMilliseconds(startIso: string, ms: number): string;
+export declare function durationMs(duration: string | number | undefined): number;
+export declare function truncateJson(value: unknown, maxBytes?: number): {
+    json: string | null;
+    truncated: boolean;
+};
+export declare function truncateEventData(value: unknown): string | null;
+export declare function validateQueueMessage(body: unknown): RaybaseJobQueueMessage | null;
+export declare function cronMatches(cron: string, date?: Date, timezone?: string | null): boolean;
+export declare function nextCronRun(cron: string, fromIso: string, timezone?: string | null): string | null;
+export declare function validateCron(cron: string): string[];
+export declare function serviceJobUser(service: string): RaybaseUser;
+//# sourceMappingURL=jobs.d.ts.map