specs/openspec/changes/persist-tbank-data/design.md

## Context

Основание — принятый [ADR 017](../../../../docs/adr/017-local-tbank-reads-and-background-sync.md)
и [дельты поведения](specs/tbank-data-sync/spec.md). Это детализация согласованной
модели для реализации. Компоненты приложения сейчас не изменены.

Исследованы локальные владельцы после чтения AGENTS каждого репозитория.
Свидетельства относятся к checkout на 2026-09-24, а не к обещаниям API:

| Граница | Текущий owner и переиспользуемое поведение |
| --- | --- |
| Хранение | `backend/prisma/schema.prisma` и `src/prisma/prisma.service.ts`: SQLite/Prisma, пользователи, сессии, подключение и ручные карты; T-Bank datasets отсутствуют. Условия владения и транзакции уже применяются в `modules/bank-cards/infrastructure/bank-cards.repository.ts`. |
| Доступ | `backend/src/integrations/tbank/tbank-access.service.ts`: `withSupportedAccounts` и `withAccountForConnection` вызывают `getOpenAccounts`; generation вычисляется из encryptedToken. `tbank-account.policy.ts` владеет допустимыми типами счетов. |
| Интеграция | `backend/src/integrations/tbank/tbank.client.ts`: общий FIFO, лимит 5 RPC/с по умолчанию, максимум 50 ожидающих, deadline и ограниченные повторы; повторный limiter не нужен. |
| Личный источник | `portfolio/application/portfolio.service.ts` хранит RAM-снимок 30 с / fallback 5 мин; `operations/application/brokerage-operations.service.ts` — страницы 30 с и обход курсоров. `income/income-analytics.service.ts` строит selected/previous/yearAgo через общий сборщик операций. Пути внутри `backend/src/modules/investments/`. |
| Общий источник | `backend/src/integrations/tbank/instrument-metadata.service.ts` уже разделяет общие metadata и pending lookup. Каталоги stocks/bonds смешивают общую информацию и личную позицию в user+generation RAM-кэше. Market services режут свечи по 365 суток. |
| Выплаты и смежные данные | `upcoming-events/upcoming-events.service.ts` отдельно получает portfolio; stock dividends приходят из T-Bank, bond events — из MOEX. Stock company use case получает asset description/fundamentals; bond metrics включают MOEX. Источники не подменяются. |
| Frontend | `frontend/src/entities/*/api` владеют generated queries; page VM собирает зависимости. `features/instrument-details/model/section.ts` знает только HTTP/query lifecycle. `features/tbank-connection/model/connection-boundary.ts` уже сбрасывает финансовую границу после успешной mutation. |
| Контракт | Backend DTO/controllers/Swagger — editable source. `frontend/src/shared/api/spec/openapi.json` — явно передаваемый snapshot. Accounts и search сейчас массивы; общего sync/coverage API нет. |

Исходный proto допускает изменение operation ID
(`backend/src/integrations/tbank/proto/contracts/operations.proto:496`),
но проект явно принимает стабильность. `is_complete` свечи задаёт источник
(`marketdata.proto:438`). В `operations.proto:472–489` не определены
inclusive/exclusive границы, срок жизни cursor и значение пропущенного `from`.
Эти пробелы не заменяются предположениями о гарантиях брокера.

## Goals / Non-Goals

**Goals:** один постоянный источник чтения в существующей БД; независимые
полнота, свежесть и состояние работы; атомарная публикация согласованного
набора; безопасный перезапуск; отсутствие RPC на пути ответа заполненной БД;
контракт всех экранных зависимостей и минимальный наблюдаемый worker.

**Non-Goals:** Redis, новый сервер БД, отдельный сервис очередей, cron,
распределённое выполнение, версии каждого портфельного снимка, live
подтверждение доступа при каждом чтении, архив отключённых счетов,
новый frontend store, изменение денежных правил или источников MOEX.

## Decisions

### 1. Существующие domain owners читают БД; RPC принадлежит синхронизации

Сохраняются controllers, application services, нормализация Money и domain
политики. Их read path получает сохранённые источники и согласованное
metadata, а запрос работы передаёт небольшому T-Bank sync coordinator.
PortfolioService становится общим владельцем последнего полного portfolio
для accounts summary, личных позиций инструментов и будущих событий.
Сборщик операций становится одним локальным источником ledger/income;
filtered HTTP page больше не является единицей источниковой полноты.
Рассчитанные доходы не требуют отдельной постоянно дублируемой таблицы.

Синхронизация использует существующие TbankClient, metadata mapping,
market-window splitting, точную денежную арифметику и MOEX adapters.
Нормализованные числа сохраняются десятичными строками, не float.
Presentation metadata не блокирует выдачу финансового снимка; fallback
UID/FIGI/name остаётся доступен до её фоновой загрузки.

