title: "Was koch ich draus? — Live-Activity Content-State-Vertrag (SILV-325)" category: dev date: 2026-06-18

Live-Activity Content-State-Vertrag: Co-Plan „Was koch ich draus?"

Wer: StratoClaude (Backend, pusht den State) → MacClaude (App baut das Widget CookSuggestActivity). Schwester zu live-activity-contract.md (Shopping) und live-activity-budget-contract.md (Budget). Charter-Regel: Backend liefert den State, die App rendert ihn. Datenfluss: cook-suggest-vertrag.md.

Die LA begleitet die Co-op-Session zu zweit („Plan mit Jaqueline das Essen"): der eine startet, der andere bekommt pushToStart + Push, beide sehen den Fortschritt live, tippen sich per Deep-Link in den jeweils richtigen Wizard-Schritt.

ActivityAttributes-Typ: CookSuggestActivityAttributes

Statische attributes (beim Start, ändern sich nicht):

Dynamischer content-state (Start, Update):

Swift-Vorlage (Mac baut):

struct CookSuggestActivityAttributes: ActivityAttributes {
    public struct ContentState: Codable, Hashable {
        var state: String
        var statusLabel: String
        var deepLinkStep: String?
        var proposalCount: Int
        var partnerPickTitle: String?
        var partnerReady: Bool
        var decidedTitle: String?
        var updatedAt: String?
        var rev: Int
        var ended: Bool?
    }
    var sessionId: String
    var date: String
    var partnerName: String?
    var partnerTint: String?
    var partnerEmoji: String?
}

aps-Payload (analog Shopping/Budget):

{ "aps": { "timestamp": 1234567890, "event": "start|update|end",
  "content-state": { "state": "proposed", "statusLabel": "3 Vorschläge sind da",
                     "deepLinkStep": "proposals", "proposalCount": 3,
                     "partnerPickTitle": null, "partnerReady": true,
                     "decidedTitle": null, "updatedAt": "2026-06-18 19:12:03",
                     "rev": 7, "ended": null },
  "attributes-type": "CookSuggestActivityAttributes",
  "attributes": { "sessionId": "cs_abc", "date": "2026-06-18",
                  "partnerName": "Jaqueline", "partnerTint": "coral", "partnerEmoji": "🐠" } } }

context_key & Token-Lookup

• context_key = "cooksuggest:{sessionId}:{userId}" — per User (nicht je Session), weil der Partner-Bezug (partnerName/statusLabel „Jaqueline ist bereit") aus Sicht jedes Geräts ein anderer ist und ein update_by_context-Push EINE Payload an alle Token mit dem Key schickt. Der Client registriert den la-update-Token mit context_key = "cooksuggest:\(sessionId):\(myUserId)" (POST /api/apns/register, kind:"la-update"). Der Server pusht je present-Teilnehmer dessen eigene Payload (Partner = der jeweils andere).
• pushToStart (Co-op-Einladung): beim create mit with_user_id startet der Server die LA auf den Geräten des eingeladenen Partners (la-pushToStart- Tokens dieses Users, nicht broadcast). Idempotent je (sessionId, deviceToken) über la_starts. Setzt voraus, dass der Partner einen la-pushToStart-Token registriert hat (POST /api/apns/register) — ein 500 dort (SILV-326, gefixt) verhinderte die Co-op-LA komplett.
• Einladungs-Zustellung (3 Kanäle, ein Aufruf notify()): zusätzlich zur LA feuert der Server eine Benachrichtigung „Plan mit Dennis das Essen" (Sparkle-Icon ✨, emoji-freier Titel, kein 🤖) — die (a) als Notification- Center-Record in der „Heute"-Glocke landet (das bestehende notifications- Polling zeigt sie), (b) als Alert-Push mit Deep-Link im Top-Level-Feld link = "/cook-suggest/{sessionId}" (der Client liest userInfo["link"] im Notification-Tap und routet in den Assistenten — gleiche Form wie Shopping/Budget), (c) als Web-Push. Idempotent über dedupe_key = "cs-invite-{sessionId}".
• Einladung ausgrauen bei Session-Ende (C1): erreicht die Session decided/ cancelled (TTL/letzter leave), setzt der Server notifications.resolved = 1 auf den Einladungs-Record. Der Client liest resolved (0/1) und graut die Glocken-Karte aus — ein Tap auf eine veraltete Einladung öffnet sonst die Planung „von vorne". (Der Client fängt „resume einer beendeten Session" zusätzlich ab: decided → Gericht zeigen, cancelled → schließen.)
• Solo (kein withUserId): keine Remote-LA nötig — der Initiator startet die Karte lokal selbst (er ist ja in der App). Push-LA ist rein das Co-op-Mittel.

Push-Trigger (welcher Zustandswechsel pusht)

Der Server pusht bei jeder Session-Mutation (voller Content-State, kein Delta): - answers/ready → statusLabel („… füllt aus" / „… ist bereit"), partnerReady. - alle ready → generating → „Die Küche denkt nach …". - Job fertig → proposed → „N Vorschläge bereit", proposalCount, deepLinkStep:"proposals". - pick → partnerPickTitle (der andere sieht „Vorschlag: …?"). - confirm-Einigung → finalizing → „Wird angerichtet …". - decided → decidedTitle, ended:true (APNs end, ~2 min). - cancelled/letzter leave/TTL → ended:true (end).

Ehrlichkeit / Reconcile (wie Shopping SILV-193)

Kein Push ist eine Zustell-Garantie (APNs fire-and-forget). Darum: monotone rev im Content-State + der Client zieht beim Push-Aufwachen / Deep-Link den vollen Zustand via GET /api/cook-suggest/sessions/{id} (= Wahrheit). Push = Wecker, Pull = Wahrheit. Der Client guardet seine lokalen Updates gegen rev.