4/28/2025, copying Lifecycle 2.0 agreed within Firebolt working group from restricted "Simplified Lifecycle2.0" page from "Preferred Program" space to public regular "RDK" space so everyone can read it and can be referred to in App Lifecycle Presentation in Tech Summit 2025 session.

1. Functional Requirements

1.1. State diagram

1.2. State & transition requirements

1.3. Intents

Non-comprehensive list of intents that are used in concert with Lifecycle to manage the deep-linking and quick switching.

{
  "action": "launch"
}

{
  "action": "preload"
}

{
  "action": "home"
}

1.4. Container mapping (tentative)

This is tentative, requires review with engineering, but having it creates a level of confidence in our model.

API Type:

method = App → Platform
notification = platform → app

1.5. W3C Page Lifecycle

This is tentative, requires review with engineering, but having it creates a level of confidence in our model.

Sample W3C app:

import { Discovery } from '@firebolt-js/sdk'

document.addEventListener("visibilityChange" (event) => {
  var deeplink = await Discovery.getNavigationIntent()

  if (deeplink.action === 'preload') {
    // reset UI and load a low resource, "good" experience, e.g. a splash screen
    clearUX()
    showSplash()
  }
  else if (deeplink.action === 'entity') {
    loadDetailsPage(deeplink.data.entityId)
  }
  else if (deeplink.action === 'playback') {
    loadPlayer(deeplink.data.entityId)
  }
    
  // check if visible or hidden
  if (document.visibilityState === 'visible') {
    // App moved to Active
    turnOnAnimations()
  }
  else {
    turnOffAnimations()
    showSplash()
  }
}) 

document.addEventListener("resume", () => {
  showSplash()
  reauthenticateWithBackoffice()
})

All method calls are to app-written functionality's except for Discovery.getNavigationIntent()

1.6. Open questions

List of open items

2. Non-functional Requirements

These use cases do not affect the Function Requirements, but need to be solved as part of non-function requirements by architecture & engineering.

2.1. Open questions

Next step: NFR PoC & documentation w/ engineering

3. States and explanation

from Bart C after finalization discussion, 6 March 25 Update

3.1. 1 AppContainer/process start & setting Navigation Intent

Various uses case can lead to start or preload an applications. Typically the user will request to start specific App in the IUI (Main UI) with the intent to bring it to the screen. 
The IUI will call upon the platform ALM (ALM stands here for ApplicationLifecycleManager) to start specific app_id and optionally also specify via NavigationIntent structure what specific view of the app should be opened. 
Technically the ALM will do many things when creating app. Won't describe here everything it does, only parts relevant to this lifecycle. ALM will create session_id/token required for secure communication between App and Firebolt Server. ALM will set the NavigationIntent value it got from IUI on the NavigationIntent singleton associated with that Application_id on the Firebolt Server. 
The ALM will check what apptype, prepare and initiate start of associated AppContainer,  optionaly set StartTargetState ENV var on AppContainer (that defines target bootflow at moment of containerstart) and and then App process execution within the Container will start. TBD if TBD in actualy native App implementation if bringing StartTargetState ENV variable brings in significant improvement in launch time 

The App can/must assume that it is in "INITIALIZING" state from its process start. No specific Notification will be send from ALM to App lto tell it that it is in Initializing state because Firebolt communication between App and ALM is not established yet. 

3.2. 2 Firebolt Lifecycle communication & getNavigationIntent

App/AppEngine connects to Firebolt Server App with Authentication token/session_id that it got as env value within the container env.

One of first things App must is to call is Discovery.getNatvigationIntent(2a) , register for each Lifecycle2.0 notifications with Lifecycle.listen('start',callback) pattern and then do 
 call Lifecycle.ready(2b) method to say to platform it is ready for Lifecycle communications. Important that this Lifecycle.ready method will be returned with OK or ERROR coming from ALM (through FireboltServer) as it serves as confirmation, handshake between App and ALM that Lifecycle communication can start.
Discovery.getNavigationIntent (is singleton for each App_id) returns NavigationIntent for the App. To for example know what screen/deeplink to load in the app. Definition of all intent values in separate section/document

3.3. 3 cold start flow to pause or suspend directly

The app will startup either in :

• A)regular App startup flow that leads to PAUSED and possibly other state afterwards
• B)or in flow that leads to SUSPENDED state directly. Latter is more unusual and not supported by all Apps (eg Netflix requires it) but platform and lifecycle model must support it 
  The ALM decides the flow the App must follow based on use case & app capabilities and communicates that to the App explicitly with with different Lifecycle Notification, onStart for flow A and onStartSuspend for flow B. ALM may also communicate that already earlier via other means (ENV variable or part of NavigationIntent structure) but these are not necessary guaranteed

