tasks

type Config struct {
	// BucketName is the JetStream KV bucket backing the task records.
	// ADR 0005 pins the coord-visible name to "bones-tasks"; this
	// package takes the name as input so tests can isolate by bucket.
	BucketName string

	// HistoryDepth is the per-key JetStream KV history depth. ADR 0005
	// recommends 8; Validate-equivalent rejection happens at Open.
	HistoryDepth uint8

	// MaxValueSize is the upper bound on an encoded task record value,
	// in bytes. Enforced at every Create and Update per invariant 14.
	MaxValueSize int32

	// ChanBuffer sets the channel buffer for Watch. Zero yields the
	// package default (defaultChanBuffer).
	ChanBuffer int
}

type Edge struct {
	Type   EdgeType `json:"type"`
	Target string   `json:"target"`
}

type EdgeType string

type Event struct {
	ID   string
	Kind EventKind
	Task Task
}

type EventKind int

type Manager struct {
	// contains filtered or unexported fields
}

type Status string

type Task struct {
	// ID is the TaskID. It must equal the KV key at Create time; the
	// duplication is deliberate — any future migration that walks the
	// bucket can use the value-side ID without parsing the key.
	ID string `json:"id"`

	// Title is the human-readable task summary. Bounded by the caller;
	// no enforcement here beyond the MaxValueSize cap.
	Title string `json:"title"`

	// Status is the lifecycle state; see Status/validStatus.
	Status Status `json:"status"`

	// ClaimedBy is the AgentID currently holding the claim. Invariant 11
	// requires non-empty iff Status == StatusClaimed; Update enforces.
	ClaimedBy string `json:"claimed_by,omitempty"`

	// Files is the absolute-path list of files this task touches. Sorted
	// by the writer (coord.OpenTask); this package stores it verbatim.
	Files []string `json:"files"`

	// Parent is the optional parent TaskID — empty when this is a root
	// task in a decomposition chain.
	Parent string `json:"parent,omitempty"`

	// Edges are outgoing typed relationships to other tasks. Invariant 25
	// forbids duplicate (Type, Target) pairs; coord.Link enforces this on
	// write. Additive in ADR 0014; nil in records written before that ADR.
	Edges []Edge `json:"edges,omitempty"`

	// Context is the caller-supplied free-form metadata. ADR 0005 caps
	// the effective size against MaxValueSize in concert with the other
	// fields; this package only size-checks the encoded whole.
	Context map[string]string `json:"context,omitempty"`

	// CreatedAt is the wall-clock time of the initial Create.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is the wall-clock time of the most recent write.
	UpdatedAt time.Time `json:"updated_at"`

	// DeferUntil hides the task from Ready until this UTC wall-clock
	// instant. Nil means immediately eligible subject to the other
	// readiness gates. Added in schema v2.
	DeferUntil *time.Time `json:"defer_until,omitempty"`

	// ClosedAt is the wall-clock time of transition into StatusClosed.
	// Nil when Status != StatusClosed; pointer makes the zero value
	// observable (and distinct from a legitimate January-1-0001 write).
	ClosedAt *time.Time `json:"closed_at,omitempty"`

	// ClosedBy is the AgentID that closed the task; empty if not closed.
	ClosedBy string `json:"closed_by,omitempty"`

	// ClosedReason is the free-form close reason; empty if not closed.
	ClosedReason string `json:"closed_reason,omitempty"`

	// ClaimEpoch is the monotonic counter bumped on every successful
	// Claim or Reclaim. Invariant 24 requires strict increase per Claim/
	// Reclaim; Commit and CloseTask fence against it to refuse zombie
	// writes after a Reclaim. Zero on records that never had a claim
	// (legacy records decode to zero; first Claim bumps to 1). ADR 0007.
	ClaimEpoch uint64 `json:"claim_epoch,omitempty"`

	// OriginalSize is the pre-compaction canonical source size for the
	// latest compaction level. Zero means the task has not been compacted.
	OriginalSize uint64 `json:"original_size,omitempty"`

	// CompactLevel is the number of compaction passes applied to this
	// task. Zero means un-compacted. Added in schema v3.
	CompactLevel uint8 `json:"compact_level,omitempty"`

	// CompactedAt is the wall-clock time of the latest compaction pass.
	// Nil means the task has not been compacted. Added in schema v3.
	CompactedAt *time.Time `json:"compacted_at,omitempty"`

	// SchemaVersion stamps the schema this record was written against.
	SchemaVersion int `json:"schema_version"`
}