# bootc composefs-finalize-staged - Process Flowchart

## Overview

This document provides a visual representation of the `bootc composefs-finalize-staged` process flow, showing the decision points, operations, and system state changes involved in finalizing staged composefs deployments.

## Main Process Flow

```
┌─────────────────────────────────────────────────────────────────┐
│              bootc composefs-finalize-staged                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Get Deployment Status                       │
│                                                                 │
│  • Get composefs deployment status                             │
│  • Validate booted composefs deployment                        │
│  • Check for staged deployment                                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Validate Staged Deployment                  │
│                                                                 │
│  • Check if staged deployment exists                           │
│  • Validate staged deployment is composefs                     │
│  • Get staged composefs configuration                          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Mount EROFS Image                           │
│                                                                 │
│  • Open sysroot directory                                      │
│  • Mount booted EROFS image                                    │
│  • Create temporary mount point                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Perform /etc Merge                          │
│                                                                 │
│  • Access pristine /etc from EROFS                             │
│  • Access current /etc from system                             │
│  • Access new /etc from staged deployment                      │
│  • Perform 3-way merge                                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Unmount EROFS Image                         │
│                                                                 │
│  • Drop temporary mount                                        │
│  • Clean up EROFS mount                                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Mount ESP Partition                         │
│                                                                 │
│  • Get sysroot parent device                                   │
│  • Get ESP partition                                            │
│  • Mount ESP partition                                          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Update Bootloader Entries                   │
│                                                                 │
│  • Determine bootloader type (GRUB vs systemd-boot)            │
│  • Determine boot type (BLS vs UKI)                            │
│  • Update appropriate bootloader entries                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Complete Finalization                       │
│                                                                 │
│  • Sync filesystem changes                                     │
│  • Update deployment state                                     │
│  • Complete finalization process                               │
└─────────────────────────────────────────────────────────────────┘
```

