@arcote.tech/arc-chat 0.7.20 → 0.7.21

package/README.md

@@ -11,25 +11,45 @@ opisuje **mental model**, którego trzeba się trzymać przy każdej modyfikacji
 
 ## Mental model
 
-> **Live wartość treści asystenta żyje wyłącznie w pamięci serwera.**
-> **DB zna tylko stan finalny — i tylko po zakończeniu tury.**
+> **DB jest jedynym źródłem prawdy o strukturze konwersacji.**
+> **Stream jest tylko overlayem — ulotnym podglądem trwającej generacji.**
+> **Timeline jest czystą funkcją obu — nigdy mutowalnym stanem.**
 
-W trakcie generacji LLM streamuje chunki do `stream-registry` (in-memory,
-per `messageId`). Klient subskrybuje SSE po `messageId` i dostaje:
+Serwer: w trakcie generacji LLM streamuje chunki do `stream-registry`
+(in-memory, per `messageId`). Klient subskrybuje SSE po `messageId` i dostaje:
 
 1. `init` — snapshot aktualnego `currentBlocks` w momencie podłączenia
 2. live `text_delta` / `tool_call_*` — kolejne chunki
-3. `done` — koniec turny
+3. `done` — koniec turnu (**advisory** — patrz niżej)
 
-Dopiero po `provider.streamComplete()` zwróci pełen wynik, listener wywołuje
+Dopiero gdy `provider.streamComplete()` zwróci pełen wynik, listener wywołuje
 `completeAssistantTurn({ blocks })` — **jedyny zapis treści do DB w całej
-turze**. Następnie `finalize(messageId)` zamyka stream i po 5s grace okresie
-drop'uje go z mapy.
+turze**, atomowo z flipem `isGenerating: false`. Następnie `finalize(messageId)`
+zamyka stream i po 5 s grace okresie drop'uje go z mapy.
+
+Klient: `chat-component.tsx` NIE merguje kanałów imperatywnie. Trzy elementy:
+
+- **liveQuery `getByScope`** — struktura: wiadomości, finalne blocks,
+  `isGenerating` / `interrupted` / `error`, tool_results,
+- **`useAssistantOverlays`** — per generujący row utrzymuje SSE i buduje
+  `overlay { blocks, status }` przez **shared reducer**
+  (`applyStreamEvent` — dokładnie ten sam kod, którym serwer akumuluje
+  `currentBlocks`),
+- **`deriveTimeline(history, overlays, optimistic...)`** — czysta funkcja
+  poza komponentem. Row `isGenerating` + overlay → renderuj overlay;
+  bez overlaya → placeholder; `interrupted` → retry; zamknięty → finalne
+  blocks z DB. Wyniki tooli zawsze z DB.
+
+**Autorytatywny koniec turnu to flip `isGenerating: false` w DB** (przychodzi
+liveQuery razem z finalnymi blocks, atomowo w jednym rzędzie). SSE `done` i
+`error` tylko zdejmują caret wcześniej. Dzięki temu kolejność dostarczenia
+(done przed/po flipie DB, zgubione done, martwy socket) **nie ma znaczenia** —
+derywacja zawsze liczy się od najnowszego stanu obu źródeł.
 
 **To NIE jest event-sourcing dla streamingu.** Snapshoty częściowej treści
 do DB były anti-pattern (niepotrzebny narzut, dublowanie stanu). Stream-registry
 to autorytatywne źródło live wartości; DB to autorytatywne źródło stanu po
-zamknięciu turny.
+zamknięciu turnu.
 
 ---
 
