# Tasks

This document defines the intended order, task, and runtime execution model for the simulation.

It describes how commander intent becomes executable work.

## Design Goals

The task model should support:

- direct player control
- long-lived commander autonomy
- clear precedence rules
- readable runtime state
- consistent execution across movement, logistics, construction, and combat

## Core Principles

- commanders decide intent
- tasks express executable work
- states describe runtime condition
- orders can temporarily override autonomy
- tasks should be concrete enough for direct simulation execution

## Control Layers

The intended execution stack should be:

1. `goal`
2. `order`
3. `behavior`
4. `task`
5. `state`

This separates long-horizon intent from short-horizon execution.

## Goals

Goals are high-level commander intentions.

Examples:

- expand into this system
- defend this claim
- protect trade in this region
- supply this station with workers

Goals belong primarily to commanders, not directly to ships.

## Orders

Orders are explicit instructions produced by the player or by higher command.

Orders should survive replanning better than tasks.

Examples:

- travel to anchor
- dock at station
- claim construction anchor
- build station here
- escort this ship
- defend this localspace

Orders are the main override layer above routine autonomous behavior.

## Behaviors

Behaviors are persistent patterns followed when no overriding direct order exists.

Examples:

- idle
- auto-trade
- mine-for-station
- region trader
- claim defender
- station supplier
- local defender
- patrol route

Behaviors should continuously refresh tasks as conditions change.

## Tasks

Tasks are the immediate executable actions the runtime can carry out.

Tasks should be concrete and short-horizon.

Examples:

- move locally
- warp to node
- request dock
- dock
- undock
- load cargo
- unload cargo
- transfer workers
- attack target
- hold near target
- build at construction site
- claim node
- retreat

## States

States describe what an entity is physically or operationally doing right now.

Examples:

- idle
- local-flight
- warp-spooling
- in-warp
- docking
- docked
- loading
- unloading
- attacking
- retreating
- building
- disabled

States should be readable runtime facts, not overloaded planning abstractions.

## Precedence Rules

Task selection should follow this priority:

1. direct player order
2. higher-commander order
3. local commander behavior
4. safety fallback

Interpretation:

- explicit orders override routine autonomy
- routine autonomy resumes when those orders end
- safety logic may still interrupt if survival requires it

## Planner Flow

The intended execution loop is:

1. commander evaluates world state
2. commander updates goals or behavior
3. planner resolves the highest-priority active instruction
4. planner chooses or updates the current task
5. runtime executes the task
6. state changes and events feed back into planning

This is the bridge between command and simulation.

## Order Lifecycle

Orders should have an explicit lifecycle.

Recommended order states:

- `queued`
- `accepted`
- `planning`
- `executing`
- `completed`
- `failed`
- `cancelled`
- `blocked`

## Task Lifecycle

Tasks should have a simpler lifecycle.

Recommended task states:

- `pending`
- `active`
- `blocked`
- `completed`
- `failed`
- `cancelled`

Tasks are shorter-lived than orders and easier to replace.

## Common Ship Task Kinds

Recommended core ship task kinds:

- `idle`
- `local-move`
- `warp-to-node`
- `use-stargate`
- `use-ftl`
- `dock`
- `undock`
- `load-cargo`
- `unload-cargo`
- `load-workers`
- `unload-workers`
- `mine-node`
- `harvest-gas`
- `deliver-to-station`
- `claim-lagrange-point`
- `build-construction-site`
- `escort-target`
- `attack-target`
- `defend-bubble`
- `retreat`
- `hold-position`

## Common Station Operational Tasks

Stations are not ships, but station operation still implies task-like work.

Examples:

- publish market orders
- update production priority
- execute recipe cycle
- accept dock request
- deny dock request
- transfer goods
- request defense

These may be implemented as station jobs, station operations, or station-side tasks.

## Safety And Fallback Tasks

Safety logic should interrupt ordinary behavior when required.

Examples:

- retreat from combat
- flee to nearest allowed station
- hold position if no valid route exists
- suspend trade when no legal destination exists
- wait for escort, or dock access

This prevents autonomous loops from becoming self-destructive.

## Space-Aware Tasking

Tasks should respect the spatial model in [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md).

That means:

- local maneuvering is distinct from warp
- docking is localspace work
- cargo transfer is localspace work
- inter-system travel is distinct from in-system travel

## Policy-Aware Tasking

Tasks should respect policies from [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md).

Examples:

- do not dock where docking is forbidden
- do not trade where access is denied
- do not leave assigned region if behavior policy forbids it
- do not build where policy would trigger conflict unless ordered

## Event Integration

Task and order transitions should generate meaningful events.

Examples:

- `order-accepted`
- `order-cancelled`
- `task-started`
- `task-blocked`
- `task-completed`
- `task-failed`
- `behavior-changed`

See [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md) for the event-side model.

## Data-Model Implication

The data model should make room for at least:

- current goal references
- active order references
- active behavior
- active task
- current state

See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the entity-side vocabulary.

## Minimum Rules

The following rules should remain true unless deliberately revised:

- goals, orders, tasks, and states are not the same thing
- orders can override ordinary behavior
- tasks are the executable layer
- states are descriptive runtime condition
- safety logic may interrupt behavior
- tasking must respect space and policy rules
- meaningful task transitions should emit events

## Relationship To Other Documents

- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
  - defines who decides and delegates

- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md)
  - defines where tasks can occur

- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
  - defines restrictions tasking must obey

- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md)
  - defines the entity fields that hold goals, orders, tasks, and states

- [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md)
  - defines the event families emitted by task and order transitions