## Detailed Process Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Deployment Status Retrieval                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Get Composefs Status                        │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              composefs_deployment_status                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                Check Kernel Cmdline                        │ │
│  │                                                             │ │
│  │  • Parse composefs parameter                               │ │
│  │  • Extract composefs digest                                │ │
│  │  • Validate composefs state                                │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Staged Deployment Validation                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check Staged Deployment                     │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Staged Deployment Check                       │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   No Staged     │    │           Staged Found              │ │
│  │   Deployment    │    │                                     │ │
│  │                 │    │  ┌─────────────────────────────────┐│ │
│  │  ┌─────────────┐│    │  │ Check Composefs Type            ││ │
│  │  │ Return OK   ││    │  │                                 ││ │
│  │  │ (No Action) ││    │  │ • Validate composefs deployment ││ │
│  │  └─────────────┘│    │  │ • Get composefs configuration   ││ │
│  └─────────────────┘    │  └─────────────────────────────────┘│ │
│                         └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    EROFS Image Operations                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Mount EROFS Image                           │
│                                                                 │
│  • Open /sysroot directory                                     │
│  • Mount booted EROFS image using verity digest                │
│  • Create temporary mount point                                │
│  • Access pristine /etc configuration                          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    /etc Configuration Merge                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Three-Way Merge Process                     │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Pristine      │  │    Current      │  │      New        │ │
│  │   /etc          │  │    /etc         │  │    /etc         │ │
│  │                 │  │                 │  │                 │ │
│  │  ┌─────────────┐│  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ From EROFS  ││  │  │ From System ││  │  │ From Staged ││ │
│  │  │ Image       ││  │  │ /etc        ││  │  │ Deployment  ││ │
│  │  └─────────────┘│  │  └─────────────┘│  │  └─────────────┘│ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
│           │                     │                     │         │
│           └─────────────────────┼─────────────────────┘         │
│                                 ▼                               │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                Compute Differences                          │ │
│  │                                                             │ │
│  │  • Compare pristine vs current                             │ │
│  │  • Identify changes made by user                           │ │
│  │  • Prepare for merge operation                             │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                 │                               │
│                                 ▼                               │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                Perform Merge                                │ │
│  │                                                             │ │
│  │  • Apply pristine configuration as base                    │ │
│  │  • Apply user changes from current                         │ │
│  │  • Apply new changes from staged deployment                │ │
│  │  • Resolve conflicts if any                                │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    EROFS Cleanup                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Unmount EROFS Image                         │
│                                                                 │
│  • Drop temporary mount                                        │
│  • Clean up EROFS mount                                        │
│  • Release file descriptors                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ESP Partition Operations                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Mount ESP Partition                         │
│                                                                 │
│  • Get sysroot parent device                                   │
│  • Get ESP partition information                               │
│  • Mount ESP partition                                          │
│  • Access bootloader entries                                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Bootloader Management                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Determine Bootloader Type                   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Bootloader Type Check                         │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      GRUB       │    │           systemd-boot              │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ BLS Entries ││    │  │ BLS Entries                     ││ │
│  │  │ UKI Entries ││    │  │ UKI Entries                     ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Bootloader Operations Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Bootloader Operations                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    GRUB Bootloader                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Determine Boot Type                         │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   BLS Entries   │    │           UKI Entries               │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Update BLS  ││    │  │ Update UKI Entries              ││ │
│  │  │ Entries     ││    │  │                                 ││ │
│  │  │             ││    │  │ • Rename staged UKI files       ││ │
│  │  │ • Exchange  ││    │  │ • Update GRUB configuration     ││ │
│  │  │   entries   ││    │  │ • Sync filesystem               ││ │
│  │  │ • Update    ││    │  └─────────────────────────────────┘│ │
│  │  │   order     ││    │                                     │ │
│  │  └─────────────┘│    │                                     │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    systemd-boot Bootloader                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Determine Boot Type                         │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   BLS Entries   │    │           UKI Entries               │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Update BLS  ││    │  │ Update UKI Entries              ││ │
│  │  │ Entries     ││    │  │                                 ││ │
│  │  │             ││    │  │ • Rename staged UKI files       ││ │
│  │  │ • Exchange  ││    │  │ • Sync filesystem               ││ │
│  │  │   entries   ││    │  │ • Update boot order             ││ │
│  │  │ • Update    ││    │  └─────────────────────────────────┘│ │
│  │  │   order     ││    │                                     │ │
│  │  └─────────────┘│    │                                     │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Error Handling Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Error Detection                              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Classification                         │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Deployment    │  │   Filesystem    │  │   Bootloader    │ │
│  │   Errors        │  │   Errors        │  │   Errors        │ │
│  │                 │  │                 │  │                 │ │
│  │ • No Staged     │  │ • EROFS Mount   │  │ • Entry Update  │ │
│  │   Deployment    │  │   Failed        │  │   Failed        │ │
│  │ • Non-Composefs │  │ • ESP Mount     │  │ • Sync Failed   │ │
│  │   Deployment    │  │   Failed        │  │ • Permission    │ │
│  │ • Invalid State │  │ • Access Denied │  │   Denied        │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Response                               │
│                                                                 │
│  • Log error details                                            │
│  • Provide context information                                  │
│  • Return appropriate error code                                │
│  • Clean up resources                                           │
│  • Notify systemd service                                       │
└─────────────────────────────────────────────────────────────────┘
```

## Systemd Service Integration Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Systemd Service Lifecycle                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Service Start                                │
│                                                                 │
│  • Service starts early in boot process                        │
│  • After local-fs.target                                       │
│  • Before basic.target and final.target                        │
│  • After systemd-journal-flush.service                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Command Execution                            │
│                                                                 │
│  • Execute bootc composefs-finalize-staged                     │
│  • With 5-minute timeout                                       │
│  • With sandboxing enabled                                     │
│  • With /etc read-only protection                              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Service Completion                           │
│                                                                 │
│  • Command completes successfully or fails                     │
│  • Service remains active (RemainAfterExit=yes)                │
│  • System continues boot process                                │
│  • Logs are written to journal                                 │
└─────────────────────────────────────────────────────────────────┘
```

## State Transitions Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    System States                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initial State                                │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   Staged Deployment Present                                 │ │
│  │                                                             │ │
│  │ • Staged composefs deployment exists                        │ │
│  │ • Booted composefs deployment active                        │ │
│  │ • System ready for finalization                             │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Finalization Process                     │ │
│  │                                                             │ │
│  │  • Mount EROFS image                                        │ │
│  │  • Perform /etc merge                                       │ │
│  │  • Update bootloader entries                                │ │
│  │  • Sync filesystem changes                                  │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Final State                              │ │
│  │                                                             │ │
│  │ • Staged deployment finalized                               │ │
│  │ • Bootloader entries updated                                │ │
│  │ • System ready for next boot                                │ │
│  │ • Staged deployment becomes active                          │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

This flowchart provides a comprehensive visual representation of the bootc composefs-finalize-staged process, showing all decision points, operations, and state transitions involved in finalizing staged composefs deployments.