lifecycle

Lifecycle

Directory map

• model/: lifecycle vocabulary and shared structs.
• metadata/: static lifecycle catalogs and validation.
• service/: lifecycle use cases called by routes.
• orchestration/: pipeline run and node-run seeding.
• projection/: management-state projection updates.
• runtime/: future execution adapters and runners.
• api/: future lifecycle-specific API surface.

Target operation model

Lifecycle operations should be described by four independent dimensions. Each dimension answers one question only.

Dimension overview

operation_type

Describes the lifecycle verb.

Typical values:

• install
• start
• stop
• upgrade
• rollback
• publish

Rules:

• operation_type remains a first-class selector dimension.
• It describes intent, not transport, origin, or runtime topology.

trigger

Initiator semantics: was this operation explicitly requested by a user or automatically generated by the system?

Canonical values:

• manual
• automatic

Rules:

• Install operations usually enter with manual.
• Follow-up lifecycle actions also remain manual unless AppOS itself enqueues work.
• trigger does not participate in pipeline selection.
• Legacy values such as manualops, gitops, fileops, store, and system should continue to normalize into the canonical trigger values during migration.

channel

Business origin of the app. This dimension answers where the app comes from, not what execution steps AppOS must perform.

Canonical values:

• store
• git
• custom

Meaning:

• store: installed from an app-store template or catalog entry.
• git: installed from a Git repository.
• custom: provided directly by the operator, regardless of whether the payload is compose content, a source archive, or an image-oriented build path.

Rules:

• channel replaces the current overloaded source concept.
• channel should be preserved across later lifecycle actions.
• channel is not a selector dimension.
• channel is business metadata for UX, policy, release lineage, and future upstream-aware behaviors.

execution_mode

Execution-mode semantics: which pipeline shape should AppOS use?

Canonical values:

• compose
• build

Meaning:

• compose: AppOS can deploy directly from resolved compose input.
• build: AppOS must build an artifact before it can deploy.

Rules:

• execution_mode replaces the current overloaded adapter concept.
• Pipeline definitions should be selected by operation_type + execution_mode.
• execution_mode is intentionally small because it represents graph shape, not ingress detail.

Build strategy is not a top-level dimension

AppOS does not need an additional top-level lifecycle dimension for build strategy.

Why:

• The meaningful graph split is whether AppOS deploys directly or builds first.
• Different build strategies are internal details of the build execution mode.
• Promoting build strategy to a top-level selector dimension too early would create unnecessary combinatorial growth.

Build-specific details should remain nested under build input metadata, for example:

• dockerfile
• buildpacks
• future binary
• future static-site

These are implementation details of build, not separate top-level lifecycle axes.

Selector rule

Pipeline definitions should be selected by:

• operation_type + execution_mode

They should not be selected by:

• operation_type + channel + execution_mode
• operation_type + trigger + execution_mode

Reasoning:

• channel changes business origin, not graph shape.
• trigger changes initiator semantics, not graph shape.
• execution_mode is the only install-time dimension that materially changes preflight, node graph, and artifact flow.

Example mapping

Current code-to-target terminology map

The codebase has not fully adopted the target names yet. During migration, these current storage names map to the target model as follows.

Migration intent:

• rename source semantics to channel
• rename adapter semantics to execution_mode
• keep current storage fields only as transitional implementation details until schema and API naming catch up

Practical guidance

• Use channel when the question is about upstream or origin.
• Use execution_mode when the question is about pipeline shape.
• Do not encode channel into execution_mode names.
• Do not create a separate top-level build dimension unless AppOS later proves that build itself must split into materially different pipeline families.