Синхронная проверка token при PUT подключения сохраняется. Успешно полученный
в этой проверке список можно сразу опубликовать как membership нового
подключения в той же транзакции, без второго GetAccounts.

### 2. Личные и общие модели в SQLite

Это логические группы таблиц, не универсальный JSON-кэш всех HTTP-ответов:

| Группа | Ключ, содержимое и инвариант |
| --- | --- |
| Подключение и membership | Существующий `TbankConnection` получает opaque `revision` и состояние известного отказа token. Список открытых поддерживаемых счетов принадлежит `(userId, revision)`; хранит accountId, type, name, openedOn, upstream order, fetchedAt, membershipRevision. Список заменяется целиком атомарно, включая успешный пустой. |
| Portfolio | `(userId, revision, accountId)` → последний полный нормализованный snapshot, fetchedAt и dataRevision. Допустимо хранить состав snapshot как versioned JSON: он читается целиком, не нужен отдельный исторический агрегат. |
| Operations | Уникальность `(userId, revision, accountId, brokerOperationId)`; индекс `(userId, revision, accountId, occurredAt, brokerOperationId)`, дополнительные instrument/category поля для фильтров. Полный исходный нормализуемый payload сохраняет точные поля, executed state и version маппинга. Cursor/пустая строка не заменяют отсутствующий ID. |
| Инструменты | Общий ключ provider + instrument UID; FIGI/ticker — aliases с существующими правилами неоднозначности. Metadata, company/fundamentals и catalog discovery имеют собственные успешные timestamps и coverage; отрицательный успешный lookup отличается от ошибки. |
| Рыночные данные | Общие quote/trading-status и необходимые price dependencies; дневная свеча уникальна по `(provider, instrumentUid, interval, time)`, содержит `isComplete`. Календари имеют source/type/instrument/range и исходные события. MOEX enrichment сохраняет собственный source и существующую семантику недоступности. |
| Последний полный прогноз | Private snapshot account events и instrument personal payout estimates по `(userId, revision, account scope, instrument при наличии, applied range)`, с dependency revisions, source timestamps и calculatedAt. Заменяется только после готовности всех обязательных источников; это fallback результата, не история portfolio. |
| Покрытие и работа | Завершённые диапазоны, fetchedThrough/fetchedAt, dataRevision, известная нижняя граница и её происхождение; pending intent, attemptId, processRunId, диапазон, стадия и прогресс страниц. Staging страниц текущей попытки изолирован от опубликованного набора. |

Общие таблицы не содержат user/account/quantity/estimatedAmount или token.
Личные payout estimates, holdings и фильтрованная личная история вычисляются
из разрешённых accounts и portfolio/operations. Статус пользовательской
работы хранится отдельно от общих instrument records; ошибка credentials
не становится общим отрицательным lookup.

FK и unique constraints обеспечивают идентичность; транзакции проверяют
владение и revision. Не создаются generic repository framework, event bus
или универсальный job engine. Точные SQL-имена выбираются по локальным
Prisma conventions без изменения этой модели.

### 3. Доступ без синхронного GetAccounts

Read path: локальная сессия → существующее подключение и его revision →
известная ошибка token → membership текущей revision → данные разрешённых
счетов. Token для этого не расшифровывается.

- Membership отсутствует: `200` с `data: null`, `availability: missing` и
  состоянием discovery, без данных неизвестного accountId. После discovery
  следующий read возвращает данные либо прежний `404`.
- Membership свежий: разрешённые данные читаются локально.
- Membership старше пяти минут: используется последнее успешное наблюдение,
  обычный запрос ставит его фоновое обновление. Это ограниченная задержка
  обнаружения отзыва доступа, принятая локальной моделью, не live authority.
- Успешный новый список немедленно ограничивает все последующие одиночные
  и aggregate reads; добавленный ещё не загруженный счёт делает aggregate
  неполным. Ответ «Все счета» использует одну согласованную DB read transaction
  с фиксированной membershipRevision.
- Известный `INVALID_TBANK_TOKEN` блокирует личные reads и возвращает прежний
  `400`; `409 TBANK_NOT_CONNECTED`, `404`, session/validation errors сохраняются.
  Старые записи не удаляются вследствие transient failure, но не выдаются
  вопреки известному отказу доступа. Исправление token выполняется существующим PUT.

При замене успешная транзакция назначает новую случайную revision, сохраняет
новый token и очищает/делает недоступными прежние private datasets/jobs
по существующей семантике invalidation. Delete остаётся идемпотентным и
каскадно убирает личные данные подключения; специальный архив не вводится.
Общие неперсональные данные могут оставаться.

