feat: add Checker Framework annotations for null-safety

Adds @nonnull and @nullable annotations to improve null-safety.

Changes:
- Added checker-qual 3.42.0 dependency to parent POM
- Added checker-qual with 'provided' scope to platform-api and platform-core
- Annotated ApplicationContext interface (13 methods)
- Annotated ServiceRegistry interface (4 methods)
- Annotated ApplicationLifecycleListener interface (6 methods)

Benefits:
- Compile-time null-safety checks
- Better IDE support for null analysis
- Documents null contracts in method signatures
- Zero runtime overhead (provided scope)

Key annotations:
- @nonnull: Method parameters/return values that cannot be null
- @nullable: Values that may be null (e.g., getApplicationInstance())
- Optional<T> always marked @nonnull (container is non-null)

All 226 tests passing with null-safety annotations.

Closes #332

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Flossy

platform-api/pom.xml

@@ -15,7 +15,12 @@
     <description>Public APIs for JPlatform - interfaces and contracts for applications and deployers</description>
 
     <dependencies>
-        <!-- No runtime dependencies - pure interfaces -->
+        <!-- Null-safety annotations (compile-time only) -->
+        <dependency>
+            <groupId>org.checkerframework</groupId>
+            <artifactId>checker-qual</artifactId>
+            <scope>provided</scope>
+        </dependency>
 
         <!-- Test dependencies -->
         <dependency>

platform-api/src/main/java/org/flossware/platform/api/ApplicationContext.java

@@ -21,6 +21,9 @@
 import java.util.Map;
 import java.util.Optional;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
 /**
  * Runtime context for an application running on the platform. Provides access to isolated resources
  * and optional platform features.
@@ -49,68 +52,68 @@ public interface ApplicationContext {
    *
    * @return the application ID
    */
-  String getApplicationId();
+  @NonNull String getApplicationId();
 
   /**
    * Returns the current lifecycle state of this application.
    *
    * @return the application state
    * @see ApplicationState
    */
-  ApplicationState getState();
+  @NonNull ApplicationState getState();
 
   /**
    * Returns the timestamp when this application was deployed.
    *
    * @return the deployment timestamp
    */
-  Instant getDeployedAt();
+  @NonNull Instant getDeployedAt();
 
   /**
    * Returns the isolated classloader for this application. All application classes are loaded
    * through this classloader for isolation.
    *
    * @return the application's classloader
    */
-  ClassLoader getClassLoader();
+  @NonNull ClassLoader getClassLoader();
 
   /**
    * Returns the dedicated thread pool for this application. Use this for concurrent execution to
    * maintain resource isolation.
    *
    * @return the application's thread pool
    */
-  ThreadPoolExecutor getThreadPool();
+  @NonNull ThreadPoolExecutor getThreadPool();
 
   /**
    * Returns the security policy for this application. Use this to check permissions before
    * performing privileged operations.
    *
    * @return the application's security policy
    */
-  SecurityPolicy getSecurityPolicy();
+  @NonNull SecurityPolicy getSecurityPolicy();
 
   /**
    * Returns the resource monitor tracking this application's resource usage. Provides CPU time,
    * memory usage, and thread count metrics.
    *
    * @return the application's resource monitor
    */
-  ResourceMonitor getResourceMonitor();
+  @NonNull ResourceMonitor getResourceMonitor();
 
   /**
    * Returns the message bus if messaging is enabled for this application.
    *
    * @return optional message bus, empty if messaging is not enabled
    */
-  Optional<MessageBus> getMessageBus();
+  @NonNull Optional<MessageBus> getMessageBus();
 
   /**
    * Returns the service registry if messaging is enabled for this application.
    *
    * @return optional service registry, empty if messaging is not enabled
    */
-  Optional<ServiceRegistry> getServiceRegistry();
+  @NonNull Optional<ServiceRegistry> getServiceRegistry();
 
   /**
    * Returns the volume manager if volumes are defined for this application. Provides access to
@@ -119,19 +122,19 @@ public interface ApplicationContext {
    * @return optional volume manager, empty if no volumes are defined
    * @since 2.0
    */
-  Optional<VolumeManager> getVolumeManager();
+  @NonNull Optional<VolumeManager> getVolumeManager();
 
   /**
    * Returns custom properties configured for this application.
    *
    * @return immutable map of application properties
    */
