core(registry): rebuild from kameo reference — local name to actor lookup

[joeldsouzax]

Part of the core-rebuild epic — follows the shared rigor contract there.

Component

src/registry.rs (~156 LOC). The local name→ActorRef registration/lookup (the remote/DHT registry is a separate concern, #3).

Learning & discussion

Local-only registry: register a name, look it up, dedup on collision. The interesting part is registration races on the same name and lookup-during-register consistency.

Existing crates

papaya, dashmap, scc (#51) — lock-free / sharded concurrent maps.

Research — best algorithm/approach

Lock-free concurrent map trade-offs (papaya vs dashmap vs scc — read-heavy vs write-heavy, memory reclamation); register-once semantics; dedup on collision.

Testing — hard as fuck

Linearizability (concurrent register/lookup/unregister with snapshot-consistency assertions), defensive boundary (duplicate name, unregister-then-lookup), sequence. DST over concurrent registration races. Mutation: cargo-mutants, zero survivors.

Absorbs

#51 (lock-free local registry — papaya/dashmap).

[joeldsouzax]

FINALIZED — registry: papaya (name/AID → slab key)

Researched concurrent maps and copy-on-write approaches against our actual workload: async tokio, read-heavy lookups, moderate CONCURRENT register/deregister churn from passivation (#20), values = Copy slab keys. Verdict: papaya.

The pick — papaya

• Maps name/AID → (index, generation) slab key (a Copy value — not the full ActorRef, so the registry never pins a channel; core(actor_ref): rebuild from kameo reference — ActorRef / Weak / Recipient #117 memory-pin residual avoided).
• Lock-free reads → "deadlocking is impossible." With a Copy value you copy the key out and drop the guard in one expression (let k = *map.pin().get(name)?;) — the across-.await hazard class simply doesn't arise. owned_guard() (Send+Sync, holdable across .await) is there if ever needed.
• Purpose-built for read-heavy; wins the read-heavy benchmark; insert tail-latency orders of magnitude below dashmap. Deferred reclamation via seize.
• Absorbs concurrent registration natively — O(1) local bucket writes, no single-writer funnel, no size-scaling write penalty. Handles passivation churn without degrading.

Why not the others

• dashmap — rejected. Its Ref holds a synchronous shard RwLock; held across .await in a work-stealing runtime → deadlock. A Copy-value copy-out works but nothing enforces it — one refactor from a silent deadlock. Exactly the failure mode to design out, not around.
• arc-swap + im HAMT (COW) — rejected here. store silently loses concurrent registrations (last-writer-wins); correct rcu degrades to CAS-retry storms under concurrent churn; documented sweet spot is minute-scale config/routing snapshots, not continuous passivation churn.
• left-right / evmap — narrow optimization only. Best-in-class wait-free reads, and our slab re-validation makes its staleness safe — but it requires forcing single-writer + batched registration. Reach for it as a measured optimization if reads overwhelmingly dominate; not the default.
• scc::HashIndex — async-safe runner-up. Closure-based lock-free reads (peek_with(k, |_, v| *v) — no guard to hold), better write throughput. Switch to it if churn turns out write-heavy.
• flurry — its own docs now redirect users to papaya.

The property that gives us headroom

A registry lookup is re-validated at the slab (#117): a stale entry pointing at a reaped actor fails the generation check → SendError/not-found — the correct semantics anyway. So the registry never needs perfect consistency; we don't pay for strong consistency we don't need (this is why left-right's staleness would even be tolerable).

Value = key, not ref

Store the Copy (index, generation) key (or a WeakActorRef), not the strong ActorRef. Lookup path: registry.get(aid) → key → slab.get(key) → validate generation → clone the typed sender. The registry stays off the channel-pinning path.

Two-tier (not conflated)

This is the local in-process resolver (name/AID → local slab key). Cross-node addressing is the Zenoh key-expr (#121/#2) — a different mechanism (routing/discovery over the dataspace), not this map. Local registry = fast in-process lookup; key-expr = the dataspace address.

Cross-links: ref model #117 · passivation #20 · identity #121 · death-watch #8.

Sources: papaya + benchmarks · Designing papaya · scc · arc-swap perf · im HashMap · left-right · dashmap deadlock.

[joeldsouzax]

Revised by the adversarial review (#122)

papaya stays as the registry, but with the arena dropped (#117 reversed) it stores an erased weak handle (WeakActorRef / Box<dyn SignalMailbox>) per AID — like kameo's HashMap<ActorId, Link> — not a generational slab key. Sits behind the Registry trait seam (#8/#9) so a deterministic impl serves loom/DST and a single-threaded (Rc+HashMap) impl serves the M6 client tier. No sharded-slab underneath unless a benchmark proves AID-hash resolve is a bottleneck (rule #4).