Surfaces_team/surfaces
4
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

docs(05-03): complete shared-volume attachment hardening plan

Browse source 
- add 05-03 summary with task commits and verification details
- update roadmap and state for completed Phase 05 plan 03
This commit is contained in:
Mikhail Putilovskij 2026-04-28 01:07:35 +03:00
parent a75b26a1cb
commit 6693d72cbd
3 changed files with 145 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

23
.planning/ROADMAP.md
View file

@ -64,6 +64,29 @@ Plans:
---
### Phase 05: MVP Deployment
**Goal:** Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru без потери Space+rooms UX: закрепить per-room `platform_chat_id`, реальный `!clear`, reconciliation, file transfer через shared volume и разделение prod/fullstack compose.
**Depends on:** Phase 4
**Plans:** 1/4 plans executed
Plans:
- [ ] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync
- [ ] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics
- [x] 05-03-PLAN.md — Shared-volume attachment path hardening for `/agents` deployment
- [ ] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs
**Deliverables:**
- Space+rooms onboarding remains the primary Matrix UX
- Per-room `platform_chat_id` provides true context isolation and `!clear`
- Reconciliation restores room metadata and routing after restart
- File transfer uses shared `/agents/` volume with room-safe behavior
- `docker-compose.prod.yml` is bot-only handoff; `docker-compose.fullstack.yml` is for internal E2E testing
---
### Phase 3: Production Hardening
**Goal:** Подготовить боты к реальному деплою — конфиг, логирование, мониторинг, обработка ошибок.

38
.planning/STATE.md
View file

@ -2,14 +2,13 @@
gsd_state_version: 1.0
milestone: v1.0
milestone_name: — Production-ready surfaces
status: Phase 04 complete — deployment architecture clarified, Phase 05 ready to plan
last_updated: "2026-04-27T18:44:51Z"
status: Executing Phase 05
last_updated: "2026-04-27T22:06:43.419Z"
progress:
total_phases: 5
total_phases: 6
completed_phases: 2
total_plans: 12
completed_plans: 9
percent: 75
total_plans: 16
completed_plans: 10
---
# State
@ -19,21 +18,18 @@ progress:
See: .planning/PROJECT.md (updated 2026-04-02)
**Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра
**Current focus:** Phase 04 multi-agent routing follow-up fully implemented; ready for live validation or Phase 05 planning
**Current focus:** Phase 05 — mvp-deployment
## Current Phase
**Phase 4** implementation complete: Matrix MVP + multi-agent routing
**Phase 05** in progress: MVP deployment hardening
All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-direct-agent-prototype`:
Plan `05-03` is complete. Shared-volume attachment handling now keeps Matrix file references room-safe on disk and relative across the `/agents` deployment boundary.
- `7627012` / `242f4aa` / `9ccba16` — agent registry loader, RoutedPlatformClient facade, fail-fast on missing registry in real mode
- `a65227e` — dispatch chat_id contract alignment
- `74cf028` — `!agent` command, `selected_agent_id` persistence, unbound-room binding on first selection
- `7623039` — attachment normalization in core message handler
- `e733119` — stale room blocking, `agent_id` binding on `!new`, durable restart state tests
- `cafb0ec` — failing regressions for `/agents` workspace paths and send-file normalization
- `9a03160` — runtime normalization of `/workspace` and `/agents` absolute paths back to relative `workspace_path` values
135 Matrix tests pass. The branch is ready for review and merge.
Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`.
## Decisions
@ -60,6 +56,9 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d
- [Phase 04 follow-up]: agent_routing_enabled flag on MatrixRuntime activates stale-room check only in real multi-agent mode (RoutedPlatformClient).
- [Phase 04 follow-up]: !new binds agent_id at room creation time using selected_agent_id from user metadata.
- [Phase 04 follow-up]: platform_chat_seq (PLATFORM_CHAT_SEQ_KEY) is stored in SQLiteStore and survives restart — confirmed by test.
- [Phase 05 reset]: Discard the single-chat / DM-first deployment direction. Replan around Space+rooms, per-room `platform_chat_id`, real `!clear`, reconciliation, and split prod/fullstack compose artifacts.
- [Phase 05]: Keep adapter/matrix/files.py as the sole path builder; sdk/real.py only normalizes shared-volume attachment references.
- [Phase 05]: Normalize /workspace and /agents absolute file paths back to relative workspace_path values before agent transport and Matrix file rendering.
## Blockers
@ -72,7 +71,7 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d
- Phase 01.1 inserted after Phase 01: Matrix restart reconciliation and dev reset workflow (URGENT)
- Phase 4 added: Matrix MVP: shared agent context and context management command
- Phase 04 follow-up added inline: multi-agent routing (RoutedPlatformClient, !agent, stale room blocking, restart persistence)
- New platform signal: upcoming proper `chat_id` support should enable file-level context separation and stronger context management in a future follow-up phase.
- Phase 05 reset on 2026-04-28: erroneous single-chat deployment artifacts were removed before fresh planning.
## Performance Metrics
@ -88,9 +87,10 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d
| 04 | 02 | 1 session | 2 commits + summary | 8 | 2026-04-17 |
| 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 |
| 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 |
| 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z |
## Session
- Last session: 2026-04-24T14:10:00Z
- Stopped at: Deployment architecture clarified with platform team; docs/deploy-architecture.md written; Phase 05 ready to plan
- Resume file: .planning/.continue-here.md
- Last session: 2026-04-27T22:06:43Z
- Stopped at: Completed 05-03-PLAN.md
- Resume file: .planning/phases/05-mvp-deployment/.continue-here.md

