# Roadmap: workspace/chat/files + artifacts

## Цель

Следующий продуктовый приоритет для `master-service`:
1. управление `workspace` / `chat` / `chat files`
2. хранение и выдача `artifacts`

Идея этапа: превратить текущий sandbox MVP в storage-centric control plane, где sandbox работает поверх явных пользовательских данных, а не только поверх `chat_id`.

## Что считаем в scope этого roadmap

- workspace metadata
- chat metadata и chat directories
- `history.md` рядом с чатом
- upload/list/download/delete/clear для chat files
- quota / usage accounting
- artifact metadata
- object storage adapter для artifacts
- delivery / mark-for-delete flow для artifacts
- интеграция storage model с текущим sandbox lifecycle

## Что пока вне scope

- полноценный auth/access control
- access lease и WebSocket handoff
- multi-node orchestration как отдельный эпик
- full retention engine для workspace/account lifecycle
- внешние messenger integrations

## Зафиксированные продуктовые решения

- trusted caller передает `user_id: UUID`
- в v1 один `Workspace` на одного `User`
- metadata adapters пока делаем `in-memory`
- chat history в v1 хранится в `history.md`
- chat files отдаем через master: metadata API + download endpoint
- soft quota 10 GB блокирует quota-relevant write-path операции, но не делает hard reservation
- chat create сам по себе не блокируется quota check, пока не появляется значимый file/artifact payload
- delete в v1 — hard delete; chat delete запрещен при active sandbox
- artifact delivery подтверждается явным ack
- artifact blob отдается через presigned URL, metadata — через master
- object storage layout: один bucket на environment + prefixes
- artifact states: `created`, `stored`, `delivered`, `delivery_failed`, `marked_for_delete`, `deleted`
- artifact retention: после ack -> `marked_for_delete` -> async cleanup; без ack действует отдельный TTL

## Принципы выполнения

- Clean Architecture и dependency direction сохраняются
- filesystem и object storage живут только во внешних adapter/repository слоях
- `domain/` и `usecase/` не знают про FastAPI, Docker, OpenTelemetry, env
- один delivery slice = одна атомарная задача = один commit
- архитектурные развилки сначала фиксируются кратким ADR-lite в `docs/`

## Легенда исполнителей

- `primary-agent` — архитектура, ADR, domain/contracts, финальная сборка решений
- `junior` — простые in-memory adapters и базовые unit-level задачи
- `junior+opus` — usecase/adapter/API slices со средним уровнем связности
- `test-engineer` — regression и integration test packs
- `code-reviewer` — review-only этапы

---

## Phase 0. Design checkpoints

### R00. ADR: storage source of truth
- **Рекомендуемый исполнитель:** `primary-agent`
- **Зачем:** определить, что является source of truth для `Workspace`, `Chat`, `ChatFile`, `Artifact`
- **Нужно решить:** как устроен in-memory-first этап, как metadata связаны с filesystem paths, как sandbox получает path текущего chat
- **Выход:** ADR-lite + список сущностей и ownership boundaries

### R01. ADR: artifact lifecycle
- **Рекомендуемый исполнитель:** `primary-agent`
- **Зачем:** зафиксировать states и delivery contract для artifact flow
- **Нужно решить:** `created -> stored -> delivered -> delivery_failed -> marked_for_delete -> deleted`
- **Выход:** ADR-lite + минимальный state machine

### R02. ADR: chat history policy
- **Рекомендуемый исполнитель:** `primary-agent`
- **Зачем:** зафиксировать, как `history.md` соотносится с metadata чата
- **Нужно решить:** кто создает файл, кто пишет initial header, как читать/обновлять metadata без парсинга файла
- **Выход:** ADR-lite + правила sync между metadata и history file

---

## Phase 1. Foundation for workspace/chat/file domain

### R10. Domain model for user storage
- **Рекомендуемый исполнитель:** `primary-agent`
- **Scope:** `Workspace`, `Chat`, `ChatFile`, domain errors
- **Layer:** `domain/`
- **Выход:** минимальные сущности, value objects, ошибки конфликтов/не-найдено/квота
- **Depends on:** `R00`, `R02`

### R11. Usecase ports for storage and metadata
- **Рекомендуемый исполнитель:** `primary-agent`
- **Scope:** repository/storage interfaces для workspace/chat/chat-file/history/quota
- **Layer:** `usecase/`
- **Выход:** порты для metadata repo, file storage, usage reader, id generator, clock и trusted caller identity input
- **Depends on:** `R10`

### R12. In-memory metadata adapter foundation
- **Рекомендуемый исполнитель:** `junior`
- **Scope:** первая metadata implementation для workspace/chat/chat-file/artifact metadata
- **Layer:** `repository/`
- **Примечание:** это промежуточный этап; durable DB идет отдельным follow-up после storage/product slice
- **Выход:** in-memory CRUD для workspace/chat/chat-file/artifact metadata
- **Depends on:** `R11`

### R13. Filesystem storage adapter foundation
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** storage adapter для chat directories, `history.md`, uploads и file metadata extraction
- **Layer:** `adapter/` или `repository/` в зависимости от финальной границы
- **Выход:** операции create/list/delete/read metadata для chat files, history path management и download path resolution
- **Depends on:** `R11`

### R14. Sandbox integration with chat metadata
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** перестать считать `chat_id` единственным источником layout, использовать metadata-backed chat path
- **Layer:** `usecase/` + outer adapters
- **Выход:** sandbox mounts current chat directory, созданную через storage model
- **Depends on:** `R12`, `R13`

