Live-Activity Content-State-Vertrag (für MacClaude)

Wer: StratoClaude (Backend) → MacClaude (native App) Wozu: Damit die ActivityKit-Structs in der App und die Backend-Push-Payloads (Bestell-Liste B1.6 Broadcast-Channel, B1.7 pushToStart) dieselben Keys sprechen. Charter-Regel: Backend liefert den State, die App rendert ihn.

Stand 08.06.2026. Quelle: app/backend/main.py (_shopping_state, LA_SHOPPING_ATTR) + app/backend/apns.py (start_activity, broadcast).

Einkaufs-Live-Activity

ActivityAttributes-Typ (Name muss exakt matchen): ShoppingActivityAttributes

Statische attributes (beim Start):

Dynamischer content-state (Start, Update, Broadcast):

Die neuen Story-Felder (lastItem/lastActorUserId/lastActorName/-AvatarTint/-Emoji/lastEventText/updatedAt) sind null, solange in der Woche noch keine getrackte Aktion lief.

SILV-191 (P3) Atomarität: lastActorUserId + lastActorName/AvatarTint/Emoji + activeShoppers[].userId + updatedAt werden serverseitig IMMER aus EINEM konsistenten Lese-Snapshot gebaut (_shopping_state: eigene WAL-Read-Verbindung + BEGIN), nie teil-aktualisiert. Der Client bekommt also nie eine Mischung aus altem Actor + neuer Shopper-Liste → kein Solo/Fremd-Flacker.

SILV-191 (P4) Reihenfolge/Monotonie: Ein „ältere Updates verwerfen"-Guard ist im Push-LA-Render NICHT ausführbar (kein Vorzustand im View-Build). Real-Garantie: _la_shopping_sync liest bei JEDEM Aufruf den aktuellen Stand → die Generierung ist monoton (updatedAt nie rückläufig), jeder Push ist ein vollständiger Snapshot (kein Delta). Der Server hält keine Suppression veralteter Broadcasts vor dem Send (APNs-/Netz-Reordering ist nicht server-kontrollierbar). Darum guardet der Client an seinen zwei lokalen update()-Stellen (optimisticCheckoff, reload-Reconcile) per updatedAt — das genügt, weil jeder Push idempotent + voll ist. KEIN unmöglicher Render-Guard nötig.

SILV-193 — Live-Sync = GARANTIE über Pull-Reconcile (Push=Wecker, Pull=Wahrheit). Kein Push-Pfad (Broadcast oder la-update) ist eine Zustell-Garantie (APNs fire-and-forget, droppt/reordert). Darum: (1) monotone rev je Woche im Content-State (s. o.). (2) GET /api/shopping/{week}?since_rev=N — der Client zieht beim Push-Aufwachen (oder Foreground) mit seiner letzten rev. Server gleich → {week, rev, unchanged:true} (kein Item-Body, kein Radar-Rechnen). Server neuer → die volle Wahrheit + rev + unchanged:false. Server-Ordnung (race-sicher): rev wird vor den Items gelesen → der Client wird nie stale (höchstens ein redundanter Voll-Pull). Damit ist „live" ehrlich: bei dünnem/abgerissenem Netz reconciled der nächste Pull, die UI behauptet nie „live", wenn sie's nicht ist (Client zeigt „zuletzt vor X" statt eingefrorenem Balken). (3) B-FIX-5 — Präsenz-Heartbeat via Item-Mutation: wer eine Item-Aktion mit by macht, frischt den last_heartbeat seiner aktiven shopping_session (_touch_presence) → ein Einkäufer fällt nicht aus der Partner-Präsenz, während er im Hintergrund abhakt. Frischt nur eine bereits aktive Sitzung — legt KEINE an (Hinzufügen von daheim macht nicht zum Einkäufer; explizites Präsenz-Modell, einkauf-praesenz-modell.md).

Swift-Seite (Vorlage):

