Placement

Ownership decides which node may commit state for a cell. Placement preference describes whether a node is a good candidate to run new work. Peren enforces ownership through the bucket and reports live placement pressure from the running node. It does not move cells between nodes in this release.

Ownership permission

A node may mutate a cell only while it holds a valid ownership lease for the current epoch. The lease is created or claimed with a conditional write on the bucket. After a successful dispatch, the node releases ownership so the owner field is clear for the next acquisition. Publish and checkpoint check the lease again; a changed ownership record fences the previous holder.

When the ownership record has no owner, any node that can reach the bucket may acquire the cell, restore published replica bytes and serve the next request. When another owner is still recorded, acquisition fails and the request does not commit new state.

Preference versus permission

[rebalance].placement_weight is a pressure input reported by the node. A higher weight makes the node appear less pressured for the same active work and resident WebSocket count. A missing weight is reported as 100.

The live peer control report includes placement_weight, websocket_resident, and placement_pressure. Nodes in draining or control_only admission report maximum placement pressure and are not eligible for new placement. The /metrics endpoint also exports peren_placement_weight and peren_placement_available for scraping.

Placement pressure is advisory. The permission that matters for durability is still ownership. When the ownership record has no owner, any node that can reach the bucket may acquire the cell and restore it.

Drain and movement

peren node drain records a draining state in the local fleet registry. It does not move cells and it does not change admission on an already running process.

The live peer drain endpoint changes the running process: readiness becomes false, new top-level work is refused, and placement availability becomes false. In-flight work may finish. WebSocket-resident cells stay on the drained node until the socket closes; messages on those existing sockets continue to dispatch to that resident cell. New WebSocket upgrades are refused after drain because they require top-level admission.

There is no operator command that relocates a cell between nodes. After a resident cell has no active WebSocket session and no active top-level work, another node can acquire it on a later request through the normal ownership and restore path.

Read Architecture for the request path and Recovery after node loss for what happens after a node stops.