Asami’s Linux HostHelper Reference

Cette référence permet de construire et tester le HostHelper Linux Python+LMDB. Il exécute les artefacts authentifiés par CORE, conserve les résultats et empêche qu’une tentative dont l’effet a pu commencer soit rejouée. Le remplacement du store conserve les clés Ed25519, les certificats, le trust, les compteurs anti-rejeu et les résultats en attente de remise.

Reference 1.0.0 fixe la distribution Linux Python+LMDB et son identité runtime 1.0.0. La candidate admise 56b4716 a été intégrée dans develop à 7fd34f5, puis le release set a passé sa suite complète avant gel. Reference 0.1.0 Python+SQLite reste publiée et figée dans son tag. Les contrats canoniques restent les spécifications Asami P1–P6 et Common Core ; les notes Reference 1.0 relient la distribution aux preuves et à leurs limites.

Construire et tester

Utilise un environnement Python dédié au dépôt. Le service requiert cryptography>=43,<51, pydantic>=2.8,<3, rfc8785>=0.1.4,<1 et lmdb>=3.0,<4. Les dépendances de test servent notamment au pair CORE conservé sous tests/support ; il ne fait pas partie du helper ni du wheel.

python3 -m venv ~/.virtualenvs/linux-hosthelper-reference
~/.virtualenvs/linux-hosthelper-reference/bin/python -m pip install -e '.[test]'
~/.virtualenvs/linux-hosthelper-reference/bin/python tools/build_reference.py --check
~/.virtualenvs/linux-hosthelper-reference/bin/python -m pytest

--check vérifie les 138 imports dans le tag SQLite immuable puis reconstruit la candidate actuelle en mémoire. La candidate LMDB peut évoluer ; ses bytes ne sont pas présentés comme ceux de la baseline SQLite. Son identité runtime et sa version de distribution sont 1.0.0. Le contrôle du tag historique exige un clone Git contenant 0.1.0 ; l’archive de livraison contient aussi les artefacts déjà construits sous artifacts/.

Les tests nécessitant root, un montage isolé ou une installation explicitement désignée indiquent leur condition de skip. Leurs injections de panne restent hors de l’artefact de production.

Diagnostics et Sentry optionnel

Le Host Helper conserve les diagnostics des exceptions inattendues à ses frontières sans modifier les receipts machine ni les décisions d’effet. Le diagnostic local est écrit sur stderr sous forme JSON filtrée et bornée ; les erreurs métier/protocole attendues restent du contrôle de flux normal. L’inventaire exhaustif des handlers peut être vérifié avec python tools/audit_exception_handlers.py --check.

Sentry reste une destination optionnelle et non autoritative. Si SENTRY_DSN est absent ou vide, le SDK n’est pas importé. Si le DSN est présent mais que sentry-sdk ou son transport est indisponible, le Helper continue son chemin nominal et ne conserve localement que la phase et le type de la panne télémétrie. Le déployeur est seul propriétaire de la projection éventuelle de SENTRY_DSN dans l’environnement du service : le Host Helper ne crée ni fichier de configuration ni drop-in systemd et ne persiste jamais le DSN.

L’extra telemetry fournit sentry-sdk>=2,<3 pour les environnements qui veulent l’activer ; il ne fait pas partie des dépendances critiques de readiness du service. Les traces/profils et les locals Sentry restent désactivés, les secrets/capabilities sont filtrés, et le shutdown télémétrie est best-effort avec une attente appelant bornée à 0,5 s.

Préparer les artefacts Debian

Le tuple de dépendance actuellement éprouvé est Debian 13 / amd64 / CPython 3.13, avec py-lmdb 3.0.0 et le moteur LMDB 0.9.36 embarqué corrigé. Le store choisit explicitement le format 0.9 ; un autre format physique est refusé. Le paquet Debian standard 1.4.1 a servi à une campagne comparative ; il n’est pas la dépendance de livraison retenue.

Le constructeur de dépendance compile le source amont au SHA enregistré, produit un paquet Debian et conserve versions de compilation, licence et provenance. Il demande GCC, les headers Python 3.13, dpkg-deb, lsb_release et les prérequis Python de compilation suivants :

~/.virtualenvs/linux-hosthelper-reference/bin/python -m pip install build setuptools wheel cffi patch-ng
~/.virtualenvs/linux-hosthelper-reference/bin/python tools/build_lmdb_backport.py \
  --source-metadata provenance/lmdb-debian-backport-stable-qa.json \
  --output /tmp/hosthelper-lmdb-dependency
~/.virtualenvs/linux-hosthelper-reference/bin/python tools/build_reference.py \
  --lmdb-backport /tmp/hosthelper-lmdb-dependency \
  --output /tmp/hosthelper-lmdb-candidate

Le bootstrap administratif embarque la dépendance exacte. L’installeur vérifie le bootstrap avant exécution ; le bootstrap vérifie le paquet et l’extension native réellement chargée. Une dépendance déjà conforme est un no-op. Le constructeur de référence refuse un répertoire d’artefacts contenant des bytes différents. Les fichiers officiels sont ceux référencés par la GitLab Release ; une reconstruction locale conserve son propre statut de qualification. Le déploiement sur le parc suit les gates des owners concernés.

CFFI, PyPy, les autres architectures et les autres distributions ne sont pas qualifiés par ce paquet. Le format de carte LMDB, sa taille virtuelle de map et la mémoire effectivement résidente sont des grandeurs distinctes.

