tasks

type AgentReachAdmission struct {
	Envelope      []byte `json:"envelope"`
	BindingDigest []byte `json:"binding_digest"`
}

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

type AgentReachAdmissionSealer interface {
	Seal([]byte) ([]byte, error)
	Open([]byte) ([]byte, error)
}

type CancelOrigin string

type Dependencies struct {
	// Store is the StateStore used to persist task lifecycle records
	// (typed-wrapper-over-generic). Required.
	Store state.StateStore
	// Bus is the EventBus where lifecycle events land. Required.
	Bus events.EventBus
	// Redactor is the audit redactor applied to Description / Query
	// / Result / Error BEFORE Save. Required; wiring code
	// passes the global redactor here.
	Redactor audit.Redactor
	// Cfg carries the TasksConfig (driver name today; Harbor
	// adds RetainTurnTimeout + ContinuationHopLimit).
	Cfg config.TasksConfig
}

type Factory func(deps Dependencies) (TaskRegistry, error)

type GroupAction string

type GroupCompletion struct {
	GroupID     TaskGroupID
	SessionID   identity.Identity
	OwnerTaskID TaskID
	FinalStatus TaskGroupStatus // GroupCompleted | GroupCancelled
	ResolvedAt  time.Time
	Members     []MemberOutcome
	Reason      string // populated for GroupCancelled (cancel reason); empty otherwise
}

type GroupRequest struct {
	ID          TaskGroupID
	SessionID   identity.Identity
	OwnerTaskID TaskID
	RetainTurn  bool
	FailFast    bool
	Description string
}

type MemberOutcome struct {
	TaskID TaskID
	Status TaskStatus
	Result *TaskResult
	Error  *TaskError
	// Description echoes the member `Task.Description` (the caller-side
	// redacted, human-readable label already stored on the record). It is
	// populated at the resolve call site that already reads the member
	// `Task`; a ref-shaped conversational-notification mirror uses it to
	// name each member without a second registry read. The typed wake
	// path ignores it.
	Description string
}

type Patch struct {
	ID        string
	SessionID identity.Identity
	Status    string // "pending" | "applied" | "rejected"
	Bytes     []byte
	CreatedAt time.Time
	UpdatedAt time.Time
}

type PatchAction string

type SpawnRequest struct {
	Identity          identity.Quadruple
	Kind              TaskKind
	ParentTaskID      *TaskID
	Description       string
	Query             string
	Priority          int
	IdempotencyKey    string
	PropagateOnCancel string
	NotifyOnComplete  bool
	GroupID           TaskGroupID
	// InputArtifactIDs are operator-uploaded multimodal inputs the
	// task carries onto its first planner turn.
	// Persisted onto `Task.InputArtifactIDs`; consumed by the run
	// loop's first-turn materializer. Empty is the text-only default.
	InputArtifactIDs []string
	// InputArtifactDispositions carries the per-attachment disposition
	// hints keyed by artifact ID. Persisted onto
	// `Task.InputArtifactDispositions`; consumed by the run loop's
	// disposition resolution (top precedence layer). Nil is the
	// default — the agent policy map / runtime default decide.
	InputArtifactDispositions map[string]string
	// OutputSchema is the OPTIONAL per-request JSON-Schema document
	// (raw bytes) the task's terminal answer is validated against —
	// carried from the `start` request's `output_schema` field. The
	// run-loop driver compiles it once at run start and sets
	// `RunContext.OutputSchema`; the validated answer lands as
	// `answer_payload` on the answer envelope. A schema-invalid answer
	// after the correction budget fails the task with the
	// `output_invalid` terminal code (planner.TaskErrorCodeOutputInvalid).
	// Persisted onto `Task.OutputSchema`; folded into the task's content
	// identity so a reused idempotency key with a different schema is a
	// loud conflict. Nil is the common case.
	OutputSchema json.RawMessage
	// AgentID is the caller-named agent, already validated at the
	// Protocol edge (the two-check rule) before the spawn — the registry
	// does not re-validate it. Empty means the runtime's configured
	// default, which is the pre-field behaviour on every path.
	// Persisted onto `Task.AgentID`; folded into the task's content
	// identity so a reused idempotency key naming a DIFFERENT agent is a
	// loud conflict rather than a silent adoption of the original agent.
	AgentID string
	// CallerMemory is the caller-supplied memory block, already bounded
	// and validated at the Protocol edge before the spawn — the registry
	// does not re-validate it. Nil means the caller supplied none, which
	// is the pre-field behaviour on every path.
	//
	// Persisted onto `Task.CallerMemory` AFTER the audit redactor runs over
	// it (see that field); consumed by the run loop's External-tier
	// composition. Folded into the task's content identity — from the
	// PRE-redaction bytes — so a reused idempotency key carrying DIFFERENT
	// caller memory is a loud conflict rather than a silent adoption of the
	// original payload. An in-process caller that bypasses the Protocol edge
	// and supplies bytes that are not valid JSON is refused loud at Spawn;
	// nothing persists.
	//
	// RESIDUAL RISK, stated rather than implied: that redactor is a
	// PATTERN redactor, not a sanitiser. It replaces secret-shaped KEYS
	// (api_key / password / secret / token / cookie / authorization) and
	// inline `Bearer …` / `Basic …` VALUES anywhere in the document, and it
	// does nothing else — it does not detect PII, it does not detect a
	// credential that looks like ordinary prose, and it cannot make hostile
	// text safe. The untrusted prompt framing remains the mitigation for
	// prompt injection. An operator who pipes third-party content through
	// `caller_memory` still has a data-leakage path no prompt wrapper and
	// no pattern redactor closes.
	CallerMemory json.RawMessage
}

