> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/talus-docs-v2.1.0/reference/move/nexus_scheduler/task.md).

# nexus\_scheduler::task

* [Struct `InFlightOccurrence`](#struct-inflightoccurrence)
* [Struct `OccurrenceRecordKey`](#struct-occurrencerecordkey)
* [Struct `OccurrenceRecord`](#struct-occurrencerecord)
* [Struct `Task`](#struct-task)
* [Struct `TaskInnerV1`](#struct-taskinnerv1)
* [Struct `TaskPointer`](#struct-taskpointer)
* [Struct `AuthorizationFieldKey`](#struct-authorizationfieldkey)
* [Struct `PaymentReserveFieldKey`](#struct-paymentreservefieldkey)
* [Enum `TaskController`](#enum-taskcontroller)
* [Enum `TaskStatus`](#enum-taskstatus)
* [Enum `TaskRejectionReason`](#enum-taskrejectionreason)
* [Enum `FailureMode`](#enum-failuremode)
* [Enum `OccurrenceState`](#enum-occurrencestate)
* [Constants](#constants)
* [Function `task_id`](#function-task_id)
* [Function `authorization`](#function-authorization)
* [Function `payment_reserve`](#function-payment_reserve)
* [Function `admission_contract`](#function-admission_contract)
* [Function `schedule_policy`](#function-schedule_policy)
* [Function `occurrence_schedule`](#function-occurrence_schedule)
* [Function `controller`](#function-controller)
* [Function `status`](#function-status)
* [Function `failure_mode`](#function-failure_mode)
* [Function `derive_execution_id`](#function-derive_execution_id)
* [Function `is_active`](#function-is_active)
* [Function `is_paused`](#function-is_paused)
* [Function `is_canceled`](#function-is_canceled)
* [Function `is_rejected`](#function-is_rejected)
* [Function `rejection_reason`](#function-rejection_reason)
* [Function `is_finalized`](#function-is_finalized)
* [Function `occurrence_record`](#function-occurrence_record)
* [Function `occurrence`](#function-occurrence)
* [Function `last_effective_start_time_ms`](#function-last_effective_start_time_ms)
* [Function `state`](#function-state)
* [Function `is_scheduled`](#function-is_scheduled)
* [Function `is_dispatched`](#function-is_dispatched)
* [Function `is_missed`](#function-is_missed)
* [Function `is_withdrawn`](#function-is_withdrawn)
* [Function `is_settled`](#function-is_settled)
* [Function `execution_id`](#function-execution_id)
* [Function `dispatched_at_ms`](#function-dispatched_at_ms)
* [Function `missed_at_ms`](#function-missed_at_ms)
* [Function `withdrawal_reason`](#function-withdrawal_reason)
* [Function `settled_at_ms`](#function-settled_at_ms)
* [Function `succeeded`](#function-succeeded)
* [Function `is_in_flight`](#function-is_in_flight)
* [Function `in_flight_count`](#function-in_flight_count)
* [Function `in_flight_execution_id`](#function-in_flight_execution_id)
* [Function `is_awaiting_funds`](#function-is_awaiting_funds)
* [Function `can_close`](#function-can_close)
* [Function `address_controller`](#function-address_controller)
* [Function `agent_controller`](#function-agent_controller)
* [Function `continue_on_failure`](#function-continue_on_failure)
* [Function `pause_on_failure`](#function-pause_on_failure)
* [Function `is_continue`](#function-is_continue)
* [Function `status_is_paused`](#function-status_is_paused)

### Struct `InFlightOccurrence`

Correlation between one occurrence and one \[`DAGExecution`].

```move
public struct InFlightOccurrence has copy, drop, store
```

<details>

<summary>Fields</summary>

[`execution_id`](#nexus_scheduler_task_execution_id)`: sui::object::ID`

</details>

#### Struct `OccurrenceRecordKey`

Dynamic field key for one occurrence allocated by a \[[`Task`](#nexus_scheduler_task_Task)].

```move
public struct OccurrenceRecordKey has copy, drop, store
```

<details>

<summary>Fields</summary>

`0: u64`

</details>

#### Struct `OccurrenceRecord`

Durable state for one occurrence allocated by a \[[`Task`](#nexus_scheduler_task_Task)].

```move
public struct OccurrenceRecord has store
```

<details>

<summary>Fields</summary>

[`occurrence`](#nexus_scheduler_task_occurrence)`:` [`nexus_scheduler::schedule::Occurrence`](/talus-docs-v2.1.0/reference/move/nexus_scheduler/schedule.md#nexus_scheduler_schedule_Occurrence)[`last_effective_start_time_ms`](#nexus_scheduler_task_last_effective_start_time_ms)`: std::option::Option<u64>`[`state`](#nexus_scheduler_task_state)`:` [`nexus_scheduler::task::OccurrenceState`](#nexus_scheduler_task_OccurrenceState)

</details>

#### Struct `Task`

Durable scheduling authority and occurrence state.

```move
public struct Task has key
```

<details>

<summary>Fields</summary>

`id: sui::object::UID`

</details>

#### Struct `TaskInnerV1`

Version one stored layout for \[[`Task`](#nexus_scheduler_task_Task)].

```move
public struct TaskInnerV1 has store
```

<details>

<summary>Fields</summary>

[`controller`](#nexus_scheduler_task_controller)`:` [`nexus_scheduler::task::TaskController`](#nexus_scheduler_task_TaskController)[`status`](#nexus_scheduler_task_status)`:` [`nexus_scheduler::task::TaskStatus`](#nexus_scheduler_task_TaskStatus)[`failure_mode`](#nexus_scheduler_task_failure_mode)`:` [`nexus_scheduler::task::FailureMode`](#nexus_scheduler_task_FailureMode)[`admission_contract`](#nexus_scheduler_task_admission_contract)`: std::type_name::TypeName`[`operation`](#nexus_scheduler_task_operation)`:` [`nexus_interface::agent::ExecutionSpec`](/talus-docs-v2.1.0/reference/move/nexus_interface/agent.md#nexus_interface_agent_ExecutionSpec)[`schedule_policy`](#nexus_scheduler_task_schedule_policy)`:` [`nexus_interface::agent::SkillSchedulePolicy`](/talus-docs-v2.1.0/reference/move/nexus_interface/agent.md#nexus_interface_agent_SkillSchedulePolicy)[`schedule`](/talus-docs-v2.1.0/reference/move/nexus_scheduler/schedule.md#nexus_scheduler_schedule)`:` [`nexus_scheduler::schedule::Schedule`](/talus-docs-v2.1.0/reference/move/nexus_scheduler/schedule.md#nexus_scheduler_schedule_Schedule)`in_flight: sui::table::Table<u64,` [`nexus_scheduler::task::InFlightOccurrence`](#nexus_scheduler_task_InFlightOccurrence)`>`

</details>

#### Struct `TaskPointer`

Owned pointer to a \[[`Task`](#nexus_scheduler_task_Task)] for discovery.

```move
public struct TaskPointer has key, store
```

<details>

<summary>Fields</summary>

`id: sui::object::UID`[`task_id`](#nexus_scheduler_task_task_id)`: sui::object::ID`

</details>

#### Struct `AuthorizationFieldKey`

Dynamic child key for the Task authorization.

```move
public struct AuthorizationFieldKey has copy, drop, store
```

<details>

<summary>Fields</summary>

</details>

#### Struct `PaymentReserveFieldKey`

Dynamic child key for the Task payment reserve.

```move
public struct PaymentReserveFieldKey has copy, drop, store
```

<details>

<summary>Fields</summary>

</details>

#### Enum `TaskController`

Immutable authority for a \[[`Task`](#nexus_scheduler_task_Task)].

```move
public enum TaskController has copy, drop, store
```

<details>

<summary>Variants</summary>

Variant `Address0: address`Variant `Agent0: sui::object::ID`

</details>

#### Enum `TaskStatus`

Explicit lifecycle state for a \[[`Task`](#nexus_scheduler_task_Task)].

```move
public enum TaskStatus has copy, drop, store
```

<details>

<summary>Variants</summary>

Variant `Active`Variant `Paused`Variant `Canceled`Variant `Rejectedreason:` [`nexus_scheduler::task::TaskRejectionReason`](#nexus_scheduler_task_TaskRejectionReason)Variant `Finalized`

</details>

#### Enum `TaskRejectionReason`

Permanent reason current runtime refused a proposal contract.

```move
public enum TaskRejectionReason has copy, drop, store
```

<details>

<summary>Variants</summary>

Variant `UnsupportedWorkAdmission`Variant `StaleSkillContract`Variant `MutableDAG`

</details>

#### Enum `FailureMode`

Behavior after a failed occurrence.

```move
public enum FailureMode has copy, drop, store
```

<details>

<summary>Variants</summary>

Variant `Continue`Variant `Pause`

</details>

#### Enum `OccurrenceState`

Monotonic lifecycle state for an allocated occurrence.

```move
public enum OccurrenceState has copy, drop, store
```

<details>

<summary>Variants</summary>

Variant `Scheduled`The occurrence is waiting in its \[[`Task`](#nexus_scheduler_task_Task)]'s schedule.Variant `Dispatched`A leader dispatched the occurrence into a \[`DAGExecution`].[`execution_id`](#nexus_scheduler_task_execution_id)`: sui::object::ID`[`dispatched_at_ms`](#nexus_scheduler_task_dispatched_at_ms)`: u64`Variant `Missed`The occurrence reached its deadline before dispatch.[`missed_at_ms`](#nexus_scheduler_task_missed_at_ms)`: u64`Variant `Withdrawn`The occurrence left its schedule without dispatch.`reason:` [`nexus_scheduler::schedule::OccurrenceWithdrawalReason`](/talus-docs-v2.1.0/reference/move/nexus_scheduler/schedule.md#nexus_scheduler_schedule_OccurrenceWithdrawalReason)Variant `Settled`The dispatched execution reached a terminal outcome.[`execution_id`](#nexus_scheduler_task_execution_id)`: sui::object::ID`[`dispatched_at_ms`](#nexus_scheduler_task_dispatched_at_ms)`: u64`[`settled_at_ms`](#nexus_scheduler_task_settled_at_ms)`: u64`[`succeeded`](#nexus_scheduler_task_succeeded)`: bool`

</details>

#### Constants

```move
const MAX_IN_FLIGHT_OCCURRENCES: u64 = 64;
```

```move
#[error]
const EControllerMismatch: vector<u8> = b"Task controller does not match authority";
```

```move
#[error]
const ETaskNotActive: vector<u8> = b"Task is not active";
```

```move
#[error]
const ETaskNotPaused: vector<u8> = b"Task is not paused";
```

```move
#[error]
const ETaskCanceled: vector<u8> = b"Canceled Task cannot resume";
```

```move
#[error]
const ETaskFinalized: vector<u8> = b"Finalized Task cannot be changed";
```

```move
#[error]
const EInFlightOccurrenceLimit: vector<u8> = b"Task in flight occurrence limit reached";
```

```move
#[error]
const EInFlightOccurrenceMissing: vector<u8> = b"Task in flight occurrence is missing";
```

```move
#[error]
const ETaskAwaitingFunds: vector<u8> = b"Task reserve cannot fund one occurrence";
```

```move
#[error]
const ETaskNotClosable: vector<u8> = b"Task still owns future or in flight work";
```

```move
#[error]
const EOccurrenceStateInvalid: vector<u8> = b"Occurrence lifecycle transition is invalid";
```

#### Function `task_id`

Returns the referenced \[[`Task`](#nexus_scheduler_task_Task)] ID.

```move
public fun task_id(self: &nexus_scheduler::task::TaskPointer): sui::object::ID
```

#### Function `authorization`

Returns the Task authorization.

```move
public fun authorization(self: &nexus_scheduler::task::Task): &nexus_interface::authorization::AgentSkillAuthorization
```

#### Function `payment_reserve`

Returns the Task payment reserve.

```move
public fun payment_reserve(self: &nexus_scheduler::task::Task): &nexus_interface::payment::TaskPaymentReserve
```

#### Function `admission_contract`

Returns the validation contract selected by this proposal.

The selector is caller supplied metadata. Current admission must validate every safety relevant field and must never treat this value as provenance.

```move
public fun admission_contract(self: &nexus_scheduler::task::Task): std::type_name::TypeName
```

#### Function `schedule_policy`

Returns the skill scheduling limits.

```move
public fun schedule_policy(self: &nexus_scheduler::task::Task): nexus_interface::agent::SkillSchedulePolicy
```

#### Function `occurrence_schedule`

Returns the occurrence schedule.

```move
public fun occurrence_schedule(self: &nexus_scheduler::task::Task): &nexus_scheduler::schedule::Schedule
```

#### Function `controller`

Returns the immutable Task controller.

```move
public fun controller(self: &nexus_scheduler::task::Task): nexus_scheduler::task::TaskController
```

#### Function `status`

Returns the explicit Task status.

```move
public fun status(self: &nexus_scheduler::task::Task): nexus_scheduler::task::TaskStatus
```

#### Function `failure_mode`

Returns the configured failure behavior.

```move
public fun failure_mode(self: &nexus_scheduler::task::Task): nexus_scheduler::task::FailureMode
```

#### Function `derive_execution_id`

Derives the \[`DAGExecution`] ID assigned to one \[[`Task`](#nexus_scheduler_task_Task)] occurrence.

```move
public fun derive_execution_id(task_id: sui::object::ID, occurrence_id: u64): sui::object::ID
```

#### Function `is_active`

Returns whether the Task is active.

```move
public fun is_active(self: &nexus_scheduler::task::Task): bool
```

#### Function `is_paused`

Returns whether the Task is paused.

```move
public fun is_paused(self: &nexus_scheduler::task::Task): bool
```

#### Function `is_canceled`

Returns whether the Task is canceled.

```move
public fun is_canceled(self: &nexus_scheduler::task::Task): bool
```

#### Function `is_rejected`

Returns whether current runtime permanently rejected the proposal.

```move
public fun is_rejected(self: &nexus_scheduler::task::Task): bool
```

#### Function `rejection_reason`

Returns the permanent rejection reason, when present.

```move
public fun rejection_reason(self: &nexus_scheduler::task::Task): std::option::Option<nexus_scheduler::task::TaskRejectionReason>
```

#### Function `is_finalized`

Returns whether the Task has released its live resources.

```move
public fun is_finalized(self: &nexus_scheduler::task::Task): bool
```

#### Function `occurrence_record`

Returns the durable record for one allocated occurrence.

```move
public fun occurrence_record(self: &nexus_scheduler::task::Task, occurrence_id: u64): &nexus_scheduler::task::OccurrenceRecord
```

#### Function `occurrence`

Returns the occurrence preserved by a record.

```move
public fun occurrence(self: &nexus_scheduler::task::OccurrenceRecord): nexus_scheduler::schedule::Occurrence
```

#### Function `last_effective_start_time_ms`

Returns the latest effective start advertised for an occurrence.

```move
public fun last_effective_start_time_ms(self: &nexus_scheduler::task::OccurrenceRecord): std::option::Option<u64>
```

#### Function `state`

Returns the monotonic lifecycle state preserved by a record.

```move
public fun state(self: &nexus_scheduler::task::OccurrenceRecord): nexus_scheduler::task::OccurrenceState
```

#### Function `is_scheduled`

Returns whether an occurrence has not left its schedule.

```move
public fun is_scheduled(self: nexus_scheduler::task::OccurrenceState): bool
```

#### Function `is_dispatched`

Returns whether an occurrence has been dispatched but not settled.

```move
public fun is_dispatched(self: nexus_scheduler::task::OccurrenceState): bool
```

#### Function `is_missed`

Returns whether an occurrence expired before dispatch.

```move
public fun is_missed(self: nexus_scheduler::task::OccurrenceState): bool
```

#### Function `is_withdrawn`

Returns whether an occurrence was withdrawn before dispatch.

```move
public fun is_withdrawn(self: nexus_scheduler::task::OccurrenceState): bool
```

#### Function `is_settled`

Returns whether a dispatched occurrence reached a terminal outcome.

```move
public fun is_settled(self: nexus_scheduler::task::OccurrenceState): bool
```

#### Function `execution_id`

Returns the related \[`DAGExecution`] ID after dispatch.

```move
public fun execution_id(self: nexus_scheduler::task::OccurrenceState): std::option::Option<sui::object::ID>
```

#### Function `dispatched_at_ms`

Returns the dispatch timestamp after dispatch.

```move
public fun dispatched_at_ms(self: nexus_scheduler::task::OccurrenceState): std::option::Option<u64>
```

#### Function `missed_at_ms`

Returns the expiration timestamp for a missed occurrence.

```move
public fun missed_at_ms(self: nexus_scheduler::task::OccurrenceState): std::option::Option<u64>
```

#### Function `withdrawal_reason`

Returns why an occurrence was withdrawn.

```move
public fun withdrawal_reason(self: nexus_scheduler::task::OccurrenceState): std::option::Option<nexus_scheduler::schedule::OccurrenceWithdrawalReason>
```

#### Function `settled_at_ms`

Returns the settlement timestamp for a settled occurrence.

```move
public fun settled_at_ms(self: nexus_scheduler::task::OccurrenceState): std::option::Option<u64>
```

#### Function `succeeded`

Returns the terminal outcome for a settled occurrence.

```move
public fun succeeded(self: nexus_scheduler::task::OccurrenceState): std::option::Option<bool>
```

#### Function `is_in_flight`

Returns whether an occurrence remains in flight.

```move
public fun is_in_flight(self: &nexus_scheduler::task::Task, occurrence_id: u64): bool
```

#### Function `in_flight_count`

Returns the number of in flight occurrences.

```move
public fun in_flight_count(self: &nexus_scheduler::task::Task): u64
```

#### Function `in_flight_execution_id`

Returns the execution correlated with an occurrence.

```move
public fun in_flight_execution_id(self: &nexus_scheduler::task::Task, occurrence_id: u64): sui::object::ID
```

#### Function `is_awaiting_funds`

Returns whether reserve funds cover one occurrence.

```move
public fun is_awaiting_funds(self: &nexus_scheduler::task::Task): bool
```

#### Function `can_close`

Returns whether the Task can release its live resources.

```move
public fun can_close(self: &nexus_scheduler::task::Task): bool
```

#### Function `address_controller`

Returns an address controller.

```move
public fun address_controller(address: address): nexus_scheduler::task::TaskController
```

#### Function `agent_controller`

Returns an Agent controller.

```move
public fun agent_controller(agent_id: sui::object::ID): nexus_scheduler::task::TaskController
```

#### Function `continue_on_failure`

Returns the default continue behavior.

```move
public fun continue_on_failure(): nexus_scheduler::task::FailureMode
```

#### Function `pause_on_failure`

Returns explicit pause behavior.

```move
public fun pause_on_failure(): nexus_scheduler::task::FailureMode
```

#### Function `is_continue`

Returns whether a failure mode continues.

```move
public fun is_continue(mode: nexus_scheduler::task::FailureMode): bool
```

#### Function `status_is_paused`

Returns whether a \[[`TaskStatus`](#nexus_scheduler_task_TaskStatus)] is paused.

```move
public fun status_is_paused(status: nexus_scheduler::task::TaskStatus): bool
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.talus.network/talus-docs-v2.1.0/reference/move/nexus_scheduler/task.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.