class_name Job extends RefCounted
## A sequence of Toils that describes a pawn's current task (walk to, haul,
## build, rest, etc.). Job is plain data; JobRunner is the state machine that
## drives execution tick-by-tick.
##
## Save/load contract:
##   var j2 := Job.from_dict(j.to_dict())
##   assert(j2.label == j.label)
##   assert(j2.current_toil_index == j.current_toil_index)
##   assert(j2.toils.size() == j.toils.size())
##   # Each toil round-trips per Toil's own invariant.

var label: String = ""
var toils: Array[Toil] = []
var current_toil_index: int = 0

## The world-space entity this job is acting on (tree, rock, build-site,
## crop, etc.). Set by the WorkProvider that built the job. Untyped to
## avoid class_name cycles. Read by sibling providers via
## Job.is_target_taken_by_other() to prevent multiple pawns claiming
## the same target.
##
## NOT serialized: target_node holds a live Node ref (or Vector2i for tile
## targets). After load, pawns re-decide and re-bind claims naturally based
## on restored JobRunner state.
var target_node = null


# ── claim helpers ────────────────────────────────────────────────────────────

## Returns true if `target` is the active target_node of any pawn's current
## job, excluding `excluding_pawn` (the pawn that's about to claim it).
## O(pawns) scan — single-threaded sim, no race within a tick because
## pawns iterate sequentially (earlier pawn commits its job before the
## next pawn's decision runs).
##
## Accepts any value for target (Node, Vector2i, etc.) — uses == comparison.
static func is_target_taken_by_other(target, excluding_pawn) -> bool:
	if target == null:
		return false
	for p in World.pawns:
		if p == excluding_pawn:
			continue
		if p.job_runner == null or not p.job_runner.has_job():
			continue
		if p.job_runner.job.target_node == target:
			Audit.log("decision", "claim skip: %s already targeting %s" % [p.pawn_name, str(target)])
			return true
	return false


# ── queries ──────────────────────────────────────────────────────────────────

## Returns the currently-executing Toil, or null when the job is done.
func active_toil() -> Toil:
	if is_complete():
		return null
	return toils[current_toil_index]


## True once every toil has been completed.
func is_complete() -> bool:
	return current_toil_index >= toils.size()


# ── state mutation ───────────────────────────────────────────────────────────

## Called by JobRunner after the current toil finishes. Steps the index forward.
func advance() -> void:
	current_toil_index += 1


# ── save / load ──────────────────────────────────────────────────────────────

func to_dict() -> Dictionary:
	var toil_list: Array = []
	for toil in toils:
		toil_list.append(toil.to_dict())
	return {
		"label": label,
		"current_toil_index": current_toil_index,
		"toils": toil_list,
	}


static func from_dict(d: Dictionary) -> Job:
	var j := Job.new()
	j.label = d.get("label", "")
	j.current_toil_index = d.get("current_toil_index", 0)
	var raw_toils: Array = d.get("toils", [])
	for raw in raw_toils:
		j.toils.append(Toil.from_dict(raw))
	return j