DEV Community

Cover image for Wie verhindert osFoundry, dass eine Änderung von Claude die Änderung einer Person in derselben Note überschreibt?
BBT for BBT Deutsch

Posted on

Wie verhindert osFoundry, dass eine Änderung von Claude die Änderung einer Person in derselben Note überschreibt?

Das ist das Schreib-Tool, das ein Claude-Chat für die Notes von osFoundry bekommt, so wie es der öffentliche MCP-Endpoint auflistet. Abgerufen wurde es am 2026-11-06 mit einem nicht authentifizierten tools/list, gekürzt auf die Felder, um die es hier geht:

{"name": "edit_note_tab",
 "description": "Use an exact tab ID and version from read_note_tab. Use replace_text for Note/Markdown, slide_add or slides_add_outline for Slides, sheet_set_range for Sheet, or replace_tab_data for supported content tabs. File and Source attachments cannot be edited through this tool. A repeated idempotency key returns the first result.",
 "inputSchema": {
   "required": ["note_id", "tab_id", "expected_version", "idempotency_key", "operation"],
   "properties": {
     "operation": {"enum": ["replace_text", "replace_tab_data", "slide_add",
                            "slides_add_outline", "sheet_set_range"]},
     "sheet_id": {"type": "string"}, "start_row": {"type": "integer"},
     "start_col": {"type": "integer"}, "values": {"type": "array", "items": {"type": "array"}}}},
 "annotations": {"readOnlyHint": false, "destructiveHint": true},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Enter fullscreen mode Exit fullscreen mode

Zwei der fünf Pflichtfelder haben mit der eigentlichen Änderung nichts zu tun. expected_version macht den Schreibvorgang zu einem Compare-and-Swap: Er greift nur, wenn die Note noch auf der Version steht, die der Agent gelesen hat. idempotency_key macht ein erneutes Senden harmlos. Die anderen Schreib-Tools für Notes, create_note_tab und add_note_source, verlangen dasselbe Paar. Lese-Tools nicht: list_note_tabs, read_note_tab, read_sheet_range (höchstens 100 mal 100 Zellen) und list_note_attachments sind alle readOnlyHint: true unter osfoundry:read.

Im Folgenden geht es darum, was dieser Vertrag bringt, gemessen an einem Nachbau. Die Versionsprüfung ist nur die eine Hälfte. Die andere ist, was der Agent tut, nachdem er abgewiesen wurde.

Warum einen veralteten Schreibvorgang ablehnen, statt ihn zu mergen?

replace_text schickt den kompletten Text eines Tabs. Hat Claude Version 7 gelesen, hat eine Person Version 8 gespeichert und schickt Claude jetzt seinen Text, liegen dem Server zwei vollständige Dokumente vor, aber nicht mehr der gemeinsame Vorfahre. Er kann nicht erkennen, ob Claude den neuen Absatz der Person löschen wollte oder ihn einfach nie gesehen hat. Last-Writer-Wins entscheidet sich still für die falsche Antwort. Ablehnen ist die einzige Reaktion, die nicht rät.

Das ist Optimistic Concurrency. Niemand hält einen Lock, während ein Modell zwanzig Sekunden nachdenkt. Jeder Schreibvorgang gibt an, auf welcher Version er beruht, und der Server tauscht nur, wenn diese noch aktuell ist:

UPDATE notes SET version = :new WHERE id = :note AND version = :expected;  -- 0 rows → conflict
Enter fullscreen mode Exit fullscreen mode

Die Desktop-App von osFoundry macht dasselbe auf der menschlichen Seite. In apps/web/src/screens/notes/context/NotesContext.tsx ist das Speichern einer Note ein PATCH /notes/:id mit expected_updated_at (der letzten Server-Revision, die der Editor gesehen hat) und, nach einem Connected-Schreibvorgang, einem expected_version, das connected-note-save-guard.ts in localStorage ablegt, damit ein Neuladen es nicht löscht. Schlägt das Speichern fehl, behält der Editor den Inhalt der Person als lokalen Entwurf und zeigt einen Sync-Fehler an. Beide Editoren schreiben bedingt.

Was sollte der Agent tun, wenn er abgewiesen wird?

Es gibt zwei naheliegende Reaktionen, und nur eine davon funktioniert:

  1. Den Tab neu lesen, die beabsichtigte Änderung auf den aktuellen Inhalt erneut anwenden und mit der neuen Version schreiben.
  2. Nur die Version neu lesen und denselben Payload noch einmal schicken.

Die zweite besteht die Prüfung und überschreibt trotzdem die Person, weil der Payload aus dem alten Text berechnet wurde. Das sieht die Prüfung nicht. Eine Version beweist nur, dass man die neueste Versionsnummer gesehen hat, nicht, dass man ihren Inhalt verwendet hat.

Der Nachbau

Hier läuft kein Claude-Binary. notes_store.py implementiert list_note_tabs, read_note_tab, read_sheet_range, edit_note_tab (replace_text, sheet_set_range) und create_note_tab auf sqlite im WAL-Modus, mit denselben Tool- und Argumentnamen wie live. Jeder Schreibvorgang läuft in BEGIN IMMEDIATE, prüft die Idempotenz-Tabelle, vergleicht die Version, wendet die Änderung an, erhöht die Version und speichert das Ergebnis, alles in einer Transaktion. race.py startet zwei Threads mit eigenen Verbindungen: einen geskripteten "Claude" und eine geskriptete Person. Beide machen 100-mal Lesen → Nachdenken → Schreiben. Die Denkzeit ist herunterskaliert: 20–80 ms für Claude, 5–40 ms für die Person, sodass das Fenster zwischen Lesen und Schreiben beim Agenten das längere ist, wie bei einem echten Modell. Jeder Schreibvorgang hängt eine eindeutige Zeile an (claude-17, human-42), sodass jede fehlende Zeile hinterher ein verlorenes Update ist, das man zählen kann. Python 3.9.6, Apple M1, Seeds 1–5.

Der Schreibpfad, ohne das sqlite-Drumherum:

def _guarded(self, note_id, tab_id, expected_version, idempotency_key, apply):
    db.execute("BEGIN IMMEDIATE")
    hit = db.execute("SELECT result FROM idem WHERE key=?", (idempotency_key,)).fetchone()
    if hit:
        return {**json.loads(hit[0]), "replayed": True}
    current = tab_version if self.check == "tab" else note_version
    if self.check != "none" and expected_version != current:
        return {"error": "version_conflict", "current_version": current}
    result = apply(db)                       # replace_text / sheet_set_range / new tab
    # bump version, store (key, result), COMMIT
Enter fullscreen mode Exit fullscreen mode

Und die Schleife des Agenten, mit dem Schalter für die Strategie:

r = s.edit_note_tab("note-1", tab, tab_now["version"], uuid.uuid4().hex, **payload)
while "error" in r:
    fresh = s.read_note_tab("note-1", tab)
    if policy == "reapply":
        payload["text"] = fresh["data"] + "\n" + line   # redo the change on what's there now
    tab_now = fresh                                      # refresh_version keeps the old text
    r = s.edit_note_tab(...)
Enter fullscreen mode Exit fullscreen mode

Ein Versuch mit Konflikt bekommt einen neuen Idempotency Key. Der Key steht für einen beabsichtigten Schreibvorgang auf einer bestimmten Basis. Nach einer Ablehnung ist der erneut angewendete Schreibvorgang ein anderer Schreibvorgang.

Wie viele Updates gehen ohne Prüfung verloren?

Fünf Durchläufe, 100 Änderungen pro Editor und Durchlauf, insgesamt 1,000 beabsichtigte Zeilen pro Tabellenzeile:

Schreibschutz Agent bei Konflikt Verlorene Zeilen Verloren: Claude / Person Konflikte: Claude / Person Max. Versuche
keiner — 300 125 / 175 0 / 0 1
Note-Version neu lesen, erneut anwenden 0 0 / 0 219 / 133 2
Note-Version nur Version neu lesen, alten Text erneut senden 304 117 / 187 213 / 136 3

Ohne Prüfung verschwanden 30% aller Änderungen, und die Person verlor mehr als Claude. Weil der Agent länger nachdenkt, beruhen seine Schreibvorgänge auf älteren Lesevorgängen und überschreiben deshalb mehr. Mit Prüfung und erneutem Anwenden ging nichts verloren. 41–48% der Schreibvorgänge von Claude brauchten einen zweiten Versuch, nie einen dritten. Im Mittel waren es 1.41–1.48 Versuche für Claude und 1.24–1.30 für die Person. Jeder Durchlauf dauerte 9.6–10.5 s Wall-Clock-Zeit, unabhängig vom Modus, weil die Denkzeit dominiert.

Die dritte Zeile sollte man sich merken. Der Server meldete über 300 Konflikte und schützte nichts. Eine Versionsprüfung erzwingt, dass man neu liest. Sie kann nicht erzwingen, dass man das Gelesene auch verwendet.

Kostet die Prüfung etwas?

bench.py misst 2,000 sequenzielle edit_note_tab-Aufrufe mit einem replace_text von 200 Zeichen, drei Wiederholungen pro Modus. Median pro Schreibvorgang: 61.9–63.1 µs ohne Prüfung, 57.0–58.8 µs mit der Note-Version, 55.1–61.1 µs mit einer Tab-Version. Der Vergleich ist ein indizierter Lesezugriff innerhalb einer Transaktion, die ohnehin offen ist. Der Unterschied liegt unter dem Rauschen zwischen den Durchläufen. Das p99 (0.42–1.33 ms) ist fsync-Jitter von sqlite und hängt nicht vom Modus ab.

Warum gehört die Version zur Note, und was kostet das?

Die Tool-Beschreibungen von osFoundry binden eine Version an die ganze Note. Bei create_note_tab heißt es "Use the version from list_note_tabs", also aus der Auflistung auf Note-Ebene. Im Pfad der Desktop-App, der Connected-Änderungen anwendet (connected-note-application.ts), wird expected_version mit dem updated_at der Note verglichen. Eine Person, die im Sheet-Tab tippt, verschiebt also die Version, gegen die Claudes Schreibvorgang im Text-Tab geprüft wird.

Im Nachbau lässt sich das messen. race.py tabs läuft mit Claude im Text-Tab und der Person, die Zellen im Sheet-Tab schreibt, 3 Durchläufe, je 100 Änderungen:

Geltungsbereich der Version Konflikte Claude Konflikte Person Verloren
Note 130 von 300 Schreibvorgängen (43%) 87 von 300 (29%) 0
Tab 0 0 0

Jeder dieser 217 Konflikte ist ein falscher, denn die beiden Editoren haben nie denselben Tab angefasst. Sie kosten jeweils ein erneutes Lesen und sonst nichts. Eine Version auf Note-Ebene bietet etwas, das eine Tab-Version nicht kann: Jeder Schreibvorgang wird gegen alles in der Note geprüft. Ein Agent, der das Sheet gelesen hat, um den Brief zu schreiben, kann also keinen Brief schreiben, der auf Sheet-Werten beruht, die sich inzwischen geändert haben. Tab-Versionen beseitigen die falschen Konflikte und verlieren genau diese Garantie über Tabs hinweg. Für einen Agenten, der einen Tab liest und einen anderen schreibt, ist die grobe Version der sicherere Standard.

Was macht ein Millisekunden-Timestamp mit einer Versionsprüfung?

Eine Timestamp-Version funktioniert nur, wenn zwei Speichervorgänge nicht denselben String erzeugen können. race.py fast setzt die Denkzeit auf null, 2,000 Änderungen pro Editor, 5 Durchläufe, und vergleicht eine auf Millisekunden gekürzte Version mit einem Mikrosekunden-Timestamp plus einem Suffix aus 6 Hex-Ziffern:

Versionsformat Verlorene Zeilen (von 20,000) Durchläufe mit Verlust
Millisekunden 136 (0.68%) 5 von 5
Mikrosekunden + Suffix 0 0 von 5

Wenn zwei Schreibvorgänge in derselben Millisekunde committen, bekommt der zweite dieselbe Version wie der erste. Ein Editor, der vor dem ersten Schreibvorgang gelesen hat, besteht dann die Prüfung gegen den zweiten. osFoundry speichert Note-Versionen mit der vollen Timestamp-Präzision von PostgreSQL. Wer so etwas selbst baut, nimmt einen Zähler oder einen Timestamp mit Tie-Breaker.

Warum braucht das Anlegen einen eigenen Key?

create_note_tab ersetzt nichts, deshalb kann eine Versionsprüfung allein keine Duplikate verhindern. Der wiederholte Aufruf ist ein neuer Tab auf der neuen Version. race.py create legt 50 Sheet-Tabs an, wobei 30% der Antworten verloren gehen, sodass der Client es erneut versucht, wie es ein Host nach einem Timeout tun würde:

Gesendete Aufrufe Angelegte Tabs Duplikate
ohne Key, 3 Durchläufe 71 / 61 / 63 71 / 61 / 63 21 / 11 / 13
gleicher Key beim Retry 71 / 61 / 63 50 / 50 / 50 0

Mit dem Key liefert der Retry das erste Ergebnis zurück, einschließlich der Tab-ID, sodass das nächste edit_note_tab des Agenten den Tab trifft, den es wirklich gibt. Das ist die Zeile "A repeated idempotency key returns the first tab" in der Tool-Beschreibung von osFoundry.

Wenn du das selbst verdrahtest

  • Mach expected_version bei jedem Schreib-Tool zur Pflicht, im Schema, nicht als optionales Feld. Eine optionale Prüfung wird übersprungen, sobald ein Modell es zum ersten Mal eilig hat.
  • Gib einen Konflikt als normales Tool-Ergebnis zurück, mit dem das Modell etwas anfangen kann, und schreib in die Tool-Beschreibung, was zu tun ist: neu lesen, dann die Änderung erneut ausführen. Deine Anweisungen sind der einzige Ort, an dem die Regel "erneut anwenden, nicht nur die Version aktualisieren" stehen kann.
  • Wähl den Geltungsbereich der Version bewusst. Versionen pro Dokument erzeugen falsche Konflikte und schützen Lesezugriffe über Tabs hinweg. Versionen pro Tab vermeiden die falschen Konflikte und verlieren diesen Schutz.
  • Sorg dafür, dass Versionen nicht kollidieren können: ein Zähler oder ein Timestamp in voller Präzision mit Tie-Breaker. Niemals ein auf Millisekunden gerundeter Timestamp.
  • Versieh Anlegen und Anhängen mit einem Idempotency Key, der genau eine Absicht auf einer Basis benennt. Speichere Key und Ergebnis in derselben Transaktion wie den Schreibvorgang.
  • Schütz auch den menschlichen Editor. Prüft man Konflikte nur beim Agenten, kann ein veralteter Browser-Tab den Agenten immer noch überschreiben.

Die Kurzdefinition des zugrunde liegenden Protokolls steht bei osFoundry im Glossareintrag zu MCP. Wie frühere Stände einer Note aufbewahrt und wiederhergestellt werden, steht auf der Seite zu Note-Versionen.

Top comments (0)