struct ShoppingActivityAttributes: ActivityAttributes {
    public struct ContentState: Codable, Hashable {
        var open: Int
        var done: Int
        var total: Int
        var estEur: Double
        var estPriced: Int                // SILV-150 (Bedeckung: estPriced von open mit Preis)
        var lastItem: String?
        var lastActorUserId: Int?         // SILV-191 (by-User als Int; Rollen-Render 'ich vs. fremd')
        var lastActorName: String?        // SILV-148
        var lastActorAvatarTint: String?  // SILV-148 (users.color)
        var lastActorEmoji: String?       // SILV-163 (users.emoji, 🐟/🐠)
        var lastEventText: String?        // SILV-148 (serverseitig formuliert)
        var updatedAt: String?            // SILV-148 (ältere Updates verwerfen)
        var nextOpen: [OpenItem]          // SILV-168 (nächste offene Posten fürs DI-Abhaken)
        var activeShoppers: [Shopper]     // SILV-152 (wer ist im Markt)
        var ended: Bool?                  // SILV-270 (Session-Abschluss -> 'Erledigt', Karte endet)
    }
    struct OpenItem: Codable, Hashable { var id: Int; var label: String }  // SILV-168
    struct Shopper: Codable, Hashable { var name: String; var avatarTint: String; var userId: Int }  // SILV-154: userId
    var week: String
}

Der Server schickt im aps:

{ "aps": { "timestamp": 1234567890, "event": "start|update",
           "content-state": { "open": 7, "done": 2, "total": 9,
                              "estEur": 14.30, "estPriced": 6, "lastItem": "Milch",
                              "lastActorUserId": 1,
                              "lastActorName": "Dennis", "lastActorAvatarTint": "azure",
                              "lastActorEmoji": "🐟",
                              "lastEventText": "Dennis hat Milch eingepackt",
                              "updatedAt": "2026-06-11 00:46:40",
                              "nextOpen": [{ "id": 42, "label": "Bananen" }, { "id": 43, "label": "Hafermilch" }],
                              "activeShoppers": [{ "name": "Jaqueline", "avatarTint": "coral", "userId": 2 }] },
           "attributes-type": "ShoppingActivityAttributes",
           "attributes": { "week": "2026-01-05" } } }

Wer hat gehandelt (by-Vertrag, SILV-148): Im Wir-Modus teilt sich ggf. eine Geräte-Session → der Server kann den Handelnden NICHT aus der Session ableiten. Der Client schickt den aktiven Profil-user_id als by im Body von PATCH /api/shopping/items/{id} und POST /api/shopping/{week}/items mit. Ohne by fällt der Server auf den Session-User zurück (bricht nichts, aber die „wer"-Story bleibt leer).

Backend-Endpoints (schon gebaut, deployed)

Abhaken (PATCH /api/shopping/items/{id}) und Hinzufügen (POST /api/shopping/{week}/items, SILV-148) rufen serverseitig automatisch _la_shopping_sync(week) → Broadcast + Einzelgerät-Update (fire-and-forget). Beide tragen den by-User in die Aktions-Chronologie ein.

Status Broadcast vs. Pull (SILV-193)

1. Broadcast-Capability — ERLEDIGT (Korrektur 11.06., SILV-193): die channels-Row für purpose=shopping wurde am 2026-06-08 via erfolgreichem create_channel angelegt (Bundle de.dennisfisch.silverscale.native, production) — die Capability war/ist aktiv (sonst 400 BroadcastFeatureNotEnabled). _la_shopping_sync feuert heute beides: apns.broadcast(channel) und update_by_context an die la-update-Token. Die Sync hängt also nicht allein an la-update. Wichtig: kein Push-Pfad ist eine Zustell-Garantie → die Garantie liefert der Pull-Reconcile (?since_rev, s. SILV-193- Block oben), nicht ein „besserer" Push. Ein scharfer End-to-End-Broadcast-Beweis steht aus (würde 31 Live-Geräte-Karten anstoßen → nur mit Dennis am Gerät, kein Sessel-Test).
2. App liefert pushToStartToken (→ register kind la-pushToStart) und je gestarteter Activity den update-Token (→ kind la-update) bzw. abonniert den Channel (Activity.PushType.channel(channelID)).
3. B1.3 (Update bei jeder Mutation Tagebuch/Budget) ist bewusst noch offen – wird abgestimmt, sobald die LA-Struct + ein Budget-Content-State stehen.