Example use case of flow B)
At box boot the ALM may decide to preload specific applications so these would launch quick (quicker compared to boot from cold start) when user requests them. But to not consume too much resources ALM decides to preload them in Suspended mode directly, provided that the application that supports that. Netflix supports it but for example WebApps won't support preloading them via this flow B) from initializing to suspended directly, these require to be preloaded via passing paused state and then suspend/hibernate them.

3.3.1. 3a coldstart to pause

3a describes flow from Initializing to PAUSED (see 3a). ALM will send OnStart(3a) to signal App that it must follow flow A to PAUSED and is entering PAUSED state and should initialize its RialtoClient and connect to associated RialtoServer (preparing but not setting up active Audio Video stream Session yet though), setup Wayland-egl surface with associated shell, fetch the App Graphics assets relevant to the NavigationIntent from network/flash and possibly load textures, vertices and shaders in GPU to prepare for frame rendering. 
The moment the Application renders its first frame on the actual wayland-EGL surface (eglSwapBuffers & wl.commit) is IMPORTANT Point in Lifecycle model.
Because that is trigger and pre-requisite for the transition to Active and if all conditions are fulfilled will lead to sending of onActivate() message in 4

Notes :
*At the moment the App got onStart event, App can assume it is in PAUSED state even though in reality it may still be transitioning to 'stable' PAUSED state (in ALM internal App state, we will make difference between transition & state at first frame render). 
*Important that ALM only sends OnStart event when RialtoServer instance associated with App/AppEngine is ready. ALM must have started RialtoServer instance through RialtoServerManager before seding OnStart notification. 

3.3.2. 3b preload in suspend (lukewarm)

3b)is for preload directly in suspend use case, for example required for netflix, where netflix will boot directly in suspended mode. The App must not setup Wayland-EGL surface, no rialto AV client and should not load textures,vertices, shaders in GPU.  
Note that only few apps can support this direct to suspeded mode preload. For example WebApps through browser cannot be preloaded this way. These need to first enter paused state and then moved to suspended state.
REMAINING open QUESTION here : On what basis will ALM know and decide that App can be considered to have landed in Suspended mode instead of still being in transiting state? 

3.4. 4 App Activation

The moment the Application renders its first frame on its actual Wayland-egl surface (eglSwapBuffers wl.commit) in PAUSED mode is IMPORTANT tipping Point in Lifecycle model.
Because that will trigger the transition to Active and sending of onActivate (see 4) message if all conditions are fulfilled.
Following chain of events happens underneath: That first fame rendering (first eglSwapBuffers wl.commit) will be detected by westeros wayland window manager and send WstClient_firstFrame event to ALM and ALM in case this is associated with LaunchApp request from IUI (and not preload request) will notify the IUI (MainApp) that this app_id is ready to be made visible. It is IUI that makes the decision to make that app/window visible or not as that depends on expected User behaviour/UI state. In regular App start flow that IUI will typically decide to make the app visible and will instruct (preferably through ALM) to make the App window visible  on the Westeros window manager. IUI will then typically also stop rendering possible App spinner or splash screen it may have rendered to avoid black screen transitions during Apploading transition.
Upon setVisible instruction from IUI ALM will send onActivate (4)  notification to the App and do set_visible for that window on windowmanager (typically via westeros simple shell). At wayland level, wayland client app will receive wl_surface.enter event for its surface.
At same time ALM will send event to RialoServer associated with the App to allow active AV sessions. Because App moved to Active state it can now setup actual audio/video sessions through Rialto
Also important is that we require that the App/Appengine first rendered frame is splash screen or a like and does not lead to bad frame-blinking experience for user

3.5. 5 App deactivation

Switch from ACTIVE to PAUSED can be quasi atomic only for those Apps that use Rialto because ALM can force AV tear down via RialtoServerManager instantly. Feedback from rialto/experts is that this force tear down will not have negative impact on such app itself (rialto client takes care?, need to confirm that in testing)
Upon switch to Paused state. onPaused(5) event is sent

3.6. 6 suspending

In suspended mode we expect APP/Appengine to reduce RAM of app, destroy its associated wayland-egl surface (to release associated GFX buffer), release its GPU textures and vertices and shaders in GPU and  release Rialto Client, ALM will release/tear down associated Rialto Server instance. 
(this states corresponds to Frozen state for WebApps in W3C PageLifecycle - Javascript execution of WebApplications within browser engine will be halted)

All these resouces cannot be atomically released by the app all at once. It will take some transition time (x ms). Also how does ALM know when App has reached the defined suspend mode?

To signal and start that transition to suspended state we send onSuspend (6a) Notification with optionally time in ms we expect App to reach suspended mode. App has now x ms to release resources. Value of sending expected time is in debate. 
From App point of view, we consider the app in "suspended state" also during transition state towards "suspended" state. On the ALM side those will remain 2 different states though. (suspending vs suspended)

Around expected transition time, ALM should check, police actual resource deallocation of App. If resouce allocation is still above what is expected the ALM can decided to trigger destroy of the app.