Каждая публикация данных, coverage, ошибки, timestamp и результата работы
проверяет в той же короткой транзакции текущие connection revision и
attemptId. Проверка после RPC только в памяти недостаточна. Проверка нужна
и при общей публикации, начатой credentials старого подключения.
Поздняя попытка не вправе изменить даже freshness; результаты старой revision
отбрасываются. Транзакция никогда не удерживается во время сетевого вызова.

### 4. Интервалы и атомарная сверка операций

Внутри БД диапазоны — `[from, to)` в UTC. Public semantics не меняются:
журнал принимает действующие UTC timestamps, его default начинается 1 января
UTC; даты доходов включительны в `Europe/Moscow`, и существующий
`planIncomePeriod` вычисляет selected/previous/yearAgo. Преобразование границ
выполняется один раз до планирования. Полнота доходного месяца проверяется
по объединению UTC coverage, а не по совпадению названия месяца.

Источник по операциям загружается ограниченными календарными UTC-месяцами
и фрагментами нужных диапазонов. Верхняя граница текущей попытки фиксируется
в момент её создания. Для неизвестной inclusivity upstream применяется
перекрытие соседних окон с защитной секундой; записи локально отбираются
по точному `[from, to)` и дедуплицируются по исходному ID. Это защищает
стык, но не доказывает отсутствие будущих исправлений брокера.

Обычная полнота счёта строится только по всем EXECUTED операциям интервала
без category/instrument фильтров. UI filters и pagination применяются после
чтения. Ручной refresh личной истории инструмента может перечитать только
`instrumentUid + shown range`; его reconciliation удаляет отсутствующие
записи только этого predicate и не присваивает полноту всему счёту.
Уже полное общее покрытие может обслуживать такой subset; обратное неверно.

Каждая успешная страница записывается в staging attempt с page count и
прогрессом. При наличии полного прежнего набора staging никогда не виден
как его замена. Новые большие периоды становятся доступными по завершении
малых интервалов при первичном заполнении, поэтому экран может иметь `partial` coverage без показа
непроверенных страниц. Сбой, repeated/missing next cursor, malformed ID или
противоречащие версии одного ID внутри попытки оставляют интервал незавершённым.
Идентичные дубликаты страницы безопасно схлопываются.

Только успешное исчерпание всех страниц фиксированного интервала разрешает
транзакцию публикации: upsert новых/изменённых полей, удаление отсутствующих записей
в перечитанном predicate, публикация coverage и времени успешной сверки.
Account dataRevision увеличивается только при изменении rowset;
coverage/timestamp/status без изменения строк меняют только stateVersion.
Читатель видит старый либо новый набор,
не их смесь. Между интервалами частичная готовность допустима и явно видима;
сумма всего периода окончательна только при полном покрытии его зависимостей.

Для повторной сверки уже полного показанного периода единица публикации —
весь запрошенный scope, а не отдельный календарный chunk. Staging объединяет
его интервалы, сравнения и счета (`all`) в одну publication group; успешные
страницы/окна сохраняют прогресс, но commit/upsert/delete/coverage всех
участников выполняются только после успеха группы. Любая ошибка оставляет
весь прежний результат. Такое же правило действует для ручного refresh
показанного диапазона свечей. Первичная загрузка ранее отсутствующих данных
по малым интервалам остаётся инкрементальной. Пересекающиеся работы
присоединяются к группе и не публикуют её часть независимо. DB transaction
короткая и локальная; RPC выполняются до неё, а staging не держится в RAM.

Для изменяемого конца `to=now` полнота означает «все операции по состоянию
на `asOf` последней успешной сверки». Новый ещё не наблюдённый хвост времени
в пределах того же текущего месяца и TTL не считается пропуском, запускающим
новую загрузку; ответ сохраняет исходный `asOf`, не утверждая покрытие будущих
операций. Настоящие пропуски до `asOf`, новый явно запрошенный исторический
диапазон и переход месяца этому исключению не подчиняются.
Текущий месяц обновляется целиком до зафиксированного now при истечении
пяти минут, чтобы учесть изменения уже виденных операций. После смены месяца
его покрытие до прежнего now не распространяется до конца месяца:
следующий подходящий запрос завершает хвост. Полные прошлые интервалы
не сверяются автоматически. Успешная наблюдённая смена полей того же ID
обновляет запись и производные результаты; поиск сменившихся ID отсутствует.

### 5. Планирование, приоритет и восстановление

Поддерживаемая поставка — один backend process с существующей SQLite.
Запрос сохраняет intent, возвращает локальные данные и передаёт выполнение
in-process coordinator. На startup нет обхода очереди или запуска импорта.
Process получает случайный runId; следующий подходящий запрос перехватывает
незавершённую работу другого runId новой attemptId. Persisted provider cursor
не переиспользуется после перезапуска: незавершённый интервал начинается
с первой страницы, staging прежней попытки очищается. Завершённые интервалы
и опубликованные данные сохраняются.

