master/tasks/sprint-01-storage-foundation.md

Sprint 01 — storage foundation

Цель спринта

Подготовить первый исполнимый storage slice для workspace / chat / chat files без durable DB и без auth, но с корректными clean-architecture границами.

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

• trusted caller передает user_id: UUID
• один Workspace на одного User
• metadata adapters пока in-memory
• история чата живет в history.md
• chat files отдаются через master download endpoint
• soft quota блокирует quota-relevant write-path операции
• chat create сам по себе quota не блокирует
• delete в v1 — hard delete; chat delete запрещен при active sandbox

Scope in

• domain model для Workspace, Chat, ChatFile
• usecase ports для metadata, filesystem storage и usage
• in-memory metadata adapters
• filesystem adapter для chat directories, history.md и file operations
• usecases для auto-create workspace, chat CRUD и file CRUD
• HTTP API для chat/file operations
• базовый usage/quota check

Scope out

• durable DB
• auth/access control
• artifacts
• retention engine
• p2p/access lease
• multi-node behavior

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

• primary-agent — архитектура, ADR, domain/contracts
• junior — простые repositories и базовые unit tasks
• junior+opus — adapter/usecase/API задачи средней сложности
• test-engineer — test packs
• code-reviewer — review-only этап

Порядок задач

S01. ADR-lite и storage contracts

• Рекомендуемый исполнитель: primary-agent
• Commit: add storage foundation contracts
• Scope: зафиксировать storage source-of-truth и history policy; добавить domain entities и usecase ports
• Files: docs/009-storage-foundation.md, docs/010-chat-history-policy.md, domain/*, usecase/interface.py или новые storage usecase files
• Acceptance: есть минимальные сущности/ошибки/порты; ADR краткий и консистентный

S02. In-memory metadata adapters

• Рекомендуемый исполнитель: junior
• Commit: add in-memory storage repositories
• Scope: WorkspaceRepository, ChatRepository, ChatFileRepository in-memory implementations
• Files: repository/*
• Acceptance: CRUD и базовые query paths работают без HTTP

S03. Filesystem chat storage adapter

• Рекомендуемый исполнитель: junior+opus
• Commit: add chat filesystem storage
• Scope: create chat directory, create history.md, save/list/delete files, collect file metadata
• Files: outer adapter/repository storage files
• Acceptance: chat directory layout стабилен; adapter не протекает внутрь

S04. Workspace and chat usecases

• Рекомендуемый исполнитель: junior+opus
• Commit: add workspace and chat usecases
• Scope: auto-create workspace on first touch, create/get/list/delete chat
• Files: usecase/*, adapter/di/container.py
• Acceptance: delete chat конфликтует при active sandbox; history path создается через storage adapter

S05. Chat file usecases + quota

• Рекомендуемый исполнитель: junior+opus
• Commit: add chat file usecases
• Scope: upload/list/metadata/delete/clear files; current usage and soft quota reject on write
• Files: usecase/*, adapter/di/container.py
• Acceptance: file write-path reject при quota overflow; usage включает history.md и chat files; chat metadata create не блокируется quota check

S06. HTTP API for chat and files

• Рекомендуемый исполнитель: junior+opus
• Commit: add chat and file http api
• Scope: versioned routes, schemas, error mapping, file download endpoint
• Files: adapter/http/fastapi/*
• Acceptance: API тонкий; FastAPI не протекает во внутренние слои

S07. Tests for storage foundation

• Рекомендуемый исполнитель: test-engineer
• Commit: add storage foundation tests
• Scope: unit + adapter + HTTP tests для workspace/chat/files/quota
• Files: test/*
• Acceptance: есть regression coverage для CRUD, history creation, quota reject, delete conflict, file download

S08. Boundary review

• Рекомендуемый исполнитель: code-reviewer
• Commit: no
• Scope: final review storage foundation slice
• Acceptance: clean architecture соблюдена, нет must-fix замечаний

Definition of done

Спринт считается завершенным, когда:

• можно создать chat для user_id
• для chat создается directory и history.md
• можно загрузить и удалить chat files
• можно получить metadata и скачать файл через master
• quota check блокирует quota-relevant file write operations
• все тесты проходят
• boundary review не содержит must-fix замечаний

Риски

• in-memory metadata не переживает restart
• download endpoint может потребовать уточнения streaming contract
• quota semantics нужно держать простыми, чтобы не породить скрытый retention scope

Что идет следующим спринтом

Сразу после этого спринта нужен bridge-спринт для sandbox/storage integration:

• metadata-backed chat path для sandbox flow
• wiring текущего CreateSandbox поверх first-class chat metadata
• review, что sandbox lifecycle не расходится с новым storage slice

И только потом логично брать artifact slice:

• artifact domain + metadata
• object storage adapter
• artifact upload/list/status
• delivery ack flow