type SpawnToolRequest struct {
	Identity          identity.Quadruple
	ParentTaskID      *TaskID
	ToolName          string
	ToolArgs          json.RawMessage
	Description       string
	Priority          int
	IdempotencyKey    string
	PropagateOnCancel string
	NotifyOnComplete  bool
	GroupID           TaskGroupID
}

type Task struct {
	ID                TaskID
	Identity          identity.Quadruple
	Kind              TaskKind
	Status            TaskStatus
	Priority          int
	ParentTaskID      *TaskID
	Description       string
	Query             string
	Result            *TaskResult
	Error             *TaskError
	PropagateOnCancel string
	NotifyOnComplete  bool
	IdempotencyKey    string
	CreatedAt         int64 // unix nanoseconds; matches sessions / events convention
	UpdatedAt         int64 // unix nanoseconds
	// ToolCount is the running count of tool dispatches the runtime
	// has performed against this task. Advanced exclusively through
	// `TaskRegistry.IncrementToolCount` — never set directly by callers.
	// Projected to `prototypes.TaskRow.ToolCount`
	// for the Console Tasks page.
	ToolCount int
	// InputArtifactIDs carry operator-uploaded multimodal inputs the
	// run consumes on its first planner turn.
	// The run loop materializes these into `RunContext.InputArtifacts`
	// via the per-MIME dispatcher: image bytes inline as
	// `ImagePart.DataURL`; everything else stays as an `ArtifactStub`
	// the LLM routes to a matching tool through the tool catalog. Empty
	// is the common case — text-only turns.
	InputArtifactIDs []string
	// InputArtifactDispositions maps an InputArtifactIDs entry to the
	// caller's per-attachment disposition hint:
	// `ref` / `inline` / `provider_native` / `tool:<name>`. The hint
	// is the TOP precedence layer of the disposition resolution
	// (hint > agent policy map > runtime default); an absent key
	// means the caller declared nothing and the lower layers decide.
	// Values are validated at the Protocol edge before they reach
	// the registry. Nil is the common case.
	InputArtifactDispositions map[string]string
	// OutputSchema is the OPTIONAL per-request JSON-Schema document
	// (raw bytes) the task's terminal answer is validated against. When
	// set, the run-loop driver compiles it once at run start, the
	// generation-steering planner constrains + retries against it, and
	// the validated answer lands as `answer_payload` on the task's
	// answer envelope. A schema-invalid answer after the correction
	// budget fails the task with the `output_invalid` terminal code.
	// Validated + compiled at the Protocol edge before the spawn; nil is
	// the common case (a schemaless run). Persisted verbatim via the
	// whole-record marshal (no migration).
	//
	// The `omitempty` tag is load-bearing (unlike the sibling
	// InputArtifactIDs slice, which round-trips nil→null→nil cleanly):
	// a nil json.RawMessage marshals to the JSON literal `null` and
	// UNMARSHALS BACK to the 4-byte RawMessage("null"), NOT nil — so
	// without omitempty a durable-backed schemaless task would hydrate
	// with a non-empty OutputSchema, tripping the driver's `len() > 0`
	// run-start guard and the idempotency-equality byte compare. omitempty
	// elides the empty slice so nil round-trips as nil.
	OutputSchema json.RawMessage `json:",omitempty"`
	// AgentID is the agent this task's run executes under when the
	// caller NAMED one on the request that created the task. Empty means
	// the caller named none and the run binds the runtime's configured
	// default — the pre-field behaviour and the value on every historical
	// row, so an empty value reads as "defaulted", never as "unknown".
	//
	// Validated at the Protocol edge before the spawn (the two-check
	// rule); persisted verbatim via the whole-record marshal, so no
	// migration is required on any driver. The `omitempty` tag keeps a
	// task that named no agent byte-identical on the wire to one spawned
	// before the field existed.
	//
	// It selects CONFIGURATION only. The run's southbound tool
	// provenance and its RFC 8693 acting principal stay boot-derived and
	// are never read from here.
	AgentID string `json:",omitempty"`
	// AgentReachAdmission is the server-minted durable receipt for the exact
	// effective agent authorized by control.start. It has no Protocol
	// projection and cannot be supplied through SpawnRequest. Historical and
	// direct SDK tasks omit it and therefore carry no signed-capability
	// credential authority.
	AgentReachAdmission *AgentReachAdmission `json:",omitempty"`
	// CallerMemory is the caller-supplied content this task's run admits
	// into its `<read_only_external_memory>` tier under the fixed
	// runtime-owned `caller_supplied` map key. Empty means the caller
	// supplied none — the pre-field behaviour and the value on every
	// historical row.
	//
	// Bounded and validated at the Protocol edge before the spawn (32 KiB,
	// non-null, valid JSON); persisted via the whole-record marshal, so no
	// migration is required on any driver.
	//
	// It is stored REDACTED. Spawn runs it through the same audit redactor
	// Description and Query take — the field is caller-controlled content
	// that the whole-record marshal writes to the StateStore on disk, and
	// leaving one of three sibling caller-controlled fields raw while the
	// other two were redacted stored secrets at rest AND misled anyone who
	// inferred the fields behaved alike. Being structured JSON, it goes
	// through the redactor's value walk rather than the string path:
	// objects, arrays, numbers, booleans and null survive structurally
	// intact and only secret-shaped keys and inline `Bearer …` / `Basic …`
	// values are replaced. The redacted form is also what reaches the
	// prompt, which is already true of Query.
	//
	// RESIDUAL RISK, stated rather than implied: that redactor is a
	// PATTERN redactor, not a sanitiser. It replaces secret-shaped KEYS
	// (api_key / password / secret / token / cookie / authorization) and
	// inline `Bearer …` / `Basic …` VALUES anywhere in the document, and it
	// does nothing else — it does not detect PII, it does not detect a
	// credential that looks like ordinary prose, and it cannot make hostile
	// text safe. The untrusted prompt framing remains the mitigation for
	// prompt injection. An operator who pipes third-party content through
	// `caller_memory` still has a data-leakage path no prompt wrapper and
	// no pattern redactor closes.
	//
	// The redaction does NOT weaken idempotency: the task's content hash
	// folds the PRE-redaction bytes.
	//
	// The `omitempty` tag is load-bearing for the same reason it is on
	// OutputSchema: a nil json.RawMessage marshals to the JSON literal
	// `null` and UNMARSHALS BACK to the 4-byte RawMessage("null"), NOT
	// nil — so without omitempty a durable-backed task that carried no
	// caller memory would hydrate with a non-empty CallerMemory and the
	// run loop would compose a `caller_supplied` key holding JSON null.
	CallerMemory json.RawMessage `json:",omitempty"`
	// CallerMemoryWireBytes is the exact pre-redaction byte length admitted at
	// Spawn. It contains no caller content and exists because redaction may
	// change the persisted document's length; admission telemetry reports the
	// wire resource cost, not the post-redaction representation. Zero means no
	// caller memory and is omitted from historical rows.
	CallerMemoryWireBytes int `json:",omitempty"`
}