Приоритеты: discovery доступа → нужные экрану зависимости и интервалы,
включая comparisons → остальная история счёта и рыночная история его бумаг.
Между окнами/страницами coordinator отдаёт приоритет новой экранной работе;
уже отправленный RPC не прерывается ради перестановки. Один producer
догрузки не ставит тысячи RPC заранее: страницы идут последовательно,
новые окна планируются постепенно, через прежний bounded limiter.
Очередь RPC и bounded retry не дублируются на уровне worker.

Ключ personal work: user + connectionRevision + account + source kind +
normalized interval/predicate. Координатор сериализует публикации одного
account source и для обычной загрузки вычитает покрытые/выполняемые
пересечения; одновременно запрошенные остатки объединяет. Force refresh
не вычитает полное покрытие: он обязан перечитать запрошенный target,
но присоединяется к уже выполняемой подходящей загрузке. Повторный force refresh присоединяется к
подходящей активной попытке, уже получающей полный запрошенный диапазон;
TTL при этом не отменяет запрос. Новая область расширяет pending intent.

Shared work использует provider/instrument/source/range identity.
Общий успешный результат переиспользуется независимо от пользователя.
У каждого наблюдателя свой авторизованный handle, без выдачи чужих job IDs
и credentials errors. Ошибка token инициатора завершает его попытку, не
портит общий источник; новый допустимый запрос другого пользователя может
запустить попытку со своими credentials. Старый job не перехватывает token
другого пользователя сам.

Остальная история начинается с известной даты открытия; если её нет,
используется существующая техническая граница `1970-01-01T00:00:00Z`,
явно помеченная как requested floor, а не доказанная дата открытия/минимум
источника. Сохраняются confirmed intervals и `historyBoundary: unknown`;
«вся история загружена» не показывается до подтверждения нижней границы.
Отказ источника за пределами доступного диапазона сохраняется как ограничение,
не как пустой полный интервал. Отсутствие `from` не используется как
недокументированное обещание all-time. Это не мешает полной готовности
подтверждённых периодов экрана.

После transient failure попытка заканчивается с error; новый обычный запрос
может возобновить недостающее/устаревшее, ручной — повторить независимо от TTL.
Наблюдение результата этого не делает. Logout/уход останавливает наблюдение
frontend, но не отменяет уже запрошенную допустимую серверную работу.
Замена/delete подключения останавливает публикацию по revision fence.

### 6. Общие market data и производные выплаты

Quotes и portfolio обновляются через минуту; metadata/catalog/company и
календари — через сутки. Freshness принадлежит конкретному source/range,
поэтому успешный lookup одного инструмента не делает свежим весь каталог.
Catalog discovery сохраняет успешный набор UID/порядок отдельно от
enrichment по нормализованному поисковому query и типу инструмента, сохраняя
существующий предел результатов. `findShares/findBonds` не загружают весь
каталог: успешный поиск SBER не подтверждает результат GAZP. Новый query
без подтверждённого покрытия запускает discovery, а не возвращает ложный
пустой результат. Metadata уже известных UID переиспользуется; повтор того
же свежего полного query не вызывает discovery RPC. Отсутствие enrichment
не превращает найденный набор в пустой поиск.

Свечи сохраняют исходную `isComplete`, диапазоны и `historyFrom`.
Переиспользуются окна до 365 суток. Завершённый диапазон без свечей хранится
как проверенное пустое покрытие. Текущий UTC-день всегда изменяемый,
включая пустое окно до торгов; его TTL — минута. Смена UTC-дня сама не
закрывает ни пустое открытое окно, ни незавершённую свечу: следующий запрос
повторяет прошедшее окно; успешный закрытый пустой диапазон подтверждает
отсутствие, для имеющейся свечи нужно `isComplete=true`.

Известный `first_1dayCandleDate` определяет нижнюю границу all-range.
Если его нет, сохраняется существующее `*_HISTORY_START_UNAVAILABLE`,
не создаётся ложная полная история. Предзагрузка касается бумаг сохранённого
текущего портфеля и использует ту же общую coverage, что открытый график.

События инструментов сохраняются без пользовательской ожидаемой суммы.
Календари купонов/дивидендов и company data охватываются общим read path;
future events используют сохранённый portfolio и исходный календарь,
сохраняя неопределённость прогноза, cancelled-dividend и offer semantics.
MOEX bond events/metrics остаются MOEX: необходимые для экрана результаты
также сохраняются и обновляются в этой работе, без нового MOEX scheduler.
Недоступность optional enrichment не делает финансовые данные ошибочными;
неполнота обязательного календаря не выдаётся за полный пустой прогноз.
Последний полный прогноз/личная оценка сохраняется отдельным private
snapshot по показанному scope/range. Если новый portfolio добавил бумагу,
а её календарь не загрузился, следующий read, в том числе после restart,
возвращает прежний полный forecast с его прежними dependency timestamps и
ошибкой обновления. При отсутствии такого snapshot возвращается missing/partial
без окончательного списка. Готовый новый результат атомарно заменяет snapshot;
снимок с иным периодом или membership не выдаётся под новым scope, а доступ
всегда повторно ограничивается текущим membership.

