refactor: plugin service lifecycle safety — @ServiceAvailability annotation and hollow-service init guards

[sridhar-panigrahi]

Summary

This PR addresses one of the core structural problems in the Besu Plugin API described in LFDT mentorship project #82: the plugin lifecycle during startup is not well-defined, causing plugins to access services before they are fully initialized.

Specifically, three services (BlockchainService, TransactionSimulationService, RpcEndpointService) follow a "hollow service" pattern — they are registered in the ServiceManager during the REGISTERING phase so plugins can obtain a reference, but their internal state (blockchain, protocolSchedule, transactionSimulator) is only set via init() calls in startPlugins(). Any plugin that calls query methods during register() receives a NullPointerException with no indication of what went wrong or how to fix it.

Changes

plugin-api: ServiceLifecyclePhase enum
Introduces a public enum documenting the ordered phases of the plugin lifecycle (UNINITIALIZED → REGISTERING → REGISTERED → BEFORE_EXTERNAL_SERVICES → STARTED → STOPPING → STOPPED) with Javadoc listing which services are available at each phase. This is the foundation for lifecycle-aware tooling and documentation.

plugin-api: @ServiceAvailability annotation
A new @Retention(RUNTIME) annotation for service interfaces. Declares:

• availableFrom — earliest phase the service is registered and accessible
• fullyInitializedFrom — phase from which all methods are safe to call (defaults to availableFrom)

The RUNTIME retention is intentional: it allows future runtime checks, logging, and IDE plugin tooling to detect premature service access programmatically.

Applied to:

Service	availableFrom	fullyInitializedFrom
BlockchainService	REGISTERING	STARTED
TransactionSimulationService	REGISTERING	STARTED
RpcEndpointService	REGISTERING	STARTED
BesuEvents	STARTED	STARTED
BesuConfiguration, PicoCLIOptions, StorageService, SecurityModuleService, PermissioningService, MetricCategoryRegistry	REGISTERING	REGISTERING

BlockchainServiceImpl: checkInitialized() guard
All query methods (getBlockByNumber, getBlockByHash, getBlockHeaderByHash, getChainHeadHash, getChainHeadHeader) now call checkInitialized() before delegating to the blockchain. If called before init(), they throw IllegalStateException with an actionable message:

BlockchainService is not yet fully initialized.
Blockchain query methods are only available after the plugin start() callback
(i.e. during the STARTED lifecycle phase). If you need to access blockchain
state, store the ServiceManager reference in register() and defer the service
call to start().

Instead of NullPointerException: Cannot invoke "MutableBlockchain.getBlockByNumber(long)".

TransactionSimulationServiceImpl: same guard pattern
simulatePendingBlockHeader() and simulate() overloads protected with checkInitialized().

BesuPluginContextImpl: three safety improvements

1. state field made volatile — the lifecycle phase is now part of the public API surface (via getLifecyclePhase()). Plugin background threads that call this need a happens-before guarantee.
2. serviceRegistry switched from HashMap to ConcurrentHashMap — consistent with the recent thread-safety fix on the same class; concurrent reads during plugin startup are now safe.
3. addService() now emits a WARN log when a service is overwritten with a different instance — surfaces accidental overwrites that would otherwise be completely silent. Same-instance re-registration does not warn.
4. getService() now emits a DEBUG log including the current lifecycle phase when a service is not found — gives plugin developers the exact context they need to diagnose ordering issues.

Tests

• BlockchainServiceImplTest — verifies IllegalStateException on all guarded query methods before init(), and that they delegate correctly after init().
• TransactionSimulationServiceImplTest — same for simulation methods.
• BesuPluginContextImplTest — covers first registration, same-instance re-registration (no warning), different-instance overwrite (new instance returned), missing service returns Optional.empty(), concurrent read/write safety with 20 threads, and type validation.

Relation to mentorship project #82

This PR directly targets Deliverable 2: Lifecycle Refinement — eliminating race conditions where plugins attempt to access a service before it is fully initialized. It also lays groundwork for Deliverable 3: API Versioning System through the @ServiceAvailability annotation, which provides a structured, machine-readable way to express service availability contracts.

[sridhar-panigrahi]

@fab-10 , please let me know your thoughts on this !