---

## Phase 2. Workspace and chat API

### R20. Create workspace on first touch
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** auto-create workspace при первом запросе на user storage
- **API:** внутренний usecase + при необходимости явная HTTP ручка
- **Выход:** гарантированный `Workspace` для пользователя по `user_id`
- **Depends on:** `R12`

### R21. Chat CRUD
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** create/get/list/delete chat
- **API:** versioned HTTP under `/api/v1`
- **Выход:** first-class chat metadata вместо implicit-only `chat_id`
- **Depends on:** `R20`, `R12`, `R13`

### R22. History file lifecycle
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** создавать `history.md` вместе с chat directory, читать и обновлять metadata
- **Выход:** первый стабильный contract для истории чата в filesystem
- **Depends on:** `R21`, `R13`

### R23. Chat file upload and file metadata API
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** upload/list/get metadata/delete single file/clear chat files
- **API:** HTTP adapter + schemas
- **Выход:** базовый file management API на chat scope + master download endpoint
- **Depends on:** `R21`, `R13`

### R24. Usage and quota accounting
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** считать storage usage по workspace/chat, мягкая quota 10 GB
- **Выход:** usecases и metrics для current usage; file/artifact write-path reject при превышении soft quota
- **Depends on:** `R23`

### R25. Tests and review for storage slice
- **Рекомендуемый исполнитель:** `test-engineer`
- **Scope:** unit + adapter + HTTP tests, boundary review
- **Выход:** regression coverage для workspace/chat/files
- **Depends on:** `R20`-`R24`

---

## Phase 3. Artifact pipeline

### R30. Artifact domain and metadata model
- **Рекомендуемый исполнитель:** `primary-agent`
- **Scope:** `Artifact` entity, states, delivery metadata, linkage to `user/chat`
- **Layer:** `domain/`, `usecase/`
- **Выход:** базовая artifact model + errors + repository ports для in-memory metadata stage
- **Depends on:** `R01`, `R12`

### R31. Object storage adapter
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** S3-compatible adapter for artifact blobs
- **Layer:** outer `adapter/` or `repository/`
- **Выход:** upload/get/delete primitives behind interface + presigned URL support
- **Depends on:** `R30`

### R32. Artifact registration and upload flow
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** usecase, который связывает metadata и object storage
- **Выход:** artifact можно зарегистрировать, сохранить blob и получить external reference
- **Depends on:** `R30`, `R31`

### R33. Artifact list/get metadata API
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** list artifacts by chat/user, get artifact metadata/status
- **Выход:** внешний API для управления artifact metadata и выдачи presigned download references
- **Depends on:** `R32`

### R34. Delivery acknowledgement flow
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** mark artifact as delivered / delivery_failed
- **Выход:** подтвержденный delivery state через explicit ack и база для retention
- **Depends on:** `R32`

### R35. Artifact delete / mark-for-delete policy
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** policy-driven cleanup hooks после delivery confirmation или TTL
- **Выход:** artifact lifecycle завершен, metadata и blob cleanup согласованы, `marked_for_delete` используется как переходное состояние
- **Depends on:** `R34`

### R36. Tests and review for artifact slice
- **Рекомендуемый исполнитель:** `test-engineer`
- **Scope:** unit + adapter + HTTP tests, boundary review
- **Выход:** regression coverage для artifact lifecycle и object storage integration
- **Depends on:** `R30`-`R35`

---

## Phase 4. Cross-slice hardening

### R40. Observability for storage usage and artifacts
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** metrics по usage/quota, artifact upload latency, artifact errors
- **Выход:** dashboards and alerts for storage-centric flows
- **Depends on:** `R24`, `R32`, `R35`

### R41. Cleanup safety rules
- **Рекомендуемый исполнитель:** `junior+opus`
- **Scope:** не удалять chat files/artifacts, если есть активный sandbox или незавершенный delivery flow
- **Выход:** safe cleanup invariants
- **Depends on:** `R24`, `R35`

### R42. Docs refresh
- **Рекомендуемый исполнитель:** `primary-agent`
- **Scope:** README, ADRs, API docs, operator notes
- **Выход:** актуальная документация для storage and artifact flows
- **Depends on:** все предыдущие slices

---

## Рекомендуемый порядок выполнения

### Priority A — workspace/chat/files
1. `R00` `R02`
2. `R10` `R11`
3. `R12` `R13`
4. `R20` `R21` `R22`
5. `R23` `R24`
6. `R14` `R25`

### Priority B — artifacts
1. `R01`
2. `R30` `R31`
3. `R32` `R33`
4. `R34` `R35`
5. `R36`

### Future follow-up after Priority A+B
1. durable metadata repository instead of in-memory adapters
2. auth/access control and access lease
3. multi-node storage/session coordination

### Priority C — hardening
1. `R40`
2. `R41`
3. `R42`

---

## Что даст этот roadmap

После выполнения Priority A + B сервис сможет:
- создавать и хранить workspace/chat metadata
- управлять файлами пользователя в chat scope
- хранить историю чата в предсказуемом layout
- поднимать sandbox поверх first-class chat storage
- хранить artifact metadata и blob отдельно
- отдавать artifact metadata наружу и подтверждать доставку

То есть `master-service` станет не только sandbox orchestrator, но и полноценным control-plane для user storage и artifact lifecycle.