### 7. Публичный контракт и наблюдение работы

**Contract Gate Decision: required.** Меняется wire shape всех T-Bank data
GET, включая bare-array accounts и stock/bond search. Backend сохраняет
маршруты и тип внутреннего payload, добавляя единый envelope:

```text
{ data: T | null, meta: {
    resourceKey, dataRevision, stateVersion,
    availability: missing | partial | complete,
    freshness: unknown | fresh | stale, lastSuccessfulAt: timestamp | null,
    sync: { id: opaque | null, state: idle | queued | running | failed,
            errorCode: safeCode | null },
    coverage?: { requested, completeRanges, missingRanges,
                 asOf, historyBoundary, historyState },
    dependencies?: [{ resourceKey, availability, freshness,
                     lastSuccessfulAt, sync, coverage?, unavailableReason? }]
} }
```

Connection generation/revision остаётся внутренней: существующая security
policy запрещает её в API/logs/errors, даже если она случайная. Frontend
использует свою существующую session/connection boundary.
`resourceKey` — нормализованная идентичность запроса без user secrets и
connection generation. `dataRevision` меняется при публикации данных;
изменение статуса работы не меняет страницу операций. Availability означает
готовность обязательных источников данного результата, а не обещание полноты
рынка или будущих выплат. `data:null` используется для missing и для
неполных финансовых агрегатов; `partial` ledger/candles может содержать
подтверждённые части. Полнота selected/comparisons задаётся отдельно:
analytics `data` доступен после полного selected, а `previous` и
`yearComparison` nullable до готовности соответствующего сравнения.
`meta.dependencies` различает missing/loading/failed comparison и
заведомо недоступное по календарю/границе истории сравнение; последнее
имеет отдельный `unavailableReason` и не планируется как пропуск.
Это явное изменение вложенного analytics DTO, а не только envelope.

Для зависимостей с разными TTL metadata содержит их состояния по
resourceKey; freshness производного результата — худшее обязательное
состояние, lastSuccessfulAt — самый ранний из использованных успешных
источников. Чтение/`calculatedAt`/`observedAt` не продлевает source freshness.
Portfolio `data.lastSuccessfulAt` и `data.isStale` сохраняются для текущих
consumers и отображают тот же portfolio source, без прежнего пятиминутного
предела хранения. Error фонового обновления не меняет успешный timestamp
и сама по себе не отменяет ещё действующий TTL.

| Операция | Контракт |
| --- | --- |
| Обычный GET существующего resource | `200` envelope, в том числе cold/partial; планирует missing/stale зависимости. До постановки проверяет auth, connection и известную принадлежность. |
| Тот же GET с `sync=observe` | Только локальное чтение; никогда не создаёт и не возобновляет work, даже при missing/stale/error. Нужен для получения изменившихся данных после status observation. |
| `POST /api/v1/tbank-sync` | Валидированный screen descriptor, force по TTL; `202` с авторизованным work handle и normalized scope. При совпадении присоединяет к work. Приём не означает успех. |
| `GET /api/v1/tbank-sync/:id` | Только статус разрешённого handle, progress, changed resource revisions и terminal outcome; никаких новых запусков/повторов. Чужой/прежней connection handle — `404`. |

Descriptor — discriminated union `screen: accounts | account | operations |
income | events | stocks | bonds | stock | bond`. Поля разрешены только
соответствующему screen: account scope (конкретный ID/`all`), applied period,
filters, instrumentUid, candle period/range. Сервер использует прежние
валидаторы дат/лимитов/UID и сам раскрывает dependency graph; произвольного
списка RPC/таблиц/чужого userId во входе нет. Зафиксированный now и нормализованный
scope возвращаются клиенту, чтобы ручная операция не переезжала на другой период.

| Экран | Зависимости force refresh |
| --- | --- |
| Accounts | Membership + portfolio summary каждого текущего доступного счёта; metadata показанных позиций по необходимости. Не вся история операций. |
| Account / all overview | Membership, portfolio, показанный recent-ledger range, current-month income, upcoming events и необходимые instrument metadata/calendars. |
| Operations | Применённые account scope и период; категории — локальная проекция. Пагинация не расширяет источниковой период. |
| Income | Применённый период + previous/yearAgo из существующего planner, membership, требуемая metadata выплат. |
| Events | Membership, portfolio и прогноз применённого включительного from/to из сохранённых календарей; default from=today UTC, to=from+30 дней. |
| Stocks / bonds search | Общий каталог, результаты/enrichment текущего поиска и показываемые prices; без истории всего каталога. |
| Stock / bond | Detail/company либо metrics, quote и price dependencies, видимый candle range, payout calendar, личная position и применённый диапазон/инструмент personal operations. |