type TaskBackgroundAcknowledgedPayload struct {
	events.SafeSealed
	TaskID TaskID
}

type TaskCancelledPayload struct {
	events.SafeSealed
	TaskID   TaskID
	Reason   string
	Cascaded bool
}

type TaskCompletedPayload struct {
	events.SafeSealed
	TaskID TaskID
	// NotifyOnComplete echoes the completing task's `Task.NotifyOnComplete`
	// opt-in. A conversational-notification consumer emits an
	// operator-visible completion line only when this is true; the typed
	// completion path is unaffected either way.
	NotifyOnComplete bool
}

type TaskError struct {
	Code    string
	Message string
}

type TaskFailedPayload struct {
	events.SafeSealed
	TaskID    TaskID
	ErrorCode string
}

type TaskFilter struct {
	Status   *TaskStatus
	Kind     *TaskKind
	ParentID *TaskID
}

type TaskGroup struct {
	ID          TaskGroupID
	SessionID   identity.Identity
	OwnerTaskID TaskID
	Status      TaskGroupStatus
	RetainTurn  bool
	FailFast    bool
	Members     []TaskID
	Description string
	CreatedAt   time.Time
	UpdatedAt   time.Time
	ResolvedAt  *time.Time
}

type TaskGroupCancelledPayload struct {
	events.SafeSealed
	Completion GroupCompletion
	Origin     CancelOrigin
}