Installer ou remplacer sous autorité administrative

L’administrateur fournit le trust public canonique de la Remote : identité et certificat CORE, instance, binding et endpoint exacts. La clé privée du helper reste générée et confinée localement. Le compte asami et l’accès administratif doivent déjà exister. Le service systemd tourne sous root ; l'agent asami invoque le helper par la délégation sudoers que le bootstrap projette et prouve (sudo -n -l -U asami -- /usr/local/sbin/asami-host-helper).

Machine vierge — installation « from scratch »

Les artefacts publics de la GitLab Release officielle suffisent : installeur épinglé, bootstrap et leurs sidecars SHA-256 (construits par tools/build_reference.py). Le script du dépôt télécharge la version demandée, vérifie les sidecars, puis n'exécute que l'installeur officiel :

tools/install-fresh-hosthelper.sh --version 1.2.0 --trust trust-public-fourni-par-core.json

soit, à la main, la commande officielle équivalente :

sudo -n /usr/bin/python3 -I install-hosthelper.py \
  --version 1.2.0 \
  --bootstrap hosthelper-bootstrap.pyz \
  --trust trust-public-fourni-par-core.json \
  --activate

Le reçu LOCAL_ACTIVE atteste la version, le store LMDB, l'intégrité et l'activation du service et de l'update.timer. L'identité publique du helper (helper_public_key du reçu) reste à faire enrôler puis lier par CORE avant tout canal privilégié. L'Enroller officiel (remote-enrollment P1–P4) automatisera ce parcours : détection de plateforme, choix automatique de la release compatible, installation via ce même installeur officiel et binding hosthelper-key.

Remplacement borné de la baseline SQLite admise

L'installeur choisit la première installation ou le remplacement borné de la baseline SQLite admise. Il conserve le binding existant. Pour une installation neuve sans activation immédiate, la préparation fournit l'identité publique à faire enrôler par CORE avant activation.

Après le binding explicite d’une installation neuve, ou pour remplacer la baseline SQLite déjà liée, la même commande avec --activate demande l’activation. Le remplacement exige l’absence d’effet actif, prouve l’arrêt du service, verrouille service/identité/slot d’effet, remplace atomiquement les bytes identifiés, convertit et relit l’état durable, puis active la nouvelle instance. Une interruption reprend seulement depuis le plan et la préimage exacts ; une divergence bloque la reprise. La correction se fait en avant.

La vérification locale seule est disponible avec --check et le même --trust. Elle ne prouve pas la fraîcheur CORE. L’activation doit encore être suivie d’un nouveau HELLO, d’une fraîcheur liée au nouvel epoch et d’une exécution contrôlée réelle. Le parcours manuel ne crée pas le compte agent, ne modifie pas SSH et n’active pas Receipes.

Preuves et limites actuelles

La candidate Linux admise a passé 1 282 tests non-root / 271 skips et 1 543 tests root / 10 skips sur H3 ; les deux comptes se recoupent. La composition exacte 7fd34f5 a repassé 1 543 tests root / 10 skips, exit 0, sur A4 avant attribution de version. Les campagnes installées prouvent la conservation de l’identité et des compteurs, les événements/sorties transférés puis ACKés, le refus d’une ancienne fraîcheur, l’absence de second effet et le no-op actif. H2 a en outre exécuté trois artefacts réellement autorisés par l’opérateur dans QA-A4, dont le dernier après reboot réel du guest, avec persistance des clés, ledgers, marqueurs et high-water.

Les saturations natives de map, disque et table de lecteurs sont classées et n’admettent pas un nouvel effet sans commit durable. Des SIGKILL avant/après fences, durant compaction et remplacement prouvent la reprise ou AMBIGUOUS, sans rejeu aveugle. Un redémarrage du conteneur systemd conserve l’état et exige un nouvel epoch/fraîcheur ; il ne remplace pas la preuve d’un reboot hôte.

Le dossier de qualification sur pilote relie les artefacts exacts aux scénarios et observations des campagnes de candidate ; les notes de release en donnent l’état de sortie.

Les données comparatives sont conservées dans provenance/. Elles ne promettent aucun gain global : le premier profil de cycle complet sans maintenance est défavorable à LMDB. Les conditions de charge, la maintenance, le stock et les compteurs d’I/O doivent être considérés avec les latences brutes. Les campagnes charge installée et endurance H2 sont conservées avec leur tuple, leurs compteurs et leurs limites ; elles ne constituent pas un budget universel.

Le helper fournit une frontière d’admission et de traçabilité pour des agents coopératifs mais faillibles ; il ne prétend pas confiner absolument un programme root arbitraire.

Provenance

provenance/extraction.json et provenance/commit-map.json relient la référence à la baseline admise. Le tag Reference 0.1.0, commit c7ff916c6cf93ef8f7530313a1ad44bc0068dc17, conserve la reproduction SQLite ; le tag Asami baseline/hosthelper-python-sqlite-20261013 conserve sa source qualifiée.

Les bilans provenance/lmdb-run*.json, les rapports installés et les manifests de dépendance identifient le code, les bytes, les tests et leurs limites. Les ports C/OpenWrt/Linux/Windows suivent leurs propres gates Common Core. Aucun état de cette branche ne ferme implicitement ces unités ni le parcours d’enrôlement.

Licence

Le fichier LICENSE conserve GNU Affero General Public License, version 3, et l’attribution de l’historique original. Le paquet de dépendance conserve aussi la licence et la provenance de py-lmdb/LMDB.