@@ -37,14 +57,21 @@ zamknięciu turny.
 
 ```
 src/
-├─ aggregates/message.ts        Aggregate: pola, eventy, mutacje
+├─ aggregates/message.ts          Aggregate: pola, eventy, mutacje
+├─ ordering.ts                    Kanoniczna kolejność rzędów (klient + serwer)
 ├─ listeners/
-│  └─ ai-generation-listener.ts Generation loop + 3 listenery (gen/resume/retry)
-├─ routes/chat-stream-route.ts  GET /chat/:name/stream/:messageId (SSE)
-├─ streaming/stream-registry.ts In-memory per-messageId MessageStream
-├─ react/chat-component.tsx     UI: auto-subscribe SSE + timeline rebuild z DB
-├─ tools/ask-questions.tsx      Reusable interactive tool
-└─ chat-builder.ts              chat().identifyBy(...).ai(...).build()
+│  └─ ai-generation-listener.ts   Generation loop + 3 listenery (gen/resume/retry)
+├─ routes/chat-stream-route.ts    GET /chat/:name/stream/:messageId (SSE)
+│                                 + lazy repair osieroconych rzędów przy 410
+├─ streaming/
+│  ├─ blocks-reducer.ts           SHARED reducer eventy→blocks (serwer + klient)
+│  └─ stream-registry.ts          In-memory per-messageId MessageStream
+├─ react/
+│  ├─ derive-timeline.ts          Czysta derywacja: (DB, overlays) → timeline + busy
+│  ├─ use-assistant-overlays.ts   SSE per generujący row → overlay map
+│  └─ chat-component.tsx          Cienki komponent: liveQuery + hook + derive + render
+├─ tools/ask-questions.tsx        Reusable interactive tool
+└─ chat-builder.ts                chat().identifyBy(...).ai(...).build()
 ```
 
 ---
@@ -55,6 +82,7 @@ src/
 USER wpisuje "Cześć", klika Send
     │
     ▼
+Klient: pendingSends += optimistic user message (busy=true od razu)
 sendMessage mutation (atomowo)
     ├─ emit assistantTurnStarted  → projection: set empty assistant row
     │                                (isGenerating=true, brak blocks)
@@ -62,107 +90,126 @@ sendMessage mutation (atomowo)
                                   → triggeruje aiGenerationListener (async)
     │
     ▼
-DB query getByScope() pushuje obie wiadomości do klienta
+liveQuery getByScope() pushuje obie wiadomości do klienta
+    ├─ pendingSend settled → drop optimistic
+    └─ generatingIds = [assistantMsgId] → useAssistantOverlays otwiera SSE
     │
     ▼
-React effect widzi isGenerating=true assistant row
-    activeGeneratingMessageId = id assistanta
-    useChatMessageStream auto-otwiera SSE
-    │
-    ▼                                          ◀───┐
-fetch /route/chat/:name/stream/:messageId          │
-    │                                              │
-    ├─ subscribe(messageId)                        │
-    │     ├─ Brak streamu → 410 ────┐              │
-    │     │                          │              │
-    │     │                          ▼              │
-    │     │                     UI: "Interrupted"  │
-    │     │                     + Retry button     │
-    │     │                          │              │
-    │     │                          ▼              │
-    │     │                     retryGeneration    │
-    │     │                          └──────────────┘
-    │     │
-    │     └─ Stream istnieje → init z currentBlocks snapshot
-    │
+fetch /route/chat/:name/stream/:messageId
+    ├─ subscribe(messageId) → init z currentBlocks snapshot
+    │     └─ Brak streamu → 410 → retry ×4 z backoffem
+    │           ├─ route: markInterrupted (lazy repair, jeśli row stary)
+    │           └─ po wyczerpaniu → overlay.status="gone" → UI "Interrupted"+Retry
     ▼
 Listener: startStream() → provider.streamComplete(onChunk)
     onChunk → publish(messageId, event)
-        ├─ mutuje currentBlocks (text append / push tool_call / set args)
+        ├─ currentBlocks = applyStreamEvent(currentBlocks, event)   ← shared reducer
         └─ broadcast SSE do wszystkich subscribers
-    Klient SSE → processEvent → setTimeline
+    Klient: overlay.blocks = applyStreamEvent(overlay.blocks, event) ← TEN SAM reducer
+    deriveTimeline renderuje overlay (caret na ostatnim bloku)
     │
     ▼
 streamComplete zwraca pełen result.blocks
     │
     ▼
-completeAssistantTurn({ blocks })  ← jedyny zapis treści do DB
-    │
+completeAssistantTurn({ blocks, error? })  ← jedyny zapis treści do DB
+    │                                         (atomowo: blocks + isGenerating=false)
     ▼
 finalize(messageId, { usage, finishReason })