type TaskGroupCreatedPayload struct {
	events.SafeSealed
	GroupID     TaskGroupID
	OwnerTaskID TaskID
	RetainTurn  bool
	FailFast    bool
	Description string
}

type TaskGroupID string

type TaskGroupResolvedPayload struct {
	events.SafeSealed
	Completion GroupCompletion
}

type TaskGroupSealedPayload struct {
	events.SafeSealed
	GroupID  TaskGroupID
	Members  []TaskID
	SealedAt int64 // unix nanoseconds
}

type TaskGroupStatus string

type TaskHandle struct {
	ID     TaskID
	Reused bool
}

type TaskID string

type TaskKind string

type TaskPatchAppliedPayload struct {
	events.SafeSealed
	PatchID string
}

type TaskPatchRejectedPayload struct {
	events.SafeSealed
	PatchID string
}

type TaskPausedPayload struct {
	events.SafeSealed
	TaskID TaskID
}

type TaskPrioritisedPayload struct {
	events.SafeSealed
	TaskID        TaskID
	PriorPriority int
	NewPriority   int
}

type TaskRegistry interface {
	// Spawn creates a new task or returns the existing handle when an
	// idempotency-key match is found. Returns `ErrIdentityRequired`
	// when the request's identity triple is incomplete.
	Spawn(ctx context.Context, req SpawnRequest) (TaskHandle, error)

	// SpawnTool creates a task representing a tool invocation. Harbor
	// ships the surface; tool dispatch wiring lands in later phases
	// — the persisted task stays at `StatusPending` until then.
	SpawnTool(ctx context.Context, req SpawnToolRequest) (TaskHandle, error)

	// Get loads the task with `id`. Returns `ErrNotFound` (wrapped)
	// when no record exists or the task is not visible to the ctx
	// identity (cross-tenant / cross-session reads are rejected).
	Get(ctx context.Context, id TaskID) (*Task, error)

	// List returns task summaries for the given session matching `f`.
	// Empty pointer fields in `f` are wildcards.
	List(ctx context.Context, sessionID identity.Identity, f TaskFilter) ([]TaskSummary, error)

	// ListTenant enumerates every task across ALL sessions of one tenant
	// — the admin-widened FLEET read. It is a SEPARATE method from the
	// session-scoped List, NOT an optional/blank-session variant of it:
	// List keeps a mandatory full (tenant, user, session) triple; there
	// is no identity-downgrading knob on the session-scoped path (CLAUDE.md
	// §13). ListTenant takes an explicit `tenantID` and returns FULL Task
	// copies (not TaskSummary) so an aggregating projector can attribute
	// each row to its own (tenant, user, session) without an N+1
	// identity-scoped Get.
	//
	// ListTenant is an ADMIN-GATE-ONLY call site: the Tasks Protocol
	// service is the sole production caller, and it gates on the verified
	// `auth.ScopeAdmin` claim BEFORE invoking. ListTenant itself does not
	// re-check the claim (the gate is the Protocol service's), but an empty
	// `tenantID` fails loud with `ErrInvalidRequest` — a fleet read with no
	// named tenant is a caller bug, never a whole-store dump.
	//
	// The optional pointer fields on `f` apply as wildcards, exactly as on
	// List (the Identities-style facet narrowing is applied by the
	// Protocol service post-projection). Result order is unspecified.
	ListTenant(ctx context.Context, tenantID string, f TaskFilter) ([]*Task, error)

	// Cancel transitions the task to `StatusCancelled`. The descendant
	// walk depends on the task's `PropagateOnCancel`:
	//
	//   - "cascade" (default): BFS through children, each emitting
	//     `task.cancelled`.
	//   - "isolate": only the target transitions.
	//
	// Returns (true, nil) when the task transitioned; (false, nil)
	// when the task was already terminal (Cancel is idempotent on
	// already-terminal states). Returns `ErrNotFound` when the task
	// does not exist.
	Cancel(ctx context.Context, id TaskID, reason string) (bool, error)

	// Prioritize updates the task's `Priority`. Harbor stores the
	// value but does not preempt or reorder execution — scheduling is
	// the runtime engine's concern. Emits `task.prioritised`.
	//
	// Returns (true, nil) when the priority changed; (false, nil)
	// when the value matched (no-op write).
	Prioritize(ctx context.Context, id TaskID, priority int) (bool, error)

	// MarkRunning transitions Pending or Paused → Running. Invalid
	// transitions return `ErrInvalidTransition`.
	MarkRunning(ctx context.Context, id TaskID) error

	// MarkPaused transitions Running → Paused.
	MarkPaused(ctx context.Context, id TaskID) error

	// MarkResumed transitions Paused → Running. Distinct method (vs
	// MarkRunning) so the bus event can be `task.resumed` rather than
	// `task.started`.
	MarkResumed(ctx context.Context, id TaskID) error

	// MarkComplete transitions Running → Complete. Persists `result`
	// on the Task record; emits `task.completed`.
	MarkComplete(ctx context.Context, id TaskID, result TaskResult) error

	// MarkFailed transitions Running → Failed. Persists `err` on the
	// Task record; emits `task.failed`.
	MarkFailed(ctx context.Context, id TaskID, err TaskError) error

	// IncrementToolCount atomically increments `Task.ToolCount` by 1
	// and persists the updated record. NOT
	// idempotent — every call increments. The new value is reflected
	// on the next `Get` / `List` projection (`prototypes.TaskRow.ToolCount`).
	//
	// Returns `ErrNotFound` when the task does not exist or is not
	// visible to the ctx identity; `ErrRegistryClosed` after Close.
	// Does NOT change the task's FSM status — runs against tasks in
	// any non-terminal state. Terminal tasks (Complete / Failed /
	// Cancelled) still accept increments (the runloop's late-arriving
	// tool dispatches against a cancelled run can still be counted);
	// the storage write is unconditional.
	//
	// The runloop calls this from its CallTool dispatch path once the
	// ToolExecutor returns without error — that is the only documented
	// producer in V1.
	IncrementToolCount(ctx context.Context, id TaskID) error

	// ResolveOrCreateGroup is the idempotent group constructor. Empty
	// `GroupRequest.ID` → registry assigns a fresh ULID. Non-empty +
	// already-existing → the existing group is returned unchanged.
	// Identity is mandatory; cross-session reuse of an ID is rejected
	// with `ErrGroupNotFound` (existence-without-access).
	//
	// Emits `task.group_created` on the first creation; the no-op
	// idempotent return does NOT re-emit.
	ResolveOrCreateGroup(ctx context.Context, req GroupRequest) (*TaskGroup, error)

	// SealGroup transitions an open group to `GroupSealed`, freezing
	// membership. Sealed groups still have non-terminal members; the
	// driver resolves the group automatically when the last member
	// transitions to terminal.
	//
	// Invalid transitions (already sealed; terminal) return
	// `ErrGroupInvalidTransition`. Emits `task.group_sealed`.
	SealGroup(ctx context.Context, id TaskGroupID) error

	// CancelGroup transitions a non-terminal group to `GroupCancelled`
	// and (when `propagate=true`) cancels every non-terminal member
	// task. The `reason` is a short caller-controlled string (same
	// `SafePayload` contract as `Cancel`'s reason).
	//
	// Emits `task.group_cancelled` carrying the canonical
	// `GroupCompletion` payload (so `WatchGroup` subscribers receive
	// the cancel-with-reason as a single typed delivery).
	CancelGroup(ctx context.Context, id TaskGroupID, reason string, propagate bool) error

	// ApplyGroup is the action-verb wrapper over `SealGroup` /
	// `CancelGroup` / explicit resolve. Convenience for callers that
	// dispatch by enum.
	//
	//   - ActionSeal    → SealGroup
	//   - ActionCancel  → CancelGroup(reason="action:cancel", propagate=true)
	//   - ActionResolve → mark sealed → completed (errors with
	//                     `ErrGroupNotSealed` on an open group)
	ApplyGroup(ctx context.Context, id TaskGroupID, action GroupAction) error

	// ListGroups returns the groups owned by `sessionID` matching the
	// optional `status` filter (nil = wildcard). Empty list + nil
	// error is the no-groups case; missing-identity returns
	// `ErrIdentityRequired`.
	ListGroups(ctx context.Context, sessionID identity.Identity, status *TaskGroupStatus) ([]TaskGroup, error)

	// ApplyPatch transitions a pending patch through
	// `pending → applied | rejected`. Returns `(true, nil)` when the
	// transition occurred; `(false, nil)` when the patch was already
	// in the target terminal state (idempotent). Returns
	// `ErrPatchNotFound` on a missing patch ID.
	//
	// Patches are persisted through StateStore under `Kind =
	// "task.patch"`. The patch payload is opaque bytes; the
	// actual context-patch shape lives at the planner.
	//
	// Emits `task.patch_applied` or `task.patch_rejected` on a real
	// transition; no re-emit on the no-op path.
	ApplyPatch(ctx context.Context, sessionID identity.Identity, patchID string, action PatchAction) (bool, error)

	// AcknowledgeBackground marks completed background tasks as
	// user-acknowledged. Returns the count of tasks that transitioned
	// from un-acknowledged → acknowledged (idempotent on a re-ack).
	//
	// Emits one `task.background_acknowledged` event per task on the
	// real-transition path. Unknown task IDs are silently skipped (no
	// error; the count reflects only the real ack transitions).
	AcknowledgeBackground(ctx context.Context, sessionID identity.Identity, ids []TaskID) (int, error)

	// RegisterRetainTurnWaiter returns a channel that closes when the
	// session's earliest-active retain-turn group resolves, and a
	// cancel func that unsubscribes. The runtime engine consumes the
	// closed channel as the "all retain-turn groups have resolved"
	// signal so foreground-turn dispatch can resume.
	//
	// Buffered size 1 — the resolve path delivers the resolved
	// group's ID without blocking even if the consumer is slow.
	// Channel close is the termination signal; the optional payload
	// is the ID of the group whose terminal transition triggered the
	// wake.
	//
	// Implementations are required to close the channel exactly once.
	RegisterRetainTurnWaiter(sessionID identity.Identity) (<-chan TaskGroupID, func())

	// WatchGroup is the non-retain-turn dual of
	// `RegisterRetainTurnWaiter`: it does NOT block any foreground
	// turn — the planner is free to proceed while the group runs in
	// the background. When the group reaches a terminal state, the
	// runtime delivers a typed `GroupCompletion` payload on the
	// returned channel and closes it.
	//
	// Callers typically use this as a "wake the planner" signal so
	// background results integrate back into the conversation; see
	// the "Wake policy modes" godoc in `groups.go` for the three
	// patterns (push, poll, hybrid) the planner runtime can implement
	// against this single mechanism.
	//
	// Returns `ErrGroupNotFound` when the group is unknown at
	// registration time (e.g. resolved + GC'd). For a
	// resolved-but-still-tracked group, the implementation returns a
	// channel that is *already* primed with the cached
	// `GroupCompletion` (so late subscribers don't deadlock).
	//
	// The cancel func unsubscribes; calling it after a delivery is a
	// no-op. The channel is closed exactly once — either by the
	// resolve path (with a delivery) or by the cancel path (without
	// a delivery).
	//
	// Concurrent reuse: multiple subscribers on the same group all
	// receive the same payload.
	WatchGroup(sessionID identity.Identity, groupID TaskGroupID) (<-chan GroupCompletion, func(), error)

	// Close releases registry resources. Subsequent operations return
	// `ErrRegistryClosed`. Idempotent.
	Close(ctx context.Context) error
}

type TaskResult struct {
	Value json.RawMessage
}

type TaskResumedPayload struct {
	events.SafeSealed
	TaskID TaskID
}

type TaskSpawnedPayload struct {
	events.SafeSealed
	TaskID         TaskID
	Kind           TaskKind
	ParentTaskID   TaskID // empty when no parent
	Priority       int
	IdempotencyKey string
}

type TaskStartedPayload struct {
	events.SafeSealed
	TaskID     TaskID
	PriorState TaskStatus
}

type TaskStatus string

type TaskSummary struct {
	ID        TaskID
	Status    TaskStatus
	Kind      TaskKind
	Priority  int
	CreatedAt int64 // unix nanoseconds — the task's spawn time
	UpdatedAt int64 // unix nanoseconds
}