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.
`context.release(delay, options)`	`TaskRelease`	Business waiting result that the handler must return to release the run. It is not a failure or retry.
`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

Enum	Value	Meaning
`RetryBackoffType.Exponential`	`exponential`	Retry delay doubles from the base delay and respects `maxDelay` when present.
`RetryBackoffType.Fixed`	`fixed`	Every retry uses the same delay.

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 a typed handler result, not an enum. The stable field names are still part of the public task contract.

Field	Required	Meaning
`delay`	Yes	Runlane duration string until the released run becomes due again.
`reason`	No	Short public reason for operator views. Runlane treats values as open vocabulary.
`meta`	No	JSON object with structured domain detail.

Core validates release-shaped handler returns before persisting them. Invalid release objects fail the attempt with ErrorCode.ConfigurationInvalid instead of silently completing the run.

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.

Selector	Inferred `ScheduleType`	Meaning
`runAt`	`ScheduleType.Once`	Materialize one run at a specific `Date`.
`every`	`ScheduleType.Interval`	Materialize recurring runs on a duration cadence.
`cron`	`ScheduleType.Cron`	Materialize recurring runs from a cron expression.

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

Enum	Value	Meaning
`ScheduleType.Cron`	`cron`	Materialize runs from a cron expression.
`ScheduleType.Interval`	`interval`	Materialize runs on a fixed duration cadence.
`ScheduleType.Once`	`once`	Materialize one run at a specific time.

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

Enum	Value	Meaning
`ScheduleOccurrenceStatus.Claimed`	`claimed`	A scheduler owns the occurrence and may be creating or recovering its run.
`ScheduleOccurrenceStatus.Completed`	`completed`	The occurrence has recorded the run ids it produced.

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

Enum	Value	Meaning
`DurationUnit.Day`	`d`	Day unit for duration strings.
`DurationUnit.Hour`	`h`	Hour unit for duration strings.
`DurationUnit.Millisecond`	`ms`	Millisecond unit for duration strings.
`DurationUnit.Minute`	`m`	Minute unit for duration strings.
`DurationUnit.Second`	`s`	Second unit for duration strings.

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, idempotency TTLs, interval schedules, worker lease options, dispatch timeouts, maintenance claim durations, and pruning filters.