-    ├─ broadcast done do subscriberów
-    ├─ close controllery
+    ├─ broadcast done (advisory — zdejmuje caret)
     └─ setTimeout(delete, 5s) — grace dla late subscribers
     │
     ▼
-Klient SSE: done → setIsStreaming(false)
-DB query update: isGenerating=false, blocks=...
-    └─ historySig refire → timeline rebuild z DB final blocks
+liveQuery update: isGenerating=false + blocks w JEDNYM rzędzie
+    ├─ overlay GC (hook)
+    └─ deriveTimeline renderuje finalne blocks z DB
+       (te same klucze itemów co overlay → zero remount-flasha)
 ```
 
 ---
 
+## Porządkowanie rzędów (`ordering.ts`)
+
+Mutacje `sendMessage` / `respondToTool` / `startStage` / `systemMessage`
+emitują `assistantTurnStarted` **przed** rzędem triggerującym (wymóg
+async listenera), więc pre-utworzony placeholder asystenta ma `createdAt`
+**wcześniejszy** niż pytanie, na które odpowiada. Samo `orderBy createdAt`
+ustawiłoby odpowiedź przed pytaniem.
+
+`orderMessages()` daje kanoniczną kolejność: `createdAt` → tie-break rolą
+(user/system → tool_result → assistant) → `_id` → fix-up przesuwający
+pierwszy assistant row sesji za jej trigger row. Używają go **oba** końce:
+`deriveTimeline` (klient) i `buildHistory` (serwer — historia dla LLM).
+Jeśli zmieniasz emit-order w mutacjach albo timestampy — zacznij od tego pliku.
+
+---
+
 ## Edge cases
 
 ### Graceful reload mid-stream (F5)
 
 Serwer i listener nadal generują. Klient po refresh:
 
-1. DB query zwraca assistant row z `isGenerating=true`
-2. `activeGeneratingMessageId` ustawia się → hook otwiera SSE
+1. liveQuery zwraca assistant row z `isGenerating=true`
+2. `generatingIds` zawiera ten row → hook otwiera SSE
 3. `subscribe(messageId)` zwraca aktualny `currentBlocks` w `init` event
-4. Klient renderuje to, co już zostało wygenerowane + kontynuuje live
+4. deriveTimeline renderuje to, co już wygenerowane + kontynuuje live
 
 **Bez duplikacji** — brak replay buffer'a chunków, jest jeden snapshot.
+Reconnect (visibility / heartbeat / BFCache) działa identycznie: zabij
+połączenie, otwórz nowe, `init` resetuje bazę overlaya.
 
 ### Server restart mid-stream
 
 Proces ginie z `currentBlocks` w pamięci → utrata. DB ma row
-`isGenerating=true` ale `subscribe(messageId)` zwraca `null` → route oddaje
-HTTP 410.
+`isGenerating=true`, ale `subscribe(messageId)` zwraca `null` → 410.
 
-1. React hook: `res.status === 410` → `setInterruptedIds(prev.add(messageId))`
-2. Timeline pokazuje TimelineItem `"interrupted"` + Retry button
-3. Klik Retry → `retryGeneration({ messageId })`:
-   - mutation emit `assistantTurnStarted` (fresh row) + `retryRequested`
-     (projection usuwa interrupted row)
-   - `aiRetryListener` reaguje, odpala `runGenerationLoop` z fresh
-     `preCreatedAssistantMessageId`
+1. Route przy 410 woła `markInterrupted` (lazy repair): jeśli row ma
+   `isGenerating=true` i jest starszy niż 10 s → emit `generationInterrupted`
+   → projection ustawia `isGenerating=false, interrupted=true`. **Trwałe
+   i cross-client** — każdy klient (też po F5) widzi interrupted z DB.
+2. Równolegle klient po wyczerpaniu retry ustawia `overlay.status="gone"` —
+   natychmiastowy lokalny stan, zanim repair przejdzie przez liveQuery.
+3. Klik Retry → `retryGeneration({ messageId })` (akceptuje `isGenerating`
+   ORAZ `interrupted` rows): emit `assistantTurnStarted` (fresh row) +
+   `retryRequested` (projection usuwa interrupted row) → `aiRetryListener`
+   odpala `runGenerationLoop`.
+
+### Błąd generacji
+
+Error path listenera zapisuje `error` w rzędzie (projection
+`assistantTurnCompleted` persystuje pole). Derywacja renderuje go z DB —
+**przeżywa F5 i reconnect**. SSE `error` event jest tylko advisory.
 
 ### Server tool call w środku tury
 
 Po `streamComplete` z `finishReason="tool_call"`:
 
-1. `completeAssistantTurn(blocks)` — assistant row finalizowany (blocks
-   zawiera tool_call w properOrder)
+1. `completeAssistantTurn(blocks)` — assistant row finalizowany
 2. `finalize(messageId)` — stream zamknięty
 3. Każdy server tool: `saveToolResult` → tool_result row w DB
-4. **Następna iteracja loop'a**: `startAssistantTurn` tworzy nowy assistant
-   row (`isGenerating=true`) → nowy `messageId` → klient widzi go w DB
-   query update → nowy SSE stream → drugi turn streamuje
+4. **Następna iteracja loop'a**: `startAssistantTurn` → nowy row
+   (`isGenerating=true`) → nowy `messageId` → nowy stream
 
-Każda iteracja loop'a = **osobny `messageId` = osobny stream**.
+Każda iteracja loop'a = **osobny `messageId` = osobny stream**. Input
+pozostaje disabled przez całą pętlę dzięki regule **busy** w derywacji
+(z DB, nie z lokalnego flagu): row `isGenerating` LUB ostatni assistant
+row ma server-tool call bez wyniku LUB ostatni row to świeży tool_result
+server-toola. Klauzule mają staleness cutoff (120 s) — gdy listener padł
+między zapisami, busy degraduje się do enabled zamiast wisieć wiecznie.
 
 ### Interactive tool (np. askQuestions)
 
-Po `streamComplete` z interactive tool calls:
-
 1. `completeAssistantTurn` + `finalize` — pierwsza tura zamknięta
 2. Listener returns (loop break)
-3. Klient widzi tool w timeline (status=pending), `ChatInput` disabled
-4. User klika answer → `respondToTool` mutation (atomowo emit
-   `assistantTurnStarted` + `userResponded`)
-5. `aiResumeListener` reaguje → kolejny turn streamuje
+3. deriveTimeline: tool bez wyniku + nie-server → status `pending`,
+   `hasWaitingInteractive=true` → input override
+4. User odpowiada → optimistic `pendingToolResults` (answer-view OD RAZU)
+   + `respondToTool` mutation (atomowo `assistantTurnStarted` + `userResponded`)
+5. tool_result row dociera liveQuery → optimistic entry GC, DB wygrywa
+6. `aiResumeListener` → kolejny turn streamuje — a answered tool pozostaje
+   w answer-view, bo derywacja zawsze widzi resultMap z DB (nie ma guardu
+   "w trakcie streamowania")
 
 ---
 
@@ -170,7 +217,7 @@ Po `streamComplete` z interactive tool calls:
 
 ```ts
 startStream(messageId)              // idempotent. Listener woła przed publish
