Atomare Multi-Datei-Edits für KI-Coding-Agenten: die Semaprax-Lektion

Ändert ein KI-Coding-Agent mehrere voneinander abhängige Dateien, reicht das sichere Ersetzen jeder einzelnen Datei nicht aus. Das Projekt braucht eine gemeinsame Publikationsgrenze. Sonst können Build-Prozess, Language Server, Test-Watcher oder ein zweiter Agent eine Hälfte des alten und eine Hälfte des neuen Programms lesen.

Dieses Problem begegnete uns bei der Entwicklung von Semaprax, unserer experimentellen agentennativen Systemsprache. Die nützliche Lehre geht über die Sprache hinaus: Bereite eine vollständige unveränderliche Generation vor, verifiziere sie und wechsle danach einen kleinen aktiven Zeiger. Dieser Artikel erklärt das Muster, seine Grenzen und die Fragen, die technische Käufer vor jedem Versprechen atomarer Agenten-Edits stellen sollten.

Was ist ein atomarer Multi-Datei-Edit?

Ein atomarer Multi-Datei-Edit macht für die definierten Leser entweder einen vollständigen alten oder einen vollständigen neuen Zustand sichtbar, nie eine Mischung dazwischen. Die Aussage bleibt unvollständig, solange das System nicht Leser, Dateiumfang, Commit-Punkt und Fehlermodell nennt.

Ein Beispiel: Eine Änderung benennt eine exportierte Funktion um und passt ihren Aufrufer in einer zweiten Datei an. Ändert sich zuerst die Definition, kann ein Watcher den alten Aufruf mit der neuen Definition sehen. Ändert sich zuerst der Aufrufer, entsteht die umgekehrte Inkonsistenz. Beide Dateien können gültiger Text sein, während das kombinierte Programm gerade ungültig ist.

Die Lehre: Generationen publizieren, nicht eine Folge von Schreibvorgängen

Semaprax brauchte einen begrenzten Weg, verifizierte Änderungen über mehrere Quelldateien zu publizieren. Die Architekturentscheidung verwirft sequenziellen Ersatz, weil Leser eine gemischte Generation beobachten können. Das gewählte Design hält vollständige Generationen unveränderlich und wählt genau eine über einen ACTIVE-Datensatz aus. Die fixierte Semaprax-Architekturentscheidung dokumentiert die Entscheidung und die verworfenen Alternativen.

.semaprax-workspace/
  ACTIVE
  generations/
    <alte-workspace-revision>/
    <kandidaten-workspace-revision>/

Der Schreibpfad besteht aus fünf getrennten Phasen:

1. Vorschlag an eine Basisrevision binden. Hat sich der gewählte Workspace bewegt, wird abgebrochen.
2. Jede betroffene Datei vorprüfen. Alle Operationen werden gegen dieselbe authentifizierte Basis aufgelöst.
3. Den vollständigen Kandidaten separat bauen. Auch unveränderte Dateien gehören hinein, damit eine ganze Generation entsteht.
4. Den vollständigen Kandidaten verifizieren. Formate, Identitäten, Limits, Digests und tatsächlich zugesagte Invarianten werden geprüft.
5. Einen Zeiger wechseln. Nach finalen Prüfungen wird nur ACTIVE ersetzt. Kooperierende Leser lösen den Zeiger auf eine unveränderliche Generation auf.

Warum reicht ein atomarer Datei-Rename nicht?

Eine temporäre Datei zu schreiben und über das Ziel umzubenennen ist ein wertvolles Muster für eine einzelne Datei. Rust dokumentiert std::fs::rename als eine Rename-Operation und nennt plattformspezifisches Verhalten sowie Fehler über Mount-Grenzen hinweg. Die API bietet keine portable Transaktion über eine beliebige Pfadmenge. Siehe den Rename-Vertrag der Rust-Standardbibliothek.

Fünf solcher Operationen erzeugen fünf Publikationszeitpunkte. Kann ein Leser zwischen Zeitpunkt zwei und drei laufen, bleibt das Gesamtprogramm als Mischung sichtbar. Atomarität auf Dateiebene setzt sich nicht automatisch zu Projektatomarität zusammen.

Macht Git Multi-Datei-Änderungen nicht bereits atomar?

Ein Git-Commit bezeichnet einen vollständigen Tree. Dadurch wird aber nicht jeder Übergang im aktiven Working Tree für Editoren, Watcher oder andere Prozesse atomar. Repository-Historie zu publizieren ist etwas anderes als Dateien zu ändern, die laufende Werkzeuge gerade lesen.

Git selbst zeigt, wie exakt die Grenze beschrieben werden muss. git update-ref kann eine erwartete alte Objekt-ID prüfen und Ref-Änderungen in einer Transaktion sammeln. Die Dokumentation warnt dennoch, dass ein gleichzeitiger Leser eine Teilmenge mehrerer Ref-Änderungen sehen kann, obwohl einzelne Refs atomar aktualisiert werden. Die offizielle Git-Dokumentation zu update-ref ist ein gutes Modell für erwartete Versionen und explizite Transaktionszustände.

Branches, Worktrees und Commits bleiben richtig für Zusammenarbeit, Review und Recovery. Eine verwaltete Publikationsschicht braucht es nur, wenn laufende Verbraucher während der Änderung einen kohärenten Anwendungssnapshot sehen müssen.

Warum unveränderliche Generationen praktisch sind

