Installation on Raspberry Pi 4 (Debian 12 Bookworm arm64) Fails Without Repository Downgrade/Upgrade Workaround

## Expected Behavior

After setting up the official Microsoft Debian 12 (`bookworm`) repository on a clean Raspberry Pi OS (64-bit) installation, running `sudo apt-get install aziot-edge` should successfully install the IoT Edge runtime and its dependencies. Following guidelines from: `https://learn.microsoft.com/en-us/azure/iot-edge/how-to-provision-single-device-linux-symmetric?tabs=azure-portal%2Cdebian`

## Current Behavior

The installation fails with the error:

1. **Package Not Found Error:** Even after correcting repositories, `apt` sometimes enters a state where it reports `E: Unable to locate package aziot-edge`, despite the repository being configured correctly and `apt-get update` completing successfully.

The only way to achieve a successful installation was to apply a specific **workaround**.

## Steps to Reproduce

1. Start with a Raspberry Pi 4 running Raspberry Pi OS (64-bit).
2. Run a cleanup script to ensure no previous IoT Edge components are installed. The script I used was:

```bash
#!/bin/bash
# This script cleans up the Azure IoT Edge installation to simulate a clean system.
# It should be run with sudo.

set -e

echo "--> Stopping and purging IoT Edge packages..."
apt-get purge -y aziot-edge aziot-identity-service

echo "--> Removing dummy packages (if any)..."
# The '|| true' prevents the script from exiting if the package isn't found
apt-get purge -y libtss2-esys0 || true

echo "--> Removing leftover dependencies..."
apt-get autoremove -y

echo "--> Removing Microsoft repository configuration..."
rm -f /etc/apt/sources.list.d/microsoft-prod.list
rm -f /etc/apt/trusted.gpg.d/microsoft.gpg

echo "--> Cleaning up downloaded files in current directory..."
# This command will be run from the user's home directory if they run 'sudo ~/script.sh'
# A safer way is to specify the path if known, e.g., /root/ or ~/
rm -f ./*.deb ./*.control

echo "--> Updating package lists..."
apt-get update

echo "Cleanup complete. The system is ready for a fresh installation test."
```

3. Execute the following sequence to set up the repository:
```bash
# Step A: Install the CORRECT Debian 12 repository config.
curl https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install -y ./packages-microsoft-prod.deb
# Step B: Intentionally DOWNGRADE to the incorrect Debian 11 repository config.
# This step appears to be necessary to unblock the corrupted package state.
curl https://packages.microsoft.com/config/debian/11/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install -y --allow-downgrades ./packages-microsoft-prod.deb

# Step C: UPGRADE back to the correct Debian 12 repository config.
# This final step leaves the system in a state where installation can succeed.
curl https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install -y ./packages-microsoft-prod.deb
```
4. Update the package lists and install:
```bash
sudo apt-get update
sudo apt-get install aziot-edge
```

This sequence succeeds, whereas just installing the Debian 12 repository directly (Step A only) would fail.

If you just run the suggested commands from https://learn.microsoft.com/en-us/azure/iot-edge/how-to-provision-single-device-linux-symmetric?tabs=azure-portal%2Cdebian, you get `Package Not Found Error`. See logs:

```bash
root@raspberrypi:~# curl https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install ./packages-microsoft-prod.deb
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 4304 100 4304 0 0 30907 0 --:--:-- --:--:-- --:--:-- 30964
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'packages-microsoft-prod' instead of './packages-microsoft-prod.deb'
packages-microsoft-prod is already the newest version (1.1-debian12).
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
root@raspberrypi:~# sudo apt-get update; \
sudo apt-get install moby-engine
Hit:1 http://deb.debian.org/debian bookworm InRelease
Hit:2 http://archive.raspberrypi.com/debian bookworm InRelease
Hit:3 http://deb.debian.org/debian-security bookworm-security InRelease
Hit:4 http://deb.debian.org/debian bookworm-updates InRelease
Reading package lists... Done
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
moby-engine is already the newest version (28.3.2-debian12u1).
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
root@raspberrypi:~# sudo apt-get update; \
sudo apt-get install aziot-edge
Hit:1 http://deb.debian.org/debian bookworm InRelease
Hit:2 http://deb.debian.org/debian-security bookworm-security InRelease
Hit:3 http://archive.raspberrypi.com/debian bookworm InRelease
Hit:4 http://deb.debian.org/debian bookworm-updates InRelease
Reading package lists... Done
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
E: Unable to locate package aziot-edge
root@raspberrypi:~#
```

## Context (Environment)

### Device Information

* Host OS: **Raspberry Pi OS (64-bit) (based on Debian 12 Bookworm)**
* Architecture: **arm64**
* Container OS: **Linux containers**

### Runtime Versions

