more refactoring

README.md

@@ -1,5 +1,36 @@
 # Go Cart Actor
 
+## Migration Notes (Ring-based Ownership Transition)
+
+This release removes the legacy ConfirmOwner ownership negotiation RPC in favor of deterministic ownership via the consistent hashing ring.
+
+Summary of changes:
+- ConfirmOwner RPC removed from the ControlPlane service.
+- OwnerChangeRequest message removed (was only used by ConfirmOwner).
+- OwnerChangeAck retained solely as the response type for the Closing RPC.
+- SyncedPool now relies exclusively on the ring for ownership (no quorum negotiation).
+- Remote proxy creation includes a bounded readiness retry to reduce first-call failures.
+- New Prometheus ring metrics: 
+  - cart_ring_epoch
+  - cart_ring_hosts
+  - cart_ring_vnodes
+  - cart_ring_host_share{host}
+  - cart_ring_lookup_local_total
+  - cart_ring_lookup_remote_total
+
+Action required for consumers:
+1. Regenerate protobuf code after pulling (requires protoc-gen-go and protoc-gen-go-grpc installed).
+2. Remove any client code or automation invoking ConfirmOwner (calls will now return UNIMPLEMENTED if using stale generated stubs).
+3. Update monitoring/alerts that referenced ConfirmOwner or ownership quorum failures—use ring metrics instead.
+4. If you previously interpreted “ownership flapping” via ConfirmOwner logs, now check for:
+   - Rapid changes in ring epoch (cart_ring_epoch)
+   - Host churn (cart_ring_hosts)
+   - Imbalance in vnode distribution (cart_ring_host_share)
+
+No data migration is necessary; cart IDs and grain state are unaffected.
+
+---
+
 A distributed cart management system using the actor model pattern.
 
 ## Prerequisites
@@ -240,8 +271,8 @@ Responsibilities:
 
 1. Discovery integration (via a `Discovery` interface) adds/removes hosts.
 2. Periodic ping health checks (ControlPlane.Ping).
-3. Ownership negotiation:
-   - On first contention / unknown owner, node calls `ConfirmOwner` on peers to achieve quorum before making a local grain authoritative.
+3. Ring-based deterministic ownership:
+   - Ownership is derived directly from the consistent hashing ring (no quorum RPC or `ConfirmOwner`).
 4. Remote spawning:
    - When a remote host reports its cart ids (`GetCartIds`), the pool creates remote proxies for fast routing.
 
@@ -270,7 +301,6 @@ Defined in `proto/control_plane.proto`:
 | `Ping` | Liveness; increments missed ping counter if failing. |
 | `Negotiate` | Merges membership views; used after discovery events. |
 | `GetCartIds` | Enumerate locally owned carts for remote index seeding. |
-| `ConfirmOwner` | Quorum acknowledgment for ownership claim. |
 | `Closing` | Graceful shutdown notice; peers remove host & associated remote grains. |
 
 ### Ownership / Quorum Rules
@@ -347,7 +377,7 @@ Defined in `proto/control_plane.proto`:
 ## gRPC Interfaces
 
 - **CartActor**: Per-mutation unary RPCs + `GetState`. (Checkout logic intentionally excluded; handled at HTTP layer.)
-- **ControlPlane**: Cluster coordination (Ping, Negotiate, ConfirmOwner, etc.).
+- **ControlPlane**: Cluster coordination (Ping, Negotiate, GetCartIds, Closing) — ownership now ring-determined (no ConfirmOwner).
 
 **Ports** (default / implied):
 - CartActor & ControlPlane share the same gRPC server/listener (single port, e.g. `:1337`).
@@ -396,7 +426,7 @@ Defined in `proto/control_plane.proto`:
 ```
 Client -> HTTP Handler -> SyncedPool -> (local?) -> Registry -> Grain State
                        \-> (remote?) -> RemoteGrainGRPC -> gRPC -> Remote CartActor -> Registry -> Grain
-ControlPlane: Discovery Events <-> Negotiation/Ping/ConfirmOwner <-> SyncedPool state
+ControlPlane: Discovery Events <-> Negotiation/Ping <-> SyncedPool state (ring determines ownership)
 ```
 
 ---
@@ -407,7 +437,7 @@ ControlPlane: Discovery Events <-> Negotiation/Ping/ConfirmOwner <-> SyncedPool
 |---------|--------------|--------|
 | New cart every request | Secure cookie over plain HTTP or not sending cookie jar | Disable Secure locally or use HTTPS & proper curl `-b` |
 | Unsupported mutation error | Missing registry handler | Add `RegisterMutation` for that proto |
-| Ownership flapping | Quorum failing due to intermittent peers | Investigate `ConfirmOwner` errors / network |
+| Ownership imbalance | Ring host distribution skew or rapid host churn | Examine `cart_ring_host_share`, `cart_ring_hosts`, and logs for host add/remove; rebalance or investigate instability |
 | Remote mutation latency | Network / serialization overhead | Consider batching or colocating hot carts |
 | Checkout returns 500 | Klarna call failed | Inspect logs; no grain state mutated |