Files
rust-discovery/docs/agent-updater-handoff.md
T
2026-11-14 21:48:21 +01:00

232 lines
15 KiB
Markdown

# Reviewstand: erhaltene Helper-/Updater-Übergabe
2026-11-14. **Isolierter Quellvertrag, keine Produktnorm oder Applyruntime.**
Basis: vollständige Spezifikation1.19, vollständige1.20-/PD-Ergänzung des
Skriptconsole-Worktrees und [bisheriger Vorschlag](agent-updater-proposal.md).
Root hat den engen Kernel und den Fullrenderer zur Ausarbeitung beauftragt;
Runtimeintegration, Zielaktionen und Veröffentlichung erfolgen erst nach
dessen Koordination. Linux-first und die tatsächliche WebUI-Grenze gelten.
Die neue Crate `rmm-updater-handoff` verändert weder den qualifizierten
Releaseverifier noch die beiden vorhandenen nativen Verifier-Abnahmerunner.
Sie enthält keinen Installer, Dateischreiber, Dienststart, IPC-Server,
Netzwerkclient, SQLiteadapter, Approver oder neuen Server-Journalslot.
Aus einem gültigen Handoff oder Healthreceipt entsteht keine Startberechtigung.
## Konkreter Vorwärtsvertrag
`Handoff` bindet ursprünglichen Tenant/Asset/Agent, beide Generationen,
Plan-/Job-/Versuchs-/Grant-/Authorization-IDs, exakte Originalrequest- und
Startzeugenhashes, beide vorhandenen Journal-IDs, Helpercheckpoint und letzten
signierten Entscheid, Boot, ursprüngliche Verbindungsgeneration, einmalige
Ownernonce, stabilen Updater-/Policyhash, Vorgängerrecord, erhaltene Zustands-
und Stagingzeugen sowie Vorgänger-/Zielcodepaar. Der Rendererbeleg und alle
benannten alten/neuen Dateihashes sind unveränderlicher Bestandteil.
Die Helperintegration muss Verbrauch, bestehenden exakten Startzeugen und
Handoff **in derselben vorhandenen Ledgertransaktion** persistieren. Eine
zusätzliche Transaktion nach `ledger::begin_execution` wäre unzureichend:
ein Crash könnte einen Verbrauch ohne bestimmbaren Owner hinterlassen.
Jeder andere offene/Unknown-Versuch verweigert die Übergabe. Das Handoff
ersetzt weder den Originaljob/-grant noch dessen unabhängige Prüfung.
Die Writergrenze ist ausdrücklich Bestandteil dieses Vertrags: Der alte
Helper persistiert auch den Stopintent vor der Übergabeantwort. Solange er
seinen lebenslangen Windowsguard hält, schreibt der Updater kein Event in
den gemeinsamen Ledger. Nach Stop/Guardübernahme kann der Updater All-stopped
und Ownership zusammen transaktional anhängen. Nach dauerhaftem Rückgabeintent
und tatsächlicher Guardabgabe stammen die weiteren Start-/Health-/Outcome-
Events ausschließlich vom neuen Helper unter dessen Guard. Der Updater
erhält nur die eng typisierte lokale Bridge; kein freies Ledger-Schreibrecht
parallel zum neuen Helper. Ein einheitlicher Ledger-/Lock-Inode-/FileID-Hash
ist vor Übergabe fest gebunden und wird bei Übernahme, neuem Servicepeer und
Health erneut verglichen; bloß ein gleichnamiger Dateipfad reicht nicht.
Der begrenzte Journalcodec prüft kanonische Bytes, Hashvorgänger, monotone
Sequenz/Zeit und höchstens16Events. Für Linux Full sind dies genau:
1. Stopintent, unabhängiger All-stopped-Zeuge, bestätigter Besitz des gleichen
Helperledgers durch den konkreten stabilen Updaterprozess.
2. Jeweils ein Intent und ein bestätigter Nachhash für Agent, Helper,
Fullconfig und Fullpin; keine neue Dienstgeneration vor vollständigem Paar.
3. Neues Code-/Pinpaar und erhaltener Zustandszeuge vollständig bestätigt.
4. Dauerhafter Ledger-Rückgabeintent unter gehaltenem Guard, danach Guard
tatsächlich abgeben; erst anschließend darf der neue Helper denselben
Guard erwerben und starten.
5. Konkrete neue Serviceprozesse mit Imagehash, PID und Prozessgeburt,
anschließend signierter Healthbeleg und ursprüngliches Outcome-CAS.
Der Codec nimmt nur Beobachtungen entgegen. `prepare` liefert Bytes für ein
append-only CAS gegen den bestehenden Head, **keinen Haltbarkeitsnachweis**.
Der Plattformadapter muss Flush/Commit vor Wirkung, echte Service-/Peer-
und Guardbeobachtungen, Dateihandles/ACLs sowie ursprüngliche SQLrows und
Signaturen prüfen. Historischer Replay allein erkennt keinen abgeschnittenen
Suffix; er muss gegen den erhaltenen dauerhaften Head, Rowcount und
Ledger-/Inode-/FileID-/Kontrollkettenbeleg geprüft werden. Ein unbekannter
Stop/Teilwechsel/Start bleibt lesend zu diagnostizieren, kein erneuter Execute.
Ein expliziter Unknown ist im neuen Updatekernel terminal und wird durch
spätere Health nicht geheilt. Bestehende allgemeine Outcome-CAS-Regeln bleiben.
## Fullhelper bleibt Teil des ersten Linux-Applyziels
Die tatsächliche Zieltopologie hat General, Full und Agent aktiv. Daher ist
Full kein pauschaler Ausschluss. `linux_general_full_v1` erhält ein geschlossenes
Stopset Agent/General/Full; ein bereits installierter APT-Reader kann zusätzlich
als vierter Dienst im Stopset stehen, **nie im Startset**. Alle tatsächlich
installierten Shared-Ledger-Reader müssen vor Austausch erkannt und gestoppt
sein. Unbekannte Profile und ausgelassene Fullservices verweigern den Schnitt.
Agent/General/Full erhalten dieselbe neue Codepaargeneration vor Restart.
Die alte APT-Unqualifikation/-Deaktivierung bleibt bestehen; kein alter
Acceptancebeleg wird umgeschrieben oder auf die neue Helperdatei übertragen.
Zukünftiger APT-Start benötigt eine gesonderte passende Qualifikation.
`render_linux_full` akzeptiert ausschließlich das bekannte Full-Configschema,
die daraus in fester Feldreihenfolge abgeleitete `control::Policy` Schema2
und den zugehörigen `GeneralPin` Schema2. Alte Binär-/Policy-/Identitybindungen
werden vorher geprüft. Die Rendererdefinitionen sind eine explizite
Schemamomentaufnahme; Integration muss sie gegen die tatsächlichen Typen aus
dem1.20-Quellstand vergleichen, bevor sie Runtime werden.
Der unabhängige Quellenreview fand einen echten Kompatibilitätsfehler des
ersten Entwurfs: Die aktuelle Full-Rawconfig enthält einen leeren Inlinekey
und einen `signing_key_file`-Pfad; die Runtime ergänzt den effektiven öffentlichen
Key vor der Policyhashbildung. Der reine Renderer erhält deshalb jetzt den
bereits provisionierten, **extern authentisierten** öffentlichen Signierkey
als expliziten Parameter. Er öffnet keine Datei. Bei vorhandenem absolutem
Keypfad darf der Raw-Inlinekey leer oder genau gleich sein; ohne Keypfad ist
der gleiche Inlinekey Pflicht. Effektive Policy und Pin werden wie in der
Runtime aus diesem Key abgeleitet; Raw-Inlinekey und Pfad bleiben unverändert.
Der Transitionbeleg bindet zusätzlich `effective_signing_key_id`. Ein bloß
geparstes `VerifyingKey`-Objekt authentisiert keine Provisionierung; der spätere
Adapter muss den Input unabhängig gegen die vorhandene geschützte Keydatei
und die gebundene öffentliche Identität prüfen. Eine neue lokale Vertragsprobe
belegt den Filekeyfall und gleiche Policy-/Pinbytes zum Inlinefall. Dies ist
weiterhin kein Lesen der realen Keydatei oder nativer Renderer-Nachweis.
Der Renderer ändert nur benannte Top-Level-Wertspans:
- Config: `helper_binary_sha256`.
- Pin: `helper_binary_sha256` und daraus exakt neu berechnetes `policy_sha256`.
Alle anderen **rohen Config-/Pinbytes** bleiben erhalten, einschließlich
Formatierung, Identity, öffentlicher Schlüssel, Keypfad, UID/GID, Socket,
Statepfad und Rechtefelder. Er nutzt begrenzte typisierte Deserialisierung
und geborgte `RawValue`-Spans; keine globale Stringersetzung, kein JSONpatch.
Ein gleicher Hash innerhalb eines anderen Feldes bleibt erhalten.
Unbekannte/duplizierte Felder, abweichende Policy, zusätzliche Profile/Services,
fremde Identität und escaped Hashwerte werden verweigert.
Der `LinuxFullTransition` bindet alte/neue Rawconfig-, Rawpin-, Policy- und
Helperhashes. Exakte Zielbytes samt Beleg müssen vor der WebUI-Genehmigung im
festen Plan aufgelöst und später unabhängig erneut geprüft werden. General-
und APT-Konfigurationen werden nicht gerendert. Die zentrale Fullscope wird
**nicht migriert**; künftige Fulljobs bleiben ohne neue konkrete Scopebindung
deny. Ein Codewechsel erteilt keine neuen Rechte.
## Enger Health- und Syncanschluss
Die eigene offene Updatezeile darf **keinen allgemeinen Readyzustand** erzeugen.
`HealthReceipt` ist separat domänengebunden (`rmm.agent-update-health.v1\0`),
mit strengem Ed25519 geprüft und an den gesamten Handoffhash, Ownernonce,
Boot, beide erhaltenen Journale, neue Verbindungsgeneration und sämtliche
konkreten neuen Agent-/Helperprozesse gebunden. Er enthält exakte Hashes des
tatsächlich angewandten SignedSync-Requests/-Responses, Decision-ID und
frisches Inventar samt ACK-Hash. `ready=true` wird ausdrücklich verweigert.
Sync und Inventarempfang müssen nach den bestätigten neuen Dienststarts
liegen. Health ist nur innerhalb180Sekunden gültig, Gesamtfrist höchstens600;
kein Receipt verlängert sie. Der öffentliche Verifikationsschlüssel wird
extern vertrauenswürdig provisioniert, nie aus dem Receipt übernommen.
Noch vor Integration normativ zu bestätigen:
| Anschluss | Erforderliche enge Änderung |
|---|---|
| `ledger::begin_execution` | Additive atomare Handoffanlage mit Originalverbrauch/-start im selben Ledger; keine Ersatzzeilen und kein Reset |
| Helper-/Agent-Startup | Nur exakt vollständiges, lebendes, gleichbootiges, fristgebundenes Updatehandoff als `inflight` erkennen; vorhandenes Unknown niemals umschreiben |
| `HelperSync`/Server-Sync | Typed Inflightdatensatz desselben Versuchs bei weiterhin geschlossenem Ready abgleichen; Originalkontrollkette erhalten |
| `ClientSync::confirm_helper` | Bestehende allgemeine Unresolved-Sperre erhalten; neuer expliziter read-only Updatekontrollpfad darf keine Startlease setzen |
| Lokales IPC | Eigener fest provisionierter Updaterparticipant mit Dienst-/UID/SID-/PID-/Geburts-/Imagebindung; Root/SYSTEM allein reicht nicht |
| Healthroute | Tatsächlich gespeicherter neuer Geräte-mTLS-/Inventory-/Syncbeleg; lokale aktuelle Peer-/Code-/Stateprüfung plus exaktes Receipt vergleichen |
| Finalisierung | Neuer Helper speichert ausschließlich das noch fehlende Originaloutcome per unverändertem CAS; danach bestehende Spiegelung/normaler Sync |
Keine dieser Runtimeänderungen ist durch den isolierten Kernel implementiert.
Insbesondere ist ein Hash im Receipt kein Ersatz für die unabhängige Prüfung
des zugehörigen aktuellen lokalen Kontroll-/Inventarbelegs. Rotation/Revoke-
und Trustprovisionierung müssen den aktuellen sowie historischen Prüfkontext
beibehalten; der Kernel implementiert keinen neuen Trustdienst.
Offen bleiben außerdem genehmigte typisierte Action/Plan/Grant-/UI-/MCP-
Integration, Updatekatalog und begrenzter eigener Streamingpfad, OSstaging,
stabiler Updaterbootstrap, Dienst-/Dateiaustausch, einmaliger zulässiger
Vorgängercode-Rollback, tatsächliche Linux-Abnahme und danach Windows.
Windows-Codepaar-/Settingsrenderer und Rollbackzustände sind hier **nicht**
implementiert. Der ursprüngliche reine Linux9-/Windows9-Verifiernachweis
bleibt unverändert; diese neuen Verträge haben noch keinen VM-Nachweis.
## Tatsächlich ausgeführte lokale Prüfungen
Offlinecontainer aus vorhandenem Image
`sha256:9a76ad3744ebfdddae96ca10001ce8291c1b332fb54c8df5eea0e8e999ac6fc6`.
Kein Server oder Agent auf dem Notebook gestartet, keine Ziel-/Policyaktion.
```text
cargo check --manifest-path /src/Cargo.toml --offline -p rmm-updater-handoff
cargo fmt --manifest-path /src/Cargo.toml -p rmm-updater-handoff
cargo test --manifest-path /src/Cargo.toml --locked --offline -p rmm-updater-handoff --all-targets --release
cargo clippy --manifest-path /src/Cargo.toml --locked --offline -p rmm-updater-handoff --all-targets -- -D warnings
```
Bestanden: Check, Formatierung, Clippy ohne Warnungen und acht gezielte
Vertragsprüfungen ohne Skip. Diese prüfen den vollständigen16-Event-Fullpfad,
Originalketten-/Clock-/Limitgrenzen, Stop-/Lock-/Austausch-/Restartreihenfolge,
fehlende Fullprozesse/APT-Ausschluss, echte getrennte Healthsignaturen,
stale/fremde/ready-Health und terminalen Unknown sowie Rawbyteerhaltung,
extern gebundene File-/Inline-Signierkeys und feindliche Fullrenderer-Eingaben.
Nur lokale Vertragsnachweise; kein
Bootstrapping, dauerhafter SQLite-Commit, nativer Dienst-/Apply-/Rollback-
oder Produktionsnachweis. Der erste Formatbefehl scheiterte vor Cargo an
einem nicht überschriebenen Image-Entrypoint; mit `--entrypoint cargo`
anschließend tatsächlich ausgeführt. Keine Tests als Folge dieses Fehlers
erfunden oder Zielaktion wiederholt.
## Fortschreibung: koordinierter Quellencheckpoint1.21
Der ursprüngliche a2efb79-Kernel und dessen Belegbytes bleiben unverändert.
Sein tatsächlicher enger Linux8-Nachweis steht in
[agent-updater-handoff-linux-results.md](agent-updater-handoff-linux-results.md).
Die darauf aufbauende Coreintegration speichert Originalverbrauch, bestehenden
Startzeugen, Handoff, konkrete Delegation und Stopintent in einer IMMEDIATE-
Transaktion des vorhandenen Ledgers. Sie überträgt einen typisierten begrenzten
Präfix in Protofeld14 und bestätigt ihn ausschließlich bei beiden Readyflags=false
und unlock=false. Persistiertes Unknown bleibt terminal. Leere neue Felder
lassen die alten Grant-/Decision-/Startcodecbytes unverändert.
Der Originalplan bindet separat provisionierten Healthpublickey und Rawpinhash;
Admission liest den lokalen Pin unabhängig, historische Prüfung benutzt diesen
Originalkontext. Server-Health verlangt originale gespeicherte SignedSync- und
Baseinventarbytes samt bestätigender Folgerunde; sie eröffnet keine Admission.
Der konkrete Helper muss dieselben lokal tatsächlich angewandten Bytes und
Applyzeit innerhalb der belegten Zeitspanne unabhängig nachweisen.
Linux Full ist vorgesehener ursprünglicher Autorizer/Owner-/Healthguard.
General bleibt in diesem Fall geschlossen und darf Nichtzuständigkeit nicht
als OwnerLost terminalisieren. Das ist nötig, weil die tatsächlichen General-
Capabilities keine Imageprüfung eines breiter berechtigten Fullprozesses erlauben.
Kein Generalhärtungs-/Capabilitywechsel ist implementiert oder freigegeben.
Native Unterintents und Nachlesezeilen hängen im selben Ledger am Originalgrant.
Feste Stop-/Dateischritte sind create-once, Rückgabe und genau drei Startclaims
committen atomar. Nur ein weiterhin lebender ursprünglicher Worker darf die
reservierte Folge nach tatsächlicher Lockabgabe einmal dispatchen. Neue Full-
Helper bestätigen echte Start-/Health-/Recordbeobachtungen unter ihrem Guard.
InstalledRecord/Floorcodec und separat signierter Bootstrapbaselinecodec sind
reine Parsingverträge und ersetzen keine Trust-, Floor- oder OSprüfung.
Offen bleiben reale enge Fullbridge-/Owner-/Healthadapter, passive gültige
Updatezustände/Kandidaten, vollständige erhaltende Baselineprovisionierung,
Workerdispatch und End-to-End-Apply. Restore bleibt ausdrücklich verweigert:
der eingefrorene Vorwärtskernel hat noch keinen qualifizierten Rollbackpfad.
Der Agent meldet bis zur echten Provisionierung nur agent.update/not_configured;
keine Applyfähigkeit aus Build/Katalog/Unitnachweis. Kein VM-Apply oder
Windows-Applynachweis dieses Checkpoints.