* aziot-edged: **1.5.21-1** (version installed after successful workaround)
* Edge Agent: **N/A** (issue occurs during runtime installation)
* Edge Hub: **N/A** (issue occurs during runtime installation)
* Docker/Moby: **28.3.2-debian12u1**

## Logs
### Successful logs using workaround:

```bash

sudo ./provision_rpi_iot_edge.sh

=================================================
RASPBERRY PI IOT EDGE PROVISIONING SCRIPT (V2.3)
=================================================
[2025-07-14 15:08:16] Starting Raspberry Pi IoT Edge provisioning...
[2025-07-14 15:08:16] Ensuring 'contrib' and 'non-free' repositories are enabled...
[2025-07-14 15:08:16] Repositories are already correctly configured.
[2025-07-14 15:08:16] Setting up Microsoft packages repository using the 12-11-12 workaround...
[2025-07-14 15:08:16] --> Step 1/3: Installing Debian 12 config...
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'packages-microsoft-prod' instead of './packages-microsoft-prod.deb'
packages-microsoft-prod is already the newest version (1.1-debian12).
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
[2025-07-14 15:08:17] --> Step 2/3: Downgrading to Debian 11 config...
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'packages-microsoft-prod' instead of './packages-microsoft-prod.deb'
The following packages will be DOWNGRADED:
packages-microsoft-prod
0 upgraded, 0 newly installed, 1 downgraded, 0 to remove and 0 not upgraded.
Need to get 0 B/3,134 B of archives.
After this operation, 43.0 kB of additional disk space will be used.
Get:1 /root/packages-microsoft-prod.deb packages-microsoft-prod all 1.0-debian11.1 [3,134 B]
dpkg: warning: downgrading packages-microsoft-prod from 1.1-debian12 to 1.0-debian11.1
(Reading database ... 152134 files and directories currently installed.)
Preparing to unpack .../packages-microsoft-prod.deb ...
Unpacking packages-microsoft-prod (1.0-debian11.1) over (1.1-debian12) ...
dpkg: warning: unable to delete old directory '/etc/debsig/policies/EB3E94ADBE1229CF': Directory not empty
dpkg: warning: unable to delete old directory '/etc/debsig/policies': Directory not empty
dpkg: warning: unable to delete old directory '/etc/debsig': Directory not empty
Setting up packages-microsoft-prod (1.0-debian11.1) ...

Configuration file '/etc/apt/sources.list.d/microsoft-prod.list'
==> Deleted (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ? Your options are:
Y or I : install the package maintainer's version
N or O : keep your currently-installed version
D : show the differences between the versions
Z : start a shell to examine the situation
The default action is to keep your current version.
*** microsoft-prod.list (Y/I/N/O/D/Z) [default=N] ? Y
Installing new version of config file /etc/apt/sources.list.d/microsoft-prod.list ...
N: Download is performed unsandboxed as root as file '/root/packages-microsoft-prod.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
[2025-07-14 15:08:25] --> Step 3/3: Upgrading back to Debian 12 config...
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'packages-microsoft-prod' instead of './packages-microsoft-prod.deb'
The following packages will be upgraded:
packages-microsoft-prod
1 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
Need to get 0 B/4,304 B of archives.
After this operation, 43.0 kB disk space will be freed.
Get:1 /root/packages-microsoft-prod.deb packages-microsoft-prod all 1.1-debian12 [4,304 B]
apt-listchanges: Reading changelogs...
(Reading database ... 152127 files and directories currently installed.)
Preparing to unpack .../packages-microsoft-prod.deb ...
Unpacking packages-microsoft-prod (1.1-debian12) over (1.0-debian11.1) ...
Setting up packages-microsoft-prod (1.1-debian12) ...
Installing new version of config file /etc/apt/sources.list.d/microsoft-prod.list ...
File /usr/share/keyrings/microsoft-prod.gpg is missing. Installing...
N: Download is performed unsandboxed as root as file '/root/packages-microsoft-prod.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
[2025-07-14 15:08:27] Repository workaround applied. Cleaning up...
[2025-07-14 15:08:27] Microsoft packages configured. Running apt update.
Hit:1 http://deb.debian.org/debian bookworm InRelease
Hit:2 http://deb.debian.org/debian-security bookworm-security InRelease
Hit:3 http://archive.raspberrypi.com/debian bookworm InRelease
Hit:4 http://deb.debian.org/debian bookworm-updates InRelease
Get:5 https://packages.microsoft.com/debian/12/prod bookworm InRelease [3,618 B]
Get:6 https://packages.microsoft.com/debian/12/prod bookworm/main all Packages [573 B]
Get:7 https://packages.microsoft.com/debian/12/prod bookworm/main armhf Packages [15.6 kB]
Get:8 https://packages.microsoft.com/debian/12/prod bookworm/main arm64 Packages [28.1 kB]
Get:9 https://packages.microsoft.com/debian/12/prod bookworm/main amd64 Packages [102 kB]
Fetched 150 kB in 1s (245 kB/s)
Reading package lists... Done
[2025-07-14 15:08:29] Container engine (Docker/Moby) is already installed and working.
[2025-07-14 15:08:29] Installing Azure IoT Edge runtime...
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
aziot-identity-service libtss2-tctildr0
The following NEW packages will be installed:
aziot-edge aziot-identity-service libtss2-tctildr0
0 upgraded, 3 newly installed, 0 to remove and 5 not upgraded.
Need to get 0 B/6,145 kB of archives.
After this operation, 30.1 MB of additional disk space will be used.
Selecting previously unselected package libtss2-tctildr0:arm64.
(Reading database ... 152134 files and directories currently installed.)
Preparing to unpack .../libtss2-tctildr0_3.2.1-3_arm64.deb ...
Unpacking libtss2-tctildr0:arm64 (3.2.1-3) ...
Selecting previously unselected package aziot-identity-service.
Preparing to unpack .../aziot-identity-service_1.5.6-1_arm64.deb ...
Unpacking aziot-identity-service (1.5.6-1) ...
Selecting previously unselected package aziot-edge.
Preparing to unpack .../aziot-edge_1.5.21-1_arm64.deb ...
useradd warning: edgeagentuser's uid 13622 is greater than SYS_UID_MAX 999
useradd warning: edgehubuser's uid 13623 is greater than SYS_UID_MAX 999
Unpacking aziot-edge (1.5.21-1) ...
Setting up libtss2-tctildr0:arm64 (3.2.1-3) ...
Setting up aziot-identity-service (1.5.6-1) ...
Created symlink /etc/systemd/system/sockets.target.wants/aziot-certd.socket → /lib/systemd/system/aziot-certd.socket.
Created symlink /etc/systemd/system/sockets.target.wants/aziot-identityd.socket → /lib/systemd/system/aziot-identityd.socket.
Created symlink /etc/systemd/system/sockets.target.wants/aziot-keyd.socket → /lib/systemd/system/aziot-keyd.socket.
Created symlink /etc/systemd/system/sockets.target.wants/aziot-tpmd.socket → /lib/systemd/system/aziot-tpmd.socket.
Setting up aziot-edge (1.5.21-1) ...
===============================================================================

Azure IoT Edge

IMPORTANT: Please configure the device with provisioning information.

Please create a new system configuration.

You can quickly configure the device for manual provisioning with
a connection string using:

sudo iotedge config mp --connection-string '...'

For other provisioning options, copy the template file
at /etc/aziot/config.toml.edge.template to /etc/aziot/config.toml,
update it with your device information, then apply the configuration to
the IoT Edge services with:

sudo iotedge config apply

===============================================================================
Created symlink /etc/systemd/system/sockets.target.wants/aziot-edged.mgmt.socket → /lib/systemd/system/aziot-edged.mgmt.socket.
Created symlink /etc/systemd/system/multi-user.target.wants/aziot-edged.service → /lib/systemd/system/aziot-edged.service.
Created symlink /etc/systemd/system/sockets.target.wants/aziot-edged.workload.socket → /lib/systemd/system/aziot-edged.workload.socket.
Processing triggers for man-db (2.11.2-2) ...
Processing triggers for libc-bin (2.36-9+rpt2+deb12u12) ...
[2025-07-14 15:08:36] IoT Edge runtime installation completed successfully.

=============================================
ACTION REQUIRED: PROVISION YOUR DEVICE
=============================================
The IoT Edge runtime is installed.
You now need to provision it with your device connection string from Azure.

1. Get your connection string from the Azure Portal.

2. Run these commands on the device, replacing the placeholder:

sudo iotedge config mp --connection-string 'YOUR_CONNECTION_STRING_HERE'
sudo iotedge config apply

3. Verify the setup after a minute:
sudo iotedge system status
=============================================
[2025-07-14 15:08:36] Script finished.
root@raspberrypi:~#
```

## Additional Information

This issue was discovered after a long troubleshooting session. The initial state of the OS package manager (`apt`) appeared to be corrupted, preventing a straightforward installation. Standard fixes (`apt-get -f install`, `dpkg --configure -a`, cache cleaning) were not sufficient to resolve the problem.

The key finding is that the `downgrade -> upgrade` cycle of the `packages-microsoft-prod` configuration package was the only method that could reliably repair the system's state and allow `aziot-edge` and its dependencies to be found and installed correctly. This may suggest that the Debian 11 package's pre/post-installation scripts perform a cleanup action that the Debian 12 package does not, which is necessary on a system in this specific state.

Start by reproducing the Raspberry Pi OS 64-bit Debian 12 installation from the linked Azure IoT Edge instructions, using the reported repository setup and apt-get commands. Inspect the packages-microsoft-prod repository configuration and package indexes; done means aziot-edge installs on arm64 without the Debian 11 downgrade and upgrade workaround.

Written by the indexing model from the issue text.