er

Author: kaspernielsen

lifecycle-todos.md

@@ -0,0 +1,66 @@
+# Lifecycle Runtime API TODOs
+
+## ManagedLifecycle
+
+**Core issue: it mixes two concerns.** It's both a state query interface (`currentState()`, `await()`, `isFailed()`) and a command interface (`start()`, `stop()`). This is fine if the only consumer is an external controller, but the comments suggest it could also be injected into guest beans — where `stop()` on yourself is odd and `start()` is meaningless.
+
+Consider splitting into a read-only `LifecycleState` (await, query) and a `LifecycleController` that extends it and adds start/stop. Beans get the read-only view; external hosts get the controller.
+
+**`state()` returns `ManagedLifetimeState`** but is suppressing an exports warning and throws UOE. If this isn't ready, leave it out of the interface entirely — stub methods on public interfaces become API debt.
+
+**`stopInfo()`** returns `Optional.empty()` as default. Same concern — it signals the feature exists but doesn't work.
+
+---
+
+## ManagedLifetimeState
+
+**The desired/actual model is premature.** Without restart support, `desiredState()` is always equal to `currentState()` except during transitions — which `isTransitioning()` already captures. And during a normal transition (e.g. STARTING), the "desired" state is ambiguous (RUNNING? or just "past STARTING"?).
+
+Defer this to when restart exists. For now, `currentState()` + `isFailed()` + `failure()` is sufficient.
+
+**Naming**: Consider `LifecycleSnapshot` or `RunStateSnapshot`. "ManagedLifetimeState" is long and overlaps with both `ManagedLifecycle` and `RunState`.
+
+The `zaLS` stub interface in the same file should be removed or moved.
+
+---
+
+## StopInfo
+
+**Overlap with RunStateTransition**: Both have `from()` state, `failure()`, and represent "what happened when we stopped." They serve similar purposes at different abstraction levels. Pick one or make one a subset of the other.
+
+**`Trigger` as a class with string constants** is an unusual pattern. It's essentially an open enum. Problems:
+- Users can't `switch` on it
+- Equality is identity-based (not string-based)
+- `ENTRY_POINT_COMPLETED` and `NORMAL` are different objects but both have the string `"Normal"` — this is a bug or at least very confusing
+
+If the set is meant to be extensible, consider making `Trigger` a sealed interface with record implementations, or at minimum fix the duplicate `"Normal"` string. If extensibility isn't actually needed, make it a proper enum.
+
+**`hasResult()` / `isCancelled()` / `isCompletedExceptionally()` / `isCompletedNormally()`** — this mirrors `CompletableFuture`'s completion model. But a lifetime stop isn't really a future completion. A stop is either normal, forced, or failed. Simplify to: `isNormal()`, `isFailed()`, `failure()`, `trigger()`.
+
+---
+
+## StopOption
+
+**Marker interface with only static factories** — this works but makes the type unimplementable by users (no methods to implement). If user extension isn't intended, `sealed interface` would make that explicit.
+
+**Too many overlapping concepts**: `forced()`, `now()`, `now(Throwable)`, `forcedGraceTime()` — three or four ways to express "stop hard." Pick one model: `forced()` means interrupt threads immediately, `forced(Duration graceTime)` means try orderly then interrupt. That's two methods, not four.
+
+**`parentStopping()` as a StopOption** feels wrong. That's an internal lifecycle event, not a user-facing option. It should be an internal signal, not part of the public API.
+
+**`restart()` / `tryRestart()`** — the distinction isn't clear from the API. If `restart()` throws when restart isn't supported and `tryRestart()` is best-effort, name them `restart()` and `restartIfSupported()` or similar.
+
+---
+
+## RunStateTransition
+
+**Clean and focused** — this is the best-designed type in the package. `from()`, `to()`, `failure()` is exactly the right surface for an `@OnStop` callback parameter.
+
+---
+
+## Package-level suggestions
+
+1. **Reduce the type count.** `StopInfo`, `RunStateTransition`, and `ManagedLifetimeState` all describe "what state are we in and why." Consider whether `RunStateTransition` alone (with an added `trigger()`) could replace `StopInfo`.
+
+2. **Package name**: `lifecycle.runtime` reads as "runtime stuff for lifecycle." If this is specifically about managed/running lifetimes, `lifecycle.managed` or just collapsing into `lifecycle` would be clearer.
+
+3. **Defer restart.** Multiple types have restart concepts baked in (`StopOption.restart()`, `Trigger.RESTARTING`, `zaLS.isRestarting()`). Since none of it works yet, removing it from the API surface makes the current API smaller and avoids locking in a restart design prematurely.

