Module virtual_endpoint 

VirtualEndpoint: substrate-level endpoint identity that resolves to either a local LocaleAdaptiveRing or a remote-via-QUIC target at runtime.

The substrate’s local data path is mmap-backed rings; the cross-host extension is the QUIC bridge. Today callers know which they’re talking to at construction time: they hold an Arc<LocaleAdaptiveRing> for local peers and configure a QuicBridgeClient for remote peers. VirtualEndpoint unifies the two behind one identifier so application code calls endpoint.send(payload) without grepping config for “is this peer local or remote”.

Registry model

Each substrate process has one in-process VirtualEndpointRegistry that maps EndpointId -> EndpointTarget. The default registry is a process-global OnceLock. Callers that want a custom lifecycle (per-test isolation, per-tenant routing) construct their own registry and pass &registry to the endpoint constructors.

EndpointTarget is an enum: Local(Arc<LocaleAdaptiveRing>) or Remote(RemoteEndpoint). The remote variant holds the address + optional bridge handle and is wired up when QUIC support is enabled.

Pin protocol

VirtualEndpoint::pin_current_target() returns a PinnedEndpoint<'_> that captures the active target at pin time. A subsequent registry.rebind(endpoint_id, new_target) bumps the registry’s generation counter; the pin sees is_still_valid() == false and the holder re-acquires.

For local targets, PinnedEndpoint::as_local() returns &LocaleAdaptiveRing; the caller chains directly into the existing locale-axis pin (pin_current_locale()) and from there into the shape-axis pin. The full chain reaches the native primitive through three Acquire loads, one per axis level.

Structs

EndpointId

Application-supplied identifier for a virtual endpoint. Opaque to the substrate; the registry maps it to a target.

PinnedEndpoint

Pinned snapshot of a virtual endpoint’s target. Captures the registry generation at pin time; one Acquire load on is_still_valid() detects rebinds.

RemoteEndpoint

Describes a remote substrate endpoint reachable over the network.

VirtualEndpoint

A virtual endpoint handle. Holds a reference to the registry + the endpoint id. Application code calls pin_current_target() to get a target snapshot, then dispatches on as_local() / as_remote() to do work.

VirtualEndpointRegistry

In-process registry mapping EndpointId to EndpointTarget. Each rebind bumps the registry-wide generation counter so pinned-endpoint holders see invalidation.

Enums

EndpointTarget

What a virtual endpoint resolves to at runtime.