Debian business package

The Debian build pipeline uses aiden-business as its baseline business package. The application build stage first builds and audits the armhf business programs. scripts/debian-package/build.sh invokes dpkg-deb in a Debian container on the Linux build host. Standalone packaging writes to output/debian-package/; full-image builds produce output/debian-system/aiden-business.deb. The system build stage runs dpkg -i inside the rootfs generated by debootstrap, then creates rootfs.ext4 and the A/B images.

Package contents use standard Debian paths:

/usr/lib/aiden/                 # Agent, frame/audio/BLE, OTA CLI, VAD helper, and runtime helper scripts
/usr/lib/aiden/models/          # RV1106 VAD models
/usr/share/aiden/config-web/    # Config Web static assets
/usr/share/aiden/skills/        # bundled skills
/usr/share/aiden/audio/         # Business audio assets
/etc/aiden/ and others         # In-scope runtime configuration, registered as conffiles

The base rootfs provides drivers, kernel modules, Rockchip runtime libraries, EDID, foundational integration scripts listed in the platform exclusions, and OTA trust roots. The OEM partition and /oem directory have been removed without compatibility paths; devices running older versions require a full reflash. /userdata/agent, /userdata/system, and user Skills are not included in the package.

Runtime configuration is included directly in the same business package. For its scope, activation timing, and initial ownership transition, see Runtime Configuration Managed by the Business Package.

The package's release-manifest.json records the business version, architecture, platform contract range, configuration schema, and business_epoch. The preinst in three-channel release packages checks the current platform contract, channel, and base identifier. A complete upgrade policy, including package signatures and disk-space checks, still requires a separate business upgrade orchestrator; downloaded packages are currently installed through apt. The new layout starts at contract 1, with a package requirement of [1, 2). The base declares its contract in /usr/lib/aiden/platform/contract.json, which is not owned by the business package. The old layout cannot cross this change through slot OTA and must be reflashed. Subsequent platform updates within the new layout use full boot/rootfs OTA.

Build commands (run on a Linux host):

scripts/debian-apps/build-apps.sh all
scripts/debian-system/build.sh builder
DEBIAN_PACKAGE_OUTPUT_DIR=output/debian-system \
  scripts/debian-package/build.sh
scripts/debian-system/build.sh bsp
OTA_PUBLIC_KEY_PATH=keys/ota_pubkey.pem scripts/debian-system/build.sh rootfs

The full-image command automatically generates and installs the package:

./debian_build.sh

macOS development machines do not run Debian/armhf builds directly. Sync the repository to a Linux build host (for example, ssh luhaodev), run the commands above, then sync the output/debian-system artifacts back to the development machine.

New platform paths and package ownership:

Contents	Path	Owner
Business programs and self-check CLI	/usr/lib/aiden/	aiden-business
Business models and notification audio	/usr/lib/aiden/models/, /usr/share/aiden/audio/voice-notifications/	aiden-business
Runtime configuration and Aiden service helpers	Namespaces defined by config-package.json (excluding platform items)	aiden-business
RGA and VQE shared libraries	/usr/lib/aiden/platform/lib/	base rootfs
Modules and Wi-Fi/MCU firmware	/usr/lib/aiden/platform/modules/	base rootfs
EDID and VQE configuration	/usr/share/aiden/edid/, /usr/share/aiden/audio/config_aivqe.json	base rootfs
OTA Ed25519 public key	/usr/share/keyrings/aiden-ota.pem	base rootfs

rootfs A/B are 1792 MiB each, at partition nodes p7/p8; userdata is p9 and ota is p10. The former OEM slots' combined 512 MiB is split equally between the rootfs slots. userdata remains 3 GiB and OTA remains 300 MiB. The new manifest uses schema 2 and must include both boot and rootfs in full. Release assets are boot_a.img.tar.gz, boot_b.img.tar.gz, rootfs.img.tar.gz, update.img.tar.gz, and manifest.json; a .deb can also be published separately.

Regenerate the rootfs after changing platform files or trusted public keys. Image assembly compares the public key input against the rootfs build record and rejects reuse of a mismatched old rootfs. Build order is apps → BSP → package/rootfs → images → manifest/config → audit. A/B writes, verification, personalization, health confirmation, and rollback on failure remain slot-based.

The rootfs also records boot/env input checksums; after rebuilding the BSP, the old rootfs cannot be used directly for assembly. Every rootfs stage repackages the current apps to avoid reusing cached business packages with old paths.

Version management