modules/packed-incubator/packed-incubator-concurrent/src/main/java/app/packed/concurrent/DaemonJobContext.java

@@ -39,8 +39,8 @@ public sealed interface DaemonJobContext extends Context<BaseExtension> permits
     boolean isShutdown();
 
     /**
-     * Blocks until the bean has been shutdown, or the timeout occurs, or the current thread is interrupted, whichever
-     * happens first.
+     * Blocks until the job has been stopped (for example, the application has been shutdown) , or the timeout occurs, or the current thread is interrupted, whichever happens
+     * first.
      *
      * @param timeout
      *            the maximum time to wait
@@ -50,6 +50,7 @@ public sealed interface DaemonJobContext extends Context<BaseExtension> permits
      * @throws InterruptedException
      *             if interrupted while waiting
      */
+    // Maybe rename to sleep instead???
     boolean awaitShutdown(long timeout, TimeUnit unit) throws InterruptedException;
 }
 

modules/packed-incubator/packed-incubator-concurrent/src/main/java/app/packed/concurrent/job/app/PackedJobApp.java

@@ -21,13 +21,13 @@
 import java.util.concurrent.TimeUnit;
 
 import app.packed.application.BootstrapApp;
+import app.packed.application.ManagedApplicationRuntime;
 import app.packed.bean.Bean;
 import app.packed.component.SidehandleBinding;
 import app.packed.component.SidehandleContext;
 import app.packed.lifecycle.LifecycleKind;
 import app.packed.lifecycle.RunState;
-import app.packed.lifecycle.runtime.ManagedLifecycle;
-import app.packed.lifecycle.runtime.StopOption;
+import app.packed.lifecycle.sandbox.StopOption;
 import internal.app.packed.ValueBased;
 
 /** The default implementation of {@link App}. */
