121 lines
7.2 KiB
Markdown
121 lines
7.2 KiB
Markdown
# Phase 01.1: Matrix restart reconciliation and dev reset workflow - Context
|
||
|
||
**Gathered:** 2026-04-03
|
||
**Status:** Ready for planning
|
||
|
||
<domain>
|
||
## Phase Boundary
|
||
|
||
Сделать Matrix-адаптер пригодным для повторяемой локальной разработки и ручного QA без ручного “ритуала” удаления БД, выхода из всех комнат и пересоздания пользователя.
|
||
|
||
В scope этой фазы:
|
||
- безопасный restart flow для Matrix-бота после потери локального state
|
||
- reconciliation локального store с уже существующими Matrix rooms / Space
|
||
- отдельный dev reset workflow для controlled clean-room QA
|
||
- диагностируемое поведение при несогласованности local state и server-side Matrix state
|
||
|
||
Вне scope:
|
||
- реальный Lambda SDK
|
||
- новые пользовательские Matrix features
|
||
- E2EE
|
||
- production-grade multi-user migration framework
|
||
|
||
</domain>
|
||
|
||
<decisions>
|
||
## Implementation Decisions
|
||
|
||
### Matrix state lifecycle
|
||
|
||
- **D-01:** Локальный SQLite store больше не должен считаться единственной точкой истины для Matrix runtime в dev workflow.
|
||
- **D-02:** При старте бот должен пытаться восстановить минимально необходимое локальное состояние из уже существующих Matrix rooms / Space, а не требовать full reset.
|
||
- **D-03:** Reconciliation должен восстанавливать как минимум `matrix_user:*`, `matrix_room:*` и missing `chat:{user}:{chat_id}` записи, если серверные комнаты уже существуют.
|
||
- **D-04:** Reconciliation не должен создавать новые Space/rooms, если задача — именно восстановление локального state после рестарта.
|
||
|
||
### Dev restart behavior
|
||
|
||
- **D-05:** Обычный restart бота должен быть основным путём для разработки; удаление `lambda_matrix.db` и `matrix_store` не должно быть обязательным для проверки workflow.
|
||
- **D-06:** Если local state неполон, бот должен либо восстановить его, либо логировать понятную причину, а не падать на командах вроде `!rename`.
|
||
- **D-07:** Несогласованность между `room_meta` и `ChatManager` должна обнаруживаться и устраняться автоматически на startup или при первом обращении.
|
||
|
||
### Dev reset workflow
|
||
|
||
- **D-08:** Нужен отдельный dev-only reset tool/script для controlled QA, вместо ручного набора shell-команд.
|
||
- **D-09:** Reset workflow должен как минимум поддерживать `local-only` reset: удаление `lambda_matrix.db` и `matrix_store` с понятной инструкцией, что делать с server-side Matrix rooms.
|
||
- **D-10:** Если full server-side cleanup не автоматизируется в этой фазе, tool должен явно печатать, какие ручные шаги обязательны в Matrix client.
|
||
|
||
### The agent's Discretion
|
||
|
||
- Точное место вызова reconciliation в startup flow
|
||
- Внутренняя структура helper-модуля (`bootstrap.py`, `reconcile.py` или аналог)
|
||
- Формат dev reset script и уровень автоматизации server-side cleanup
|
||
- Детали debug-logging и dry-run режима, если они помогают без раздувания scope
|
||
|
||
</decisions>
|
||
|
||
<specifics>
|
||
## Specific Ideas
|
||
|
||
- Главный критерий: после обычного restart бот не должен ломаться только потому, что local DB была сброшена или частично потеряна.
|
||
- Reset workflow должен быть явным и repeatable, а не завязанным на память разработчика.
|
||
- Нужно различать две ситуации:
|
||
- broken because code is wrong
|
||
- broken because local dev state was deliberately reset and requires reconciliation
|
||
|
||
</specifics>
|
||
|
||
<canonical_refs>
|
||
## Canonical References
|
||
|
||
**Downstream agents MUST read these before planning or implementing.**
|
||
|
||
### Matrix phase artifacts
|
||
- `.planning/phases/01-matrix-qa-polish/01-CONTEXT.md` — locked Matrix decisions from Phase 1
|
||
- `.planning/phases/01-matrix-qa-polish/01-VERIFICATION.md` — what Phase 1 already validated and what manual QA still expects
|
||
- `.planning/phases/01-matrix-qa-polish/01-HUMAN-UAT.md` — remaining real-client Matrix checks
|
||
|
||
### Current Matrix runtime
|
||
- `adapter/matrix/bot.py` — startup flow, sync loop, runtime wiring, DB/store env vars
|
||
- `adapter/matrix/store.py` — persisted Matrix metadata and pending confirmation keys
|
||
- `adapter/matrix/room_router.py` — room_id to chat_id resolution and current unregistered fallback
|
||
- `adapter/matrix/handlers/auth.py` — invite bootstrap that creates Space and first chat room
|
||
- `core/chat.py` — `ChatManager` persistence contract that currently breaks when local state is missing
|
||
|
||
### Supporting docs
|
||
- `docs/matrix-prototype.md` — intended Matrix UX and architecture direction
|
||
- `README.md` — current run instructions and existing manual QA/reset habits
|
||
|
||
</canonical_refs>
|
||
|
||
<code_context>
|
||
## Existing Code Insights
|
||
|
||
### Reusable Assets
|
||
- `adapter/matrix/store.py` already persists room/user metadata and is the obvious place to anchor reconciliation inputs.
|
||
- `adapter/matrix/room_router.py` already detects unknown rooms via `unregistered:{room_id}` fallback; this is a useful reconciliation trigger point.
|
||
- `core/chat.py` already has `get_or_create`, `rename`, `archive`, `list_active`; missing chat records can be rebuilt through this API instead of inventing a parallel format.
|
||
|
||
### Established Patterns
|
||
- Matrix runtime uses `SQLiteStore` for adapter-local metadata and `matrix-nio` room callbacks for transport events.
|
||
- Phase 1 already moved Matrix to Space+rooms and command-only confirmations, so this phase must preserve that model rather than reverting to DM-first simplifications.
|
||
|
||
### Integration Points
|
||
- Startup path in `adapter/matrix/bot.py:main()` is the natural place to run reconciliation before `sync_forever`.
|
||
- Invite/bootstrap path in `adapter/matrix/handlers/auth.py` is the existing source of truth for what metadata a healthy first room should have.
|
||
- `ChatManager` records and `matrix_room:*` metadata must stay consistent enough that commands like `!rename`, `!archive`, and `!chats` work after restart.
|
||
|
||
</code_context>
|
||
|
||
<deferred>
|
||
## Deferred Ideas
|
||
|
||
- Full production-grade migration of historical Matrix state across schema versions
|
||
- Automatic server-side deletion/leave for all Matrix rooms and Space during reset, if it requires broader admin semantics
|
||
- Any Phase 2 SDK integration work
|
||
|
||
</deferred>
|
||
|
||
---
|
||
|
||
*Phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow*
|
||
*Context gathered: 2026-04-03*
|