-publish(messageId, event)           // mutuje currentBlocks + broadcast SSE
+publish(messageId, event)           // applyStreamEvent + broadcast SSE
 subscribe(messageId): {             // route handler. null → 410
   stream, currentBlocks
 } | null
@@ -186,26 +233,46 @@ getCurrentBlocks(messageId)         // debug/test, readonly
 
 ## Key invariants
 
+**Derywacja (klient):**
+- Timeline jest CZYSTĄ funkcją `(history, overlays, optimistic) → items`.
+  **Nigdy nie pisz do timeline'u imperatywnie** — każdy merge dwóch kanałów
+  przez mutowalny stan + flagę trybu kończył się produkcyjnymi race'ami
+  (watchdogi/backstopy/nonce w git log to historia tych prób).
+- SSE reader aktualizuje WYŁĄCZNIE overlay (nigdy timeline) i robi to
+  wyłącznie przez `applyStreamEvent`.
+- Klucze itemów (`${msgId}_t${n}`, `toolCallId`) są IDENTYCZNE dla overlaya
+  i finalnych blocks — przejście stream→DB nie remountuje elementów.
+- Stale overlay dla zamkniętego rowa jest ignorowany przez derywację
+  (GC w hooku to optymalizacja, nie poprawność).
+
 **Live wartość:**
 - `currentBlocks` w stream-registry jest jedynym źródłem prawdy dla treści
