feat: Add IAppStartExtender bridge and SentryOptions wiring for app start extension

Introduces the @ApiStatus.Internal IAppStartExtender contract and a NoOp
default, wired into SentryOptions. This is the naming-stable core bridge for
the app start extension API; it is inert until the Android implementation
(PR2/PR3) and public Sentry facade (PR4) land.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: buenaflor

sentry/api/sentry.api

@@ -796,6 +796,12 @@ public final class io/sentry/HubScopesWrapper : io/sentry/IHub {
 	public fun withScope (Lio/sentry/ScopeCallback;)V
 }
 
+public abstract interface class io/sentry/IAppStartExtender {
+	public abstract fun extendAppStart ()V
+	public abstract fun finishAppStart ()V
+	public abstract fun getExtendedAppStartSpan ()Lio/sentry/ISpan;
+}
+
 public abstract interface class io/sentry/IConnectionStatusProvider : java/io/Closeable {
 	public abstract fun addConnectionStatusObserver (Lio/sentry/IConnectionStatusProvider$IConnectionStatusObserver;)Z
 	public abstract fun getConnectionStatus ()Lio/sentry/IConnectionStatusProvider$ConnectionStatus;
@@ -1543,6 +1549,13 @@ public final class io/sentry/MonitorScheduleUnit : java/lang/Enum {
 	public static fun values ()[Lio/sentry/MonitorScheduleUnit;
 }
 
+public final class io/sentry/NoOpAppStartExtender : io/sentry/IAppStartExtender {
+	public fun extendAppStart ()V
+	public fun finishAppStart ()V
+	public fun getExtendedAppStartSpan ()Lio/sentry/ISpan;
+	public static fun getInstance ()Lio/sentry/NoOpAppStartExtender;
+}
+
 public final class io/sentry/NoOpCompositePerformanceCollector : io/sentry/CompositePerformanceCollector {
 	public fun close ()V
 	public static fun getInstance ()Lio/sentry/NoOpCompositePerformanceCollector;
@@ -3603,6 +3616,7 @@ public class io/sentry/SentryOptions {
 	public fun addScopeObserver (Lio/sentry/IScopeObserver;)V
 	public static fun empty ()Lio/sentry/SentryOptions;
 	public fun findPersistingScopeObserver ()Lio/sentry/cache/PersistingScopeObserver;
+	public fun getAppStartExtender ()Lio/sentry/IAppStartExtender;
 	public fun getBackpressureMonitor ()Lio/sentry/backpressure/IBackpressureMonitor;
 	public fun getBeforeBreadcrumb ()Lio/sentry/SentryOptions$BeforeBreadcrumbCallback;
 	public fun getBeforeEnvelopeCallback ()Lio/sentry/SentryOptions$BeforeEnvelopeCallback;
@@ -3749,6 +3763,7 @@ public class io/sentry/SentryOptions {
 	public fun isTraceSampling ()Z
 	public fun isTracingEnabled ()Z
 	public fun merge (Lio/sentry/ExternalOptions;)V
+	public fun setAppStartExtender (Lio/sentry/IAppStartExtender;)V
 	public fun setAttachServerName (Z)V
 	public fun setAttachStacktrace (Z)V
 	public fun setAttachThreads (Z)V

sentry/src/main/java/io/sentry/IAppStartExtender.java

@@ -0,0 +1,27 @@
+package io.sentry;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Bridges the {@code Sentry.extendAppStart()} / {@code Sentry.finishAppStart()} / {@code
+ * Sentry.getExtendedAppStartSpan()} static API to the Android implementation. The default
+ * implementation ({@link NoOpAppStartExtender}) does nothing, so the API is a no-op on platforms
+ * that don't provide an app start measurement.
+ */
+@ApiStatus.Internal
+public interface IAppStartExtender {
+
+  /** Starts extending the app start measurement. See {@code Sentry.extendAppStart()}. */
+  void extendAppStart();
+
+  /** Finishes the extended app start. See {@code Sentry.finishAppStart()}. */
+  void finishAppStart();
+
+  /**
+   * Returns the active extended app start span to attach child spans to, or a no-op span when no
+   * extension is active. See {@code Sentry.getExtendedAppStartSpan()}.
+   */
+  @NotNull
+  ISpan getExtendedAppStartSpan();
+}

sentry/src/main/java/io/sentry/NoOpAppStartExtender.java

@@ -0,0 +1,29 @@
+package io.sentry;
+
+import org.jetbrains.annotations.NotNull;
+
+public final class NoOpAppStartExtender implements IAppStartExtender {
+
+  private static final @NotNull NoOpAppStartExtender instance = new NoOpAppStartExtender();
+
+  private NoOpAppStartExtender() {}
+
+  public static @NotNull NoOpAppStartExtender getInstance() {
+    return instance;
+  }
+
+  @Override
+  public void extendAppStart() {
+    // no-op
+  }
+
+  @Override
+  public void finishAppStart() {
+    // no-op
+  }
+
+  @Override
+  public @NotNull ISpan getExtendedAppStartSpan() {
+    return NoOpSpan.getInstance();
+  }
+}

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -529,6 +529,9 @@ public class SentryOptions {
   private @NotNull FullyDisplayedReporter fullyDisplayedReporter =
       FullyDisplayedReporter.getInstance();
 
+  /** Bridges the app start extension API to the Android implementation. */
+  private @NotNull IAppStartExtender appStartExtender = NoOpAppStartExtender.getInstance();
+
   private @NotNull IConnectionStatusProvider connectionStatusProvider =
       new NoOpConnectionStatusProvider();
 
@@ -2653,6 +2656,21 @@ public void setFullyDisplayedReporter(
     this.fullyDisplayedReporter = fullyDisplayedReporter;
   }
 
+  /**
+   * Gets the app start extender, which bridges the app start extension API to its implementation.
+   *
+   * @return the app start extender.
+   */
+  @ApiStatus.Internal
+  public @NotNull IAppStartExtender getAppStartExtender() {
+    return appStartExtender;
+  }
+
+  @ApiStatus.Internal
+  public void setAppStartExtender(final @NotNull IAppStartExtender appStartExtender) {
+    this.appStartExtender = appStartExtender;
+  }
+
   /**
    * Whether OPTIONS requests should be traced.
    *

sentry/src/test/java/io/sentry/NoOpAppStartExtenderTest.kt

@@ -0,0 +1,28 @@
+package io.sentry
+
+import kotlin.test.Test
+import kotlin.test.assertSame
+
+class NoOpAppStartExtenderTest {
+  private val extender = NoOpAppStartExtender.getInstance()
+
+  @Test
+  fun `getInstance returns the same singleton`() {
+    assertSame(NoOpAppStartExtender.getInstance(), NoOpAppStartExtender.getInstance())
+  }
+
+  @Test
+  fun `getExtendedAppStartSpan returns NoOpSpan`() {
+    assertSame(NoOpSpan.getInstance(), extender.extendedAppStartSpan)
+  }
+
+  @Test
+  fun `extendAppStart is a no-op`() {
+    extender.extendAppStart()
+  }
+
+  @Test
+  fun `finishAppStart is a no-op`() {
+    extender.finishAppStart()
+  }
+}

sentry/src/test/java/io/sentry/SentryOptionsTest.kt

@@ -645,6 +645,26 @@ class SentryOptionsTest {
     assertEquals(FullyDisplayedReporter.getInstance(), SentryOptions().fullyDisplayedReporter)
   }
 
+  @Test
+  fun `when options are initialized, appStartExtender defaults to noop`() {
+    assertEquals(NoOpAppStartExtender.getInstance(), SentryOptions().appStartExtender)
+  }
+
+  @Test
+  fun `when appStartExtender is set, its returned as well`() {
+    val options = SentryOptions()
+    val customExtender =
+      object : IAppStartExtender {
+        override fun extendAppStart() = Unit
+
+        override fun finishAppStart() = Unit
+
+        override fun getExtendedAppStartSpan(): ISpan = NoOpSpan.getInstance()
+      }
+    options.appStartExtender = customExtender
+    assertEquals(customExtender, options.appStartExtender)
+  }
+
   @Test
   fun `when options are initialized, connectionStatusProvider is not null and default to noop`() {
     assertNotNull(SentryOptions().connectionStatusProvider)