From 7c53faa727600dec038b08c874df580d2f406e41 Mon Sep 17 00:00:00 2001 From: bsodfather Date: Thu, 1 Oct 2026 20:16:50 +0300 Subject: [PATCH] docs: resolve story 3.6 Draft and MCP scope --- .../spec-3-6-typed-static-resource-drafts.md | 164 ++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 _bmad-output/implementation-artifacts/spec-3-6-typed-static-resource-drafts.md diff --git a/_bmad-output/implementation-artifacts/spec-3-6-typed-static-resource-drafts.md b/_bmad-output/implementation-artifacts/spec-3-6-typed-static-resource-drafts.md new file mode 100644 index 0000000..c77dc65 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-3-6-typed-static-resource-drafts.md @@ -0,0 +1,164 @@ +--- +title: '3.6 — Сохранять typed static Resource Drafts' +type: feature +created: '2026-10-01' +status: blocked +review_loop_iteration: 0 +followup_review_recommended: false +context: + - '{project-root}/_bmad-output/implementation-artifacts/epic-3-context.md' +warnings: [oversized] +deferred: [] +--- + + + +## Intent + +**Problem:** Администратору необходимо безопасно сохранять text, JSON и binary Resource Drafts с typed contract, bounded artifact и безопасным preview. + +**Approach:** Создать отдельный typed Resource aggregate и persistence/API для Draft, сохраняя content bytes в существующем content-addressed artifact store. AC ниже уточнены решением пользователя: эта story ограничена Draft/Admin preview и безопасным download; MCP read и negotiated representation реализуются и проверяются в Story 3.8. + +## Boundaries & Constraints + +**Always:** Отдельные Resource ID/version/lifecycle, CapabilityKind::Resource и sensitivity; immutable Published contract; bounded bytes, exact digest и metadata; стабильные URI/name; UTF-8 и JSON validation без изменения semantics; безопасные preview/download и ошибки без content leakage. Следовать существующим Rust, registry, migration и API conventions. + +**Never:** Untyped Operation subtype, универсальный JSON blob, filesystem paths/upload filenames/mutable external references в published contract; исполнение HTML/SVG в origin Crank; unbounded content в DOM/logs/errors. Не писать и не откатывать sprint-status.yaml. Не реализовывать соседние stories без разрешённой границы intent. + + + +### Согласованная граница Story 3.6 + +Решение пользователя от 2026-10-01 (вариант 1): Story 3.6 сохраняет typed static Resource Drafts и предоставляет Draft/Admin preview и безопасный download. Для binary проверяются MIME, точный byte size, bounded opaque bytes и безопасная выдача без text decoding, без unbounded bytes в DOM/telemetry и без content в logs/errors. + +`resources/list`, `resources/read`, MCP version adapter, negotiated binary representation и их wire qualification относятся к Story 3.8. Publication и exact Agent binding остаются в Story 3.7; Story 3.6 задаёт typed domain/persistence contract, но не реализует эти lifecycle действия ради MCP read. Условие завершения Story 3.6 не требует MCP surface или будущей qualification. Эта граница определяет чтение AC ниже и исходной формулировки binary AC в epics.md. + + + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| Text | Bounded UTF-8 | Exact bytes и digest | Invalid UTF-8/oversize: stable finding, без truncation | +| JSON | Bounded valid JSON | Сохранение data semantics и exact artifact | Malformed/oversize отклоняются до publication | +| Binary Draft/Admin preview/download | Bounded opaque bytes + MIME | Точные MIME/byte size, inert metadata preview и безопасная binary выдача без text decoding; без unbounded bytes в DOM/telemetry | Safe finding, без content в logs/errors | +| MCP read / negotiated representation | Bound Published Resource Version | Реализация и wire qualification в Story 3.8 после Story 3.7; не критерий завершения 3.6 | Не добавлять MCP surface в 3.6 | +| Active content | HTML/SVG | Inert preview либо безопасный attachment | Safe Content-Type, nosniff, CSP/sandbox, sanitized filename | +| Integrity | Несовпадение digest/metadata | Fail closed | Safe error без filesystem/content leakage | + + + +## Code Map + +- `crates/crank-core/src/ids.rs` — существующий define_id! pattern; ResourceId/ResourceVersionId отсутствуют. +- `crates/crank-core/src/lib.rs`, `crates/crank-registry/src/model.rs` — domain exports и PublishedAgentTool; отдельного Resource aggregate и CapabilityKind нет. +- `crates/crank-artifacts/src/store.rs`, `model.rs` — ArtifactStore put/read API и ArtifactRef с digest; reuse для exact bytes. +- `crates/crank-registry/src/model/artifact_source.rs` — ArtifactSourceSensitivity относится к OpenAPI, не является готовым Resource sensitivity contract. +- `crates/crank-registry/src/migrations.rs`, `migrations/` — canonical authority, versioned SQL/Rust migrations; Resource tables отсутствуют. +- `apps/admin-api/src/routes/agents.rs`, `service/agents.rs`, `dto.rs` — Draft lifecycle и DTO conventions. +- `apps/admin-api/src/service/imports/verified_preview.rs` — существующий artifact preview pattern. +- `apps/ui/js/openapi-import.js`, `i18n.js` — vanilla JS preview и RU/EN conventions; Resource UI отсутствует. +- `crates/crank-community-mcp/src/jsonrpc.rs:3` — supported revisions 2025-03-26, 2025-06-18, 2025-11-25; negotiation есть, Resource version adapter отсутствует. +- `crates/crank-community-mcp/src/app.rs:827` — method dispatch без resources/list/read; `:1378` — capabilities только tools, listChanged=false. +- `apps/mcp-server/tests/integration/transport_protocol.rs`, `catalog_access.rs` — существующие wire integration surfaces; Resource evidence отсутствует. +- `justfile:59` — обязательный just verify. +- `_bmad-output/planning-artifacts/epics.md:2462` — read-only исходный intent 3.6; `:2520` — 3.7 publication/binding; `:2568` — 3.8 MCP read. + +## Tasks & Acceptance + +**Execution (предварительно; gate не пройден):** +- [ ] `crates/crank-core/src/ids.rs`, `lib.rs`, новый Resource domain module — typed identity/kinds/lifecycle/sensitivity и bounded validation. +- [ ] `crates/crank-registry/src/model.rs`, `repository.rs`, `postgres/`, `migrations/`, `docs/schemas/migration-sequence.json` — отдельная typed Draft persistence и canonical migration contract. +- [ ] `crates/crank-artifacts/src/`, `tests/` — reuse digest storage и проверить Resource artifact integrity. +- [ ] `apps/admin-api/src/routes/`, `service/`, `dto.rs` — authenticated Draft create/update/upload/preview с stable findings и safe download headers. +- [ ] `apps/ui/js/`, `apps/ui/css/`, `apps/ui/tests/` — безопасный Resource preview/download согласно согласованной границе. +- [ ] `crates/crank-core/tests/`, `crates/crank-registry/tests/`, `apps/admin-api/tests/` — domain/artifact/API edge cases; regression cases до fix. + +MCP implementation и wire tests не входят в задачи 3.6: `crates/crank-community-mcp/src/` и `apps/mcp-server/tests/` для Resource read/version adapter относятся к 3.8. + +**Acceptance Criteria (с уточнённой пользователем границей Draft/Admin):** +**Given** Resource domain model +**When** добавляется persistence и API contract +**Then** Resource является отдельным typed aggregate с собственными ID/version/lifecycle, `CapabilityKind::Resource`, sensitivity и immutable Published Version +**And** не хранится как untyped Operation subtype или универсальный JSON blob. + +**Given** новый Resource Draft +**When** администратор выбирает static text, JSON или binary kind +**Then** задаются URI, name, description, MIME type, sensitivity и bounded content +**And** URI и name валидируются как стабильные capability identifiers. + +**Given** static content +**When** оно сохраняется +**Then** bytes размещаются в content-addressed artifact store, а Resource Version хранит exact digest и metadata +**And** filesystem path, raw upload filename или mutable external reference не входит в published contract. + +**Given** JSON Resource +**When** Draft сохраняется или preview-ится +**Then** content валидируется как JSON и возвращается без изменения data semantics +**And** malformed либо oversized JSON отклоняется до publication. + +**Given** text Resource +**When** content принимается +**Then** он сохраняет валидный UTF-8 в пределах configured size +**And** invalid encoding или unsafe truncation отклоняются с stable finding. + +**Given** binary Resource +**When** Draft preview-ится или скачивается через Admin API/UI +**Then** соблюдаются MIME, точный byte size и configured size limit; preview показывает inert metadata, а download безопасно возвращает exact binary bytes +**And** content не декодируется как text, unbounded bytes не попадают в DOM/telemetry, content не попадает в logs/errors. + +MCP read, version adapter и negotiated binary representation реализуются и проверяются в Story 3.8; они не являются AC завершения Story 3.6. + +**Given** Resource с active либо browser-renderable content type, включая HTML или SVG +**When** Admin UI показывает preview/download +**Then** untrusted bytes не исполняются в origin Crank: используется inert text/metadata, sandboxed isolated preview либо attachment download по explicit allowlist +**And** response применяет safe `Content-Type`, `nosniff`, CSP/sandbox и filename sanitization без content sniffing. + +**Given** static Resource Draft suite +**When** выполняются domain, artifact и API tests +**Then** покрыты text/JSON/binary validation, MIME/size, active-content preview, malformed encoding и artifact integrity +**And** `just verify` проходит. + +## Spec Change Log + +- 2026-10-01 — пользователь выбрал вариант 1 в bmad-loop-resolve: 3.6 ограничена Draft/Admin preview/download; MCP read/version adapter/negotiated representation закреплены за 3.8. Уточнены frozen intent, binary AC, матрица и verification scope; статус оставлен оркестратору. + +## Review Triage Log + +## Design Notes + +### Разрешённая граница intent + +Исходный binary AC объединял Admin preview и MCP read, хотя цепочка зависимостей 3.6 → 3.7 → 3.8 относит publication/binding к 3.7, а MCP discovery/read и version adapter к 3.8. Пользователь выбрал вариант 1: в 3.6 проверяются только Draft/Admin preview/download, в 3.8 — exact published MCP read и negotiated representation. Frozen intent и AC выше фиксируют это решение; первоначальные результаты остановок ниже сохранены как история, а не актуальное требование MCP scope. + +## Verification + +Для повторного запуска 3.6: domain/artifact/registry/Admin API tests для text/JSON/binary Drafts, exact bytes/digest, MIME/size, encoding, safe preview/download и integrity; `just verify`, UI проверки при UI изменениях. MCP wire tests всех supported revisions, включая negotiated representation, выполняются в 3.8. В resolve-сессии код не реализовывался и тесты не запускались; исторические результаты предыдущих запусков приведены ниже. + +## Auto Run Result + +Status: blocked +Blocking condition: intent gap + +- Workflow остановлен на step-02 Plan по правилу intent gaps; код не изменён, реализация/ревью/проверка AC не выполнены. +- Baseline получен напрямую через `git rev-parse HEAD`: `7ffde8885ddd7c0196134f6085330536911a72be`. +- Исходное рабочее дерево чистое, ветка соответствует story; `git add --refresh -- .` завершился успешно. +- Составлен Epic 3 context и read-only Code Map; ведущий проверил MCP dispatch, capabilities и negotiation непосредственно в коде. +- Нет действий AC, требующих покупки/настройки внешнего сервиса человеком. `awaiting-operator` неприменим: препятствие — противоречие границ спецификации внутри repo. +- `sprint-status.yaml` не изменён и не использован как доказательство верификации. +- Неразрешённый вопрос: должна ли 3.6 включать MCP binary read, или этот AC ограничивается Draft/Admin preview, а MCP проверяется в 3.8? + +- Финальные проверки: `git diff --check` успешен, tracked working tree чистое. Документы `_bmad-output` игнорируются Git; commit кода не создавался. +- Read-only Pi завершил handoff; его tmux/Pi-сессия остановлена после завершения инструментов. +- `docker volume prune -f` завершён, освобождено 0B; активные контейнеры и именованные тома не удалялись. Повторные `docker system df`, `df -h /`, `btrfs filesystem usage /`: доступно около 110 ГБ, Metadata DUP 998.34 MiB / 7.01 GiB, global reserve used=0. Подробный per-device usage недоступен без root, общий запас metadata достаточен. + +### Повторный запуск 2026-10-01 + +Status: blocked +Blocking condition: blocked spec supplied + +- При маршрутизации story найдена существующая спецификация со статусом `blocked`; решение о границе Draft/Admin preview и MCP read не предоставлено. По HALT workflow реализация и ревью не запускались. +- Это нерешённая граница intent внутри репозитория, а не HUMAN-only operator action; статус `awaiting-operator` неприменим. +- Текущая ревизия: `7ffde8885ddd7c0196134f6085330536911a72be`. Код и `sprint-status.yaml` не изменялись; commit не создавался. +- `git diff --check` успешен, tracked working tree чистое. Тесты не запускались, фоновые исполнители не создавались. +- `docker volume prune -f` завершён (0B); последующие `docker system df`, `df -h /` и `btrfs filesystem usage /` успешны. Свободно около 110 ГБ, Metadata DUP использует 998.16 MiB из 7.01 GiB, global reserve used=0; подробный per-device usage недоступен без root.