103
.planning/phases/05-mvp-deployment/05-03-SUMMARY.md Normal file
View file

@ -0,0 +1,103 @@
---
phase: 05-mvp-deployment
plan: 03
subsystem: infra
tags: [matrix, attachments, shared-volume, agents, pytest]
requires:
- phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
provides: direct AgentApi integration and Matrix outgoing file rendering
provides:
- shared-volume attachment path regressions for /agents deployment
- relative workspace-path normalization for upstream attachment transport
- send-file event normalization for Matrix outbound file rendering
affects: [matrix, deployment, shared-volume, file-transfer]
tech-stack:
added: []
patterns: [relative workspace_path transport, shared-volume root normalization]
key-files:
created: []
modified:
- tests/adapter/matrix/test_files.py
- tests/platform/test_real.py
- sdk/real.py
key-decisions:
- "Keep adapter/matrix/files.py as the only path-construction source; sdk/real.py only normalizes attachment references crossing the shared-volume boundary."
- "Normalize both /workspace and /agents absolute paths back to relative workspace paths before forwarding to the agent API or rendering Matrix send-file events."
patterns-established:
- "Matrix attachment transport stays relative even when the bot sees absolute shared-volume paths."
- "Agent-emitted file paths are rendered back to Matrix without HTTP proxy shims or inline blobs."
requirements-completed: [PH05-04]
duration: 3 min
completed: 2026-04-27
---
# Phase 05 Plan 03: Shared-volume attachment path hardening Summary
**Room-safe Matrix inbox paths and relative shared-volume attachment normalization for `/agents` deployment**
## Performance
- **Duration:** 3 min
- **Started:** 2026-04-27T22:02:34Z
- **Completed:** 2026-04-27T22:05:41Z
- **Tasks:** 2
- **Files modified:** 3
## Accomplishments
- Added regression coverage for room-safe `surfaces/matrix/.../inbox/...` attachment layout under `/agents` workspaces.
- Added explicit tests for `/workspace/...` and `/agents/...` attachment-path normalization on both upstream send and downstream send-file rendering.
- Tightened `RealPlatformClient` so only relative `workspace_path` values are forwarded to the agent API.
## Task Commits
Each task was committed atomically:
1. **Task 1: Add shared-volume file contract tests for `/agents` deployment** - `cafb0ec` (test)
2. **Task 2: Tighten attachment path handling for the shared volume contract** - `9a03160` (fix)
## Files Created/Modified
- `tests/adapter/matrix/test_files.py` - covers room-safe shared-volume inbox paths under an `/agents` workspace root.
- `tests/platform/test_real.py` - covers relative attachment forwarding and send-file normalization for `/workspace` and `/agents` paths.
- `sdk/real.py` - normalizes shared-volume roots before attachments cross the upstream or Matrix rendering boundary.
## Decisions Made
- Kept `adapter/matrix/files.py` unchanged so path construction remains centralized there.
- Reused one normalization helper in `sdk/real.py` for both `_attachment_paths()` and `_attachment_from_send_file_event()` to keep inbound and outbound behavior aligned.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] Adjusted verification to use the project uv environment**
- **Found during:** Task 2 (Tighten attachment path handling for the shared volume contract)
- **Issue:** The plan's raw `pytest` command collected with an interpreter missing `PyYAML`, which blocked `tests/adapter/matrix/test_send_outgoing.py` before runtime assertions could execute.
- **Fix:** Re-ran verification with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest ...`, matching the repo's `CLAUDE.md` guidance and the project `.venv`.
- **Files modified:** None
- **Verification:** `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`
- **Committed in:** None (verification-environment adjustment only)
---
**Total deviations:** 1 auto-fixed (1 blocking)
**Impact on plan:** No scope creep. The deviation only changed the verification entrypoint so the planned test slice could run in the correct environment.
## Issues Encountered
- The ambient `pytest` resolved to a different virtualenv than the project `.venv`, so direct verification was unreliable for dependency-backed Matrix tests.
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- Shared-volume file references now stay relative across inbound bot downloads, agent API attachment transport, and outbound Matrix send-file rendering.
- Phase 05 compose and deployment work can assume the `/agents` contract without adding file proxy infrastructure.
## Self-Check: PASSED
- Found `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md`
- Verified commit `cafb0ec` exists in git history
- Verified commit `9a03160` exists in git history
---
*Phase: 05-mvp-deployment*
*Completed: 2026-04-27*