@deksden-com/dd-console 0.0.0-stage → 0.2.0

package/docs/implementation-plan.md

@@ -0,0 +1,456 @@
+# План реализации локальной веб-консоли dd-flow / dd-eval
+
+Статус: базовая реализация первого read-only выпуска поставлена; этот документ
+остаётся целевой спецификацией для незакрытых compatibility/performance пунктов.
+Дата: 2026-09-13, актуализирован: 2026-09-13.
+Основание: [исследование текущего кода](research.md).
+
+## 0. Зафиксированные решения
+
+| Вопрос | Решение |
+|---|---|
+| Продукт | Отдельный локальный пакет и репозиторий `deksden-com/dd-console` |
+| Первая ценность | Наблюдение и детализация реальных запусков dd-flow и dd-eval |
+| Доступ | Один пользователь, текущая машина, только loopback |
+| Выполнение | Раннеры остаются единственными владельцами процесса и состояния; консоль только читает |
+| Обновление | Polling с общим серверным кэшем; SSE — после измеренного первого выпуска |
+| UI | Отдельные URL для сущностей, breadcrumbs, Back/Forward, детали по запросу |
+| Управление | Не входит в первый выпуск; появится отдельным этапом на существующих control contracts |
+| Хранение консоли | `DD_CONSOLE_HOME`, по умолчанию `~/.dd-console`; только настройки sources, кэш и логи консоли |
+
+Инструментарий зафиксирован в разделе 3. До подключения реальных данных остаётся проверить compatibility matrix и наличие публичной проекции текущего состояния Eval. Это обязательные результаты этапа 1, а не предположение о готовности существующих контрактов.
+
+## 1. Решение и границы первого выпуска
+
+Локальный сервер с веб-интерфейсом, двумя разделами Flows/Evals и отдельными экранами детализации. Каждый экран доступен по прямому URL. Breadcrumbs, браузерные Back/Forward и обновление страницы сохраняют корректную навигацию.
+
+Первый выпуск позволяет наблюдать как самостоятельные flow, так и flow внутри eval: стадии, работы, сессии, события, проверки, результаты и причины ожидания. Сервер наблюдения не владеет процессами раннеров; закрытие браузера и остановка сервера не останавливают выполнение.
+
+Первый выпуск включает polling и чтение истории. Pause/resume/stop, запуск новых заданий, удалённый доступ и SSE — следующие этапы. Полные диалоги не загружаются автоматически: в первом выпуске доступны структурированные события, зарегистрированные результаты и безопасный просмотр текстовых артефактов порциями.
+
+## 2. Экраны и навигация
+
+`source` в маршрутах — стабильный непрозрачный идентификатор зарегистрированного runtime. Короткие RUN/WORK ID могут совпадать в разных runtime и проектах, поэтому source и project обязательны для Flow. Его соответствие каноническому корню сохраняется в конфигурации консоли между перезапусками. При исчезновении источника ссылка показывает unavailable, а не переиспользуется для другого источника.
+
+| Экран | Предлагаемый URL | Содержимое и переходы |
+|---|---|---|
+| Обзор | `/` | Активные и требующие внимания запуски; переходы в Flows/Evals |
+| Источники | `/sources` | Подключённые sources, состояние чтения, диагностика и инструкции подключения через CLI |
+| Flows | `/flows` | Фильтры: проект, источник, статус, harness; сортировка и список RUN |
+| Flow | `/sources/:source/projects/:project/runs/:run` | Сводка, стадии/попытки, работы, сессии, проверки, события и артефакты |
+| Стадия / попытка | `/sources/:source/projects/:project/runs/:run/stages/:stage/attempts/:attempt` | Результат конкретной попытки, её работы и проверки; предыдущая/следующая попытка |
+| Работа | `/sources/:source/projects/:project/runs/:run/works/:work` | Статус, зависимости, родительская работа, сессии, проверки, результат |
+| Сессия | `/sources/:source/projects/:project/runs/:run/sessions/:session` | Harness, роль, наблюдаемая модель, связанные работы, события и артефакты |
+| Проверка | `/sources/:source/projects/:project/runs/:run/checks/:check` | Результат конкретной проверки, попытка, связанные работа/сессия и артефакты |
+| Evals | `/evals` | Case, checkpoint, статус, время; фильтры и список EVAL |
+| Eval | `/sources/:source/evals/:eval` | Параметры, executions, состояние candidate/Judge, версии и evidence |
+| Execution | `/sources/:source/evals/:eval/executions/:execution` | Статус запуска, операции, recovery, результат и проверенная ссылка на вложенный flow |
+| Артефакт | `/artifacts/:artifact` | Имя, тип, источник, ограниченный текстовый просмотр или скачивание |
+
+Вкладки внутри сущности: `?tab=overview|works|sessions|checks|events|artifacts`. Использовать только применимые вкладки, не показывать пустую структуру ради единообразия. Фильтры, сортировка и pagination cursor списка находятся в URL. Состояние прокрутки хранится на запись browser history.
+
+### Breadcrumbs
+
+- Самостоятельный flow: `Обзор → Flows → RUN → Работа`.
+- Из eval: `Обзор → Evals → EVAL → Execution → RUN → Работа`.
+- Сессия, открытая из работы: добавить работу только при подтверждённой связи; сессия может обслуживать несколько работ, поэтому это контекст навигации, а не единственный родитель сущности.
+- Канонический URL Flow/Session остаётся один. Параметр `context` хранит проверяемые идентификаторы eval/execution и при необходимости work; сервер валидирует связи. Не использовать произвольный return URL.
+- При прямом открытии без контекста строить каноническую цепочку. При удалённом/устаревшем контексте показать уведомление и доступную цепочку, не ломая экран.
+- Последний элемент цепочки — текущая страница; остальные — ссылки. Длинную цепочку можно сворачивать, оставляя доступ к скрытым предкам с клавиатуры.
+- Breadcrumbs ведут по иерархии, Back/Forward — по фактической истории. Обе модели должны работать независимо.
+
+### Общий каркас экрана
+
+Шапка с разделами Flows/Evals и состоянием подключения; breadcrumbs; заголовок и статус сущности; текущая операция/причина ожидания; время обновления; основное содержимое и вкладки. Loading, empty, partial, unavailable, unsupported и not found имеют отдельные представления.
+
+Автообновление не сбрасывает фокус, вкладку, фильтры, прокрутку и раскрытые детали. Для событий есть переключатель «Следить за новыми»; при ручной прокрутке вверх новые строки показываются счётчиком, без принудительного перемещения вниз. Статусы различаются текстом и значками, а не только цветом.
+
+### Информационная архитектура экранов
+
+У каждой сущности сверху компактная сводка: идентификатор, статус, начало/последнее наблюдение, причина ожидания или ошибки и ближайшее полезное действие человека. Ниже — только относящиеся к ней данные. Список всегда показывает агрегированные строки; тяжёлые детали открываются отдельной страницей или вкладкой, не загружаются для всех строк заранее.
+
+| Экран | Верхняя сводка | Детали |
+|---|---|---|
+| Обзор | активные, ожидающие и требующие внимания источники | последние изменения, ссылки на конкретные RUN/EVAL |
+| Flow | status, stage, controller, last observation, duration | attempts, work graph, sessions, checks, timeline, artifacts |
+| Работа | status, parent, dependencies, launch policy | попытки, сессии, результаты и связанные checks |
+| Сессия | harness, role, observed model, status | связанные works, хронология, безопасные артефакты |
+| Eval | case/checkpoint, definition/engine identity, candidate/Judge | executions, evidence, журнал и диагностика определения |
+| Execution | status, active/pending operation, recovery, nested Flow | события операции, модель, результат, ссылка на derived Flow source |
+
+Три независимые оси: `execution_status` (исходный статус и документированное отображение, включая planned/queued/running/waiting/paused/blocked/failed/completed/cancelled/stopped/unknown), `availability` (available/partial/unavailable/unsupported) и `control` (запрошенное действие, подтверждение, recovery). Например, completed остаётся последним известным статусом при unavailable; запрос отмены не подменяет running на cancelled. Неизвестный статус производителя показывается буквально с диагностикой, не считается успехом. Таблица отображения обязана иметь ссылку на source schema и fixture для каждого правила.
+
+«Требует внимания» рассчитывается отдельно: подтверждённая ошибка, blocker, запрос участия человека или recovery; недоступность наблюдения отмечается как проблема чтения. Длительное молчание само по себе не означает зависание. Длительности берутся из подтверждённых timestamps; у незавершённой работы показывается elapsed, а при некорректных часах — unknown. Счётчики обзора разделяют EVAL и Flow, чтобы execution и его Flow не удваивали число запусков одного типа.
+
+## 3. Размещение кода и запуск
+
+Проект **dd-console** размещён в отдельном репозитории `deksden-com/dd-console`, локально — `/Users/deksden/Documents/_Projects/dd-console`. В нём реализованы Node/TypeScript package, loopback HTTP server, registry, Flow/Eval readers, browser UI и contract/browser tests. Консоль — общий пользовательский продукт для dd-flow и dd-eval, поэтому её UI, HTTP API, тесты и релизы принадлежат одному репозиторию и не привязаны к релизу одного раннера. Это уточнение заменяет первоначальное предложение исследования размещать сервер в dd-flow-cli.
+
+Команда: `dd-console serve --port 0 [--open] [--flow-home <path>] [--eval-home <path>]`. `--port 0` выбирает свободный порт; фиксированный порт позволяет сохранять browser bookmarks. Сервер печатает фактический URL и поддерживает JSON receipt. Запуск в foreground; остановка по Ctrl+C завершает только сервер наблюдения. Автоматическое открытие браузера выполняется только с --open. Возможные алиасы `dd-flow dashboard open` и `dd-eval dashboard open` обсуждать отдельно после рабочего выпуска; они не обязательны для запуска консоли.
+
+Один Node/TypeScript пакет: сервер и собранный frontend поставляются вместе, одним процессом и на одном порту. Первый сервер: Node HTTP, тот же origin для API и веб-ресурсов, без новой БД. Минимальный History API router отвечает за URL/Back/Forward; сервер возвращает оболочку для допустимых UI routes и JSON ошибки для неизвестных API routes. Отдельные npm workspaces, frontend runtime framework и framework backend для первого выпуска не нужны.
+
+### Инструментарий первого выпуска
+
+- Node.js `>=26.0.0`, TypeScript, ESM и npm package: первый выпуск проверяется на Node 26, как текущий dd-flow-cli. Предыдущее `>=22` было неточным: node:sqlite появился в 22.5, без специального флага доступен с 22.13 ([Node SQLite](https://nodejs.org/api/sqlite.html)). Поддержка других major не заявляется без CI; package manager — npm с lockfile.
+- Frontend — TypeScript, обычные DOM-компоненты и History API, статическая CSS. Это сохраняет один понятный пакет, не добавляет runtime framework и не препятствует переходу на компонентный UI, если после первого выпуска появится реальная потребность.
+- Отдельные tsconfig для server (Node ESM) и web (DOM, browser ESM); browser imports используют относительные `.js` пути. `tsc` компилирует TS, отдельный build script копирует HTML/CSS в `dist/web`. Сервер находит assets относительно своего модуля, не cwd. Development-режим использует тот же routing и политику доступа. Pack smoke запускается из постороннего каталога без исходников.
+- Unit/contract tests — встроенный `node:test`; browser acceptance — Playwright как dev dependency. Проверки реальных fixture не зависят от сети и не требуют запущенного чужого раннера.
+- ESLint и форматирование добавляются при bootstrap пакета. Скрипты: `build`, `typecheck`, `lint`, `test`, `test:browser`, `check` (последовательно запускает все обязательные проверки), `pack:check`.
+
+Это намеренно не SPA framework и не отдельный API service: первый выпуск — локальная операционная консоль, а не продукт с удалёнными пользователями. Решение пересматривается только после измеримой проблемы с сложностью UI или производительностью.
+
+Предлагаемая структура репозитория:
+
+```text
+dd-console/
+  src/
+    cli.ts
+    server/       # HTTP, API, discovery источников и артефакты
+    readers/      # flow/eval, проверка версий, read-only доступ
+    contracts/    # публичные DTO консоли
+    web/          # экраны, router, breadcrumbs, стили
+  test/
+    fixtures/     # обезличенные snapshots поддерживаемых версий
+  docs/           # архитектура, контракты источников, эксплуатация
+  package.json
+```
+
+Runtime-данные остаются в DD_FLOW_HOME/DD_EVAL_HOME. Собственная конфигурация источников и необязательный восстанавливаемый кэш — в DD_CONSOLE_HOME (по умолчанию `~/.dd-console`), никогда в исходниках. Консоль не копирует evidence в свою БД и не становится владельцем состояния RUN.
+
+Границы репозиториев: dd-console владеет представлением, навигацией и адаптацией чтения; dd-flow-cli — механикой Flow и документированным контрактом наблюдения; dd-eval — механикой Eval и его контрактом наблюдения; dd-memorybank — принятой общей документацией. Не импортировать внутренние TypeScript-модули соседнего checkout, не использовать workspace symlinks и не дублировать reducers бизнес-состояния. Если имеющейся проекции недостаточно, добавлять компактный read-only export у владельца раннера, затем адаптер в консоли. Прямое чтение SQLite допускается только для проверенной поддерживаемой версии и документированных полей; это ограничение явно отражать в compatibility matrix.
+
+Существующий dd-flow dashboard использовать как источник требований и проверенных полей; автоматически переносить большой renderer и его зависимости в новый репозиторий не следует. Сохраняется действующий статический dashboard раннера.
+
+dd-eval отвечает за документирование своего формата наблюдения и producer contract tests; dd-console — за fixture/contract tests адаптера. Первый адаптер читает сохранённые manifest/journal/results, без импорта runner.mjs и без запуска закреплённых исполняемых файлов из старых manifests при открытии страницы. При необходимости дополнительный компактный экспорт добавляется в dd-eval; зависимость от checkout dd-eval для установленной консоли не допускается.
+
+Изменения dd-memorybank нужны только для окончательного пользовательского контракта запуска и эксплуатации; самостоятельный runtime-компонент там не создаётся.
+
+### Дизайн и поведение интерфейса
+
+Аудитория — человек, который сопровождает долгий запуск и должен быстро понять, где он остановился, что уже доказано и в какую деталь перейти. Основная работа страницы — дать честный ответ «что происходит сейчас» и путь к доказательству, а не нарисовать абстрактный процент прогресса.
+
+Визуальная идея: **операционный журнал и карта исполнения**, а не маркетинговый dashboard. Основной фон — холодный `#F5F7FA`; поверхности — `#FFFFFF`; основной текст — `#18212B`; вторичный — `#5D6875`; рабочий акцент — индиго `#3157A8`; состояния внимания — янтарный `#9A5D00`; ошибка — бордовый `#A33A3A`. Цвет не является единственным носителем статуса. Для данных использовать моноширинный системный стек, для обычного текста — системный sans-serif; display-шрифт не нужен: читабельность и плотность данных важнее характерной типографики.
+
+Макет: слева фиксированная навигация Sources / Flows / Evals с количеством требующих внимания; сверху один ряд breadcrumbs и статуса подключения; основная колонка шириной до 1440px; справа на широком экране узкая «наблюдение сейчас» панель с freshness и активной операцией. На планшете правая панель становится верхней сводкой; на телефоне навигация превращается в меню, таблицы — в карточки с раскрытием. Единственный выразительный элемент — **линия исполнения**: тонкая, доступная текстовая шкала «последнее подтверждённое событие → текущая операция → ожидаемое следующее условие», которая показывает причины ожидания без фиктивного процента выполнения.
+
+```text
+┌ Sources / Flows / Evals ┐ ┌ Overview › EVAL-… › Execution-… ───────────┐
+│ • attention count       │ │ EVAL-…        waiting for provider          │
+│ • filters               │ │ Line: completed CODE → observe repair       │
+│                          │ ├ Overview ┬ Executions ┬ Events ┬ Evidence ┤
+│                          │ │ summary / table / selected detail          │
+└──────────────────────────┘ └─────────────────────────────────────────────┘
+```
+
+Копирайт использует термины, знакомые пользователю: «ожидает провайдера», «нужно восстановление», «нет данных о Judge», «источник недоступен». Ошибка всегда содержит следующую безопасную проверку, если она известна. Анимация ограничивается одним коротким обновлением линии исполнения; `prefers-reduced-motion` полностью её отключает.
+
+## 4. Чтение данных и API
+
+Источники: текущий DD_FLOW_HOME, указанный DD_EVAL_HOME и подтверждённые managed-runtime связи вложенных execution. Дополнительные homes регистрируются явно. Не сканировать весь диск и каталоги чужих сессий. Обнаружение новых запусков ограничено зарегистрированными корнями; каталог перечитывается периодически, по запросу списка и при явном refresh.
+
+### 4.1. Реестр источников и идентичность
+
+При первом запуске `dd-console serve` создаёт либо открывает `DD_CONSOLE_HOME/sources.json`. Запись содержит ID, kind, canonical root, label, время регистрации и registry schema version. Версия reader не является свойством identity. Root хранится только на сервере; изменение root существующего ID запрещено, отключённые записи остаются tombstones. Правила подключения приведены ниже.
+
+| Kind source | Кто создаёт | Корень | Идентичность сущности |
+|---|---|---|---|
+| `flow-home` | serve input или явная регистрация | один DD_FLOW_HOME | `source_id + project_id + run_id` |
+| `eval-home` | serve input или явная регистрация | один DD_EVAL_HOME | `source_id + eval_run_id` |
+| `eval-execution-flow` | только Eval reader после проверки managed-runtime | execution runtime_root | `source_id + parent_eval_id + execution_id + project_id + run_id` |
+
+Derived `eval-execution-flow` не регистрируется как независимый глобальный source и не становится доступен по пути, присланному браузером. Сервер заново проверяет `managed-runtime.json`: ожидаемые `project_root`, `runtime_root`, schema и `run_id` должны совпасть с родительским execution. Именно эта проверка разрешает переход `Execution → Flow`.
+
+Корневой source ID — UUID, сохраняемый в registry. Derived ID детерминирован из parent source ID, eval ID и execution ID; принадлежность runtime всё равно проверяется отдельно. Resolver восстанавливает связь при прямом открытии после перезапуска, без предварительного посещения EVAL. Artifact ID аналогично привязан к source/entity и зарегистрированной относительной ссылке; ID не является разрешением читать файл. При повторной регистрации того же kind/root используется существующий ID. Дубликат derived runtime, явно подключённый как flow-home, получает одну каноническую identity и несколько связей в UI.
+
+### Первое подключение и конфигурация
+
+В первом выпуске настройка доступна через CLI: `sources list`, `sources add --kind flow|eval --path <path> [--label <name>]`, `sources remove <id>`. Remove отключает регистрацию и сохраняет tombstone для старых ссылок, не удаляет данные. `serve --flow-home/--eval-home` — сокращение идемпотентного add. Registry дополняется явно заданными flags; при отсутствии источников используются существующие каталоги из DD_FLOW_HOME/DD_EVAL_HOME либо стандартные `~/.dd-flow`/`~/.dd-eval`, отсутствующие каталоги не создаются. Пустой registry открывает экран подключения с готовыми командами.
+
+Один сервер на DD_CONSOLE_HOME: process lock с проверкой владельца; второй запуск показывает действующий URL или сообщает конфликт, не перезаписывает registry. CLI-изменения registry используют краткую межпроцессную блокировку и atomic rename, сервер перечитывает ревизию. Невалидный config не заменяется пустым: запуск завершается с конкретной диагностикой, исходный файл сохранён. При ошибке перечитывания работающий сервер сохраняет последнюю валидную конфигурацию и показывает предупреждение.
+
+Первый выпуск квалифицируется на macOS. Default bind — 127.0.0.1; --host не входит в CLI. Default port 0, фиксированный --port поддерживает bookmarks; новый случайный порт меняет origin, что явно указано в помощи. В --json stdout содержит один startup receipt, логи идут в stderr; --open выполняется после listen. Ctrl+C освобождает lock и закрывает только console resources.
+
+### 4.2. Публичная модель ответа
+
+Все JSON endpoints возвращают общий envelope. Он отделяет успешное чтение от пригодности данных и не подменяет отсутствующие значения нулём:
+
+```json
+{
+  "schema_version": "dd-console/api@1",
+  "request_id": "REQ-…",
+  "observed_at": "2026-09-13T12:00:00.000Z",
+  "source": {
+    "id": "SRC-…",
+    "kind": "flow-home",
+    "availability": "available",
+    "source_updated_at": "2026-09-13T11:59:59.000Z"
+  },
+  "data": {},
+  "diagnostics": []
+}
+```
+
+`diagnostics` — безопасные записи `{ code, severity, message, entity? }`. Для агрегатов `source: null`, отдельные части имеют собственную source/availability. У cached data `observed_at` — время фактического чтения, отдельно `served_at` — время ответа; source_updated_at и last_event_at не являются heartbeat. HTTP 200 содержит available/partial/unavailable/unsupported, включая detail известных источников; 404 — неизвестная identity, 400 — неверные параметры, 409 stale_cursor — потеря snapshot, 405 — неподдерживаемый method, 500 — ошибка консоли, 503 — занятая очередь чтения с Retry-After. Неверный breadcrumb context даёт diagnostic и каноническую цепочку при HTTP 200, не блокирует доступную сущность. Error envelope содержит request_id и безопасный code/message.
+
+| DTO | Обязательные поля | Не включать |
+|---|---|---|
+| `SourceSummary` | ID, kind, label, availability, freshness | root path, token, raw DB config |
+| `RunSummary` | identity, status, stage, created/updated, attention reason | полный index_json |
+| `FlowDetail` | RunSummary, stages/attempts, work/session/check summaries, controller projection | owner/lease tokens, private transcript body |
+| `EvalDetail` | identity, case/checkpoint, immutable definition identity, executions, candidate/Judge states | raw manifest и скрытые ответы subject |
+| `ExecutionDetail` | identity, state, operations, recovery, derived Flow link | runtime env, executable paths |
+| `WorkDetail` / `SessionDetail` | identity, state, safe relations, timestamps, results summary | raw adapter payloads без allowlist |
+| `EventPage` | source-local cursor, events, has_more, next_cursor | глобальный причинный порядок между sources |
+| `ArtifactInfo` | opaque ID, name, media type, byte length, preview eligibility | абсолютный filesystem path |
+
+### 4.3. API первого выпуска
+
+Все list/event endpoints ограничивают `limit` диапазоном 1–200; default 50. Cursor привязан к endpoint, source и фильтрам. Список страниц использует замороженную ревизию каталога (TTL 5 минут), стабильную сортировку с полным identity как tie-breaker. Polling предлагает новые строки без перестановки просматриваемых страниц; явное обновление начинает новую ревизию. По истечении snapshot или перезапуске сервера — 409 stale_cursor; UI сохраняет фильтры, объясняет сброс страницы. Event cursor использует generation/offset, append его не инвалидирует; rotate/truncate требует reset. `refresh=1` — ограниченный hint кэшу, без обхода лимитов.
+
+| Метод и endpoint | Ответ | Назначение |
+|---|---|---|
+| `GET /api/v1/overview` | обзор всех sources | домашний экран |
+| `GET /api/v1/sources` | `SourceSummary[]` | статусы подключений |
+| `GET /api/v1/flows` | paged `RunSummary[]` | список самостоятельных и доступных derived Flow |
+| `GET /api/v1/sources/:source/projects/:project/runs/:run` | `FlowDetail` | экран Flow |
+| `GET …/stages/:stage/attempts/:attempt` | stage attempt detail | детализация попытки |
+| `GET …/works/:work` | `WorkDetail` | экран работы |
+| `GET …/sessions/:session` | `SessionDetail` | экран сессии |
+| `GET …/checks/:check` | `CheckDetail` | экран проверки |
+| `GET /api/v1/evals` | paged Eval summary | список EVAL |
+| `GET /api/v1/sources/:source/evals/:eval` | `EvalDetail` | экран EVAL |
+| `GET …/executions/:execution` | `ExecutionDetail` | execution и ссылка на Flow |
+| `GET /api/v1/events` | `EventPage` | events конкретной сущности, определяемой query identity |
+| `GET /api/v1/artifacts/:artifact` | `ArtifactInfo` | метаданные |
+| `GET /api/v1/artifacts/:artifact/preview` | ограниченная текстовая страница | безопасный просмотр |
+| `GET /api/v1/artifacts/:artifact/download` | поток attachment | скачивание по явному действию |
+| `GET /healthz` | `{ ok, version }` | доступность процесса, без состояния запусков |
+
+В первом выпуске нет `POST`, `PUT`, `PATCH`, `DELETE` API. Любой незнакомый путь или HTTP method получает JSON error и не падает на filesystem fallback.
+
+Слой наблюдения возвращает небольшие публичные структуры: RunSummary, FlowDetail, EvalDetail, ExecutionDetail, WorkDetail, SessionDetail, EventPage, ArtifactInfo. У каждого ответа — schema_version, source_id, observed_at, source_updated_at, availability и diagnostics. Источники ошибок различаются: ошибка раннера не равна ошибке чтения или отключению браузера.
+
+Идентификаторы, статусы и связи берутся из источника. Производные поля явно обозначаются. Не вычислять общий «процент готовности» из номера стадии; отсутствующий usage/score возвращается null с причиной, а не 0. Показать configured и observed model отдельно, если обе доступны.
+
+API повторяет экранные сущности: `/api/v1/sources`, `/overview`, `/flows`, `/evals` и detail endpoints с source/entity IDs. Для списков и событий обязательны limit/cursor с верхним пределом; для файлов — artifact ID и ограничение размера. API никогда не принимает произвольную команду или путь к файлу/БД.
+
+Flow reader реализует readOnly/query_only самостоятельно, без импорта getDatabase из соседнего проекта. Наличие файла и обязательных таблиц проверяется до чтения: существующий getDatabase может вернуть пустую БД при отсутствующем файле, что нельзя показывать как «нет запусков». Ревизия публичной проекции определяет приоритет runtime snapshot над устаревшим index, как в producer authoritativeIndex; правила фиксируются в контракте. Совместимость определяется schema/capabilities, не только package version или SQLite schema_version.
+
+Для Eval manifest и конечного report недостаточно, чтобы знать текущие pending operations: runnerStatus использует reduceEvents и запускает живые status-команды. Поэтому этап 1 обязан выделить у dd-eval публичную сохраняемую observation-проекцию с last_sequence, run/execution results, provenance и отдельным candidate/Judge состоянием. Её обновляет владелец раннера; консоль не копирует reducer и не вызывает runnerStatus. При отсутствии проекции у исторического запуска доступны проверенные manifest/report/journal, но текущий статус unknown/partial. Если полного актуального состояния нет и producer export не реализован, интеграция Eval считается незавершённой, а не «готовой с заглушкой».
+
+Для первого выпуска запрещены автоматические вызовы CLI/provider probes при любом HTTP чтении, включая details. «Живое» означает чтение новых сохранённых фактов; состояние процесса без таких фактов помечается unknown. Дополнительный прямой опрос провайдера — отдельная будущая возможность.
+
+Журнал JSONL читается инкрементально: хранить смещение и незавершённый хвост строки. Незавершённая последняя строка во время append ожидает следующего чтения; повреждённая законченная строка выдаёт диагностику, не пропускается молча. Усечение/замена файла сбрасывает cursor. Для SQLite использовать короткие read snapshots, не держать транзакцию между запросами.
+
+Отдельные файлы и БД не образуют атомарный общий snapshot: сохранять revisions/timestamps источников и показывать partial при расхождении. Не объявлять остановку всех процессов доказанной на основании нескольких независимых чтений.
+
+### 4.4. Матрица совместимости и readers
+
+Перед реализацией каждый reader получает собственную compatibility matrix: producer, supported schema/build ranges, минимальные признаки, fixtures, fallback, owner изменений. Матрица начинается с реально установленных/актуальных релизов и пополняется только после теста на fixture и реальном read-only source.
+
+| Reader | Первичный источник | Проверка | Fallback при несовместимости |
+|---|---|---|---|
+| Flow list/detail | публичная проекция run + read-only store | contract/schema, project/run ownership | summary `unsupported`, без деталей |
+| Flow timeline | timeline JSONL | event schema, cursor generation, boundary строки | доступная сводка без журнала |
+| Eval list/detail | eval directory, manifest, events, report/candidate | schemas, run identity, event sequence | summary `unsupported` или `partial` |
+| Eval execution Flow | managed-runtime + изолированный Flow store | schema, root/run identity и containment | execution остаётся видимым, link unavailable |
+| Artifact | allowlisted registered artifact reference | realpath containment, size/media policy | metadata с diagnostic, без выдачи файла |
+
+Readers ничего не мигрируют, не исправляют и не синхронизируют. Если текущие dd-flow-cli/dd-eval проекции не дают безопасного стабильно читаемого поля, решение — компактный producer export в репозитории владельца с его contract tests, а не копирование внутренней бизнес-логики в dd-console.
+
+### Большие источники и холодный запуск
+
+Discovery выполняется порциями с прогрессом indexed/total-known; неполная индексация не выглядит как пустой список. Source error изолирован от других roots. Cold start журнала читает ограниченный хвост для событий, не выводит итог операции из неполной истории; состояние берётся из producer snapshot. Полная доступная история догружается страницами. Максимальная строка JSONL — 1 МиБ; превышение фиксируется как diagnostic, обработка продолжения строки не накапливает бесконечный buffer.
+
+Синхронный SQLite и разбор больших журналов выполняются в ограниченном пуле worker_threads (начально 2), чтобы busy_timeout не блокировал HTTP и /healthz. Read task имеет deadline 2 секунды; timeout возвращает последнюю snapshot со stale/diagnostic, освобождает или пересоздаёт только console worker. Глобальный LRU кэш — целевые 64 МиБ, очередь — 32 задания, журнальные чанки — 256 КиБ. Это стартовые бюджеты для измерения; превышение не должно молча увеличивать память или создавать новые workers.
+
+SQLite читается с существующим WAL; нельзя копировать только .sqlite активного источника и нельзя выставлять immutable на живой базе. Fixture создаётся согласованным backup либо производителем тестовой БД. Read-only SQL не гарантирует отсутствие SQLite служебных файлов: отдельно проверить WAL/SHM поведение на fixture. Строго неизменяемый архив при необходимости читается через согласованную копию в console cache, а не через запись рядом с evidence.
+
+## 5. Живое обновление и нагрузка
+
+Начальные целевые интервалы: выбранный экран — 2 секунды, обзор — 5 секунд; скрытая вкладка замедляет polling. Запросы не перекрываются; при уходе с экрана отменяются. После ошибок — backoff, после восстановления — новый snapshot. Это параметры для проверки, не измеренные характеристики текущего кода.
+
+Один серверный reader/cache на источник обслуживает все вкладки. Чтение старой части большого журнала повторно не выполняется для каждого refresh. Первичная загрузка истории имеет ограничение объёма; старые страницы читаются по запросу. Состояние «подключено» означает доступность сервера; отдельно показывать возраст исходных данных.
+
+SSE добавлять после первого выпуска, если это оправдано измерениями. Использовать snapshot + cursor + update/reset и reconnect. Порядок событий гарантировать только внутри источника. Не вводить единую шину событий и не переписывать раннеры ради интерфейса.
+
+## 6. Границы локального сервера
+
+Bind только loopback, проверка Host и Origin, без permissive CORS. Не отдавать owner/lease tokens, env, сырые DB rows и manifests целиком. Артефакты разрешать по realpath в зарегистрированных корнях; проверять symlinks и traversal. HTML/JS артефакты отдавать как скачивание либо экранированный текст, не исполнять в origin консоли. Логи и имена сущностей экранировать.
+
+Просмотр не вызывает migrations, reconcile, usage recalculation, resume и обновление run projections. Полезные существующие getters перед подключением проверяются по цепочке вызовов. В первом выпуске HTTP API только для чтения.
+
+Отсутствующий Origin допустим для обычного GET; присутствующий чужой Origin отклоняется. Host проверяется с фактическим портом, API выдаёт application/json и nosniff. Артефакты разрешены только по зарегистрированным публичным ссылкам, не по любому файлу внутри home: env, credentials, private prompts и полные transcripts исключены. Metadata/preview/download имеют одну политику. Preview — до 256 КиБ за страницу, Markdown/JSON отображаются текстом, HTML/SVG не исполняются. Download идёт потоком с backpressure; подмена symlink между регистрацией и открытием входит в тесты.
+
+Persistent cache payloads по умолчанию отключён; локальные logs ограничены 3 файлами по 5 МиБ, содержат timings/bytes/codes/opaque IDs. Registry доступен только текущему пользователю. Assets имеют build revision; после обновления UI выполняет согласованный reload. API/data не сохраняются service worker или offline cache.
+
+## 7. Полный план поставки
+
+Каждый этап заканчивается работающей, проверяемой частью. Нельзя начинать следующую интеграцию на допущении, что незафиксированный контракт раннера «наверняка подойдёт».
+
+### Этап 1. Основание и contract audit
+
+**Цель:** доказать, что консоль может только читать нужные данные актуальных раннеров.
+
+1. Зафиксировать актуальные commit/version dd-flow-cli и dd-eval, их публичные schemas и расположение поддерживаемых artefacts.
+2. Выписать для каждого экрана поля, их producer, schema/version, safe display transformation и поведение при отсутствии.
+3. Проверить read-only путь Flow: открыть только `read_existing`, выполнить разрешённые queries и сравнить до/после файлы store/run projection.
+4. Проверить read-only путь Eval: manifest, journal, report/candidate и `managed-runtime.json`; не вызывать `runnerStatus`, если он запускает live child commands для массового списка.
+5. Сформировать fixtures из копий разрешённых малых артефактов: `flow-completed`, `flow-running`, `flow-retry`, `eval-multi-execution`, `eval-recovery`, `unavailable`, `unsupported`. Удалить secrets, личные пути, токены, ответы subject и большие transcript/log blobs.
+6. Создать compatibility matrix и contract tests readers на fixtures. Для каждого требуемого, но недоступного поля открыть отдельную задачу в dd-flow-cli или dd-eval с предложением producer export.
+7. Согласовать с владельцами раннеров изменения публичного контракта до написания адаптера, если они нужны.
+
+**Артефакты в dd-console:** `docs/compatibility.md`, `docs/data-contract.md`, `test/fixtures/…`, `test/contracts/…`.  
+**Готово, когда:** fixture readers дают стабильные DTO; unknown/unsupported не падают; hash/mtime/read-only assertions подтверждают отсутствие записей.  
+**Не делать здесь:** UI, polling, migrations, совместимость «на глаз» с историческими runtime.
+
+### Этап 2. Bootstrap пакета, serve и безопасный shell UI
+
+**Цель:** запустить установленную консоль с настоящим браузерным маршрутом, но пока на fixture source.
+
+1. Добавить `package.json`, Node/TS configs, scripts, lint, build output и package files allowlist.
+2. Добавить CLI parser: `dd-console serve --port --open --flow-home --eval-home --json` и `sources list/add/remove`; нераспознанные флаги завершаются с usage error. --host отсутствует, bind только loopback.
+3. Реализовать config/load/save source registry атомарной записью в `DD_CONSOLE_HOME`; проверять canonical path только на сервере.
+4. Реализовать Node HTTP router: static assets, History fallback только для allowlisted UI routes, JSON API errors, `/healthz`, graceful shutdown.
+5. Реализовать Host/Origin policy, request ID, response envelope, content-security-policy для собственных assets и запрет directory listing.
+6. Собрать shell: sidebar, header, source badge, breadcrumbs component, empty/loading/error states; добавить fixture overview и прямые URL для каждого базового экрана.
+7. Реализовать browser state: `popstate`, URL query filters, scroll restoration, focus в h1 после navigation, без полной перезагрузки при внутренних ссылках.
+
+**Артефакты:** `src/cli.ts`, `src/server/`, `src/contracts/`, `src/web/`, server/router/browser tests.  
+**Готово, когда:** `npm pack` и установка tarball дают `dd-console serve`; `/`, Flow, Eval и несуществующий route ведут себя определённо; Back/Forward и direct link проходят browser test.  
+**Не делать здесь:** доступа к production homes и живого обновления.
+
+### Этап 3. Flow reader и вертикальный путь Flow
+
+**Цель:** сделать самостоятельный flow полезным для диагностики от списка до причины ожидания.
+
+1. Реализовать Flow source reader с source registry, version gate и read-only SQLite/file adapter.
+2. Реализовать paged Flow list с filters `source`, `project`, `status`, `harness`, `from/to`, sort `updated|created|attention`.
+3. Реализовать `FlowDetail`: верхняя сводка, raw/normalized status, stage attempts, controller projection, work graph summary, sessions/checks count, last observation/freshness.
+4. Реализовать отдельные readers/details для stage attempt, work, session и check. Graph отображать как список зависимостей в первом срезе; визуальную диаграмму добавлять только если она реально ускоряет поиск блокировки.
+5. Реализовать event pagination и artifact registry. Viewer отображает text только при safe MIME/type/size; binary — метаданные и controlled download.
+6. Добавить Flow UI: таблица списка, cards для узкого экрана, tabs detail, «линия исполнения», breadcrumbs и links между работой/сессией/check.
+7. Запустить read-only integration на одном доступном текущем Flow, записать observed results и проверить, что его runtime неизменён.
+
+**Готово, когда:** пользователь может открыть RUN, увидеть точный статус, последнюю подтверждённую операцию, работу/проверку-источник блокировки и вернуться назад без потери фильтра. Legacy `current_stage` не требуется для отображения works.
+
+### Этап 4. Eval reader и сквозной путь Eval → Flow
+
+**Цель:** связать executions EVAL с их изолированными Flow, не смешивая runtime и не интерпретируя результаты неверно.
+
+1. Реализовать discovery только зарегистрированных EVAL directories и eval list с cursor.
+2. Реализовать `EvalDetail`: case/checkpoint, definition identity, execution cards, journal state, candidate/Judge/evidence summaries, diagnostics валидности.
+3. Реализовать `ExecutionDetail`: normalized state, source event sequence, pending/terminal operations, recovery/control state, observed model only where source подтверждает её.
+4. Реализовать validation `managed-runtime.json` и derived Flow source; contained path + identities проверяются до того, как Flow reader откроет store.
+5. Добавить links и context token: Eval → execution → derived Flow → work/session; при возвращении context создаёт полный breadcrumb, но не даёт доступа к постороннему runtime.
+6. Добавить явные UI состояния: Judge отсутствует, candidate не сформирован, provider observation lost, recovery required, nested Flow unavailable.
+7. Проверить Eval с несколькими executions и fixture с одинаковыми Run ID в разных derived source.
+
+**Готово, когда:** пользователь видит, что произошло в Eval, где именно находится каждый execution и какой Flow действительно ему принадлежит. «Нет Judge» не выводится как score 0, а failed observation не выдаётся за completed.
+
+### Этап 5. Живое наблюдение, производительность и устойчивость
+
+**Цель:** экран остаётся быстрым и честным во время работающего процесса.
+
+1. Ввести ReaderCache: source/entity key, in-flight deduplication, TTL, LRU и ограниченную очередь workers.
+2. Читать file/DB snapshots и сохранённую Eval observation-проекцию. Ни списки, ни details не запускают CLI/provider процессы; при отсутствии свежих фактов возвращаются предыдущая snapshot и diagnostics.
+3. Добавить polling scheduler: selected detail 2 s, overview 5 s, hidden document 30 s, exponential backoff при ошибках, cancel через AbortController при смене route.
+4. Реализовать JSONL tailer с file identity, offset, partial line, parser diagnostics и reset при rotate/truncate. Добавить cursor pagination истории без загрузки целого файла.
+5. Сохранить UI state при данных: ключевые списки обновляются diff-ом; вкладки, focus, scroll и opened disclosures сохраняются. Новые events не принудительно скроллят пользователя.
+6. Добавить telemetry только в локальный log консоли: reader duration, cache hit, bytes, error code. Никакой внешней отправки; экран диагностики может показывать агрегат.
+7. Запустить performance suite на 100 MB journal и трёх browser clients; зафиксировать memory/latency и откорректировать defaults только по результатам.
+
+**Готово, когда:** новые данные появляются в выбранной детали не позднее 5 s в управляемом fixture; одна и та же source не перечитывается отдельно каждой вкладкой; недоступный source не делает интерфейс неотзывчивым.
+
+### Этап 6. Hardening, документация и релиз кандидата
+
+**Цель:** проверить границы локального инструмента и возможность установки без checkout.
+
+1. Пройти security tests для traversal, symlink escape, invalid source/context/cursor, Host/Origin и HTML/JS в artifact/log fields.
+2. Пройти accessibility/browser tests: клавиатурная навигация, skip link, focus order, `aria-current` breadcrumbs, contrast, reduced motion, 320px и широкий экран.
+3. Пройти compatibility fixtures и read-only integration tests на закреплённых поддерживаемых версиях.
+4. Проверить graceful shutdown, занятый порт, port 0, stale registry entry, отсутствующий DD_FLOW_HOME/DD_EVAL_HOME, corrupt JSON config и update во время append journal.
+5. Сформировать usage docs: install, `serve`, sources, URL, где лежит config/log, безопасное завершение, известные ограничения и troubleshooting.
+6. Выполнить clean install + `pack:check`, полный `check`, browser acceptance и manual smoke на macOS в Chrome/встроенном browser.
+7. Подготовить release notes, version, changelog и PR review; публикация и тег — отдельное действие после review.
+
+**Готово, когда:** package запускается без соседних репозиториев, все критерии раздела 8 проходят, а known limitations документированы без выдачи за ошибки пользователя.
+
+### Разбиение на PR и порядок интеграции
+
+| PR | Содержание | Зависит от |
+|---|---|---|
+| 1 | package bootstrap, contracts base, fixture harness | — |
+| 2 | source registry, server shell, routing, safe HTTP policy | PR 1 |
+| 3 | Flow reader + Flow API + contract tests | PR 1, PR 2; producer contract если необходим |
+| 4 | Flow UI/screens/events/artifacts | PR 2, PR 3 |
+| 5 | Eval reader + derived Flow identity | PR 1–3; producer observation contract |
+| 6 | Eval UI, context breadcrumbs | PR 2, PR 4, PR 5 |
+| 7 | polling/cache/tailer/performance | PR 3–6 |
+| 8 | hardening, accessibility, docs, pack/release candidate | PR 1–7 |
+
+Изменения public contract у dd-flow-cli или dd-eval получают отдельный PR в проекте-владельце и объединяются до или вместе с зависящим адаптером. dd-console не меняет рабочие деревья раннеров без явной задачи на этот контракт. Работу вести в feature branches и независимых worktrees; перед параллельной работой закреплять владение общими файлами `contracts`, router и source registry.
+
+## 8. Приёмка первого выпуска
+
+1. Самостоятельный Flow: обзор → RUN → работа → сессия → артефакт; возврат breadcrumbs и Back восстанавливает ожидаемый экран, фильтры и прокрутку.
+2. Eval с несколькими executions: переход в правильный изолированный Flow и обратно; одинаковые короткие RUN ID в разных runtime не смешиваются.
+3. Refresh/direct link на каждом detail экране сохраняет сущность и проверенный контекст.
+4. Running/waiting/failed/recovery/completed, повтор стадии, отсутствующий Judge и отсутствующий usage имеют различимые корректные представления.
+5. Отключённый/удалённый runtime, неподдерживаемая версия и частично записанный журнал не ломают другие источники.
+6. На замороженной fixture до/после просмотра логическое содержимое БД, run projections и evidence совпадает; read-only вызовы не запускают migrations/children. На живом запуске закрытие UI и сервера не меняет жизненный цикл раннера.
+7. Большой журнал (тестовая цель: 100 МБ) читается порциями; refresh читает приращение; три вкладки не создают три независимых перечитывания источника. Замерить память/задержки и записать фактические результаты.
+8. При локально доступном источнике новое событие появляется в выбранном экране в пределах целевых 5 секунд; при задержке чтения отображается freshness. Проверить с управляемым writer fixture и затем живым RUN.
+9. Traversal, symlink за пределы корня, неподдерживаемый Host/Origin и HTML в логе не дают доступ к лишним файлам и исполнение кода.
+10. Навигация клавиатурой, focus после переходов, aria-current в breadcrumbs, читаемые статусы и узкое окно проходят браузерную проверку.
+11. Pack/install smoke подтверждает наличие UI assets и запуск сервера из установленного пакета. Существующие CLI checks, typecheck/lint/build и релевантные тесты проходят.
+
+Для browser CI использовать выбранный Playwright; интерактивная проверка дополняет CI. Read fixtures не содержат секретов и скрытых ответов eval. Проверки Markdown не подтверждают работоспособность readers/UI.
+
+Дополнительные обязательные сценарии приёмки:
+
+12. Пустой старт, add/remove/re-add, второй serve, повреждённый config и исчезнувший source не теряют registry и не создают runtime каталоги.
+13. После перезапуска прямые ссылки на derived Flow и artifact работают без посещения родителя; неверный breadcrumb context не блокирует доступную сущность.
+14. Два проекта в одном source с одинаковыми Run ID различаются. Queued/cancelled/stopped и неизвестные producer статусы не смешиваются с availability.
+15. Ни один UI request не запускает CLI/provider process. Eval без observation export показывает ограниченную доступность; актуальный поддерживаемый Eval проходит полный producer contract test.
+16. Во время индексации 100 МиБ и SQLite lock /healthz остаётся отзывчивым (цель p95 <200 мс); очередь/cache ограничены бюджетом. Пагинация frozen списка не даёт дублей при обновлениях.
+17. Fixture с WAL подтверждает чтение committed данных. На frozen fixture сравниваются логические данные и evidence; на живом RUN отдельно проверяются read-only handles, отсутствие write calls и console child processes: изменение файлов самим раннером не доказывает вмешательство консоли.
+
+Первый release candidate квалифицируется на macOS/Node 26, Chromium и WebKit в Playwright. Package name планируется @deksden-com/dd-console, bin dd-console; доступность имени и видимость проверяются до публикации. Приватность GitHub не определяет видимость npm. До этого поставка проверяется tarball install, публикация не является критерием реализации. Непроверенные версии не объявляются поддерживаемыми.
+
+### Матрица проверок
+
+| Область | Unit/contract | Интеграция | Browser acceptance |
+|---|---|---|---|
+| Source registry/identity | create/load/collision/stale tests | flow/eval fixture | direct URL и bad context |
+| Flow reader | fixtures каждого статуса | read-only real Flow | list → Run → Work → Session |
+| Eval reader | fixtures execution/Judge/recovery | read-only real Eval | Eval → Execution → derived Flow |
+| HTTP/artifacts | URL/method/path/realpath tests | local server | error and attachment behaviour |
+| Navigation | router and context validation | — | breadcrumbs, Back/Forward, focus, scroll |
+| Live updates | cache/tailer/cursor tests | managed writer fixture | freshness and no forced scroll |
+| Package | build manifest test | tarball install | `serve --open` smoke |
+
+Минимум одна проверка в каждой строке обязательна до merge соответствующего PR; полный набор — до release candidate. Результаты real integration не копируют в fixtures, если они могут содержать личные данные или ответы eval.
+
+## 9. Риски и правила принятия решений
+
+| Риск | Ранний сигнал | Решение |
+|---|---|---|
+| Проекции раннеров меняются без совместимого schema | reader fixture перестаёт читаться | заблокировать новый version как unsupported; запросить producer contract, не эвристически угадывать поля |
+| Просмотр вызывает запись | меняется hash/mtime/runtime revision | убрать вызов и перейти на read-only adapter; release блокируется |
+| Журнал большой или пишется одновременно | рост задержки/memory, partial JSON | incremental tail + cursor; ограничить initial page; не читать файл целиком |
+| Два runtime дают одинаковые IDs | ссылка открывает другой Run | source + project обязательны во всех routes/API keys; regression fixture |
+| Неатомарные snapshots создают противоречие | timestamp/revision расходятся | `partial` + freshness; не делать вывод о settlement |
+| Артефакт раскрывает файл за пределами source | realpath выходит из allowlist | отказ с diagnostic, тест traversal/symlink; никаких браузерных путей |
+| UI маскирует отсутствие данных | score/usage/status выглядит окончательным | null + причина + source status; UX test на partial/unavailable |
+| Polling перегружает чтение | рост очереди, несколько вкладок | shared cache, TTL, worker cap; CLI/provider вызовы запрещены |
+| Домашний каталог консоли повреждён | registry/config parse error | сохранить файл; на старте завершиться с diagnostic, при reload удержать последнюю валидную конфигурацию |
+
+Любое решение, расширяющее scope до удалённого доступа, нескольких пользователей, автоматического запуска/остановки процессов, загрузки transcript целиком или хранения evidence, требует отдельного design review. Оно не может войти в первый выпуск как «малое улучшение».
+
+## 10. После первого выпуска
+
+Следующий этап — pause/resume/stop через существующие команды: request ID, expected generation, durable receipt, состояние requested → observed → settled. Scope команды явно показан: весь Eval или отдельный Flow. Не запускать процессы через произвольный shell из API и не считать получение HTTP 200 завершением операции.
+
+Далее по фактической потребности: SSE; расширенный просмотр transcripts; запуск новых flow/eval; удалённые источники с отдельной моделью доступа. Эти возможности не блокируют выпуск живой панели наблюдения.

package/docs/implementation-review.md

@@ -0,0 +1,33 @@
+# Ревью и исправления — 2026-09-13
+
+Все пять незакрытых категорий предыдущего ревью исправлены в dd-console.
+Изменения соседних рабочих checkout не включались в этот коммит.
+
+| Недостаток | Исправление | Проверка |
+| --- | --- | --- |
+| Несогласованное копирование SQLite/WAL | Копирование и временный кеш удалены. `readOnly`, `query_only` и короткая транзакция обеспечивают согласованность запросов одной детали | Конкурентный writer меняет RUN/Work одной транзакцией и выполняет checkpoint; 60 чтений не смешивают ревизии. INSERT/UPDATE через reader запрещены |
+| Только последние 256 KiB/200 событий | Полная история читается обратными страницами от новых событий к старым. Cursor содержит scope/generation/offset и подпись; append его сохраняет, rotate/truncate сбрасывает | 550 событий больше 256 KiB без пропусков/дубликатов, append/partial line, rotate, truncate, неверный scope, oversized/invalid строки |
+| Неполные экраны и навигация | Поиск/фильтры/сортировка в URL; отдельный artifact viewer и фрагменты preview; work/session/check/attempt links; Eval и execution в канонических breadcrumbs вложенного Flow | Chromium/WebKit: переходы до артефакта и обратно, фильтры/Back, клавиатура, polling и экран 320 px |
+| TOCTOU файлов и некорректный derived source | JSON, журналы и артефакты открываются через `openat`/`O_NOFOLLOW` с удержанием дескрипторов каталогов. Чтение, stat и download используют открытый файл. Derived source проверяет manifest и ограничен своим RUN | Traversal, symlink наружу, symlink каталога reports, подмена каталога после открытия, повторное открытие после подмены, metadata/preview/download одной политики |
+| Только ручные SQLite/observation fixtures | Добавлены captures схемы и проекций, созданные producers на пустом временном home, с версиями и commits | Настоящая схема Flow, failure/wait/recovered execution проекции Eval; тесты автономны от соседних checkout |
+
+Дополнительно исправлены: перезапись повреждённого registry из кеша, валидация registry и observation identity, HTML-инъекция через href, потеря фокуса, обрезка таблиц, коллизии составных ключей кеша, кеш страниц без лимита памяти, некорректные API suffix/limit/Host, Unicode на границе preview и освобождение ресурсов при остановке.
+
+Файлы lock используют kernel `flock`: блокировка освобождается при закрытии дескриптора или смерти процесса. Файл lock остаётся на диске для сохранения единственного inode; его наличие не означает работающий сервер. Пустые/старые PID-файлы не мешают новому запуску.
+
+`observed_at` сохраняет время фактического чтения; `served_at` — время ответа. При ошибке чтения доступен предыдущий успешный результат с `reader_stale`. Неизвестное время состояния не заменяется текущим временем. Неподтверждённый Eval context игнорируется с видимым пояснением.
+
+## Проверки
+
+- `npm run check`: typecheck, 25 Node integration/contract tests, 18 Chromium/WebKit tests — пройдено.
+- `npm run pack:check`: чистая установка tarball в другой каталог, native dependency, UI assets, API, запуск и SIGTERM — пройдено.
+- `git diff --check`.
+- Agent-browser: ручной маршрут списка/детали Eval и axe WCAG 2 A/AA, 0 нарушений на проверенном экране списка.
+
+## Уточнения контракта
+
+Read-only SQLite может обновлять служебный SHM read-mark или создавать необходимые sidecars. Это поведение SQLite для согласованного WAL-чтения, разрешённое исходным планом (§4.5, §8): тест сравнивает содержимое основной БД и WAL, а не запрещает штатную работу SHM. Консоль не выполняет миграции или SQL-записи в данные раннера. Байтово неизменяемый архив следует готовить согласованным backup производителя, не копированием живой пары DB/WAL. Основание: [SQLite WAL](https://www.sqlite.org/wal.html) и [Online Backup API](https://sqlite.org/backup.html).
+
+Бюджеты явные: JSON — до 8 MiB, строка журнала — до 1 MiB, чтение journal page — до 4 MiB чанками 256 KiB, preview — до 256 KiB за фрагмент. Превышения не выдаются за полную историю: есть диагностика, признак усечения и ссылка продолжения. Все законченные строки допустимого размера доступны через страницы.
+
+Поддерживаемые версии закреплены в `test/fixtures/contracts/provenance.json`; автоматическая совместимость со всеми будущими версиями не обещается. Отсутствующие у producer факты и связи остаются unknown/partial, а не вычисляются по догадке. Pause/resume/stop и удалённые источники остаются за рамками read-only выпуска.

package/docs/plan-review.md

@@ -0,0 +1,27 @@
+# Результаты перепроверки плана
+
+Первоначально были проверены implementation-plan.md, work-plan.md и выбранные пути текущего кода dd-flow-cli/dd-eval. После review реализованы отдельный dd-console package, read-only сервер/UI, worker pool, cursor snapshots, producer-owned Eval observation и contract/browser tests. Оставшиеся пункты отмечены в work-plan.md и не считаются закрытыми только по наличию документации.
+
+## Исправленные противоречия
+
+- Запрет запускать процессы противоречил live probes в details. Теперь все HTTP readers читают только сохранённые данные, одинаково для списков и деталей.
+- Eval runnerStatus использует reduceEvents и runnerControlStatus. Чтение manifest/report не заменяет это состояние. В плане обязательный producer-owned observation export, а исторические запуски без него имеют явно ограниченную детализацию. Бизнес-reducer в консоли не дублируется.
+- Статусы выполнения были смешаны с availability. Разделены execution_status, availability и control; добавлены queued/cancelled/stopped и правила unknown.
+- Ошибка context раньше блокировала detail через 409, хотя breadcrumbs обещали fallback. Теперь canonical breadcrumb + diagnostic; 409 оставлен для stale cursor.
+- Unsupported source ранее одновременно требовал 422 и видимой сводки. Теперь известные sources возвращают typed availability в 200, ошибочные запросы — отдельные HTTP errors.
+- Node >=22 не соответствовал заявленной доступности node:sqlite. Первый выпуск ограничен Node 26, как текущий dd-flow-cli; отсутствующая поддержка старых Node не подразумевается.
+- tsc не копирует HTML/CSS. Добавлен явный asset build, separate server/web tsconfig и install smoke вне cwd репозитория.
+- Registry corruption больше не ведёт к запуску с пустой конфигурацией и риску её перезаписи.
+- Зависимости PR Flow API/Eval derived reader дополнены зависимостями от server/Flow reader.
+
+## Добавленные сценарии
+
+Первое подключение и отключение источника; пустой старт; повторная регистрация; один сервер на console home; стабильные deep links и derived identities после restart; source/check screens; metadata/preview/download; обновление assets; пагинация меняющегося списка; cold indexing; bounded workers/cache/queue; WAL/SHM; занятый store; лимит строки журнала; дедупликация явно подключённого и вложенного runtime; различие event age и времени последнего успешного чтения.
+
+Артефакты доступны только по публичным зарегистрированным ссылкам, а не по всему содержимому home. Preview и download имеют одну политику. Приёмка расширена проверками restart/config/WAL/no-process/pagination/load и macOS/Node 26/Chromium/WebKit.
+
+## Граница готовности
+
+План готов как последовательность реализации. Это не подтверждение совместимости существующих runtime. Этап 1 обязан произвести compatibility matrix, доказательство read-only чтения и контракт observation export Eval. Если export отсутствует, требуется изменение у владельца dd-eval; этот шаг теперь виден в зависимостях, а не скрыт в адаптере UI.
+
+Источники проверки: dd-flow-cli/src/services/runs.ts (getFlowRunStatus, authoritativeIndex), src/storage/database.ts (getDatabase/read_existing), dd-eval/lib/runner.mjs (runnerStatus/runnerControlStatus), текущий dd-flow-cli/package.json. Доступность SQLite API сверена с [документацией Node](https://nodejs.org/api/sqlite.html).