-  in-progress assistanta
-- `partialBlocks`/`partialLastSeq` **NIE ISTNIEJĄ** — jeśli pojawi się PR
-  dodający je, odrzuć
+  in-progress assistanta; jedyna semantyka akumulacji to `applyStreamEvent`
+  (`blocks-reducer.ts`) — zmiana TYLKO tam, inaczej klient i serwer się rozjadą
+- inwariant reconnectu: snapshot w punkcie K + replay od K == pełny replay
+  (test w `blocks-reducer.test.ts`)
+- `partialBlocks`/`partialLastSeq`/sekwencery **NIE ISTNIEJĄ** — `init`
+  snapshot załatwia reconnect; jeśli pojawi się PR dodający je, odrzuć
 
 **DB:**
 - Assistant row z `isGenerating=true` ma `blocks=undefined`
 - Po `assistantTurnCompleted` row ma `isGenerating=false` + `blocks` final
+  + ewentualny `error` — **atomowo, w jednym rzędzie** (na tym stoi cała
+  derywacja: klient nigdy nie zobaczy flipa bez finalnej treści)
 - Treść NIGDY nie ląduje w DB chunk po chunku
+- `interrupted=true` ustawia wyłącznie `generationInterrupted` (lazy repair
+  w route przy 410, próg wieku 10 s)
 
 **Stream lifecycle:**
-- `startStream(messageId)` PRZED pierwszym `publish` (listener gwarantuje)
+- `startStream(messageId)` PRZED pierwszym `publish` (listener gwarantuje,
+  synchronicznie przed 1. awaitem)
 - `finalize(messageId)` PO `completeAssistantTurn` (DB → in-memory order)
 - Każda iteracja generation loop'a → osobny `messageId` → osobny stream
 
 **Subscribe:**
 - Pierwszy event po `subscribe()` to ZAWSZE `init`
-- `subscribe()` zwraca `null` (→ 410 HTTP) **tylko gdy** stream nie istnieje
-  w mapie (poza grace window). Klient interpretuje 410 jako "interrupted".
+- `subscribe()` zwraca `null` (→ 410) **tylko gdy** stream nie istnieje
+  w mapie (poza grace window)
 
 ---
 
@@ -213,18 +280,9 @@ getCurrentBlocks(messageId)         // debug/test, readonly
 
 **`assistantTurnStarted` emit'owany PRZED `messageSent`/`userResponded`/
 `retryRequested` w jednej mutacji.** Powód: async listener reaguje na
-to drugie i potrzebuje, żeby assistant row już istniał w DB. Patrz komentarz
-w `sendMessage` mutation.
-
-**`historySig` w chat-component zależy od `_id:isGenerating:blocks:contentLen`.**
-Nie dodawaj tu pól typu `updatedAt` — useEffect refireuje dla każdego DB
-update, ale rebuild timeline nie może się fire'ować w trakcie streamingu
-(reset bubble caret). Strategia: rebuild fire tylko gdy `isStreaming === false`,
-SSE flippuje to dopiero w `done`.
-
-**`activeGeneratingMessageId` derived z `historyData` + `interruptedIds`.**
-Jeśli zmieniasz logikę detekcji "który row trzeba subskrybować", trzymaj
-ją w tym `useMemo` — auto-subscribe effect odpali się sam.
+to drugie i potrzebuje, żeby assistant row już istniał w DB. Konsekwencja:
+placeholder ma wcześniejszy `createdAt` niż trigger — dlatego istnieje
+fix-up w `ordering.ts`. Zmieniasz jedno → sprawdź drugie.
 
 **`buildHistory` w listenerze pomija `assistant` rows z `isGenerating=true
 && !blocks`.** Czyli interrupted rows (przed retryRequested projection)
