Module identity 

Task identity

TaskId is the opaque identity reserved for one task submission.

Direct add* methods return it after the registry accepts a task. Controller submit* methods return it after queueing, before slot admission. Controller prepare_submission exposes it earlier, before the submission can publish any event. The same ID therefore also identifies a controller submission that is rejected without running.

One identity across the lifecycle

Every submission accepted into Taskvisor’s command path has one TaskId. It is allocated before the first admission decision, then passed unchanged through every stage that the submission reaches:

allocate TaskId A
        │
        ├── direct add ───────────────────────────────────────────────┐
        │                                                             │
        └── optional controller ─► queue[A] ─► slot admission[A] ─────┤
                                     │                                │
                                     └──► rejected[A] (not registered)│
                                                                      ▼
                                                        registry admission[A]
                                                            │        │
                                     rejected[A] ◄──────────┘        └──► registry[A]
                                     (not registered)                     │
                                                                           ▼
                                             task runner[A] ─► attempt 1, 2, ...
                                                                           ▼
                                                                      cleanup[A]

No new TaskId is allocated at admission or between retry attempts. Queue management, registry membership, the managed runner, and completion tracking carry the same A. Related lifecycle events expose it so callers can correlate cancellation, logs, and metrics.

TaskId vs Name vs Slot

Concept	Owned by	Meaning
TaskId	taskvisor	identity of one submission across its full lifecycle
task name	task	label used for logs, metrics, and registry uniqueness
controller slot	controller	admission key for “one at a time” scheduling

A task name is unique only while its registry entry exists. After terminal cleanup removes that entry, a later submission may reuse the same name. Reusing a name does not reuse its identity:

first submission:  name = "worker", slot = "jobs", TaskId = A
terminal cleanup:  removes A and releases the name "worker"
later submission:  name = "worker", slot = "jobs", TaskId = B (B != A)

Each TaskId is allocated from a process-local u64 counter.

The counter is not stored across process restarts, and a TaskId is not a UUID. If external systems need a persistent identity, store their own ID next to this one.

With the controller feature, a submitted task also has a slot key (ControllerSpec::slot_name). The slot controls admission only; it is not the same thing as the submission identity.

Structs

TaskId

Opaque process-local identity of one task submission.