PLBA2-2. Архивация спек
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped

This commit is contained in:
2026-10-10 20:55:13 +03:00
parent 19fa591c31
commit d517820088
33 changed files with 1313 additions and 25 deletions
@@ -0,0 +1,3 @@
schema: function-driven
created: 2026-10-10
skip_specs: true
@@ -0,0 +1,42 @@
# Design
## Context
Пакету требуется Python 3.11 или новее; он использует setuptools с исходниками в `src/`, объявляет pytest в extra `test` и хранит тесты в `tests/`. Infra v2 поднимает общий Python CI runner на `cloud`; workflow Gitea выбирают его по метке `cloud-build`.
Существующая проверка версии читает базовую версию командой `git show <ref>:pyproject.toml`, поэтому целевая ветка pull request должна присутствовать в локальной истории Git. Мотивация и общий scope приведены в `proposal.md`.
## Goals / Non-Goals
**Goals:**
- Запускать тесты пакета для pull request и push в `main` на build runner infra v2.
- Требовать один допустимый шаг SemVer для каждого pull request.
- Выполнять CI пакета без прав и секретов деплоя приложений.
**Non-Goals:**
- Автоматически публиковать wheel, container image или релиз приложения.
- Деплоить сам PLBA через `infra_v2`.
## Decisions
- Использовать единый `.gitea/workflows/ci.yml` для тестов пакета и проверки версии pull request. Проверки остаются отдельными jobs одного workflow.
- Запускать тесты для pull request и push в `main`. Проверять версию только для pull request, используя `github.base_ref` как целевую ветку.
- Выбирать метку `cloud-build`, соответствующую host runner, зарегистрированному как `cloud-build:host`.
- Использовать Python, установленный для runner; завершать job с понятной ошибкой, если версия ниже 3.11. Устанавливать пакет и test-зависимости через `python -m pip install -e ".[test]"`, затем запускать `python -m pytest`.
- Загружать полную историю Git для job проверки версии и вызывать существующий checker со ссылкой `origin/${{ github.base_ref }}`. Checker использует только стандартную библиотеку Python.
- До `1.0.0` использовать PATCH для исправлений, рефакторинга и документации; MINOR — для новых возможностей и любых изменений публичного контракта, включая несовместимые. Версия `1.0.0` обозначает начало стабильного контракта. Начиная с `1.0.0`, использовать PATCH для совместимых исправлений, MINOR — для совместимых возможностей, MAJOR — для несовместимых изменений публичного контракта.
- Проверка принимает только один допустимый шаг SemVer относительно base pull request. Она не определяет, соответствует ли выбранный компонент типу изменения; это проверяют OpenSpec-планирование и code review.
- Не настраивать доступ к registry или токен деплоя. PLBA является Python-пакетом; публикацией образа и деплоем занимаются репозитории приложений.
## Risks / Trade-offs
- На build runner может оказаться Python ниже 3.11 → проверять версию интерпретатора до установки и выводить обнаруженную версию при ошибке.
- Для установки extra `test` нужен доступ к package index → устанавливать только объявленные зависимости и сохранять ошибки установки в job log.
- Контекст pull request в Gitea должен предоставлять `github.base_ref`, а checkout action — получать целевую ветку → загружать полную историю и использовать тот же контекст, что и текущая проверка версии.
- Внешние структурные заголовки OpenSpec остаются на английском, чтобы инструменты схемы распознавали артефакты; весь пояснительный текст, включая заголовки групп задач и сценариев, оформляется на русском.
## Migration Plan
Заменить version-only workflow объединённым CI workflow. Первый pull request запускает тесты и проверяет версию относительно целевой ветки; последующие push в `main` запускают тестовую job. Production-деплой и миграция данных не затрагиваются.
@@ -0,0 +1,30 @@
# Proposal
## Why
PLBA v2 нужен единый порядок версионирования пакета и автоматические проверки на Gitea runner для Python-проектов. Кроме того, артефакты OpenSpec change должны создаваться на русском языке, а CI должен запускать тесты при push в `main`.
## What Changes
- Требовать от каждого реализованного OpenSpec change отдельную финальную задачу на увеличение версии пакета по правилам SemVer для версий до и после `1.0.0`.
- Проверять версию pull request относительно целевой ветки и запускать Python-тесты для pull request и push в `main` на общем build runner.
- Требовать русский язык для пояснительного текста всех артефактов change: `proposal.md`, `design.md`, `specs/**/*.md` и `tasks.md`.
- Ограничить CI проверками Python-пакета: не публиковать container image и не запускать деплой приложения.
- Увеличить версию пакета ровно один раз: с `0.1.0` до `0.1.1`.
## Capabilities
### New Capabilities
Нет. Изменение добавляет правила разработки и CI-инструменты репозитория, не меняя runtime-поведение PLBA.
### Modified Capabilities
Нет. В `.openspec.yaml` указано `skip_specs: true`, поскольку продуктовые возможности и контракты не меняются.
## Impact
- Обновляет `openspec/config.yaml`, инструкции и шаблоны схемы `function-driven`.
- Добавляет `scripts/check_package_version.py` и workflow Gitea Actions.
- Использует дополнительную зависимость `test`, уже объявленную в `pyproject.toml`.
- Требует Gitea runner `cloud-build` с Python 3.11 или новее; секреты registry и деплоя не нужны.
@@ -0,0 +1,18 @@
# Tasks
## 1. Политика версии пакета
- [x] 1.1 Добавить в `openspec/config.yaml` правила SemVer для версий до и после `1.0.0`; проверить, что правила задач требуют финальную задачу версии для каждого реализуемого изменения.
- [x] 1.2 Добавить финальную задачу версии в шаблон `function-driven` и реализовать `scripts/check_package_version.py`; проверить отклонение неизменённой, ошибочной, пропущенной и пониженной версии.
## 2. CI Python-пакета PLBA
- [x] 2.1 Добавить `.gitea/workflows/ci.yml` для pull request и push в `main` с runner `cloud-build`; проверить события и метку runner в workflow.
- [x] 2.2 Добавить job тестов Python, которая проверяет версию Python 3.11+, устанавливает `.[test]` и запускает `python -m pytest`; сверить команды с `pyproject.toml`.
- [x] 2.3 Добавить job проверки версии для pull request, получать целевую ветку и вызывать `scripts/check_package_version.py`; удалить прежний version-only workflow и проверить ref, передаваемый checker.
- [x] 2.4 Задать русский язык для пояснительного текста каждого изменения в `openspec/config.yaml` и инструкциях `function-driven`; проверить, что правило охватывает proposal, design, specs и tasks.
- [x] 2.5 Перевести пояснительный текст артефактов этого изменения на русский; проверить сохранение обязательных заголовков OpenSpec и технических идентификаторов.
## 3. Версия этого change
- [x] 3.1 Последней задачей увеличить версию в `pyproject.toml` с `0.1.0` до `0.1.1` на один PATCH и проверить её скриптом `scripts/check_package_version.py` относительно базового коммита.
@@ -0,0 +1,2 @@
schema: function-driven
created: 2026-10-09
@@ -0,0 +1,86 @@
# Design
## Context
PLBA2 — библиотека компонентов и runtime. Приложение владеет entrypoint, composition root, бизнес-логикой, рабочими сообщениями, схемой БД и HTTP host. Изменение объединяет десять capabilities, перечисленных в [proposal.md](proposal.md), и использует PLBA v1 как ориентир для workers, health, workflow и business trace.
## Goals / Non-Goals
**Goals:**
- Запускать именованные workers независимо и управлять ими через lifecycle приложения.
- Предоставить единые contracts для lifecycle, health, workflow, HTTP API, application identity, двух слоёв конфигурации и business trace.
- Отделить business trace от технических логов.
- Позволить бизнес-коду читать настройки через `SettingsReader`, не завися от PostgreSQL-адаптера.
**Non-Goals:**
- Не создавать entrypoint, composition root, HTTP server, сервис конфигурации, хранилище/API бизнес-истории.
- Не предоставлять общую очередь рабочих заданий или RabbitMQ API для них; приложение самостоятельно читает и публикует такие сообщения.
- Не выполнять миграции приложения, не реализовывать бизнес-логику workflow и не доставлять технические логи в платформенные системы.
## Decisions
### Runtime и workers
- `runtime/worker` задаёт уникальное стабильное имя worker, его независимый lifecycle, расписание, остановку и health. Отдельных API для запуска или остановки worker нет.
- При старте приложения запускаются workers, у которых `workers.<worker_name>.disabled` отсутствует или равно `false`. `disabled: true` исключает worker из запуска; изменение этого признака действует при следующем запуске приложения.
- Для включённого worker задаётся ровно одно положительное значение: `interval_seconds` или `pause_seconds`. Первый цикл начинается сразу, циклы одного worker не пересекаются. Интервал задаёт период между началами циклов; пауза задаётся после завершения цикла. Изменения расписания из активной конфигурации применяются при планировании следующего цикла.
- Graceful stop завершает текущий цикл и не запускает следующий. `force=true` прерывает активную обработку. Supervisor останавливает все запущенные workers и сообщает имена тех, кто ещё работает.
- Исключение цикла переводит автоматический health worker в `unhealthy`, но не завершает worker: runtime планирует следующий цикл. Превышение интервала даёт `degraded`; успешный следующий цикл восстанавливает автоматический статус `ok`. Итоговый статус — худший из автоматического и прикладного; прикладная health-логика не скрывает ошибку цикла.
### Lifecycle и health приложения
- `runtime/application-lifecycle` запускает все включённые workers; ошибка запуска переводит приложение в `failed`. При остановке lifecycle становится `stopped` после подтверждения остановки всех workers.
- Необязательный положительный `timeout_seconds` ограничивает ожидание ответа на stop-запрос. При истечении возвращается `stopping`, а остановка продолжается; без timeout ожидание не ограничено. Runtime не завершает OS process или HTTP host приложения.
- Health report включает `application_id`, lifecycle и состояния запущенных workers/contributors. Disabled workers не входят в набор ожидаемых компонентов. Статусы компонентов упорядочены `ok < degraded < unhealthy`; `unhealthy` некритичного компонента ограничивается до `degraded`. Отсутствующий некритичный worker даёт как минимум `degraded`, отсутствующий критичный — `unhealthy`. Lifecycle `new`/`failed` даёт `unhealthy`, `starting`/`stopping` — как минимум `degraded`, а `stopped` задаёт общий health `stopped`.
### Единый HTTP API
- `api/http/control-api` предоставляет общий route adapter, который приложение подключает к собственному HTTP host и listener. PLBA2 не запускает сервер и не открывает отдельный порт.
- Adapter предоставляет `GET /health`, `POST /runtime/start`, `POST /runtime/stop` и `GET /runtime/status`. Health делегируется aggregator, управление — lifecycle runtime; отдельные worker routes отсутствуют.
- `GET /health` возвращает health report без пересчёта в adapter. Start/status возвращают lifecycle status. Stop принимает `force` и необязательный положительный `timeout_seconds`; завершённая остановка возвращает HTTP 200 и `stopped`, продолжающаяся после timeout — HTTP 202 и `stopping`, некорректный запрос — HTTP 400.
### Workflow
- Приложение передаёт именованный `WorkflowDefinition` с начальным шагом и именованными узлами. Узел содержит `WorkflowStep` и карту переходов; шаг принимает `WorkflowContext` и возвращает `StepResult` с переходом, изменениями состояния и статусом.
- Engine применяет только объявленные переходы и не содержит бизнес-правил приложения. Переданный `WorkflowPersistence` сохраняет начало и итог запуска, начало и завершение каждого шага, snapshots контекста и ошибки.
- Исключение шага сохраняется и передаётся вызывающему коду; workflow прекращается без скрытого retry и без выполнения следующих шагов. Подключение к БД остаётся ответственностью приложения.
### Идентификатор приложения
- В корневом `config.yaml` приложение может задать необязательный строковый `application_id`. Непустое значение используется без изменений; иначе берётся `[project].name` из `pyproject.toml`, а при недоступности имени генерируется UUIDv4.
- Идентификатор разрешается до запуска зависимых компонентов, предоставляется runtime-контексту и не меняется в процессе. Сгенерированный UUIDv4 создаётся заново при следующем запуске, если имя проекта или значение в файле не заданы.
- Health report и технические логи используют этот ID; business trace adapter добавляет его в `attrs_json` контекста и каждого сообщения.
### Два слоя конфигурации
- `configuration/application-config-file` читает `config.yaml` из корня приложения по объявленной приложением типизированной модели. Общие поля PLBA2 — `application_id`, `workers.<worker_name>.disabled` (default `false`), `interval_seconds` и `pause_seconds`; остальные поля определяет приложение.
- YAML предназначен для редко меняемых технических параметров. Бизнес-параметры, feature toggles и технические значения, меняемые удалённо в runtime, хранятся в `settings`.
- Ошибка начальной загрузки файла блокирует запуск зависимых компонентов. При успешной проверке обновление атомарно заменяет активную конфигурацию без рестарта; уже полученные snapshots остаются неизменными. При ошибке перезагрузки остаётся последняя валидная конфигурация и приложению передаётся ошибка.
- `configuration/application-settings` задаёт таблицу `settings` в схеме приложения. В таблице хранятся `config_key`, `setting_key`, `setting_value`, `sort_order`, `is_enabled` и `description` вместе с идентификатором строки; уникальность `setting_key` не требуется. `is_enabled` включает строку в чтение, а значение feature toggle хранится в `setting_value`.
- Приложение создаёт таблицу `settings` и загружает начальные данные своей миграцией. PLBA2 миграции не запускает, строки не изменяет и YAML в БД не переносит.
- `SettingsReader` использует типизированные ключи и возвращает упорядоченные значения. PostgreSQL adapter читает через переданный приложением pool из его схемы, фильтрует по ключу, `config_key` и `is_enabled = TRUE`, сортирует по `sort_order`, затем `id`. Следующее чтение видит актуальные значения без рестарта.
### Business trace и технические логи
- Business trace adapter записывает контексты в `trace_contexts`, сообщения — в `trace_messages` схемы приложения. Публичный идентификатор называется `business_trace_id`, а в таблицах хранится как `trace_id`. В `attrs_json` обоих видов записей добавляется `application_id`.
- Приложение передаёт адаптеру PostgreSQL pool и имя схемы, а таблицы создаёт собственной миграцией. PLBA2 не владеет данными, не публикует business events в RabbitMQ и не предоставляет API бизнес-истории.
- Техническая запись — JSON-контракт с обязательными `timestamp`, `level`, `logger`, `message`, `application_id` и необязательными `attributes`, `business_trace_id`. Formatter использует stdlib `StreamHandler` для stdout; доставку и просмотр обеспечивает платформа.
## Risks / Trade-offs
- Если приложение не задаёт `application_id` и не имеет `[project].name`, UUIDv4 меняется между запусками; потребителям, которым нужен постоянный ID, следует задать его в `config.yaml`.
- Изменение `workers.<worker_name>.disabled` применяется только при следующем запуске приложения, тогда как валидные изменения расписания применяются при планировании следующего цикла.
- Приложению нужно владеть миграциями `settings`, `trace_contexts` и `trace_messages`, передавать PostgreSQL pool адаптерам и подключить HTTP routes к своему host.
## Migration Plan
1. Реализовать runtime, health, workflow, identity и контракты адаптеров согласно capabilities.
2. Добавить загрузку и перезагрузку `config.yaml`, PostgreSQL adapters для настроек и business trace, а также технический formatter для stdout.
3. Документировать для потребителей, что создание таблиц и начальных данных `settings`, `trace_contexts`, `trace_messages` выполняется миграциями приложения.
4. Подключить route adapter к host приложения и выпустить обновлённую версию библиотеки; миграции и изменение кода потребителей выполняются в самих приложениях.
## Open Questions
Нет. HTTP host и listener принадлежат приложению; PLBA2 предоставляет подключаемый route adapter.
@@ -0,0 +1,30 @@
# Proposal
## Summary
Подготовить PLBA2 — библиотеку Python-компонентов и runtime для приложений. Приложение сохраняет собственные entrypoint, composition root, бизнес-логику и интеграции.
## Scope
- Запускать и останавливать приложение целиком, независимо исполнять именованные workers по расписанию из `config.yaml` и агрегировать их health.
- Разрешать `application_id` из `config.yaml`, метаданных проекта или UUIDv4 и передавать его runtime.
- Предоставить один подключаемый HTTP route adapter для `GET /health`, `POST /runtime/start`, `POST /runtime/stop` и `GET /runtime/status`, использующий host и listener приложения.
- Разделить настройки: редко меняемые технические параметры задаются в корневом `config.yaml`; бизнес-параметры, feature toggles и технические значения для удалённого изменения хранятся в таблице `settings` схемы приложения.
- Поддержать workflow orchestration, запись business trace в таблицы приложения и единый контракт технического JSON-лога в stdout.
## Capabilities
- `runtime/application-lifecycle`: запуск и остановка всего приложения с graceful/force режимами и ограничением времени ожидания.
- `runtime/worker`: независимое циклическое выполнение именованных workers, расписание, health и контролируемая остановка.
- `health/aggregation`: единый health-отчёт приложения и его запущенных компонентов.
- `api/http/control-api`: общий HTTP route adapter для health и lifecycle endpoints на host приложения.
- `runtime/application-identity`: разрешение `application_id` из конфигурации или метаданных проекта с UUIDv4 fallback.
- `configuration/application-config-file`: загрузка и перезагрузка технической конфигурации из корневого `config.yaml`.
- `configuration/application-settings`: контракт таблицы `settings` и чтение бизнес-параметров, feature toggles и удалённо меняемых технических значений из схемы приложения.
- `workflow/orchestration`: выполнение шагов workflow по явным переходам и сохранение хода выполнения.
- `observability/business-tracing`: контракт и PostgreSQL-адаптер записи бизнес-контекстов и сообщений в таблицы приложения.
- `observability/technical-logging`: контракт технической JSON-записи и её передача в stdout.
## Out of scope
PLBA2 не становится приложением или развёртываемым сервисом и не владеет entrypoint, HTTP host, схемой и миграциями приложения. В PLBA2 не входят сервис конфигурации или истории, API бизнес-истории, публикация бизнес-событий в RabbitMQ, общая очередь рабочих сообщений, RabbitMQ consumer/producer для рабочих заданий, бизнес-логика, доставка технических логов и средства развёртывания.
@@ -0,0 +1,280 @@
# Spec Delta
## Purpose
Объединить health и управление lifecycle приложения в одном HTTP API, подключаемом к host приложения.
## ADDED Requirements
### Requirement: Единый HTTP adapter
**ID:** `API.HTTP.CA-01`
PLBA2 SHALL предоставлять один route adapter для всех HTTP endpoints управления приложением; adapter подключается к host приложения и использует его единственный listener.
#### Scenario: Сокращенный use case: подключение control API
##### Основной поток
1. Приложение подключает route adapter к своему host по [API.HTTP.CA-01.FR-01](#apihttpca-01fr-01-подключение-к-host-приложения).
#### Функциональные требования
##### API.HTTP.CA-01.FR-01: Подключение к host приложения
Приложение подключает route adapter к собственному HTTP host. Все endpoints control API используют его listener и порт. PLBA2 не запускает HTTP server и не открывает отдельный порт; adapter делегирует обработку соответствующим capabilities.
### Requirement: Health через GET /health
**ID:** `API.HTTP.CA-02`
PLBA2 SHALL возвращать агрегированный health report приложения через GET /health.
#### Scenario: Получение health-отчёта через GET /health
##### Участники
- HTTP-клиент, route adapter PLBA2 и health aggregator.
##### Предусловия
- Control API подключён к host приложения.
- Health aggregator получает состояния зарегистрированных workers и contributors.
##### Основной поток
1. Клиент вызывает GET /health; adapter получает запрос.
2. Adapter запрашивает агрегированный health report по [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов).
3. Adapter сериализует report по [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) и завершает с HEALTH_RESPONSE_RETURNED.
##### Альтернативы и ошибки
- Aggregator отклоняет некорректное состояние компонента — adapter передаёт ошибку с кодом HEALTH_INPUT_INVALID по [API.HTTP.CA-02.FR-02](#apihttpca-02fr-02-ошибка-источника-health).
##### Результат
Клиент получает текущий агрегированный health status, lifecycle и состояния компонентов приложения.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `HEALTH_RESPONSE_RETURNED` | Агрегированный health report сериализован и возвращён клиенту | [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) |
| `HEALTH_INPUT_INVALID` | Aggregator отклонил некорректное состояние компонента | [API.HTTP.CA-02.FR-02](#apihttpca-02fr-02-ошибка-источника-health) |
#### Функциональные требования
##### API.HTTP.CA-02.FR-01: Сериализация health-отчёта
Adapter возвращает без пересчёта агрегированный health report, включая application_id, lifecycle, итоговый status и состояния компонентов; при успешной сериализации завершает с HEALTH_RESPONSE_RETURNED. Правила агрегирования и состав report задаёт [HL.AG-01](../../../health/aggregation/spec.md).
##### API.HTTP.CA-02.FR-02: Ошибка источника health
Если health aggregator отклоняет входное состояние, adapter передаёт ошибку HEALTH_INPUT_INVALID и не подменяет причину или повторно не рассчитывает статусы.
#### CONTRACT
##### Request
Метод: `GET`; путь: `/health`. Тело запроса и query-параметры отсутствуют.
##### Response
HTTP status: 200 при успешной сериализации health report.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `application_id` | `string` | Обязательное | null запрещён | Идентификатор приложения | Берётся из runtime context по [RT.AI-01.FR-01](../../../runtime/application-identity/spec.md#rtai-01fr-01-разрешение-идентификатора) |
| `lifecycle` | `string` | Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Lifecycle приложения | Копируется из runtime state по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки) |
| `status` | `string` | Обязательное | ok, degraded, unhealthy или stopped; null запрещён | Итоговый health status приложения | Рассчитывается aggregator согласно [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов) и [HL.AG-01.FR-02](../../../health/aggregation/spec.md#hlag-01fr-02-результат-агрегации) |
| `components` | `array<object>` | Обязательное | null запрещён; пустой массив допустим | Health-состояния workers и contributors | Содержит состояния, переданные aggregator; workers с disabled: true исключены |
| `components[].name` | `string` | Обязательное | null запрещён | Имя worker или health contributor | Копируется из имени, с которым компонент зарегистрирован в приложении |
| `components[].status` | `string` | Обязательное | ok, degraded или unhealthy; null запрещён | Health status компонента | Копируется из переданного компонентом health-состояния |
| `components[].critical` | `boolean` | Обязательное | null запрещён | Влияние компонента на общий health | Копируется из признака critical, переданного при регистрации или health-отчёте |
| `components[].detail` | `string or null` | Обязательное | null допустим | Краткое пояснение состояния | Копируется из detail health-состояния; при отсутствии передаётся null |
| `components[].meta` | `object` | Обязательное | null запрещён | Дополнительные структурированные данные | Копируется из meta health-состояния; при отсутствии передаётся пустой объект |
### Requirement: Запуск приложения через POST /runtime/start
**ID:** `API.HTTP.CA-03`
PLBA2 SHALL запускать приложение по запросу POST /runtime/start и возвращать итоговый lifecycle status.
#### Scenario: Запуск приложения через POST /runtime/start
##### Участники
- HTTP-клиент, route adapter PLBA2, runtime и workers приложения.
##### Предусловия
- Control API подключён, workers зарегистрированы, конфигурация приложения загружена.
##### Основной поток
1. Клиент вызывает POST /runtime/start без тела запроса.
2. Adapter запускает приложение по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения).
3. Adapter возвращает итоговый lifecycle status по [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) и завершает с APPLICATION_STARTED.
##### Альтернативы и ошибки
- Не удалось запустить один или несколько workers — runtime получает status failed, adapter возвращает его с кодом APPLICATION_START_FAILED по [API.HTTP.CA-03.FR-02](#apihttpca-03fr-02-ошибка-запуска).
##### Результат
Клиент получает lifecycle status после попытки запуска приложения.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STARTED` | Приложение перешло в lifecycle status running | [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) |
| `APPLICATION_START_FAILED` | Запуск приложения завершился ошибкой; lifecycle status равен failed | [API.HTTP.CA-03.FR-02](#apihttpca-03fr-02-ошибка-запуска) |
#### Функциональные требования
##### API.HTTP.CA-03.FR-01: Результат запуска
Adapter делегирует запуск runtime по [RT.AL-01](../../../runtime/application-lifecycle/spec.md), возвращает APPLICATION_STARTED после успешного запуска и lifecycle status running.
##### API.HTTP.CA-03.FR-02: Ошибка запуска
Если запуск одного или нескольких workers завершается ошибкой, runtime устанавливает status failed; adapter возвращает APPLICATION_START_FAILED и status failed.
#### CONTRACT
##### Request
Метод: `POST`; путь: `/runtime/start`. Тело запроса отсутствует.
##### Response
HTTP status: 200 после обработки запроса запуска; результат запуска передаётся в поле status.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | running или failed; null запрещён | Итоговый lifecycle status после запуска | running после APPLICATION_STARTED; failed после APPLICATION_START_FAILED |
### Requirement: Остановка приложения через POST /runtime/stop
**ID:** `API.HTTP.CA-04`
PLBA2 SHALL останавливать приложение через POST /runtime/stop и возвращать его актуальный lifecycle status.
#### Scenario: Остановка приложения через POST /runtime/stop
##### Участники
- HTTP-клиент, route adapter PLBA2, runtime, supervisor и workers приложения.
##### Предусловия
- Control API подключён, приложение запущено, workers зарегистрированы.
##### Основной поток
1. Клиент передаёт параметры остановки в теле POST /runtime/stop.
2. Adapter валидирует запрос и делегирует остановку по [RT.AL-02.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-02fr-01-режимы-остановки-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки).
3. Adapter возвращает stopped или stopping по [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) с кодом APPLICATION_STOPPED или APPLICATION_STOPPING.
##### Альтернативы и ошибки
- Таймаут ожидания истёк — остановка продолжается, adapter возвращает HTTP 202 и APPLICATION_STOPPING.
- Тело или значение timeout невалидно — adapter возвращает HTTP 400 с кодом HTTP_CONTROL_REJECTED по [API.HTTP.CA-04.FR-01](#apihttpca-04fr-01-валидация-запроса-остановки).
##### Результат
Клиент получает status stopped после завершения workers либо stopping, пока приложение завершает их работу.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STOPPED` | Все workers остановлены; ответ содержит stopped | [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) |
| `APPLICATION_STOPPING` | Остановка продолжается после истечения времени ожидания API | [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) |
| `HTTP_CONTROL_REJECTED` | Параметры stop-запроса отклонены | [API.HTTP.CA-04.FR-01](#apihttpca-04fr-01-валидация-запроса-остановки) |
#### Функциональные требования
##### API.HTTP.CA-04.FR-01: Валидация запроса остановки
Adapter принимает объект запроса по контракту ниже; невалидное тело или значение timeout_seconds отклоняется с HTTP 400 и кодом HTTP_CONTROL_REJECTED. Правила остановки определяет [RT.AL-02](../../../runtime/application-lifecycle/spec.md).
##### API.HTTP.CA-04.FR-02: Результат остановки
Без timeout_seconds adapter ожидает завершения всех workers без ограничения времени. force=true прерывает активную обработку; timeout ограничивает ожидание ответа и не включает force. Если workers завершились, adapter возвращает HTTP 200, status stopped и APPLICATION_STOPPED. При истечении timeout он возвращает HTTP 202, status stopping и APPLICATION_STOPPING; остановка продолжается.
#### CONTRACT
##### Request
Метод: `POST`; путь: `/runtime/stop`. Тело запроса — JSON object.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- |
| `force` | `boolean` | Опциональное | null запрещён; по умолчанию false | Принудительно прервать активную обработку workers |
| `timeout_seconds` | `number` | Опциональное | Положительное число секунд; null запрещён; отсутствие означает неограниченное ожидание | Ограничить время ожидания завершения workers |
##### Response
HTTP status: 200, если остановка завершена; 202, если она продолжается после истечения timeout; 400 для отклонённого запроса.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | Для HTTP 200 — stopped; для HTTP 202 — stopping; null запрещён | Текущий lifecycle status приложения | Берётся из runtime: stopped после остановки всех workers; stopping, пока их остановка продолжается |
### Requirement: Lifecycle status через GET /runtime/status
**ID:** `API.HTTP.CA-05`
PLBA2 SHALL возвращать текущее lifecycle status приложения через GET /runtime/status.
#### Scenario: Чтение lifecycle status через GET /runtime/status
##### Участники
- HTTP-клиент, route adapter PLBA2 и runtime приложения.
##### Предусловия
- Control API подключён к host приложения.
##### Основной поток
1. Клиент вызывает GET /runtime/status.
2. Adapter читает lifecycle status без запуска или остановки компонентов по [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status).
3. Adapter возвращает status с кодом APPLICATION_STATUS_RETURNED.
##### Альтернативы и ошибки
- Приложение ещё не запускалось или уже остановлено — endpoint возвращает соответственно new или stopped.
##### Результат
Клиент получает текущее lifecycle status приложения без изменения его состояния.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STATUS_RETURNED` | Текущее lifecycle status сериализовано и возвращено клиенту | [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status) |
#### Функциональные требования
##### API.HTTP.CA-05.FR-01: Чтение lifecycle status
Adapter читает status без побочных действий и завершает с APPLICATION_STATUS_RETURNED по [RT.AL-01](../../../runtime/application-lifecycle/spec.md) и [RT.AL-02](../../../runtime/application-lifecycle/spec.md).
#### CONTRACT
##### Request
Метод: `GET`; путь: `/runtime/status`. Тело запроса и query-параметры отсутствуют.
##### Response
HTTP status: 200 при успешном чтении lifecycle status.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Текущее lifecycle status приложения | Копируется без пересчёта из runtime state по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки) |
@@ -0,0 +1,99 @@
# Spec Delta
## Purpose
Предоставлять приложению загрузчик редко меняемых технических параметров из `config.yaml` с поддержкой перезагрузки без рестарта.
## ADDED Requirements
### Requirement: Загрузка технической конфигурации из файла
**ID:** `CFG.ACF-01`
PLBA2 SHALL загружать техническую конфигурацию приложения из `config.yaml` в корне приложения и предоставлять её в типизированном виде до запуска компонентов, которые от неё зависят.
#### Scenario: Начальная загрузка технической конфигурации
##### Участники
- Приложение, загрузчик YAML-конфигурации и файл `config.yaml`.
##### Предусловия
- В корне приложения находится `config.yaml`; приложение объявило типизированную модель своей конфигурации.
##### Основной поток
1. Загрузчик читает `config.yaml` и проверяет его по модели приложения.
2. Загрузчик предоставляет приложению типизированную конфигурацию до запуска зависимых компонентов и сообщает `APP_CONFIG_LOADED` по [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки).
##### Альтернативы и ошибки
- Файл отсутствует, содержит некорректный YAML или не соответствует модели — запуск приложения завершается с `APP_CONFIG_LOAD_FAILED` по [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки).
##### Результат
Зависимые компоненты получают техническую конфигурацию приложения из валидного файла.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APP_CONFIG_LOADED` | Файл прочитан, проверен и предоставлен приложению | [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки) |
| `APP_CONFIG_LOAD_FAILED` | Файл отсутствует или не соответствует формату либо модели приложения | [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки) |
#### Функциональные требования
##### CFG.ACF-01.FR-01: Файл и модель технической конфигурации
Стандартный файл называется `config.yaml` и располагается в корне приложения. PLBA2 определяет общее необязательное строковое поле `application_id` и поля workers: `workers.<worker_name>.disabled` (boolean, по умолчанию `false`), `workers.<worker_name>.interval_seconds` и `workers.<worker_name>.pause_seconds`. При `disabled: true` worker не запускается; если поле не задано, worker запускается. Остальные поля YAML и типизированную модель приложения определяет само приложение. В файле находятся редко меняемые технические параметры приложения. Бизнес-параметры, feature toggles и технические значения, которые требуется менять удалённо во время работы приложения, хранятся через capability `configuration/application-settings` в таблице `settings` и не входят в `config.yaml`.
##### CFG.ACF-01.FR-02: Результат загрузки
Загрузчик разбирает YAML по типизированной модели приложения и предоставляет проверенную конфигурацию до запуска зависимых компонентов. При отсутствии файла, ошибке разбора или ошибке проверки модели возвращается `APP_CONFIG_LOAD_FAILED`, запуск приложения прекращается. Успешная загрузка завершается с `APP_CONFIG_LOADED`.
### Requirement: Перезагрузка технической конфигурации без рестарта
**ID:** `CFG.ACF-02`
PLBA2 SHALL подхватывать валидные изменения `config.yaml` во время работы приложения без перезапуска процесса.
#### Scenario: Изменение технической конфигурации во время работы
##### Участники
- Приложение, загрузчик YAML-конфигурации и файл `config.yaml`.
##### Предусловия
- Приложение работает с успешно загруженной технической конфигурацией.
##### Основной поток
1. Загрузчик обнаруживает изменение `config.yaml` и проверяет новое содержимое по модели приложения.
2. Валидная конфигурация заменяет текущую; последующие чтения получают новое значение без рестарта, операция завершается с `APP_CONFIG_RELOADED` по [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки).
##### Альтернативы и ошибки
- Новое содержимое невалидно — приложение продолжает использовать последнюю валидную конфигурацию, а загрузчик сообщает `APP_CONFIG_RELOAD_FAILED` по [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки).
##### Результат
После успешной перезагрузки новые чтения используют обновлённую конфигурацию; процесс приложения продолжает работу без рестарта.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APP_CONFIG_RELOADED` | Новая валидная конфигурация активирована без рестарта | [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки) |
| `APP_CONFIG_RELOAD_FAILED` | Изменённый файл не прошёл проверку; активна последняя валидная конфигурация | [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки) |
#### Функциональные требования
##### CFG.ACF-02.FR-01: Замена активной конфигурации
Загрузчик обнаруживает изменения файла и проверяет их по модели приложения. После успешной проверки он атомарно заменяет текущую конфигурацию; все последующие чтения получают новую конфигурацию, а уже полученные снимки остаются неизменными. Перезапуск приложения не требуется.
##### CFG.ACF-02.FR-02: Результат перезагрузки
Успешная проверка и замена завершаются с `APP_CONFIG_RELOADED`. Если файл не читается, YAML не разбирается или новое содержимое не соответствует модели, загрузчик оставляет активной последнюю валидную конфигурацию, сообщает приложению ошибку и завершает попытку с `APP_CONFIG_RELOAD_FAILED`.
@@ -0,0 +1,145 @@
# Spec Delta
## Purpose
Давать приложениям общий контракт хранения бизнес-параметров и технических значений, которые должны меняться в runtime без рестарта.
## ADDED Requirements
### Requirement: Контракт хранения настроек
**ID:** `CFG.AS-01`
PLBA2 SHALL определять назначение полей и структуру таблицы для бизнес-параметров и технических значений, которыми приложение управляет в runtime.
#### Scenario: Сокращенный use case: структура настроек
##### Основной поток
1. Фиксируем поля таблицы `settings`, их назначение и ограничения по [CFG.AS-01.FR-01](#cfgas-01fr-01-db-таблица-хранения-settings).
#### Функциональные требования
##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings
Таблица `settings` создаётся в схеме приложения и содержит:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки |
| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения |
| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки |
| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки |
| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей |
| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении |
| `description` | `TEXT` | NULL | Пояснение к настройке |
Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается. Приложение владеет DDL, данными и связями `config_key` со своими сущностями.
В `settings` хранятся бизнес-параметры, feature toggles и технические значения, которые нужно менять удалённо во время работы приложения. Feature toggle хранится в `setting_value`; `is_enabled` только включает или исключает строку из чтения. Редко меняемые технические параметры задаются отдельным файлом `config.yaml`.
### Requirement: Загрузка настроек
**ID:** `CFG.AS-02`
Приложение SHALL загружать начальные настройки в собственную базу данных миграцией при установке или первой раскатке.
#### Scenario: Загрузка начальных настроек
##### Участники
- Миграция приложения и база данных приложения.
##### Предусловия
- База данных приложения доступна для применения миграции.
##### Основной поток
1. Миграция создаёт нужное приложению хранилище по [CFG.AS-01.FR-01](#cfgas-01fr-01-db-таблица-хранения-settings).
2. Миграция записывает начальные значения непосредственно в базу приложения и завершается с `SETTINGS_LOADED` по [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки).
##### Альтернативы и ошибки
- Миграция не может создать хранилище или записать значения — загрузка завершается с `SETTINGS_LOAD_FAILED` по [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки).
##### Результат
Настройки приложения доступны в его базе до запуска использующего их кода.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `SETTINGS_LOADED` | Миграция записала настройки в базу приложения | [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки) |
| `SETTINGS_LOAD_FAILED` | Миграция не создала хранилище или не записала настройки | [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки) |
#### Функциональные требования
##### CFG.AS-02.FR-01: Загрузка миграцией
Приложение создаёт таблицу `settings` и загружает начальные значения собственными миграциями при первой раскатке. Последующие значения бизнес-параметров и технических параметров, меняемых удалённо, могут обновляться в БД без рестарта приложения. PLBA2 не запускает миграции, не управляет изменением строк и не переносит YAML-конфигурацию в `settings`; конфигурация из `config.yaml` является отдельным слоем.
##### CFG.AS-02.FR-02: Результат загрузки
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `SETTINGS_LOADED` | Сообщение отсутствует | Приложение может запускать компоненты, которым нужны загруженные настройки |
| `SETTINGS_LOAD_FAILED` | Исходная ошибка миграции доступна инструменту установки | Раскатка не считается успешной; приложение исправляет причину и повторно применяет миграцию по правилам своего инструмента |
### Requirement: Чтение настроек
**ID:** `CFG.AS-03`
PLBA2 SHALL предоставлять типизированный контракт чтения настроек и PostgreSQL-адаптер, читающий данные из схемы приложения.
#### Scenario: Чтение настроек приложения
##### Участники
- Бизнес-модуль, SettingsReader, PostgreSQL-адаптер и база данных приложения.
##### Предусловия
- Приложение объявило типизированный ключ с decoder и передало адаптеру пул PostgreSQL и имя своей схемы.
##### Основной поток
1. Запрашиваем включённые записи по ключу и, если задана, области `config_key` в порядке контракта по [CFG.AS-03.FR-02](#cfgas-03fr-02-postgresql-адаптер).
2. Декодируем значения и возвращаем их через SettingsReader с кодом `SETTING_READ` по [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения).
##### Альтернативы и ошибки
- Нет обязательного значения — возвращаем `SETTING_NOT_FOUND`; decoder отклонил значение — `SETTING_INVALID`; PostgreSQL недоступен — `SETTINGS_DATABASE_UNAVAILABLE`, согласно [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения).
##### Результат
Бизнес-код использует типизированный контракт независимо от конкретного адаптера хранения.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `SETTING_READ` | Значения прочитаны и декодированы в исходном порядке | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) |
| `SETTING_NOT_FOUND` | Отсутствует обязательная настройка | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) |
| `SETTING_INVALID` | Значение не прошло decoder приложения | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) |
| `SETTINGS_DATABASE_UNAVAILABLE` | Запрос к базе приложения завершился ошибкой | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) |
#### Функциональные требования
##### CFG.AS-03.FR-01: Контракт SettingsReader
SettingsReader принимает типизированный ключ настройки и необязательный `config_key`, возвращает упорядоченный список значений типа ключа. Для ключа приложение задаёт decoder и обязательность или default. Каждый вызов использует актуальное значение источника настроек; удалённое изменение применяется при следующем чтении без рестарта приложения. Бизнес-код зависит от контракта, а не от SQL или драйвера БД.
##### CFG.AS-03.FR-02: PostgreSQL-адаптер
Адаптер читает `settings` схемы приложения через переданный приложением пул. Он фильтрует по `setting_key`, заданному `config_key` и `is_enabled = TRUE`, сохраняя порядок `sort_order`, затем `id`. Значения запроса параметризуются; имя схемы валидируется и безопасно экранируется. Адаптер не создаёт таблицу, не запускает миграции и не владеет настройками.
##### CFG.AS-03.FR-03: Результат чтения
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `SETTING_READ` | Сообщение отсутствует | Декодированные значения передаются приложению в порядке контракта |
| `SETTING_NOT_FOUND` | Сообщение отсутствует | Для обязательного ключа возвращается типизированная ошибка; default применяется только по настройке ключа |
| `SETTING_INVALID` | Сообщение отсутствует; исходная ошибка decoder доступна приложению | Значение не выдаётся как успешно прочитанное |
| `SETTINGS_DATABASE_UNAVAILABLE` | Сообщение отсутствует; исходная ошибка драйвера передаётся приложению | PLBA2 не подменяет ошибку default-значением и не выполняет скрытый retry |
@@ -0,0 +1,58 @@
# Spec Delta
## Purpose
Агрегировать текущий health приложения из runtime, workers и health contributors.
## ADDED Requirements
### Requirement: Агрегация health-состояния
**ID:** `HL.AG-01`
Health aggregator SHALL формировать единый отчёт по lifecycle приложения и текущему состоянию компонентов.
#### Scenario: Получение health-отчёта
##### Участники
- Приложение, runtime, workers и health contributors.
##### Предусловия
- Каждый worker и contributor предоставляет состояние по health-контракту.
##### Основной поток
1. Собираем состояния runtime и компонентов — aggregator формирует отчёт по [HL.AG-01.FR-01](#hlag-01fr-01-состав-и-приоритет-статусов).
2. Рассчитываем общий статус и завершаем с `HEALTH_REPORT_CREATED` по [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации).
##### Альтернативы и ошибки
- Входной статус не соответствует контракту — возвращаем `HEALTH_INPUT_INVALID` по [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации).
##### Результат
Приложение получает единый статус и детализацию состояния каждого запущенного worker.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `HEALTH_REPORT_CREATED` | Отчёт сформирован из валидных состояний | [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации) |
| `HEALTH_INPUT_INVALID` | Состояние не соответствует health-контракту | [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации) |
#### Функциональные требования
##### HL.AG-01.FR-01: Состав и приоритет статусов
Worker сообщает status, critical, detail и meta через health-контракт. Отчёт содержит application_id, lifecycle приложения и состояния каждого запущенного worker/contributor. Worker с `disabled: true` исключён из набора ожидаемых компонентов и не ухудшает health. Статусы упорядочены как `ok < degraded < unhealthy`; применяется худший итоговый статус. Для критичного компонента учитывается переданный status. Для некритичного компонента `unhealthy` ограничивается до `degraded`; отсутствие некритичного worker также даёт не ниже `degraded`. Отсутствующий критичный worker даёт `unhealthy`. Lifecycle `new` и `failed` даёт `unhealthy`, `starting` и `stopping` — не ниже `degraded`. Когда lifecycle приложения `stopped`, общий health status — `stopped` независимо от прежних статусов компонентов.
##### HL.AG-01.FR-02: Результат агрегации
Health-статус является данными. Валидные агрегированные `ok`, `degraded`, `unhealthy` и `stopped` возвращаются в отчёте; `stopped` обозначает lifecycle приложения, а статусы запущенных worker/contributor остаются `ok`, `degraded` или `unhealthy`. Ошибка появляется только при нарушении контракта входного состояния.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `HEALTH_REPORT_CREATED` | Сообщение отсутствует | Отчёт возвращается вызывающему коду для представления клиенту |
| `HEALTH_INPUT_INVALID` | Сообщение отсутствует; ошибка контракта передаётся вызывающему коду | Отчёт не формируется; приложение исправляет contributor |
@@ -0,0 +1,86 @@
# Spec Delta
## Purpose
Сохранять ход бизнес-операций в trace_contexts и trace_messages схемы приложения.
## ADDED Requirements
### Requirement: Персистентная бизнес-история
**ID:** `OBS.BT-01`
PLBA2 SHALL предоставлять приложению контракт и PostgreSQL-адаптер для записи бизнес-контекстов и сообщений в БД приложения.
#### Scenario: Запись сообщения бизнес-операции
##### Участники
- Прикладной workflow, business trace adapter и схема БД приложения.
##### Предусловия
- Приложение установило business trace context и передало адаптеру пул PostgreSQL и схему приложения.
##### Основной поток
1. Создаём контекст — адаптер сохраняет его в `trace_contexts` по [OBS.BT-01.FR-01](#obsbt-01fr-01-db-таблица-хранения-tracecontexts).
2. Записываем шаг операции — адаптер сохраняет сообщение в `trace_messages` по [OBS.BT-01.FR-02](#obsbt-01fr-02-db-таблица-хранения-tracemessages) и завершает с `BUSINESS_TRACE_WRITTEN` по [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи).
##### Альтернативы и ошибки
- PostgreSQL недоступен или запись не выполнена — исходная ошибка передаётся приложению с `BUSINESS_TRACE_WRITE_FAILED` по [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи).
##### Результат
Бизнес-события сохранены отдельно от технических JSON-логов.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `BUSINESS_TRACE_WRITTEN` | Контекст или сообщение сохранены | [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи) |
| `BUSINESS_TRACE_WRITE_FAILED` | Запись в бизнес trace хранилище завершилась ошибкой | [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи) |
#### Функциональные требования
##### OBS.BT-01.FR-01 [DB]: Таблица хранения trace_contexts
Таблица `trace_contexts` создаётся в схеме приложения и содержит:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `trace_id` | `UUID` | NOT NULL, primary key | Публичный `business_trace_id` контекста |
| `parent_id` | `UUID` | NULL | `trace_id` родительского контекста |
| `alias` | `TEXT` | NOT NULL | Короткое имя контекста |
| `trace_type` | `TEXT` | NOT NULL | Тип бизнес-операции |
| `event_time` | `TIMESTAMPTZ` | NOT NULL | Время создания контекста |
| `attrs_json` | `JSONB` | NOT NULL | JSON-атрибуты контекста, включая `application_id` по RT.AI-01.FR-01 |
Создаются индексы по `parent_id` и `event_time`. Таблица принадлежит приложению.
##### OBS.BT-01.FR-02 [DB]: Таблица хранения trace_messages
Таблица `trace_messages` создаётся в схеме приложения и содержит:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор сообщения |
| `trace_id` | `UUID` | NOT NULL | `trace_id` контекста |
| `event_time` | `TIMESTAMPTZ` | NOT NULL | Время сообщения |
| `step` | `TEXT` | NOT NULL | Имя шага бизнес-операции |
| `status` | `TEXT` | NOT NULL | Результат шага |
| `level` | `TEXT` | NOT NULL | Уровень бизнес-сообщения |
| `message` | `TEXT` | NOT NULL | Текст бизнес-сообщения |
| `attrs_json` | `JSONB` | NOT NULL | JSON-атрибуты сообщения, включая `application_id` по [RT.AI-01.FR-01](../../runtime/application-identity/spec.md#rtai-01fr-01-разрешение-идентификатора) |
Поле `trace_id` ссылается на `trace_contexts.trace_id` с каскадным удалением. Создаются индексы по `trace_id`, `event_time` и `status`. Таблица принадлежит приложению.
##### OBS.BT-01.FR-03: Результат записи
Приложение передаёт адаптеру пул PostgreSQL и имя своей схемы. Адаптер записывает контексты и сообщения по [OBS.BT-01.FR-01](#obsbt-01fr-01-db-таблица-хранения-tracecontexts) и [OBS.BT-01.FR-02](#obsbt-01fr-02-db-таблица-хранения-tracemessages), добавляя `application_id` в `attrs_json` обоих типов записей. Приложение создаёт таблицы своей миграцией; PLBA2 не запускает миграции, не владеет данными, не публикует события в RabbitMQ и не реализует API истории.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `BUSINESS_TRACE_WRITTEN` | Сообщение отсутствует | Выполнение бизнес-сценария продолжается по решению приложения |
| `BUSINESS_TRACE_WRITE_FAILED` | Сообщение отсутствует; исходная ошибка БД передаётся приложению | PLBA2 не выполняет скрытый retry; приложение выбирает политику ошибки |
@@ -0,0 +1,40 @@
# Spec Delta
## Purpose
Формировать единые технические JSON-логи в stdout с application_id и business_trace_id.
## ADDED Requirements
### Requirement: Структурированные технические логи
**ID:** `OBS.TL-01`
PLBA2 SHALL задавать контракт технической JSON-записи и передавать её в stdout.
#### Scenario: Сокращенный use case: техническая запись
##### Основной поток
1. Описываем поля отправляемой записи по [OBS.TL-01.FR-01](#obstl-01fr-01-api-контракт-сообщения-технической-записи).
2. Фиксируем контекст и вывод записи в stdout по [OBS.TL-01.FR-02](#obstl-01fr-02-контекст-и-передача-в-stdout).
#### Функциональные требования
##### OBS.TL-01.FR-01 [API]: Контракт сообщения технической записи
Тип контракта: request
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- |
| `timestamp` | `string` | Обязательное | UTC timestamp; null запрещён | Время формирования записи |
| `level` | `string` | Обязательное | Null запрещён | Уровень технической записи |
| `logger` | `string` | Обязательное | Null запрещён | Имя logger |
| `message` | `string` | Обязательное | Null запрещён | Текст записи |
| `application_id` | `string` | Обязательное | Null запрещён | Идентификатор приложения |
| `attributes` | `object` | Опциональное | Значения должны быть JSON-safe | Структурированные поля записи |
| `business_trace_id` | `string` | Опциональное | Передаётся при установленном business trace context | Связь технической записи с бизнес-историей |
##### OBS.TL-01.FR-02: Контекст и передача в stdout
При установленном контексте formatter добавляет `business_trace_id`; контекст поддерживает async-задачи и использует то же значение, что business trace adapter. JSON кодируется стандартным сериализатором. Приложение направляет formatter в stdlib StreamHandler для stdout. PLBA2 не отправляет технические логи в БД, RabbitMQ, Loki или Grafana; доставку и просмотр обеспечивает платформа.
@@ -0,0 +1,48 @@
# Spec Delta
## Purpose
Определять `application_id` приложения и предоставлять разрешённое значение runtime-контексту.
## ADDED Requirements
### Requirement: Разрешение идентификатора приложения
**ID:** `RT.AI-01`
PLBA2 SHALL разрешать `application_id` до запуска зависящих от него компонентов и предоставлять значение runtime.
#### Scenario: Определение идентификатора приложения
##### Участники
- Файл `config.yaml`, метаданные проекта, загрузчик конфигурации и runtime приложения.
##### Предусловия
- Файл `config.yaml` успешно загружен; поле `application_id` и метаданные проекта могут отсутствовать.
##### Основной поток
1. Разрешаем `application_id` по приоритету источников согласно [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора).
2. Предоставляем значение runtime-контексту; операция завершается с `APPLICATION_ID_RESOLVED` по [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора).
##### Альтернативы и ошибки
- `application_id` не задан, а `pyproject.toml` или `[project].name` отсутствует — генерируем UUIDv4; результат тот же.
##### Результат
Runtime-контекст содержит один `application_id`, неизменный в течение работы процесса.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_ID_RESOLVED` | Идентификатор выбран и предоставлен runtime | [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора) |
#### Функциональные требования
##### RT.AI-01.FR-01: Разрешение идентификатора
В корневом `config.yaml` приложение может задать необязательное строковое поле `application_id`. Непустое значение используется без изменений. Если значение отсутствует или пустое, PLBA2 использует имя проекта из `[project].name` в `pyproject.toml`. Если файл, секция или имя проекта недоступны, PLBA2 генерирует случайный UUIDv4. Идентификатор разрешается один раз до запуска зависящих компонентов, предоставляется runtime-контексту и остаётся неизменным в течение работы процесса; UUIDv4 при новом запуске генерируется заново. Успешное разрешение завершается с `APPLICATION_ID_RESOLVED`.
@@ -0,0 +1,106 @@
# Spec Delta
## Purpose
Управлять lifecycle всего приложения через runtime-контракт, сохраняя entrypoint и HTTP host в приложении.
## ADDED Requirements
### Requirement: Запуск приложения
**ID:** `RT.AL-01`
Runtime SHALL запускать все зарегистрированные и не отключённые workers и предоставлять состояние запуска приложения.
#### Scenario: Запуск приложения
##### Участники
- Приложение, runtime PLBA2 и зарегистрированные workers.
##### Предусловия
- Workers зарегистрированы с уникальными именами.
- Приложение подключило runtime control API.
##### Основной поток
1. Запрашиваем запуск приложения — runtime запускает workers, не отключённых в конфигурации, по [RT.WK-01.FR-01](../worker/spec.md#rtwk-01fr-01-имя-состояния-и-управление-worker).
2. После запуска workers возвращаем `APPLICATION_STARTED` по [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения).
##### Альтернативы и ошибки
- Запуск одного или нескольких workers завершился ошибкой — возвращаем `APPLICATION_START_FAILED`; состояние приложения становится `failed`.
##### Результат
Lifecycle приложения и результат запуска workers доступны приложению.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STARTED` | Все зарегистрированные и включённые workers запущены | [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения) |
| `APPLICATION_START_FAILED` | Не удалось запустить один или несколько workers | [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения) |
#### Функциональные требования
##### RT.AL-01.FR-01: Запуск и состояния приложения
При запуске runtime переводит приложение в `starting`, запускает зарегистрированные workers, у которых `workers.<worker_name>.disabled` отсутствует или равно `false`, по их контракту и переводит приложение в `running` после их успешного старта. Ошибка запуска переводит lifecycle в `failed`. Состояния приложения: `new`, `starting`, `running`, `stopping`, `stopped` и `failed`.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `APPLICATION_STARTED` | Сообщение отсутствует | Приложение доступно для control operations |
| `APPLICATION_START_FAILED` | Сообщение отсутствует; исходная ошибка доступна приложению | Lifecycle приложения остаётся `failed` |
### Requirement: Остановка приложения
**ID:** `RT.AL-02`
Runtime SHALL останавливать все workers приложения в graceful или принудительном режиме и предоставлять актуальный lifecycle status.
#### Scenario: Остановка приложения
##### Участники
- Клиент control API, runtime PLBA2, supervisor и зарегистрированные workers.
##### Предусловия
- Приложение запущено и его workers зарегистрированы.
##### Основной поток
1. Запрашиваем остановку приложения с выбранным режимом — runtime останавливает workers по [RT.AL-02.FR-01](#rtal-02fr-01-режимы-остановки-приложения).
2. Дожидаемся завершения workers и возвращаем `APPLICATION_STOPPED` по [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки).
##### Альтернативы и ошибки
- Истёк заданный timeout ожидания — возвращаем status `stopping` и `APPLICATION_STOPPING`; runtime продолжает остановку по [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки).
##### Результат
Lifecycle становится `stopped` только после остановки всех workers.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STOPPED` | Все workers приложения остановлены | [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки) |
| `APPLICATION_STOPPING` | Остановка продолжается после завершения ожидания API | [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки) |
#### Функциональные требования
##### RT.AL-02.FR-01: Режимы остановки приложения
По умолчанию runtime запрашивает graceful stop у всех workers: каждый worker завершает активный цикл и не начинает следующий. При `force=true` runtime принудительно прерывает активную обработку workers. После любого режима новые циклы не запускаются.
##### RT.AL-02.FR-02: Ожидание и статус остановки
Положительный необязательный `timeout_seconds` ограничивает только ожидание ответа на запрос остановки. Если timeout отсутствует, runtime ждёт завершения всех workers без ограничения по времени. По истечении timeout runtime возвращает status `stopping`, продолжая остановку в фоне; timeout не включает принудительный режим. Lifecycle становится `stopped`, когда supervisor подтвердил остановку всех workers по [RT.WK-02.FR-02](../worker/spec.md#rtwk-02fr-02-результат-остановки-группы). Health aggregator возвращает `stopped` по [HL.AG-01.FR-01](../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов). Runtime не завершает принадлежащий приложению OS process или HTTP host; их остановка остаётся решением приложения.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `APPLICATION_STOPPED` | Сообщение отсутствует | Runtime фиксирует lifecycle `stopped` |
| `APPLICATION_STOPPING` | Сообщение отсутствует; lifecycle доступен в status | Runtime продолжает остановку workers |
@@ -0,0 +1,205 @@
## Purpose
Запускать именованные workers независимо друг от друга, выполнять их процессы по расписанию и формировать их health-состояния.
## ADDED Requirements
### Requirement: Независимые workers
**ID:** `RT.WK-01`
Runtime SHALL выполнять каждый зарегистрированный worker независимо от остальных по его стабильному уникальному имени.
#### Scenario: Работа worker в составе приложения
##### Участники
- Приложение, runtime PLBA2, supervisor и зарегистрированный worker.
##### Предусловия
- Composition root зарегистрировал workers с уникальными именами.
- Приложение запускает workers через lifecycle приложения.
##### Основной поток
1. При запуске приложения supervisor запускает worker, если `workers.<worker_name>.disabled` отсутствует или равно `false`, с результатом `WORKER_STARTED` по [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker).
2. Runtime хранит lifecycle и health каждого запущенного worker отдельно по [RT.WK-01.FR-02](#rtwk-01fr-02-независимость-работы-и-состояния).
##### Альтернативы и ошибки
- Для worker задано `disabled: true` — supervisor пропускает его запуск.
- Worker не удалось запустить — runtime сообщает `WORKER_START_FAILED` по [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker), остальные workers сохраняют собственное состояние.
##### Результат
Каждый включённый worker выполняется независимо и имеет отдельные имя, lifecycle и health-состояние.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKER_STARTED` | Включённый worker запущен при запуске приложения | [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker) |
| `WORKER_START_FAILED` | Worker не удалось запустить | [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker) |
#### Функциональные требования
##### RT.WK-01.FR-01: Имя, состояния и управление worker
Каждый worker регистрируется с уникальным стабильным именем. Runtime управляет его внутренним lifecycle через supervisor: запускает worker при запуске приложения, если `workers.<worker_name>.disabled` отсутствует или равно `false`, и останавливает его при остановке приложения. При `disabled: true` worker не запускается. Значение `disabled` применяется при запуске приложения; изменение этого значения во время работы не запускает и не останавливает worker до следующего запуска приложения. Отдельные операции API для запуска или остановки worker не предоставляются. Lifecycle и health запущенных workers доступны в общем health-отчёте. Неудачный внутренний запуск worker фиксируется с `WORKER_START_FAILED`; успешный — с `WORKER_STARTED`.
##### RT.WK-01.FR-02: Независимость работы и состояния
Runtime хранит lifecycle и health каждого worker отдельно. Исключение в процессе или состояние одного worker не меняет lifecycle и состояние остальных workers; операции управления приложением применяются ко всем включённым workers. Контракт health определён в [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health).
### Requirement: Контролируемая остановка workers
**ID:** `RT.WK-02`
Supervisor SHALL запрашивать остановку всех запущенных workers приложения и сообщать, когда каждый из них завершил текущую работу.
#### Scenario: Остановка группы workers
##### Участники
- Runtime PLBA2, supervisor и зарегистрированные workers.
##### Предусловия
- Workers запущены и доступны supervisor.
##### Основной поток
1. Передаём всем запущенным workers приложения режим остановки по [RT.WK-02.FR-01](#rtwk-02fr-01-режимы-остановки-worker).
2. Сообщаем о результате группы по [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы); после завершения возвращаем `WORKERS_STOPPED`.
##### Альтернативы и ошибки
- Часть workers ещё выполняет работу — сообщаем `WORKERS_STOPPING` и их имена по [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы).
##### Результат
Для каждого запущенного worker известно, завершена ли его работа.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKERS_STOPPED` | Все запущенные workers приложения остановлены | [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы) |
| `WORKERS_STOPPING` | Не все запущенные workers приложения завершили работу | [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы) |
#### Функциональные требования
##### RT.WK-02.FR-01: Режимы остановки worker
При graceful stop worker завершает текущий цикл и не начинает следующий. При принудительной остановке runtime прерывает активную обработку worker. Supervisor отправляет запрос остановки всем запущенным workers приложения; остановка одного не задерживает отправку запросов остальным.
##### RT.WK-02.FR-02: Результат остановки группы
Supervisor возвращает `WORKERS_STOPPED` только после остановки всех запущенных workers приложения. Пока хотя бы один worker работает, результат — `WORKERS_STOPPING` со списком таких workers. Ожидание и таймаут ответа API определяет capability `runtime/application-lifecycle`.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `WORKERS_STOPPED` | Сообщение отсутствует | Supervisor подтверждает завершение группы |
| `WORKERS_STOPPING` | Результат содержит имена ещё работающих workers | Supervisor продолжает остановку |
### Requirement: Периодическое выполнение worker
**ID:** `RT.WK-03`
Runtime SHALL выполнять прикладной процесс worker циклами по расписанию, заданному для этого worker в `config.yaml`.
#### Scenario: Циклическое выполнение процесса
##### Участники
- Runtime PLBA2, зарегистрированный worker и конфигурация приложения.
##### Предусловия
- Приложение зарегистрировало worker с уникальным именем и предоставило его прикладной процесс.
- Для каждого включённого worker задан ровно один допустимый режим расписания.
##### Основной поток
1. Запускаем процесс worker без начальной задержки — runtime принимает расписание с `WORKER_SCHEDULE_STARTED` по [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) и начинает цикл по [RT.WK-03.FR-01](#rtwk-03fr-01-режимы-и-настройки-расписания).
2. После завершения цикла планируем следующий запуск по текущей конфигурации и продолжаем последовательное исполнение по [RT.WK-03.FR-01](#rtwk-03fr-01-режимы-и-настройки-расписания).
##### Альтернативы и ошибки
- Настройки расписания отсутствуют, заданы вместе или имеют недопустимое значение — worker не запускается с `WORKER_CONFIG_INVALID` по [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания).
##### Результат
Worker выполняет прикладной процесс последовательно и повторяет его согласно выбранному режиму расписания.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKER_SCHEDULE_STARTED` | Расписание принято, worker начал циклическое исполнение | [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) |
| `WORKER_CONFIG_INVALID` | Расписание отсутствует или некорректно | [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) |
#### Функциональные требования
##### RT.WK-03.FR-01: Режимы и настройки расписания
Настройки каждого worker находятся в корневом `config.yaml` по пути `workers.<worker_name>`. Для включённого worker нужно задать ровно одну положительную длительность в секундах: `interval_seconds` или `pause_seconds`. Worker с `disabled: true` не запускается и не требует настроек расписания. Первый цикл начинается сразу после старта worker; циклы одного worker не выполняются параллельно. При `interval_seconds` задан период между началами циклов: после обработки runtime ждёт остаток периода, а если обработка заняла дольше интервала — запускает следующий цикл сразу. При `pause_seconds` runtime ждёт указанную паузу после завершения каждого цикла. При планировании следующего цикла используются активные настройки; валидные изменения файла применяются без рестарта по capability `configuration/application-config-file`.
##### RT.WK-03.FR-02: Валидация расписания
Для включённого worker runtime принимает расписание только если задан ровно один ключ — `interval_seconds` или `pause_seconds` — со значением больше нуля. Если оба ключа отсутствуют, заданы вместе или значение некорректно, запуск приложения завершается ошибкой `WORKER_CONFIG_INVALID`; детали доступны приложению. Для worker с `disabled: true` проверка расписания не выполняется. Валидное расписание завершается с `WORKER_SCHEDULE_STARTED`.
### Requirement: Health worker
**ID:** `RT.WK-04`
Runtime SHALL формировать health-состояние каждого worker, продолжая циклическую работу после исключения в прикладном процессе.
#### Scenario: Обновление health worker
##### Участники
- Runtime PLBA2, worker, прикладная health-логика и health aggregator.
##### Предусловия
- Worker запущен и зарегистрирован в health aggregator.
##### Основной поток
1. Определяем состояние worker по результату цикла и прикладным условиям по [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health).
2. Передаём status и critical aggregator по [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления); обновление завершается с `WORKER_HEALTH_UPDATED`.
##### Альтернативы и ошибки
- Процесс цикла выбрасывает исключение — фиксируем `unhealthy`, возвращаем `WORKER_PROCESS_FAILED`, сохраняем worker запущенным и планируем следующий цикл по [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления).
##### Результат
Health-состояние worker доступно aggregator; исключение одного цикла не прекращает последующие циклы.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKER_HEALTH_UPDATED` | Новое health-состояние worker передано aggregator | [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health), [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления) |
| `WORKER_PROCESS_FAILED` | Цикл завершился исключением, worker продолжит работу по расписанию | [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления) |
#### Функциональные требования
##### RT.WK-04.FR-01: Контракт и прикладные условия health
Health worker содержит `status` (`ok`, `degraded` или `unhealthy`), `critical`, `detail` и `meta` по контракту capability `health/aggregation`. Приложение задаёт `critical` при регистрации worker и может предоставить прикладную health-логику, возвращающую один из этих статусов по условиям своей задачи.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `WORKER_HEALTH_UPDATED` | Сообщение отсутствует | Новое состояние worker передаётся health aggregator |
##### RT.WK-04.FR-02: Правила статуса и восстановления
Исключение прикладного процесса переводит автоматическое состояние worker в `unhealthy`, но runtime перехватывает исключение и планирует следующий цикл. В режиме `interval_seconds` превышение длительностью цикла заданного интервала переводит автоматическое состояние в `degraded`; в режиме `pause_seconds` этот статус не возникает из-за расписания. Успешный следующий цикл сбрасывает автоматическое состояние в `ok`. Итоговый status — худший по порядку `ok < degraded < unhealthy` из автоматического состояния и результата прикладной health-логики; прикладная логика не маскирует ошибку цикла.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `WORKER_PROCESS_FAILED` | Сообщение отсутствует; исходное исключение доступно приложению | Worker сохраняет работу и запускает следующий цикл по расписанию |
@@ -0,0 +1,59 @@
# Spec Delta
## Purpose
Выполнять workflow из шагов приложения по явным переходам и сохранять состояние выполнения.
## ADDED Requirements
### Requirement: Workflow engine
**ID:** `WF.OR-01`
Workflow engine SHALL выполнять определение из именованных шагов, применять их переходы и сохранять ход запуска через persistence-контракт.
#### Scenario: Выполнение workflow
##### Участники
- Приложение, workflow engine, шаги приложения и persistence adapter.
##### Предусловия
- Приложение передало определение workflow, начальный шаг, контекст и адаптер сохранения.
##### Основной поток
1. Запускаем workflow — engine сохраняет начало запуска и вызывает объект текущего шага по [WF.OR-01.FR-01](#wfor-01fr-01-определение-и-выполнение).
2. Применяем результат шага — engine выбирает только объявленный переход и сохраняет checkpoint по [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки).
3. Достигаем конечного шага и завершаем с `WORKFLOW_COMPLETED`.
##### Альтернативы и ошибки
- Шаг выбрасывает исключение — engine сохраняет ошибку запуска, прекращает дальнейшие шаги и передаёт исходное исключение с `WORKFLOW_STEP_FAILED` по [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки).
##### Результат
Приложение получает результат запуска и актуальный контекст workflow.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKFLOW_COMPLETED` | Workflow достиг конечного шага | [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки) |
| `WORKFLOW_STEP_FAILED` | Шаг завершился исключением | [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки) |
#### Функциональные требования
##### WF.OR-01.FR-01: Определение и выполнение
Приложение задаёт WorkflowDefinition с именем, начальным шагом и именованными узлами. Узел содержит WorkflowStep и карту переходов; шаг получает WorkflowContext и возвращает StepResult с переходом, обновлениями состояния и статусом. Engine исполняет только объявленные переходы и не содержит бизнес-правил приложения.
##### WF.OR-01.FR-02: Сохранение и ошибки
Engine сохраняет начало и итог workflow, старт и завершение каждого шага, snapshot контекста и ошибки через переданный WorkflowPersistence. Ошибка шага сохраняется и передаётся вызывающему коду; скрытые повторы и выполнение следующих шагов не допускаются. Подключение к БД для сохранения задаёт приложение.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `WORKFLOW_COMPLETED` | Сообщение отсутствует | Engine возвращает итоговый context и run id |
| `WORKFLOW_STEP_FAILED` | Сообщение отсутствует; исходное исключение передаётся вызывающему коду | Engine сохраняет ошибку, прекращает workflow и не повторяет шаг |
@@ -0,0 +1,42 @@
# Tasks
## 1. Runtime, workers и идентификатор приложения
- [x] 1.1 Разрешать `application_id` в порядке `config.yaml` → `[project].name` из `pyproject.toml` → UUIDv4; предоставлять его runtime до запуска зависимых компонентов по RT.AI-01.FR-01.
- [x] 1.2 Реализовать регистрацию workers с уникальными именами и независимыми lifecycle/health; запускать worker при отсутствующем или `false` `disabled`, пропускать при `true`; применять изменение `disabled` при следующем запуске приложения по RT.WK-01.FR-01–RT.WK-01.FR-02.
- [x] 1.3 Реализовать последовательные циклы worker с настройками `interval_seconds` или `pause_seconds`, немедленным первым запуском и проверкой допустимого расписания по RT.WK-03.FR-01–RT.WK-03.FR-02.
- [x] 1.4 Формировать автоматический health worker по результату цикла, продолжать работу после исключения, поддержать прикладную health-логику и признак `critical` по RT.WK-04.FR-01–RT.WK-04.FR-02.
- [x] 1.5 Реализовать graceful/force stop всех запущенных workers и групповые результаты `WORKERS_STOPPED`/`WORKERS_STOPPING` по RT.WK-02.FR-01–RT.WK-02.FR-02.
- [x] 1.6 Реализовать запуск и остановку всего приложения, lifecycle states, необязательный `timeout_seconds` и продолжение остановки после ответа `stopping` по RT.AL-01.FR-01 и RT.AL-02.FR-01–RT.AL-02.FR-02.
## 2. Health и workflow
- [x] 2.1 Формировать отчёт с `application_id`, lifecycle и состояниями запущенных workers/contributors; применить правила criticality, отсутствующих workers и статусов `new`, `starting`, `running`, `stopping`, `stopped`, `failed` по HL.AG-01.FR-01–HL.AG-01.FR-02.
- [x] 2.2 Реализовать object-based workflow с именованными шагами и явными переходами; сохранять начало/итог запуска, шаги, snapshots и ошибки через переданный persistence-контракт; прекращать выполнение после исключения без retry по WF.OR-01.FR-01–WF.OR-01.FR-02.
## 3. Единый HTTP API
- [x] 3.1 Реализовать общий route adapter, подключаемый к host приложения и его listener; не запускать отдельный HTTP server или порт по API.HTTP.CA-01.FR-01.
- [x] 3.2 Реализовать `GET /health` с сериализацией health report и передачей ошибок aggregator согласно API.HTTP.CA-02.
- [x] 3.3 Реализовать `POST /runtime/start` и `GET /runtime/status`, делегируя lifecycle runtime и возвращая описанные status по API.HTTP.CA-03 и API.HTTP.CA-05.
- [x] 3.4 Реализовать `POST /runtime/stop` с валидацией `force` и `timeout_seconds`, HTTP 200/202/400 и ответами `stopped`/`stopping` по API.HTTP.CA-04.
## 4. Настройки приложения
- [x] 4.1 Реализовать и документировать контракт таблицы `settings`: типы, ограничения и назначение полей, индексы, порядок чтения, отсутствие уникальности `setting_key`; зафиксировать роль `setting_value` и `is_enabled` по CFG.AS-01.FR-01.
- [x] 4.2 Документировать границу владения начальными данными: приложение создаёт `settings` и загружает начальные значения своей миграцией; PLBA2 не запускает миграции и не переносит YAML в БД по CFG.AS-02.FR-01–CFG.AS-02.FR-02.
- [x] 4.3 Реализовать типизированный `SettingsReader` и PostgreSQL adapter с чтением из переданных pool и схемы, фильтрами, сортировкой, безопасным именем схемы и результатами декодирования по CFG.AS-03.FR-01–CFG.AS-03.FR-03.
- [x] 4.4 Реализовать начальную загрузку корневого `config.yaml` по типизированной модели приложения; поддержать `application_id`, `workers.<worker_name>.disabled` (по умолчанию `false`), `interval_seconds` и `pause_seconds`; описать, что остальные поля задаёт приложение, файл содержит редко меняемые технические параметры, а бизнес-настройки, feature toggles и удалённо меняемые технические значения находятся в `settings` по CFG.ACF-01.FR-01–CFG.ACF-01.FR-02.
- [x] 4.5 Реализовать обнаружение и атомарное применение валидных изменений `config.yaml` без рестарта; сохранять последний валидный snapshot и сообщать об ошибке при невалидном обновлении по CFG.ACF-02.FR-01–CFG.ACF-02.FR-02.
## 5. Business trace и техническое логирование
- [x] 5.1 Реализовать business trace contract и PostgreSQL adapter для `trace_contexts` и `trace_messages`, добавляя `application_id` в `attrs_json` обоих типов записей по OBS.BT-01.FR-01–OBS.BT-01.FR-03.
- [x] 5.2 Документировать структуру и ограничения таблиц business trace, включая `trace_id`, индексы и каскадную связь сообщений с контекстом; явно указать, что таблицы создаёт миграция приложения по OBS.BT-01.FR-01–OBS.BT-01.FR-03.
- [x] 5.3 Реализовать техническую JSON-запись с обязательными `timestamp`, `level`, `logger`, `message`, `application_id`, необязательными `attributes` и `business_trace_id`, выводом через stdlib `StreamHandler` в stdout по OBS.TL-01.FR-01–OBS.TL-01.FR-02.
## 6. Интеграция и документация
- [x] 6.1 Сохранить границы PLBA2: не добавлять сервис конфигурации или бизнес-истории, миграции приложения, API истории, публикацию business events в RabbitMQ или общую инфраструктуру рабочих очередей.
- [x] 6.2 Обновить package metadata и зависимости загрузчика YAML; описать интеграцию всех десяти capabilities, включая подключение HTTP adapter и миграции, выполняемые приложением.
- [x] 6.3 Добавить contract/unit/integration проверки поведения, заданного требованиями RT.AL, RT.WK, RT.AI, HL.AG, API.HTTP, WF.OR, CFG.AS, CFG.ACF, OBS.BT и OBS.TL.