@@ -232,19 +290,35 @@ oraz fresh rows w trakcie generacji nie trafiają do LLM history. Po retry
 fresh row też jest skip'owany — historia kończy się na ostatniej user
 message, LLM kontynuuje od niej.
 
-**Stream-registry trzyma `toolCallsById` Map.** `publish("tool_call_pending")`
-tworzy block w `currentBlocks` ORAZ wpis w mapie. `tool_call_arguments_complete`
-update'uje args na tym samym block'u. Jeśli zmieniasz strukturę blocks
-asystenta, oba miejsca muszą być spójne.
-
 **Server-tool execution loop NIE używa stream-registry.** Po `finalize` dla
-tury z tool_calls, kolejne `publish` byłyby no-opem. Server tool results
-trafiają do klienta przez aggregate query update (`saveToolResult` → tool_result
-row w DB). To **świadome** — następna tura ma własny stream.
-
-**Brak retencji buforów eventów.** Klient który podłączy się 6s po `finalize`
-dostanie 410. Brak `?afterSeq`, brak replay. Po `done` klient ma final
-blocks z DB i nie potrzebuje SSE.
+tury z tool_calls kolejne `publish` byłyby no-opem. Server tool results
+trafiają do klienta przez liveQuery (`saveToolResult` → tool_result row).
+To **świadome** — następna tura ma własny stream, a derywacja i tak czyta
+wyniki tooli z DB.
+
+**`queueMicrotask` w pętli readera SSE (use-assistant-overlays).** NIE
+zamieniaj na `setTimeout(0)`: Chrome throttluje timeouty w kartach w tle
+do ≥1 s — pętla zamienia się w 1-event/s freeze. Microtaski nie są
+throttlowane.
+
+**Brak retencji buforów eventów.** Klient, który podłączy się 6 s po
+`finalize`, dostanie 410. Brak `?afterSeq`, brak replay. Po zamknięciu turnu
+klient ma final blocks z DB i nie potrzebuje SSE; 410 dla świeżego rowa
+obsługuje retry z backoffem + lazy repair.
+
+**Pola tekstowe z JSON-em (`blocks`, `content`) mają DWA kształty.**
+W świeżym in-memory store to stringi, ale adapter Postgresa auto-parsuje
+kolumny tekstowe wyglądające jak JSON (`deserializeValue`) — po hydracji
+store'a z bazy (restart serwera) te same pola przychodzą jako gotowe
+tablice/obiekty, również do klienta przez liveQuery. Każde miejsce czytające
+`msg.blocks` / `msg.content` musi tolerować oba kształty (`parseBlocks` w
+derive-timeline, `buildHistory` w listenerze). Regresja "po odświeżeniu
+znikają wiadomości asystenta" brała się dokładnie stąd.
+
+**Reguła busy ma staleness cutoff.** Klauzule "tool bez wyniku" i "świeży
+tool_result" wygasają po 120 s braku aktywności w DB — celowo: lepszy
+przedwcześnie aktywny input (zachowanie sprzed redesignu) niż chat
+zablokowany na zawsze po crashu listenera.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-chat",
   "type": "module",
-  "version": "0.7.20",
+  "version": "0.7.21",
   "private": false,
   "description": "Chat module with AI integration for Arc framework",
   "main": "./src/index.ts",
@@ -10,12 +10,12 @@
     "type-check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.7.20",
-    "@arcote.tech/arc-ai": "^0.7.20",
-    "@arcote.tech/arc-ai-voice": "^0.7.20",
-    "@arcote.tech/arc-auth": "^0.7.20",
-    "@arcote.tech/arc-ds": "^0.7.20",
-    "@arcote.tech/platform": "^0.7.20",
+    "@arcote.tech/arc": "^0.7.21",
+    "@arcote.tech/arc-ai": "^0.7.21",
+    "@arcote.tech/arc-ai-voice": "^0.7.21",
+    "@arcote.tech/arc-auth": "^0.7.21",
+    "@arcote.tech/arc-ds": "^0.7.21",
+    "@arcote.tech/platform": "^0.7.21",
     "lucide-react": ">=0.400.0",
     "react": ">=18.0.0",
     "typescript": "^5.0.0"

