<!-- Stacklift documentation: "Concepts". Source: https://stacklift.joynul.com/docs/concepts · All pages for LLMs: https://stacklift.joynul.com/llms-full.txt -->

> About Stacklift: Stacklift is a hosted platform with source-available SDKs for shipping app releases and over-the-air updates. It works for mobile (React Native, Expo, Flutter, native iOS and Android, Kotlin Multiplatform, .NET MAUI, Unity), web, desktop (Electron, .NET, Java) and backend apps. Developers create releases with the `stacklift` CLI or the dashboard; the server verifies and signs every artifact (SHA-256 + Ed25519), deploys releases to channels with staged rollouts and rollback, and app SDKs check, download and verify updates. Native apps can change screens over the air with server-driven UI layouts and logic with sandboxed scripts, within App Store and Google Play rules. Apps never depend on Stacklift to keep working: everything has a built-in fallback and an exit path.
>
> This page: Runtime versions, channels, rollouts and the release lifecycle.

# Concepts

## Organizations, workspaces, projects

An **organization** is the tenant boundary: members, roles, billing and audit log live there. **Workspaces** group projects inside it. A **project** is one application.

Roles are Owner, Admin, Developer and Viewer. A *project membership* can raise a person's role for one project (never lower it).

## Runtime version

The runtime version is the compatibility key between a release and an installed binary. You set it; Stacklift enforces it:

- a device only receives a release whose `runtimeVersion` equals the one it reports;
- a rollback is refused across runtime versions;
- bump it whenever native code, native modules, permissions or the JS engine change.

## Releases

A release is a version plus verified artifacts. Statuses:

| Status | Meaning |
| --- | --- |
| Draft | Created, no artifacts yet |
| Uploading | Waiting for artifacts |
| Processing | The server is verifying bytes and signing |
| Ready | Every platform has a verified, signed artifact. Deployable |
| Deploying | A deployment or staged rollout is in progress |
| Active | A channel is actually serving it |
| Failed | Verification failed |
| Rolled back | Was served, then replaced by a rollback |
| Archived | Retired; read-only |

A release can carry more than one artifact per platform, as long as the kinds differ: for example a `script-bundle` (rules in JavaScript) and a `ui-layout` (a server-driven screen layout) together. Each SDK asks for the kind it handles.

Transitions are enforced in one place (`@stacklift/shared`), with row-level locks so concurrent operations can't interleave.

## Channels and environments

Channels (`production`, `staging`, `development`, `beta`, or your own) are what devices subscribe to. A channel points at exactly one release at a time. Environments label where a build is meant to run and can be attached to channels and releases.

> A channel serves **one** release. If you deploy a release with a different runtime version, devices on the old runtime stop receiving updates from that channel. The dashboard and CLI warn before you do it.

## Deployments, rollouts, rollbacks

- A **deployment** records the intent to point a channel at a release. It starts `Pending` and only becomes `Succeeded` when the engine has switched the channel in a transaction.
- A **rollout** is a deployment below 100%. Devices are bucketed by `sha256(rolloutId : deviceId) mod 100`; a device is in the cohort when its bucket is below the percentage. Raising the percentage only adds devices. Cancelling returns the cohort to the baseline release.
- A **rollback** points the channel back at an earlier compatible release, cancels any in-flight rollout on it and records the reason.

## Update checks

The delivery plane answers one question: *which release should this device run?* It considers the channel, the active rollout cohort, the runtime version, the platform, the artifact kind the SDK asks for (optional) and whether a verified deliverable artifact exists. Native binaries (`native-binary`, i.e. store builds) and container image references are never offered as updates — store builds are *recorded* by the CLI without being uploaded, see [Store releases](https://stacklift.joynul.com/docs/store-releases.md); desktop installers (`desktop-installer`) are, because the installer is the update mechanism on desktop — see [Desktop apps](https://stacklift.joynul.com/docs/desktop.md).