Unveränderliche Generationen verlagern den Großteil des Risikos vor den Commit-Punkt. Ein Kandidat lässt sich bauen, prüfen und verwerfen, ohne den ausgewählten Zustand zu verändern. Die finale Operation bleibt klein, weil sie einen Zeiger statt aller Nutzdaten ändert.

Dieses Muster ist nicht auf Agentenwerkzeuge beschränkt. Nix erklärt atomare Upgrades ähnlich: Pakete werden nicht an Ort und Stelle überschrieben, und ein Profil wechselt auf eine neue Generation. So entsteht kein Zeitfenster mit teils alten und teils neuen Dateien. Der offizielle Nix-Architekturleitfaden zeigt ein reifes Beispiel des Generationsmusters.

Der agentenspezifische Zusatz ist Evidenz. Eine flüssige Modellantwort darf keine Commit-Authority sein. Das System sollte Basisrevision, vorgeschlagene Operationen, Kandidatendigest, Prüfergebnisse und Pivot-Ausgang bewahren, damit eine andere Komponente den Ablauf kontrollieren kann.

Was Semaprax tatsächlich implementiert und was nicht

Am geprüften Commit definiert Semaprax eine begrenzte Transaktion für 2 bis 16 verwaltete .spx-Dateien. Schreiber nehmen einen exklusiven Lock, bauen oder authentifizieren eine vollständige Kandidatengeneration, führen finale Prüfungen aus und ersetzen ACTIVE. Kooperierende Leser nehmen einen Shared Lock und lösen die gewählte unveränderliche Generation auf. Die fixierte Workspace-Transaction-Spezifikation definiert Wire-Format, Limits, Diagnosen, Evidenz und Nonclaims.

Die Grenze zählt mehr als die Überschrift. Das Protokoll macht Raw-Quellpfade, Git, Editoren oder nicht kooperierende Leser nicht atomar. Es verspricht kein Verhalten auf Netzwerkdateisystemen, keine Power-Loss-Durability, keinen automatischen Rollback, keine allgemeine Repository-Semantik und keine beliebige Multi-Datei-Reparatur. Semaprax bleibt Pre-Alpha-Forschung. Dieser Artikel macht aus begrenzter Evidenz keine Behauptung von Produktionsreife.

Build or Buy: acht Fragen an Anbieter von Agentenwerkzeugen

1. Welche Leser sind geschützt? Gilt die Zusage nur für die Tool-API oder auch für Working Tree, Language Server, Builds und externe Prozesse?
2. Was ist die Basisrevision? Jeder Vorschlag braucht eine erwartete Version und einen klaren Stale-Rejection-Pfad.
3. Wo liegt der Commit-Punkt? „Wir nutzen temporäre Dateien“ beantwortet die Multi-Datei-Frage nicht.
4. Wird der vollständige Kandidat geprüft? Syntaxprüfungen je Datei übersehen dateiübergreifende Brüche.
5. Wer besitzt Schreibberechtigung? Modelloutput, Evidenz und Approval-Token dürfen nicht still zu wiederverwendbarer Commit-Macht werden.
6. Was geschieht vor und nach dem Pivot? Ablehnung vor dem Pivot und Unsicherheit danach brauchen unterschiedliche Recovery-Prozesse.
7. Welches Durability-Versprechen wurde getestet? Prozessabsturz, OS-Absturz, Stromausfall und Netzwerkspeicher sind verschiedene Fehlermodelle.
8. Ist die Evidenz reproduzierbar? Verlange Hostile Tests, feste Fixtures, Limits und exakte Versionen, nicht nur eine Demo.

Wann brauchst du diese Architektur?

Für einen Agenten, der einen Patch vorschlägt, stoppt und auf menschliches Review eines normalen Git-Diffs wartet, brauchst du wahrscheinlich kein Generationenprotokoll. Prüfe es, wenn autonome Arbeit mehrere gekoppelte Dateien ändert, während Builds, Services oder andere Agenten den Workspace fortlaufend lesen und ein Mischzustand Deployment, Codegenerierung, Migration oder eine irreversible Aktion auslösen kann.

Beginne eine Schicht früher, wenn der Agent die richtigen Programmentitäten nicht zuverlässig identifiziert. Unser Semaprax-Beitrag über semantische Identität erklärt stabile Deklarations-IDs und revisionsgebundene Patches. Der Leitfaden zu KI-Agenten-Harnesses ordnet die Publikation in Kontext, Richtlinien, Tools, Verifikation und Observability ein.

Häufige Fragen

Sind Git-Commits atomar?

Ein Commit bezeichnet einen vollständigen Repository-Tree. Das garantiert nicht, dass aktive Leser eines sich ändernden Arbeitsverzeichnisses nie Zwischenstände sehen.

Ist atomares Schreiben dasselbe wie Rollback?

Nein. Atomare Publikation definiert, was am Pivot sichtbar wird. Rollback, Cleanup und Recovery nach einem Absturz sind getrennte Verträge mit eigener Evidenz.

Verhindern unveränderliche Generationen Merge-Konflikte?

Nein. Sie steuern die Sichtbarkeit für kooperierende Leser. Branch-Koordination, semantische Konflikte und menschliches Review bleiben getrennte Themen.

Redaktioneller Hinweis: OpenAI Codex unterstützte Recherche, Entwurf und Übersetzung. Wavect prüfte die technischen Aussagen am 6. September 2026 gegen Semaprax-Commit 942ed70 und die verlinkte Primärdokumentation. Aus dem Modelloutput werden keine Performance- oder Production-Readiness-Aussagen abgeleitet.