package/src/aggregates/message.ts

@@ -77,6 +77,19 @@ export const createMessageAggregate = <
      */
     previousResponseId: string().optional(),
     isGenerating: boolean().optional(),
+    /**
+     * Assistant rows: błąd generacji (provider error / wyjątek listenera).
+     * Persystowany żeby przeżył F5 i reconnect — SSE `error` event jest
+     * tylko ulotnym sygnałem advisory.
+     */
+    error: string().optional(),
+    /**
+     * Assistant rows: generacja przerwana bez wyniku (restart serwera
+     * mid-stream). Ustawiane przez `generationInterrupted` (lazy repair w
+     * stream route przy 410). Trwałe i cross-client — UI renderuje
+     * "interrupted" + Retry z samego stanu DB.
+     */
+    interrupted: boolean().optional(),
     usage: string().optional(),
     createdAt: date(),
   })
@@ -166,7 +179,27 @@ export const createMessageAggregate = <
           blocks: p.blocks,
           previousResponseId: p.previousResponseId,
           usage: p.usage,
+          error: p.error,
+          isGenerating: false,
+        } as any);
+      },
+    )
+
+    // ─── generationInterrupted — orphaned turn marked as interrupted ─
+    // Lazy repair: serwer zrestartował się mid-stream → in-memory stream
+    // zniknął, a assistant row wisi z `isGenerating=true` na zawsze. Stream
+    // route emituje ten event przy 410 dla wystarczająco starego rowa.
+    // Dzięki temu "interrupted" jest trwałe (przeżywa F5) i cross-client,
+    // a UI nie potrzebuje lokalnego stanu interruptedIds.
+    .publicEvent(
+      "generationInterrupted",
+      {
+        messageId,
+      },
+      async (ctx, event) => {
+        await ctx.modify(event.payload.messageId, {
           isGenerating: false,
+          interrupted: true,
         } as any);
       },
     )
@@ -438,7 +471,13 @@ export const createMessageAggregate = <
           if (!interrupted) {
             throw new Error("retryGeneration: message not found");
           }
-          if ((interrupted as any).role !== "assistant" || !(interrupted as any).isGenerating) {
+          // Akceptujemy oba stany przerwania: `isGenerating=true` (klient
+          // widzi 410 zanim lazy repair przeszedł) oraz `interrupted=true`
+          // (row już naprawiony przez `generationInterrupted`).
+          if (
+            (interrupted as any).role !== "assistant" ||
+            (!(interrupted as any).isGenerating && !(interrupted as any).interrupted)
+          ) {
             throw new Error("retryGeneration: row is not an interrupted assistant turn");
           }
 
@@ -467,6 +506,40 @@ export const createMessageAggregate = <
       ),
     )
 
+    // ─── markInterrupted — lazy repair of an orphaned generating row ─
+    // Wołane przez stream route gdy `subscribe()` zwraca null (410), a row
+    // w DB nadal ma `isGenerating=true`. No-op (ok:false) zamiast wyjątku,
+    // bo route woła to przy KAŻDYM 410 — w tym podczas niewinnego wyścigu
+    // ze świeżym startem turnu (klient retry'uje 410 z backoffem zanim
+    // listener zdąży wywołać startStream). Stąd próg wieku rowa: świeże
+    // rowy zostawiamy w spokoju, naprawiamy tylko sieroty po restarcie.
+    .mutateMethod(
+      "markInterrupted",
+      (fn) => fn.withParams({
+        messageId,
+      }).handle(
+        ONLY_SERVER &&
+        (async (ctx, params) => {
+          const MIN_ORPHAN_AGE_MS = 10_000;
+          const row = await ctx.$query.findOne({
+            where: { _id: params.messageId },
+          });
+          if (!row) return { ok: false };
+          const r = row as any;
+          if (r.role !== "assistant" || !r.isGenerating || r.interrupted) {
+            return { ok: false };
+          }
+          const age = Date.now() - new Date(r.createdAt).getTime();
+          if (age < MIN_ORPHAN_AGE_MS) return { ok: false };
+
+          await ctx.generationInterrupted.emit({
+            messageId: params.messageId,
+          });
+          return { ok: true };
+        }),
+      ),
+    )
+
     // ─── startStage — initiate stage with a default priming prompt ─
     // Stored as role="system" so the UI timeline hides it, but the AI
     // generation listener still picks it up as a conversational turn