HTTP ошибки auth/input/access сохраняют `application/problem+json`.
`TBANK_UNAVAILABLE` из принятой фоновой работы передаётся как безопасный
`meta.sync.errorCode`, включая cold failure; `503` остаётся для запроса,
который не удалось принять/обслужить. Известный отказ credentials остаётся
`400 INVALID_TBANK_TOKEN`, не успешным envelope с недоступными private data.
Frontend различает server work error и transport failure.

Работа имеет terminal `succeeded | failed | cancelled` в status endpoint;
envelope отображает successful отсутствие активной работы как `idle`.
Статус имеет `stateVersion` нужных экрану ресурсов и отдельный прогресс background
history, поэтому готовые данные можно прочитать до окончания всей догрузки.
Frontend наблюдает только известный active handle на открытом экране
с интервалом 1–5 секунд и без автоматического retry failed work. После
изменения stateVersion или terminal status выполняется `sync=observe` GET.
После ухода/terminal status наблюдение прекращается. Это наблюдение уже
запрошенной работы, не периодический запуск импорта.

`stateVersion` — opaque идентичность состояния ответа, меняется при изменении
данных, coverage (включая пустое завершённое окно), successfulAt, ошибок,
работы и доступа; это не pagination revision. Он вычисляется из версий
зависимостей и состояния без выдачи внутренних connection identifiers.
Прогресс далёкой истории, не меняющий этот resource, не меняет его
stateVersion и не заставляет повторно читать уже готовый экран.
Истечение времени не создаёт работу: freshness вычисляется из timestamp.

Entity query owner записывает observe-ответ в ту же canonical cache identity
исходного GET; не создаётся второй cache по параметру observe. Query keys
берутся из generated owner, не собираются вручную. Все новые status/mutation
ответы участвуют в существующих session/connection boundary fences.
Кроме них owner использует latest-request sequence для каждого resource:
ответ более раннего запроса не заменяет уже принятый более поздний ответ.
При status notification запоминается ожидаемый stateVersion; observe-ответ
с прежней версией не публикуется, выполняется только новое observational read.
Подтверждённый access loss отменяет/инвалидирует соответствующие personal
queries и повышает локальную access epoch; даже поздний успешный ответ той же
connection, начатый до отзыва, не восстанавливает скрытые данные.

### 8. Локальная пагинация и финансовые результаты

Порядок операций сохраняет действующую сортировку с детерминированным
tie-break по accountId/operationId. Оpaque cursor связан с user, connection,
membershipRevision для all, нормализованными filters/period/limit и
account operations dataRevision. Любое изменение relevant rowset делает
cursor недействительным. Binding хранится серверно либо проверяется keyed
digest: connection generation не находится даже в декодируемом cursor payload.
Изменение rowset возвращает существующий `INVALID_OPERATIONS_CURSOR`;
исторические копии всех rowsets не хранятся. Первая реализация использует
revision на счёт: изменение другого периода тоже может сбросить его cursor;
более узкая revision нужна только при доказанно мешающих сбросах.

Frontend сбрасывает cursor stack на первую страницу, сохраняя applied filters
и объясняя обновление списка; ни страницы, ни суммы разных revisions не
склеиваются. `hasNext=false` означает конец текущей локальной выдачи,
а не полноту истории. Coverage/status без изменения строк cursor не ломают.

Income сохраняет точные signed coupon/dividend payments и существующие
comparison rules. Stable operation ID устраняет повторный финансовый учёт;
прежняя норма о разных entries с одинаковым ID явно изменена delta spec.
Analytics читает согласованный набор операций и coverage в read transaction.
Неполнота selected скрывает его окончательные totals; неполнота comparison
скрывает только его суммы/разницы и не создаёт нулевую базу. Уже опубликованный полный результат того же
period/context сохраняется при неудачной повторной сверке; данные другого
периода никогда не подписываются новым диапазоном.

### 9. Измеримый бюджет и стоимость интеграции

500 мс — цель, не текущий результат. Начальный профиль приёмки: один backend
process, локальная SQLite на SSD, 4 CPU / 8 GiB, 3 счёта, по 100 000 операций
за 10 лет, 200 инструментов и по 5 000 дневных свечей, включая пустые
интервалы; до 1 000 операций/200 доходных выплат на счёт в активном месяце.
Измеряются account/all reads, ledger page 50, monthly income с comparisons,
instrument detail/quote/company/metrics, year/all candles и payouts/search.

