Cursor rule

1---
2globs: packages/core/src/**/*
3---
4 
5## Core (packages/core)
6 
7- **Role**: Event-driven "kernel" containing domain logic, database access, and message processing. It must stay UI-agnostic and transport-agnostic.
8- **Design rules**:
9  - New domain behavior belongs here first, then is exposed to clients via events.
10  - Separate **event handlers** from **services**:
11    - Event handlers translate `ToCoreEvent` / `FromCoreEvent` into service calls.
12    - Services encapsulate business logic, DB queries, and Telegram API access.
13 
14### Events & CoreContext
15 
16- Keep `CoreContext` the single point of coordination:
17  - One instance per session in server mode or browser mode.
18  - All cross-module collaboration flows through its event emitter and helpers.
19- When introducing new events:
20  - Add them to the typed `ToCoreEvent` / `FromCoreEvent` maps.
21  - Wire them through:
22    - `packages/core/src/event-handlers`
23    - `packages/client` adapters and event handler maps
24    - `@tg-search/server/types` for WS mode
25  - Provide **clear names** in `<domain>:<action>` form.
26 
27### Database & Drizzle
28 
29- Use `initDrizzle` as the only entry point for DB initialization:
30  - It must support both PostgreSQL and PGlite via the `DatabaseType` enum and `Config.database`.
31  - Avoid leaking raw `pg` or PGlite APIs outside dedicated DB modules (`pg.ts`, `pglite*.ts`).
32- For queries:
33  - Prefer Drizzle ORM APIs for type safety and portability.
34  - Reserve raw SQL for performance-critical paths and keep them well-documented.
35- When adding migrations:
36  - Update TypeScript schemas/models first.
37  - Use `drizzle-kit` to generate SQL migrations and avoid manual edits except for surgical fixes.
38 
39### Message Resolvers & Pipelines
40 
41- Resolvers under `src/message-resolvers` must:
42  - Treat messages as **streams**, not immutable global state.
43  - Be **idempotent**: re-running on the same input should not corrupt data.
44  - Rely on message IDs for ordering and deduplication.
45- Expensive operations (embeddings, link resolution) should:
46  - Cache results whenever reasonable.
47  - Defer to background-like processing while exposing progress events to clients.
48 
49### Error Handling & Logging
50 
51- Use `ctx.withError(error, description)` for all unexpected failures inside core services and handlers.
52- Emit errors as events suitable for user-facing handling:
53  - Avoid leaking raw Telegram or DB internals into error payloads.
54  - Prefer structured error codes + contextual fields.
55- Use `@guiiai/logg` consistently:
56  - Attach domain-specific fields (chat/message IDs, operation names) instead of dumping entire payloads.
57 
58