@@ -552,12 +625,20 @@ export const createMessageAggregate = <
     )
 
     // ─── getByScope ─────────────────────────────────────────────
+    // Jawny orderBy — bez niego Postgres zwraca kolejność heapu, którą
+    // UPDATE (np. completeAssistantTurn) fizycznie przemieszcza, a klient
+    // renderuje dokładnie w kolejności serwera. Tie-break w ramach tej
+    // samej sekundy (mutacje emitujące kilka rzędów naraz) robi derywacja
+    // timeline'u po stronie klienta (rola, potem _id).
     .clientQuery(
       "getByScope",
       (fn) => fn
         .withParams({ scopeId: string() })
         .handle(async (ctx, params) =>
-          ctx.$query.find({ where: { scopeId: params.scopeId } }),
+          ctx.$query.find({
+            where: { scopeId: params.scopeId },
+            orderBy: { createdAt: "asc" },
+          }),
         ),
     )
 

package/src/chat-builder.ts

@@ -420,6 +420,7 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     const streamRoute = createChatStreamRoute({
       name,
       userToken,
+      messageElement: Message,
     });
 
     const elements: ArcContextElement<any>[] = [

package/src/listeners/ai-generation-listener.ts

@@ -16,6 +16,7 @@ import {
   startStream,
   type PublishableEvent,
 } from "../streaming/stream-registry";
+import { orderMessages } from "../ordering";
 
 // ─── Config ─────────────────────────────────────────────────────
 
@@ -99,7 +100,10 @@ function buildHistory(
 ): ConversationTurn[] {
   const turns: ConversationTurn[] = [];
 
-  for (const msg of messages) {
+  // Kanoniczna kolejność konwersacji — patrz src/ordering.ts. Bez tego
+  // pre-utworzony assistant placeholder (emitowany PRZED user rowem) po
+  // ukończeniu turnu lądowałby w historii LLM przed pytaniem użytkownika.
+  for (const msg of orderMessages(messages)) {
     if (msg._id === skipMessageId) continue;
 
     // System messages are developer-injected priming prompts (stage welcome,
@@ -117,8 +121,14 @@ function buildHistory(
 
     if (msg.role === "assistant") {
       if (msg.isGenerating && !msg.blocks) continue;
+      // `blocks` to string w świeżym in-memory store, ale po hydracji
+      // z Postgresa adapter zwraca JUŻ sparsowaną tablicę (deserializeValue
+      // auto-parsuje text wyglądający jak JSON). Bez tolerancji obu kształtów
+      // historia LLM traciła całą treść asystenta po restarcie serwera.
       let blocks: AssistantContentBlock[] = [];
-      if (typeof msg.blocks === "string" && msg.blocks.length > 0) {
+      if (Array.isArray(msg.blocks)) {
+        blocks = msg.blocks;
+      } else if (typeof msg.blocks === "string" && msg.blocks.length > 0) {
         try {
           blocks = JSON.parse(msg.blocks);
         } catch {
@@ -138,7 +148,12 @@ function buildHistory(
         role: "tool_result",
         toolCallId: msg.toolCallId,
         name: msg.toolName,
-        content: msg.content ?? "",
+        // Tolerancja kształtu jak przy blocks — JSON-owy content wraca
+        // z Postgresa sparsowany, a provider oczekuje stringa.
+        content:
+          typeof msg.content === "string"
+            ? msg.content
+            : JSON.stringify(msg.content ?? ""),
       });
     }
   }