[em3s]

Summary

The teardown order and its preconditions are the part every operational client reimplements: replication off before disable or the standby stops tracking, unlink before drop or the metadata dangles, delete the metadata only once the table is gone. Getting one wrong breaks a cluster, so the rule belongs in one place.

POST /control/jobs answers what an action would do, over a batch of targets. Nothing takes effect: dryRun=false is refused until authorization lands.

Relates to #370

Three choices worth naming

Targets are a list. A per-table endpoint is what makes each client build its own execution queue, and then makes the next client build it again.

dryRun is a flag on the endpoint that will execute, not a separate preview endpoint. Two code paths computing the same plan is exactly how a plan and its execution come to disagree — and the plan an operator reviewed has to be the plan that runs.

Refusals are typed. An operator facing a disabled action needs to know which precondition to satisfy, and a test needs to assert the right one was named, so Precondition is an enum with the human detail beside it:

{
  "target": {"tenant": "...", "table": "..."},
  "action": "DROP_TABLE",
  "ok": false,
  "refusal": "NEEDS_LOCAL_REPLICATION",
  "detail": "STANDBY still replicates: turn replication off first",
  "steps": []
}

These are predictions. The data plane enforces these invariants itself and stays the one that says no — #477 already refuses a teardown while a reference is live. Predicting them here is how a client learns before it asks, not a second source of truth.

Rules encoded

Action	Steps	Refused when
REPLICATION_OFF / REPLICATION_ON	replication off / on	already there; REPLICATION_ON on a disabled table
DISABLE_TABLE / ENABLE_TABLE	disable / enable	already there; DISABLE_TABLE while replication is on
UNLINK	deactivate collections, then storages	nothing active still binds it
DROP_TABLE	drop, per side that has it	metadata still bound; still enabled; still replicating; already gone
DELETE_METADATA	delete collections, then storages	the table still exists anywhere

Fanout is partial — only the sides not already at the target state get a step, so an active/standby pair that has drifted apart is brought together rather than refused. Metadata actions (UNLINK, DELETE_METADATA) stay on the active side, because metadata is not replicated. A table living only on the standby is still droppable there.

Naming

Action and step names follow the #470 decision: table is the physical HBase table, collection the logical v3 entity. That matters most for the two steps that used to be DROP_TABLE and DELETE_TABLE — a verb apart, but one loses the rows and the other only the definition. They are now DROP_TABLE and DELETE_COLLECTION.

CleanupAction.destructive marks the same boundary in the type rather than in prose: DROP_TABLE and DELETE_METADATA cannot be undone, everything else is a staging step. That is the line a confirmation prompt belongs on.

How to Test

./gradlew :server:test --tests "*CleanupPlannerTest*" --tests "*ControlJobE2ETest*"

Because the plan is dry, the grid can be walked exhaustively: every refusal test asserts the precondition it named, not just that it failed.

POST /control/jobs is the first operational write, so the endpoint classification gains a CONTROL_WRITE_ENDPOINTS set — refused by a read-only instance like any other write, but served by a control instance, which is why it cannot simply join the data-plane write list.

Not touched

CleanupAction keeps its name even though ENABLE_TABLE and REPLICATION_ON undo rather than clean up. Renaming it reaches CleanupPlan, CleanupPlanner and CleanupJobService; better done alongside the executor.

AI Assistance

• This PR was written largely with AI assistance.
  • Tool / model: Claude Code (Opus 5)

[em3s]

Optimistic