Tasks And Schedules

Task and schedule vocabulary appears in public task configuration, runtime trigger boundaries, release results, and durable schedule occurrence state. Use these values when authoring task definitions, validating runtime options, or implementing storage schedule claims.

Task ids, queue names, idempotency keys, singleton keys, and concurrency keys are opaque public identifiers; see Identifiers. Trigger outcomes and run sources are run-lifecycle vocabulary; see Run Lifecycle. Queue policy fields are provider-neutral configuration rather than enum values; see Queues.

Task Boundary Vocabulary

| Value | Stable shape | Meaning | | --- | --- | --- | --- | | retry.maxAttempts | Positive safe integer | Total attempt budget, including the first attempt. | | retry.backoff | Duration string or RetryBackoff object | Delay policy used only after retryable failures. A string is fixed backoff. | | maxAttemptDuration | Duration string | Maximum wall-clock duration for one attempt. The fixed deadline is written when the attempt lease is claimed. | | context.release(delay, options) | TaskReleaseType.Release result | Business waiting result that the handler must return to release the run. It is not a failure or retry. | | context.waitForSignal(signalKey, options) | TaskReleaseType.Release result | Business wait until runlane.signals.send(signalKey) requests delivery, with optional timeout fallback. | | context.waitForRun(runId, options) | TaskReleaseType.Release result | Business wait until the referenced run reaches terminal state, with optional timeout fallback. | | runlane.signals.send(signalKey, options) | Promise<readonly RunRecord[]> | Runtime API that appends durable resume delivery requests for released runs waiting on the signal key. It does not execute handlers inline. | | context.trigger(task, payload, options) | Promise<TriggerRunResult> | Child trigger that validates and creates work through the same runtime path as public trigger(), linked to the parent run. | | context.step.run(stepKey, { output }, callback) | Promise<SchemaOutput> | Durable per-run checkpoint. Completed steps return stored output and skip the callback on later attempts. | | handler JSON return | JsonValue | undefined | Successful output. undefined is void success; null is explicit JSON output. | | idempotencyKeyTTL | Duration string or 'active' | Retention policy for the selected idempotency owner. It requires an idempotency key. |

When an idempotency key is selected and no TTL is supplied, run creation captures 30d. With a finite TTL, successful and cancelled terminal owners remain readable until that TTL expires; failed terminal owners release automatically. The literal 'active' releases ownership when the run reaches any terminal state.

Release reason strings, cancellation reasons, cron expressions, time zones, and metadata keys are open vocabulary. Keep provider or business-specific values in meta instead of inventing Runlane enum values.

RetryBackoffType

A string retry.backoff is accepted as shorthand for RetryBackoffType.Fixed. Object backoff policies should use RetryBackoffType. When a retry policy omits backoff, core uses contractDefaults.retry.backoff, currently 30s.

When retry itself is omitted, task failures do not schedule automatic retries.

RetryBackoffType.Exponential uses the failed attempt number: the first retry waits the base delay, then later retries double from that base. maxDelay must be greater than or equal to delay.

TaskRelease

TaskRelease is the typed handler result returned by context.release(...), context.waitForSignal(...), and context.waitForRun(...). type: 'task_release' is reserved as the release discriminant, so successful output objects must not use that exact type value.

Signal and run-completion releases store RunWaitConditionType.Signal or RunWaitConditionType.RunCompletion, plus an optional timeout. They do not duplicate that timeout as resumeAt on the event. Time releases store delay and the reducer-owned resumeAt; run projection materializes RunWaitConditionType.Time from that due time. Core validates release arguments before returning the result. A plain object with fields such as delay, reason, or meta but no TaskReleaseType.Release discriminant is ordinary handler output and must be JSON-compatible.

RunlaneSignalsApi

runlane.signals.send(signalKey, options) resumes released runs waiting on one external signal key. It validates signalKey with the same public identifier rules as other Runlane id values: non-empty string, no :, and no hidden parsing contract.

The return value contains the RunRecord values whose wait condition was cleared by a newly appended run.delivery_requested event. It is not an execution result and does not guarantee the next attempt has run. Duplicate sends after a wait is already cleared return no run for that cleared wait.

Signals do not carry payloads. Store webhook bodies, approval detail, provider result data, and other domain facts in application storage; use the signal key only to wake runs that should reread that state.

TaskStepContext

context.step.run(stepKey, { output }, callback) persists one named step completion for the current run. The callback returns the output schema input shape, and the resolved value is the parsed JSON-safe output shape. A completed step is replayed for the same run and step key without calling the callback again.

Step callbacks receive { token }, a deterministic RunStepToken derived from environment, run id, and step key. Pass it to providers that support idempotency tokens, or use it as the key for an application submission ledger. The token is opaque and should not be parsed.

Step keys follow public identifier rules: non-empty string, no :, stable across deployments. Store only small continuation pointers such as provider job ids in step output; domain state belongs in application storage and final task results belong in handler output.

Schedule Authoring Vocabulary

Task-colocated schedules infer their kind from exactly one selector field. The public authoring shape must not include type or taskId; core attaches those lower-level fields during registration.

Shared schedule authoring fields are id, optional queue, optional enabled, and optional or required static payload depending on the task schema. Schedule queues must match the runtime queue registry. Static payloads validate synchronously at task registration and again before materialization.

ScheduleType

Lower-level ScheduleDefinition records use this discriminant after core normalizes task-colocated schedules.

Interval schedules anchor to Unix epoch unless startsAt is supplied. endsAt caps the latest eligible interval boundary. Cron schedules use the supplied timeZone when present. Each maintenance pass materializes at most one latest due occurrence per schedule; missed intermediate boundaries are not backfilled in the same tick.

ScheduleOccurrenceStatus

Occurrence ids are deterministic for environment + scheduleId + fireAt. If a scheduler creates the run and crashes before completion, another materializer can reclaim the occurrence after claim expiry, recover the already-created scheduled run, and complete the occurrence with that run id.

DurationUnit

Duration strings look like 500ms, 0.5s, 30s, 5m, 2h, or 7d. Durations must include a unit, be no longer than 100 characters, and resolve to positive whole safe-integer milliseconds.

Use durationSchema or createDurationSchema(message) at boundaries; read .duration for the public string and .milliseconds for executable time math. Duration strings appear in retry backoff, release delay, signal/run-completion wait timeouts, max attempt duration, idempotency TTLs, interval schedules, worker lease options, dispatch timeouts, maintenance claim durations, and pruning filters.