Actor deregistration / actor_config cleanup for ephemeral deployments

[rcbevans]

actor_config.actor is the table's primary key, and queue + metadata are drift-protected structural fields (_STRUCTURAL_FIELDS in worker/startup.py, enforced via ActorConfigDriftList). That's a sensible stance for long-lived deployments, but it pushes apps that run the same code against many short-lived, per-run queues toward per-deployment actor names like my-actor.<run-id> — you can't re-point the same actor name at a different queue without tripping the drift check.

That workaround functions, but each run leaves an actor_config row behind, usually with a matching queues row, and nothing ever removes them. There's deregister_worker for the workers table, and actor_config_ops exposes list_actor_configs / get_actor_config / set_actor_config_capacity — read and tune, but no delete. For ephemeral per-run workers the tables grow monotonically and the admin actor list fills up with dead names.

Today the cleanup is hand-rolled SQL:

await conn.execute(f'DELETE FROM "{schema}".actor_config WHERE actor = $1', actor_name)
await conn.execute(f'DELETE FROM "{schema}".queues WHERE name = $1', queue_name)

which works until it doesn't — it's outside the migration-managed surface, and I have to reason about the referential questions myself: what about terminal jobs whose actor column still names the deleted row, or a cron_schedules entry pointing at it?

What I'd rather have:

await client.actors.deregister("my-actor.<run-id>")

with defined semantics — refuse while non-terminal jobs or enabled schedules reference the actor, optionally a force=True that documents what happens to terminal history, and the same question answered for orphaned queues rows once no actor_config points at them.

If there's an intended GC path for per-run actors that I've missed, point me at it. Otherwise: is deregistration in scope for the operator surface, or is "actors are forever" a deliberate design stance? If it's deliberate, it'd be worth documenting, because the drift-check-plus-PK combination quietly funnels ephemeral deployments into exactly this accumulation pattern.

[rcbevans]

Worth separating two fixes here, because they solve different halves and only one of them removes the pressure that creates the mess.

Deregistration cleans up after the workaround. A composite key would remove the need for it. The reason ephemeral deployments end up with per-run actor names is that actor_config.actor is the whole primary key, so one logical actor cannot be pointed at two queues without tripping the drift check. If the key were (actor, queue) instead, the same actor name could legitimately exist on many queues, the drift check would still catch a genuine mis-routing within a queue, and per-run names — along with the rows they leave behind — would stop being necessary at all. That reading also makes the current drift error more accurate: what it's really detecting is "this actor name is already bound elsewhere", which is only a bug because the schema can't express the alternative.

The migration cost is real (repointing anything that joins on actor, and deciding what a capacity override means when it's now per-queue rather than per-actor), so this may well be the wrong trade. But it's a different question from deregistration, and if the composite key is off the table for 1.x it'd be useful to know that, because then per-run naming is the sanctioned pattern and deregistration becomes load-bearing rather than tidy-up.

If deregistration is the answer, the referential questions you raise have a natural default. Refusing while non-terminal jobs or enabled schedules reference the actor is the right stance; terminal history keeping a dangling actor string seems fine, since jobs.actor is already a plain text column rather than an FK, and archived rows are read as history, not resolved. Orphaned queues rows feel like they want to be swept in the same call rather than left to a separate pass — an empty queue with no actor_config pointing at it isn't meaningfully different from a deleted one.

Either way, the combination of PK-on-name plus drift-protected queue deserves a line in the docs, since it's what funnels this whole class of deployment into per-run names in the first place, and that isn't obvious until a second worker fails to start.