scripts/debian-package/version.sh is the single source of default business versions: business version 0.0.1, Debian revision 2, and full local package version 0.0.1-2. Override these from the command line with AIDEN_BUSINESS_VERSION and AIDEN_BUSINESS_REVISION. For published three-channel releases, the release plan automatically allocates the version and base contract; see Three-Channel Releases.

Without a release plan, the platform contract defaults to 1. Every published system OTA allocates a new contract; subsequent business packages inherit the latest base for their channel. OTA manifests still use schema 2.

Standalone builds and GitHub Releases

The Linux amd64 build host requires Docker, Git, curl, Python 3.11+, and dpkg-deb. The working tree must be clean, and the SDK commit must match the application build record.

scripts/debian-package/release.sh build

This command prepares a pinned Go toolchain, builds OpenCV and the business programs, audits application ELF files, and generates a .deb. It uses a separate lightweight packaging container; it does not compile the BSP, build a rootfs, or require an OTA private key or Agent credentials. Go/OpenCV cache environment variables are the same as those for debian_build.sh. If applications for the current commit have already been built and audited, use release.sh stage to repackage only. Artifacts from other commits or with uncommitted changes are rejected.

The artifact directory output/debian-package/release/ contains:

aiden-business_0.0.1-2_armhf.deb
release-manifest.json
build-metadata.json
RELEASE-NOTES.md
SHA256SUMS

The Debian Business Package (artifacts only) workflow only builds artifacts. Published releases use Aiden Channel Release, all manually triggered, with the plan deciding whether to release a business package or a full OTA. The old scripts/debian-package/release.sh publish entry point is disabled. For release operations, automatic change comparisons, retries after failure, and required repository settings, see Three-Channel Releases.

Publication also updates the GitHub APT Repository. Devices use Signed-By to verify the signed index and package checksums, then upgrade business packages with apt update && apt upgrade. A manually downloaded SHA256SUMS file checks only transfer integrity and is not equivalent to a package signature.

Installing on an existing device

Install only on devices with the new layout and a compatible contract. First compare contract.json with the package manifest, and keep the previous .deb and a backup of user configuration.

cd /path/to/downloaded-release
sha256sum -c SHA256SUMS
cat /usr/lib/aiden/platform/contract.json
sudo apt install ./aiden-business_0.0.1-2_armhf.deb
sudo /usr/lib/aiden/ota --config /userdata/debian/ota/config.json self-check
dpkg-query -W aiden-business

Starting with revision 2, the preinst/prerm/postinst/postrm maintainer scripts automatically stop and start business services through apt/dpkg. Upgrades and reinstalls record running services, first stop the proxy restart listener and its tasks, then stop Agent, Config Web, Wi-Fi proxy, frame, audio, BLE, and ttyd. After successful unpacking and configuration, they run daemon-reload, restore previously running services, and finally restore the listener. Enablement state is unchanged; previously stopped services are not started automatically, while manually started but non-enabled services are restored. Normal systemd dependencies still apply.

On the first upgrade from an old package, the new package's preinst also handles stopping services. To rehearse with the same version:

sudo apt install --reinstall ./aiden-business_0.0.1-2_armhf.deb

Service operations are skipped in rootfs-build chroots, with SYSTEMD_OFFLINE=1, with a nonempty DPKG_ROOT, or without systemd, and respect policy-rc.d. Business services not running at first installation are not automatically started; the systemd units installed in the image start them on first boot. Removing the package stops services. Conffiles are retained according to dpkg rules, helper scripts are removed, and user data is not deleted.

Service snapshots are stored in /var/lib/aiden-business/service-transition/. dpkg abort callbacks attempt to restore previous services. If restoration fails, the snapshot is retained and the maintainer script returns failure. Fix the cause and run sudo dpkg --configure -a to retry. Do not delete the snapshot before fixing the issue. Maintainer scripts do not automatically roll back package files, migrate configuration, or run hardware health checks. After successful installation, still run the self-check above; if it fails, restore the old package from backup. The self-check logs unavailable Agent HTTP as a warning but requires Config Web to be accessible so that corrupted Agent configuration can still be repaired through the recovery portal. For managed packages, preinst automatically checks the contract.

Renumbering from the earlier test package 5.2.1-2 to 0.0.1-2 is an explicit downgrade. For automated installation, additionally use apt install -y --allow-downgrades ./aiden-business_0.0.1-2_armhf.deb. The business package modifies only the active rootfs; slot B is not upgraded in sync, and the firmware OTA factory-version record is not updated. The business package manages LANG=C.UTF-8 in /etc/locale.conf; Debian's /etc/default/locale symlink points to it, and it takes effect at the next login. The platform contract file remains base-owned. The initial configuration ownership transition requires a new OTA baseline; manually editing the contract file is not sufficient.