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

15 KiB

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. 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.

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. 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.