Бюджет — p95 ≤ 500 мс от входа HTTP на backend до окончания ответа при
10 одновременных клиентах и не менее 100 чтений каждой группы после прогрева.
Отдельно сохраняются p50/p99/max, размер ответа, состояние БД, hardware и
время первого DB-only ответа после перезапуска. Cold import исключён из
бюджета заполненной БД, но его HTTP ответ также не ожидает RPC. Больший
реальный профиль не объявляется измеренным по этим данным.

Изоляция от брокера проверяется задержанным/отказывающим T-Bank; источник
замеряемых данных — HTTP timing и счётчики RPC существующего logger. Для
fresh полной выборки ожидается 0 RPC; для 20 simultaneous stale requests —
один логический проход каждой нужной зависимости, с явным учётом pages и
разрешённых retries. После завершения, без screen/manual requests — 0 RPC.
Повторные старые полные intervals/candles, в том числе после restart, —
0 повторных RPC этих диапазонов. Сравнение с исходной реализацией выполняется
на одинаковом navigation trace; сохраняются абсолютные числа и доля снижения
`1 - new/old`, если baseline ненулевой. Измерения не требуют real tokens
в артефактах или логах.

## UI/UX Applicability and Package

**Applicability and scope:** `new/changed` — общие состояния и действие
обновления всех T-Bank экранов, без перестройки их содержимого.

**Package revision:** `1`. Пакет полностью inline; локальные PNG/SVG не
нужны, поскольку меняются информационные состояния и существующие controls,
а не композиция экранов. Self-hash и внешние визуальные зависимости отсутствуют.

**Screens, states and interactions:**

| Состояние | Представление и действие |
| --- | --- |
| Missing без результата | Существующий структурный skeleton только отсутствующих секций, «Загружаем данные», доступное busy-состояние; без нулей/«операций нет». |
| Partial period | Подтверждённые строки видны с «Период загружен не полностью». Финансовые totals/comparisons ждут полноты. «История догружается» отдельно от состояния показанного периода. |
| Complete fresh | Контент, время источника и «Обновить» в заголовке экрана. Истечение TTL само не запускает UI timer refresh. |
| Complete stale / active | Прежний контент и timestamp, «Обновляем» либо «Данные на …»; без skeleton поверх сумм. Повторная кнопка disabled для уже запрошенного текущего scope с доступным пояснением. |
| Failed with data | Прежний контент, исходное время, безопасное предупреждение и повторное «Обновить». Transport failure и server work failure различимы; статус не сообщает об успешном обновлении. |
| Failed without data | Локальное error-состояние секции, безопасный retry либо действие настроек согласно коду. |
| Complete empty | Только подтверждённое пустое состояние; empty portfolio не создаёт нулевые карточки, пустой доход объясняет отсутствие купонов/дивидендов. |
| Access lost / connection changed | Очистка недоступного personal view, настройки для token/connection, возврат к счетам для 404. Нельзя удерживать чужую/прежнюю revision под предупреждением. |

Accounts показывают freshness списка отдельно от локального состояния
portfolio summary каждой карточки. Account/all overview сохраняет независимые
секции. Operations сохраняет применённые фильтры; income не переименовывает
старый snapshot новым period. Stock/bond показывают состояния по sections,
не смешивая общий график с личными holdings/payout estimates. Детали candle
по-прежнему обозначают незавершённость.

**Responsive behavior:** на 320–375 px timestamp, предупреждение и кнопка
переносятся без горизонтального overflow и обрезания сумм; на широком экране
используют существующий header/section layout. Focus сохраняется после
обновления; button доступен с клавиатуры, текст статуса не зависит от цвета,
`aria-live=polite` объявляет смену стадии/ошибку, но не каждую страницу.
Skeleton не фокусируется; reduced motion сохраняется.

**Reused source and differences:** runtime Mantine controls, существующие
Section/VM patterns и generated query owners переиспользуются как код.
Это новый inline пакет, не reuse изменяемого или архивного design package;
его состояние полностью определено выше.

## Delivery Map

| Area | Status | Architectural outcome or N/A reason |
| --- | --- | --- |
| frontend | `affected` | Новый snapshot/types, metadata-aware entity queries/VMs всех экранов, scoped refresh и observe-only status, connection/cursor boundaries, inline UI package. |
| backend | `affected` | Prisma storage/migration, local access/read owners, durable interval sync/fencing, shared market sources, DTO и OpenAPI; evidence корректности, latency и RPC. |
| specs | `affected` | Этот change и семь delta capabilities; traceability реализации без преждевременного изменения main specs или чужих changes. |
| docs | `affected` | As-built freshness/storage/access/flows/API/glossary и актуальный статус ADR после поставки; не второй источник требований. |

## Solution Assessment

Trigger: storage, external integration, caching, concurrency и public API.

