Cursor rule

1---
2globs: packages/core/src/event-handlers/**, packages/core/src/services/**, packages/client/src/event-handlers/**, packages/client/src/adapters/**, apps/server/src/**
3---
4## Cross-Layer Events & Protocol Design
5 
6- **Scope**: Any change that adds/renames/removes events flowing between:
7  - Vue/Pinia (apps/web)
8  - `packages/client`
9  - `apps/server` WebSocket layer
10  - `packages/core` event handlers & services
11 
12### 1. Before You Add or Change an Event
13 
14- Answer, in your head or in an RFC:
15  - **Where is the bottleneck?** (UX latency? DB load? Telegram API limits?)
16  - **What is the minimal new behavior?** (One sentence, domain language.)
17  - **What is the data flow?** (Component → store → client adapter → WS/core → DB → back.)
18  - **How does this handle failure?**
19    - Core error?
20    - Network loss?
21    - Partial success (e.g. some messages processed)?
22 
23### 2. Event Naming & Payloads
24 
25- Naming:
26  - Use `<domain>:<action>` or `<domain>:<action>:<subaction>`.
27  - Avoid generic verbs like `update`, `done`; always include the domain (`message`, `storage`, `auth`, etc.).
28- Payloads:
29  - Prefer **IDs + small shapes** over dumping full DB rows or Telegram objects.
30  - Do not leak raw internal schemas as event payloads unless they are explicitly part of the public model.
31  - Include enough context to render the UI without requiring a second roundtrip when reasonable.
32 
33### 3. End-to-End Wiring Checklist
34 
35When adding a new event, ensure all of the following are updated **in one change**:
36 
37- **Types & contracts**:
38  - `@tg-search/core` `ToCoreEvent` / `FromCoreEvent`.
39  - `@tg-search/server/types` WS mappings (`WsEventToServer`, `WsEventToClient`).
40  - Client event handler maps in `packages/client`.
41- **Handlers**:
42  - Core event handler under `packages/core/src/event-handlers`.
43  - Service function(s) in `packages/core/src/services`.
44  - Client-side handler that maps `FromCoreEvent` into Pinia state.
45- **UI**:
46  - Minimal component/store changes to actually use the new event.
47 
48### 4. Backwards Compatibility & Refactors
49 
50- Prefer **adding** new events over changing semantics of existing ones.
51- If an event must change:
52  - Keep the old event name working for at least one release where possible.
53  - Introduce a new event name for the new behavior and migrate callers gradually.
54- For refactors across layers (e.g. renaming a domain or action):
55  - Do a **mechanical rename** across types, handlers, and callers in one PR.
56  - Avoid long-lived “mixed” states where some code uses old names and some uses new ones.
57 
58### 5. Errors, Timeouts & Idempotency
59 
60- Treat every event as potentially:
61  - Lost (network issues).
62  - Duplicated (retries).
63  - Delayed (backpressure).
64- Design handlers to be **idempotent** where possible:
65  - Re-applying the same event should not corrupt state.
66  - Use message IDs and versioning to detect duplicates.
67- Error semantics:
68  - Core should emit structured error events with codes and key context, not just strings.
69  - Client should surface user-friendly messages and, where safe, allow retry.
70 
71