@@ -41,9 +41,9 @@ final class PackedJobApp implements JobApp {
     public static final BootstrapApp<PackedJobApp> BOOTSTRAP_APP = BootstrapApp.of(LifecycleKind.MANAGED, Bean.of(PackedJobApp.class));
 
     /** Manages the lifecycle of the app. */
-    private final ManagedLifecycle lifecycle;
+    private final ManagedApplicationRuntime lifecycle;
 
-    PackedJobApp(@SidehandleBinding(FROM_CONTEXT) ManagedLifecycle lc, @SidehandleBinding(FROM_CONTEXT) Future<?> result, SidehandleContext context) {
+    PackedJobApp(@SidehandleBinding(FROM_CONTEXT) ManagedApplicationRuntime lc, @SidehandleBinding(FROM_CONTEXT) Future<?> result, SidehandleContext context) {
         this.lifecycle = lc;
     }
 
@@ -111,6 +111,12 @@ public void close() {}
     /** {@inheritDoc} */
     @Override
     public void stop(StopOption... options) {}
+
+    /** {@inheritDoc} */
+    @Override
+    public String name() {
+        return null;
+    }
 }
 
 /// retur typer

modules/packed-incubator/packed-incubator-concurrent/src/main/java/internal/app/packed/concurrent/daemon/DaemonJobSidehandle.java

@@ -82,10 +82,10 @@ protected void onStart() {
     protected void onStop() {
         // Atomic transition to shutdown state
         if (isShutdown.compareAndSet(false, true)) {
-            // 1. Trigger the latch so awaitShutdown() returns false immediately
+            // Trigger the latch so awaitShutdown() returns false immediately
             shutdownLatch.countDown();
 
-            // 2. Interrupt the thread if the user wants to break out of blocking I/O
+            // Interrupt the thread if the user wants to break out of blocking I/O
             Thread t = thread;
             if (t != null && interruptOnShutdown) {
                 t.interrupt();

modules/packed/src/main/java/app/packed/application/App.java

@@ -7,7 +7,7 @@
 import app.packed.binding.Key;
 import app.packed.container.Wirelet;
 import app.packed.lifecycle.RunState;
-import app.packed.lifecycle.runtime.StopOption;
+import app.packed.lifecycle.sandbox.StopOption;
 
 /**
  * Represents the main entry point for executing and managing Packed applications. This interface provides methods for
@@ -74,6 +74,9 @@ public interface App extends AutoCloseable, ApplicationInterface {
     @Override
     void close();
 
+    /** {@return the name of the application} */
+    String name();
+
     /**
      * Returns the current state of the application.
      *
@@ -232,22 +235,21 @@ interface Launcher extends ApplicationLauncher {
 
         // Config also
 
-
-        @Override
-        default <T> Launcher provide(Key<? super T> key, T value) {
-            return null;
+        default Launcher alwaysRestart() {
+            return this;
         }
 
-        default Launcher alwaysRestart() {
+        default Launcher ignoreAllExceptions() {
             return this;
         }
 
         // rename to arg
 
         // @LaunchArgument/@LaunchArg <--- Injectable
 
-        default Launcher ignoreAllExceptions() {
-            return this;
+        @Override
+        default <T> Launcher provide(Key<? super T> key, T value) {
+            return null;
         }
 
         /**

modules/packed/src/main/java/app/packed/application/ApplicationConfiguration.java

@@ -26,7 +26,7 @@
 import app.packed.build.BuildException;
 import app.packed.build.BuildProcess;
 import app.packed.component.ComponentConfiguration;
-import app.packed.lifecycle.runtime.StopOption;
+import app.packed.lifecycle.sandbox.StopOption;
 
 /**
  * The configuration of an application.

modules/packed/src/main/java/app/packed/application/ApplicationContext.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2026 Kasper Nielsen.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package app.packed.application;
+
+import java.util.concurrent.TimeUnit;
+
+import app.packed.context.Context;
+import app.packed.extension.BaseExtension;
+import app.packed.lifecycle.RunState;
+import app.packed.lifecycle.sandbox.StopOption;
+
+/**
+ * Every bean is automatically in ApplicationContext.
+ */
+public interface ApplicationContext extends Context<BaseExtension> {
+
+    /** {@return the name of the application} */
+    String name();
+
+    /**
+     * Blocks until the lifetime reaches the specified run state, or the current thread is interrupted, whichever happens
+     * first.
+     * <p>
+     * If the lifetime has already reached (or passed) the specified state this method returns immediately. For example, if
+     * attempting to wait on the {@link RunState#RUNNING} state and the lifetime has already terminated. This method will
+     * return immediately.
+     *
+     * @param state
+     *            the state to wait on
+     * @throws InterruptedException
+     *             if interrupted while waiting
+     * @see #await(RunState, long, TimeUnit)
+     * @see #state()
+     */
+    // Er det ikke de eneste relevante states: Running, Stopping???
+    // Hvad er usecase for Running???
+
+    // Terminated <--- er ikke lovligt at vente paa internt
+    // Den her er ikke saerlig brugbart
+    void sleep(RunState state) throws InterruptedException;
+
+    /**
+     * Blocks until the component has reached the requested state, or the timeout occurs, or the current thread is
+     * interrupted, whichever happens first.
+     * <p>
+     * If the component has already reached or passed the specified state this method returns immediately with. For example,
+     * if attempting to wait on the {@link RunState#RUNNING} state and the object has already been stopped. This method will
+     * return immediately with true.
+     *
+     * @param state
+     *            the state to wait on
+     * @param timeout
+     *            the maximum time to wait
+     * @param unit
+     *            the time unit of the timeout argument
+     * @return {@code true} if this component is in (or has already passed) the specified state and {@code false} if the
+     *         timeout elapsed before reaching the state
+     * @throws InterruptedException
+     *             if interrupted while waiting
+     * @see #await(RunState)
+     * @see #state()
+     */
+    boolean sleep(RunState state, long timeout, TimeUnit unit) throws InterruptedException;
+
+    /** {@return the current state of the application} */
+    RunState currentState();
+
+    /** {@return the desired state of the application.} */
+    RunState desiredState();
+
+    /**
+     * @return
+     */
+    boolean isManaged();
+
+    /**
+     * Attempts to stop the application.
+     *
+     * @param options
+     *            stop options
+     * @return false if already shutdown otherwise true
+     * @throws IllegalStateException
+     *             if attempting to shutdown the container while initializing
+     * @throws UnsupportedOperationException
+     *             if the application is not {@link #isManaged() managed}
+     */
+    boolean stopAsync(StopOption... options);
+}

modules/packed/src/main/java/app/packed/application/BootstrapApp.java

@@ -164,6 +164,9 @@ default <E> BootstrapApp<E> map(Function<? super I, ? extends E> mapper) {
     // withExpectingResult
     BootstrapApp<I> withExpectsResult(Class<?> resultType);
 
+    // Can have injected ApplicationName
+    // ManagedApplicationRuntime
+
     static <A> BootstrapApp<A> of(LifecycleKind lifecycleKind, Bean<A> bean) {
         return PackedBootstrapApp.of(lifecycleKind, bean);
     }