-  Map<String, String> getProperties();
+  @NonNull Map<String, String> getProperties();
 
   /**
    * Returns the application instance if it has been started.
    *
    * @return the application instance, or null if not yet started
    */
-  Object getApplicationInstance();
+  @Nullable Object getApplicationInstance();
 }

platform-api/src/main/java/org/flossware/platform/api/ApplicationLifecycleListener.java

@@ -17,6 +17,8 @@
 
 package org.flossware.platform.api;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 /**
  * Observer interface for application lifecycle events.
  *
@@ -61,30 +63,30 @@ public interface ApplicationLifecycleListener {
    * @param applicationId the application identifier
    * @param descriptor the application descriptor containing configuration
    */
-  void onDeployed(String applicationId, ApplicationDescriptor descriptor);
+  void onDeployed(@NonNull String applicationId, @NonNull ApplicationDescriptor descriptor);
 
   /**
    * Called when an application transitions to RUNNING state.
    *
    * @param applicationId the application identifier
    */
-  void onStarted(String applicationId);
+  void onStarted(@NonNull String applicationId);
 
   /**
    * Called when an application transitions to STOPPED or FAILED state.
    *
    * @param applicationId the application identifier
    * @param exitCode the exit code (0 for normal shutdown, non-zero for errors)
    */
-  void onStopped(String applicationId, int exitCode);
+  void onStopped(@NonNull String applicationId, int exitCode);
 
   /**
    * Called when an application is automatically restarted by the RestartManager.
    *
    * @param applicationId the application identifier
    * @param attemptNumber the restart attempt number (1-based)
    */
-  void onRestarted(String applicationId, int attemptNumber);
+  void onRestarted(@NonNull String applicationId, int attemptNumber);
 
   /**
    * Called when an application's health status changes.
@@ -95,7 +97,10 @@ public interface ApplicationLifecycleListener {
    * @param oldStatus the previous health status
    * @param newStatus the new health status
    */
-  void onHealthChanged(String applicationId, HealthStatus oldStatus, HealthStatus newStatus);
+  void onHealthChanged(
+      @NonNull String applicationId,
+      @NonNull HealthStatus oldStatus,
+      @NonNull HealthStatus newStatus);
 
   /**
    * Called when an application is undeployed from the platform.
@@ -104,5 +109,5 @@ public interface ApplicationLifecycleListener {
    *
    * @param applicationId the application identifier
    */
-  void onUndeployed(String applicationId);
+  void onUndeployed(@NonNull String applicationId);
 }

platform-api/src/main/java/org/flossware/platform/api/ServiceRegistry.java

@@ -20,6 +20,8 @@
 import java.util.List;
 import java.util.Optional;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 /**
  * Service registry for inter-application service discovery. Allows applications to register
  * services and look up services provided by other applications.
@@ -50,7 +52,7 @@ public interface ServiceRegistry {
    * @throws IllegalArgumentException if serviceInterface is not an interface or implementation does
    *     not implement the interface
    */
-  <T> void registerService(Class<T> serviceInterface, T implementation);
+  <T> void registerService(@NonNull Class<T> serviceInterface, @NonNull T implementation);
 
   /**
    * Returns the first registered service for the specified interface. If multiple services are
@@ -60,7 +62,7 @@ public interface ServiceRegistry {
    * @param serviceInterface the interface class
    * @return optional containing the service, or empty if none found
    */
-  <T> Optional<T> getService(Class<T> serviceInterface);
+  @NonNull <T> Optional<T> getService(@NonNull Class<T> serviceInterface);
 
   /**
    * Returns all registered services for the specified interface.
@@ -69,13 +71,13 @@ public interface ServiceRegistry {
    * @param serviceInterface the interface class
    * @return list of all registered services, empty if none found
    */
-  <T> List<T> getAllServices(Class<T> serviceInterface);
+  @NonNull <T> List<T> getAllServices(@NonNull Class<T> serviceInterface);
 
   /**
    * Unregisters a specific service implementation.
    *
    * @param serviceInterface the interface class
    * @param implementation the service implementation to remove
    */
-  void unregisterService(Class<?> serviceInterface, Object implementation);
+  void unregisterService(@NonNull Class<?> serviceInterface, @NonNull Object implementation);
 }