| Вариант | Fit, maturity, security, operating cost и migration cost |
| --- | --- |
| Существующие SQLite/Prisma + транзакции, unique keys и небольшой request-driven coordinator | Выбран: зрелая используемая БД, один процесс, отсутствие нового сервиса; ownership/fencing доступны в SQL. Миграция добавляет таблицы и revision. Специфичные broker intervals/reconciliation остаются доменной логикой. |
| Продлить RAM/TanStack кэш | Зрелый дешёвый механизм показа, но несовместим с durability и полнотой после restart. Остаётся presentation cache, не решение хранения. |
| Redis + BullMQ | Зрелые retries/locks/queues, но требует нового сервиса, persistence/security/backup и двойной согласованности с SQLite; его jobs всё равно не решают domain coverage/атомарную сверку. Нет нужды в распределённых workers, поэтому цена миграции/эксплуатации не оправдана. |
| Temporal либо аналогичный workflow server | Зрелое recovery, но отдельная инфраструктура и execution model для одной последовательности RPC; domain data transactions всё равно необходимы. Не соответствует минимальному одному backend. |
| Cron/планировщик | Зрелый механизм, но несовместим с явным запретом периодических запусков. |

Собственный код ограничен доменными интервалами, dependency planning,
staging/publish и coalescing; transport queue/retries и DB lifecycle уже
существуют. Существующий runtime не предоставляет durable job framework;
добавлять его ради этих конечных стадий не требуется. При переходе к нескольким
backend processes понадобится отдельное решение о durable claims/leases;
эта поставка не выдаёт processRunId за распределённую блокировку.

## Risks / Trade-offs

- Локальный membership не замечает отзыв доступа мгновенно. Он обновляется
  по пятиминутной политике; известный отказ применяется немедленно.
- Stable operation ID противоречит возможностям upstream proto, но принят
  как допущение; сменившийся ID может потребовать отдельной будущей сверки.
- Broker cursor не обещает snapshot isolation: полнота означает успешный
  обход доступного интервала на момент сверки, не отсутствие последующих
  исправлений. Staging защищает от наших частичных публикаций.
- Долгая первичная история расходует rate-limit и диск. Ограниченные окна,
  приоритет экрана и отсутствие предварительной массовой очереди сдерживают
  ресурсы; объём и время первой загрузки пока не измерены.
- Запись SQLite сериализуется. Короткие транзакции и индексы должны уложиться
  в бюджет; это проверяется, а не считается доказанным архитектурой.
- Envelope — несовместимое wire изменение, поэтому backend/frontend
  поставляются согласованной парой. API version path сам по себе не делает
  старый frontend совместимым.

## Migration Plan

1. Зафиксировать текущие DB/API invariants и measurement baseline на
   изолированной базе. Добавить additive schema с revision и пустыми новыми
   datasets; текущие users/sessions/connection/manual-card записи сохранить.
   У существующих подключений появляется новая revision без изменения token.
2. Реализовать storage/coordinator и local owners; старые RAM snapshots
   не мигрировать как доказанно полную историю. Проверить crash/rollback и
   fences до включения нового read path.
3. Backend публикует OpenAPI artifact; frontend получает его явно и
   регенерирует типы локально. Совместно поставляется новый UI и server
   read path, включая observer semantics и terminal errors.
4. Первые пользовательские запросы заполняют данные. Startup/deploy не
   запускает импорт. После подтверждённых checks обновляются as-built docs;
   specs остаётся единственным SDD authority.

### Rollback Contract

| Field | Decision |
| --- | --- |
| Status | `required` |
| Trigger | Cross-user/connection leak, частичная публикация финансовых данных, повреждение миграции, несовместимый API pair либо существенная регрессия latency. |
| Actions | Остановить новый worker/backend, сохранить согласованную копию SQLite, вернуть совместимую пару backend/frontend. Не запускать старую и новую write-модель одновременно. Отдельно проверить Prisma migration state; не удалять additive tables как способ отката. |
| Data safety | Сохранить новые datasets, progress и все прежние User/Session/TbankConnection/manual-card записи. Если старая версия не поддерживает новую Prisma schema, использовать совместимый rollback build либо восстановить backup в отдельной БД; нельзя перезаписать рабочую БД старой копией, потеряв новые ручные операции. |
| Verification | Проверить integrity/FK и равенство прежних пользовательских данных, невозможность публикации остановленного worker, auth/connection boundaries, согласованность API pair и повторное безопасное чтение/возобновление после возврата исправленной версии. |

## Open Questions

Блокирующих продуктовых вопросов нет. Неизвестны измеренные latency/объём
истории и provider semantics при отсутствующем `from`/openedDate. Они не
меняют выбранный путь: явные интервалы, replay с начала, unknown lower bound
и отсутствие ложного признака полной истории. Подтверждение минимальной
даты источника может уточнить только boundary metadata; до него используется
описанный безопасный fallback. Числовые результаты будут получены задачами
проверки, а не вписаны заранее.