ALM monitor can monitor releasing of
-RAM : monitor PID ram usage:Yes
-EGL surface destroy: event from WesterosWindow Manager : Yes 
-releasing GPU memory textures, release GPU objects (triangles) & operations. : Currently RDK has no tools/HAL defined that allows that. to Investigate. Android AOSP is doing it see "adb shell dumpsys gfxinfo <package_name>" and is using Gralloc module for that in its HAL. Sky has addeded cgroup gpu resouce extension and did  modifs/adds on gfx driver code to measure usage

Alternative to Full EGL surface destroy by application is reducing its size to 1x1 pixel by the platform Window Manager under the hood. That also releases quasi all memory associated with double/tripple buffer app renders in. Comcast has done positive PoC with that.

3.7. 7 hibernating

App should have released all GPU objects, EGL surfaces and reduced its RAM already in suspended mode. That is pre-requisite and abosolute MUST (No GPU textures, W-EGL surfaces anymore associated wit the App) before app can be transitioned to hibernated mode.  
Other pre-requisite is that App/AppEngine is designed to handle restoring from hibernate.

Same pattern. onHibernate (7) notification Event to signal to app that we are about to hibernate within x ms. 
Most apps will already have done the necessary things for it in suspended mode. (eg WebApps themselves will have done that,)? A few apps might still have to close few remaining files, nework connections. Platform may decide to tweek those x ms wait for hibernate per app type/platform. The actual technology & component used by the Platform to do App hibernation is MEMCR in RDK. 

3.8. 8 restoring from Hibernated

is about restoring App from Hibernate mode. ALM triggers restore of App processes on MEMCR deamon (eg via wakeup container on dobby)
(question: AML does get success/failure back from  MemCR/Dobby when triggering restore but is success always really a success?)
Effectively when restore happend successfully, the App is back in RAM and gets CPU cycles.
ALM then sends onRestore (8) notification ( to App (perhaps with info params like period App was hibernated ) to make App aware it was hibernated, can communicate agan with ALM and can act as trigger for App to do some App component specific refresh/restore logic
We assume that websocket connection between App and FireboltServer was not torn down.  Hope that is safe and rocksolid assumption also in corner cases. Will need to be confirmed and well tested, otherwise it will create problems

3.9. 9 resuming from suspended

ALM sends onResume (9a) notification to signal the app to resume and allocate resources again RAM, W-EGL surface, GFX textures, Rialto Client. ALM will reinstantiated associated RialtoServer and set new NavigationIntent prior to onResume Notification.
App can assume it is in PAUSED state when receiving this Notification even though in reality it is still transitioning to stable PAUSED state (in ALM we will make diff between transition & state at first frame rend)
The Notification also serves as trigger for the App to get the Disovery.getNavigationIntent value (see 9b) (which is singleton for each App_id) which App needs to know what screen to load

3.10. 10 hotstart

User/IUM wants to launch app that is PAUZED stated, Since in PAUSED state App is already well preloaded (is hot) transition is quasi instant. Associated new NavigationIntent should set by ALM prior to onActivate (10a) Notification.
onActive Notification is sent by ALM upon IUI trigger together with setVisible on Windowmanager. In this scenario the OnActive Notification also serves as trigger for the App to get the Disovery.getNavigationIntent value (see 10b)

3.11. 11 user exit within App

User is interacting with app and uses App menu to exit it. App must use .Close (11) method on FireboltServer to tell ALM and then ALM will initiate either onDestroy, onPaused (and possibly then further OnSuspend) depending on its chosen policy

3.12. 12 destroy App

There can be several reasons why ALM decides to destroy an App. If it decides to destroy the app. It sends onDestroy (12) notification giving Application some time to close some of its internal resources before actually shutting down the AppContainer/killing the App process and providing reason string for destoring it

4. PRD

4.1. Use-cases

Acceptance criteria reference the flow diagrams above with a number, (#), next to each MUST/SHOULD/MAY statement. 

4.2. Container Notes

4.2.1. Netflix

Can't share the Neflix info on public site, requires appropriate access control 

Referring to restricted pages behind access control

Simplified Lifecycle 2.0#ApplicationStates  

https://docs.netflixpartners.com/docs/nrdp/nrdp2024/application-states-and-management/

4.2.2.  Youtube Cobalt

4.2.2.1. 4.2.2.1. Application States

https://developers.google.com/youtube/cobalt/docs/reference/starboard/modules/16/event
https://developers.google.com/youtube/cobalt/docs/reference/starboard/modules/16/system
https://developers.google.com/youtube/cobalt/docs/gen/cobalt/doc/lifecycle

4.2.2.2. Shutdown Reasons

Cobalt does not support any particular shutdown reasons–the app can be killed or transitioned between states without specifying a reason.

4.2.3. Prime

Can't share the Amazon info on public site, requires appropriate access control 

Referring to restricted pages behind access control

Simplified Lifecycle 2.0#Prime

https://partnercentral.amazon.com/docs/avpkv6/display.html