feat: optimize bucket data caching and document refresh behavior

- Add private five-minute browser caching for SvelteKit page-data responses:
- Ranking,
- Details,
- Visualizations.
- Set Cache-Control to private, max-age=300.
- Remove the stale-while-revalidate window so expired route data is refreshed before rendering.
- Support cache handling for both localized and non-localized __data.json routes.

- Add gzip compression for page-data responses larger than 1 KB.
- Respect the client Accept-Encoding header and gzip quality value.
- Set Content-Encoding and Vary headers for compressed responses.
- Preserve uncompressed responses for clients without gzip support.
- Reduce transferred payload sizes approximately:
- Ranking from 171 KB to 58 KB,
- Details from 643 KB to 158 KB,
- Visualizations from 709 KB to 122 KB.

- Refresh the small bucket manifest whenever a browser cache miss reaches the server.
- Add refreshManifest snapshot option to separate manifest checks from full payload refreshes.
- Reuse catalog, leaderboard, and adapted datasets when snapshot_id is unchanged.
- Download and rebuild payloads only after detecting a new snapshot_id.
- Remove independent Ranking and Details TTL checks that could compound cache freshness delays.
- Keep the expected freshness window tied to the five-minute browser cache.

- Key ranking snapshot in-flight requests by snapshot_id.
- Prevent a request for a newly published snapshot from joining an older snapshot download.
- Add a shared Details snapshot cache keyed by snapshot_id.
- Reuse details_matrix between Ranking partial-run detection and the Details page.
- Deduplicate concurrent Details snapshot downloads.
- Refresh the Tools manifest after a browser cache miss while retaining cached visualization data
for an unchanged snapshot.

- Add detailed English and Russian documentation for the current data flow:
- bucket configuration and server-only authentication,
- manifest and snapshot_id versioning,
- route-to-payload mapping,
- browser and in-memory cache behavior,
- gzip response handling,
- data freshness guarantees,
- validation and stale fallback behavior,
- cold starts and multiple replicas,
- atomic snapshot publishing requirements,
- operational verification commands,
- implementation file map.

- Document that every bucket publish must use a new unique snapshot_id and update manifest.json
only after all referenced payload files are available.

docs/data-loading-cache_en.md

@@ -0,0 +1,355 @@
+# Data loading and caching
+
+This document describes the current implementation of data loading and caching in the
+HiveTrace Guardrail Leaderboard frontend.
+
+The implementation has three goals:
+
+- keep the private Hugging Face token on the SvelteKit server;
+- avoid downloading and adapting unchanged bucket payloads;
+- make repeated client-side navigation fast while providing a predictable data freshness window.
+
+## Architecture
+
+```text
+Browser
+  -> SvelteKit page or __data.json request
+  -> Hugging Face Space Node process
+  -> private Hugging Face bucket
+       -> latest/manifest.json
+       -> payload files referenced by the manifest
+```
+
+The browser never reads the private bucket directly. All bucket requests are made by the
+SvelteKit server with the server-only `HF_TOKEN` environment variable.
+
+## Data source
+
+The bucket is configured with these runtime variables:
+
+```text
+HF_TOKEN=<private read token>
+HF_BUCKET_ID=hivetrace/leaderboard_frontend_v2
+HF_BUCKET_PREFIX=latest
+HF_BUCKET_REQUEST_TIMEOUT_MS=10000
+HF_BUCKET_ENDPOINT=https://huggingface.co
+```
+
+`HF_BUCKET_ENDPOINT` and `HF_BUCKET_REQUEST_TIMEOUT_MS` are optional. The values above are
+their defaults.
+
+`HF_BUCKET_CACHE_TTL_MS` still controls the regular in-memory manifest cache and the direct
+Tools snapshot helper. The main Ranking, Details, and Visualizations page-data flow explicitly
+refreshes the manifest after the browser cache misses, so this variable does not add another
+freshness delay to normal client-side page transitions.
+
+## Manifest as the version pointer
+
+`latest/manifest.json` is the single version pointer used by the frontend. Its important fields
+are:
+
+- `snapshot_id`: the identity of the published dataset;
+- `files`: paths to all payload files;
+- `hashes`: SHA-256 hashes of the payload files;
+- `schema_version`: the bucket contract version;
+- model, group, and dataset counts used for validation.
+
+The frontend decides whether payload data changed by comparing `snapshot_id`. A new publish
+must always use a new, unique `snapshot_id`.
+
+Changing payload files or hashes without changing `snapshot_id` is not supported. In that case,
+the frontend considers the snapshot unchanged and can continue using the old in-memory payload
+until the Space process restarts.
+
+## Routes and payloads
+
+| Route          | Server loader               | Bucket data                                                                                                       |
+| -------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `/`            | `getHfBucketRankingState()` | catalog, leaderboard, and details matrix                                                                          |
+| `/details`     | `getHfBucketDetailsState()` | catalog, leaderboard, and details matrix                                                                          |
+| `/tools`       | `getHfBucketToolsState()`   | catalog, leaderboard, drilldown index, radar, scatter, heatmap, grouped bars, Pareto, performance, and robustness |
+| `/methodology` | no bucket page loader       | no bucket payload                                                                                                 |
+
+Ranking also uses the details matrix because the `partial` model status is derived from
+`metrics_evaluated_samples < sample_count`.
+
+The root `+layout.server.ts` reads the manifest separately to expose public bucket status such
+as snapshot date and model count. That status uses the regular manifest cache. It is metadata
+for the layout and does not control page-data freshness.
+
+## Client-side navigation
+
+SvelteKit intercepts internal menu links and requests route data through endpoints such as:
+
+```text
+/__data.json
+/details/__data.json
+/tools/__data.json
+```
+
+Localized variants are recognized as well, for example `/ru/details/__data.json`.
+
+The response optimization in `src/hooks.server.ts` applies only to these three page-data
+routes. It does not apply to Methodology, static assets, errors, or arbitrary API responses.
+
+### Browser cache
+
+Successful page-data responses use:
+
+```http
+Cache-Control: private, max-age=300
+```
+
+This means:
+
+- each browser can reuse a route response for five minutes;
+- the response is not a public CDN or shared-proxy cache entry;
+- no `stale-while-revalidate` window is used;
+- after five minutes, the next navigation must contact the SvelteKit server before rendering
+  that route.
+
+The cache is per response URL, including SvelteKit query parameters. Ranking, Details, and
+Visualizations therefore have independent browser cache entries.
+
+An already rendered page does not update itself. Fresh data is applied on a later navigation or
+full page reload.
+
+### Gzip compression
+
+The same hook compresses a page-data response when all conditions are true:
+
+- the response is successful and has a body;
+- its declared size is at least 1,024 bytes;
+- the client accepts `gzip`.
+
+The compressed response contains:
+
+```http
+Content-Encoding: gzip
+Vary: Accept-Encoding
+```
+
+`Content-Length` is removed because the compressed body is streamed. Clients without gzip
+support receive the original body with the same five-minute private cache policy.
+
+Approximate measured sizes for the current dataset are:
+
+| Route data     | Uncompressed |   Gzip |
+| -------------- | -----------: | -----: |
+| Ranking        |       171 KB |  58 KB |
+| Details        |       643 KB | 158 KB |
+| Visualizations |       709 KB | 122 KB |
+
+These sizes depend on the bucket contents and will change as models and datasets are added.
+
+## Server request flow
+
+When the browser does not have a fresh page-data response, the server follows this flow:
+
+1. The page loader calls the corresponding Ranking, Details, or Tools state function.
+2. The state function calls `fetchBucketRankingSnapshot({ refreshManifest: true })`.
+3. `refreshManifest: true` bypasses the regular manifest TTL and reads the current small
+   `manifest.json` from Hugging Face.
+4. If the returned `snapshot_id` matches the in-memory ranking snapshot, catalog and leaderboard
+   are reused without another payload download.
+5. If `snapshot_id` changed, catalog and leaderboard are downloaded in parallel, their hashes
+   and schemas are validated, and the ranking snapshot is replaced.
+6. Route-specific data is reused or rebuilt for the same new `snapshot_id`.
+7. SvelteKit serializes the adapted route data, and the server hook applies the private cache
+   header and gzip compression.
+
+The important distinction between the snapshot options is:
+
+- `refreshManifest: true` always checks the manifest but reuses payloads when `snapshot_id` is
+  unchanged;
+- `forceRefresh: true` also bypasses payload reuse and rebuilds the ranking snapshot.
+
+Normal page transitions use `refreshManifest`, not `forceRefresh`.
+
+## In-memory caches
+
+All server caches are module-level memory in the running Node process. They are private to a
+single Space replica and are cleared when the container restarts, sleeps, or is redeployed.
+
+### Manifest cache
+
+`src/lib/server/hf-bucket/cache.ts` stores:
+
+- the parsed manifest;
+- the time it was fetched;
+- its expiration time;
+- one shared in-flight manifest request.
+
+Regular callers use `HF_BUCKET_CACHE_TTL_MS`, with a five-minute default. Page-data refreshes use
+the forced manifest path described above. Concurrent forced checks join the same in-flight
+request when they overlap.
+
+### Ranking snapshot
+
+The ranking snapshot contains the manifest, catalog, and leaderboard. It is cached by
+`snapshot_id`.
+
+Concurrent downloads of the same snapshot share one promise. In-flight requests are also keyed
+by `snapshot_id`, so a request for a newly published snapshot does not accidentally reuse a
+download for an older snapshot.
+
+### Details snapshot
+
+The details snapshot adds `details_matrix` to the ranking snapshot and is cached by
+`snapshot_id`.
+
+This cache is shared by Ranking and Details. Ranking needs the matrix for `partial` detection, so
+opening Details after Ranking does not download and validate `details_matrix` a second time.
+Concurrent requests for the same details snapshot also share one promise.
+
+### Adapted Ranking and Details datasets
+
+The UI-ready Ranking and Details objects are cached by `snapshot_id`. When the manifest is
+unchanged, the server returns the already adapted object. A new snapshot is parsed, validated,
+and adapted once per Node process.
+
+### Visualizations snapshot and adapted Tools dataset
+
+For a new snapshot, the visualization files are downloaded in parallel. The raw visualization
+snapshot and the adapted Tools dataset are cached separately by `snapshot_id`.
+
+The direct `getHfBucketToolsSnapshot()` helper retains its TTL-based fast path. The `/tools`
+page uses the state path, which refreshes the manifest after a browser cache miss.
+
+## Validation
+
+Payload reuse is allowed only after the manifest version check. New payloads go through:
+
+- JSON parsing;
+- schema parsing;
+- SHA-256 verification when a hash is present;
+- manifest count checks;
+- model, group, and dataset reference checks;
+- matrix completeness and duplicate-pair checks;
+- visualization reference checks.
+
+A validation error is handled in the same way as another refresh failure.
+
+## Data freshness guarantee
+
+Assume a valid new snapshot is published at time `T` and the bucket remains reachable.
+
+### Route response is already in the browser cache
+
+The old route response can be used until its individual five-minute `max-age` expires. The first
+navigation to that route after expiration reads the fresh manifest. If `snapshot_id` changed,
+the same navigation waits for and receives the new payload.
+
+Therefore, the expected guarantee is:
+
+> No later than the first navigation after the route's five-minute browser cache expires, the
+> user receives the new snapshot.
+
+There is no additional stale response window.
+
+### Route response is not in the browser cache
+
+The navigation immediately contacts the server and checks the manifest. If the server already
+has the new payload, it reuses it. Otherwise, the navigation waits while the new snapshot is
+downloaded and adapted.
+
+### Full page reload
+
+The five-minute policy targets SvelteKit `__data.json` navigation responses. A normal full HTML
+request is not covered by this page-data cache and runs the server page loader again.
+
+### Exceptions
+
+The five-minute expectation does not apply when:
+
+- Hugging Face or the network is unavailable;
+- the new payload fails parsing, hash checks, or validation;
+- the publisher reused the old `snapshot_id`;
+- the manifest was published before all referenced files became readable.
+
+## Failure behavior
+
+The cache is also a resilience mechanism:
+
+- if a refresh fails and a usable route dataset exists, the server returns cached data;
+- if a new manifest is readable but a new payload is invalid or unavailable, the route state is
+  returned as `stale` and the UI can show a warning;
+- if no usable cache exists, the route returns an `unavailable` state with an empty fallback
+  dataset;
+- simultaneous requests share in-flight work to avoid duplicate bucket downloads.
+
+One implementation detail is worth noting: when a forced manifest read fails but an older
+manifest is cached, the manifest layer can return that stale manifest. The existing route data
+can then continue to be served. The current route state does not always propagate this specific
+manifest fallback as a visible `stale` warning.
+
+## Publishing a new snapshot
+
+The producer must publish atomically from the frontend's point of view:
+
+1. Generate all payload files.
+2. Use immutable or snapshot-specific file paths where practical.
+3. Calculate and write the SHA-256 hashes.
+4. Upload every payload file and verify it is readable.
+5. Create a manifest with a new unique `snapshot_id`, correct paths, hashes, counts, and schema
+   version.
+6. Upload `latest/manifest.json` last.
+
+Publishing the manifest last prevents the frontend from seeing a new version that references
+files which are not available yet.
+
+## Cold starts and replicas
+
+After a Space restart or cold start, no in-memory snapshot exists. The first request must read
+the manifest and all payloads required by that route. Later requests reuse the prepared data.
+
+If the Space runs multiple replicas, each replica has its own memory cache and warms
+independently. The browser cache remains local to each user.
+
+## Operational checks
+
+To inspect the page-data response headers, use an authenticated request to the Space:
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  -H "Accept-Encoding: gzip" \
+  -D - \
+  -o /dev/null \
+  "https://<space-domain>/details/__data.json"
+```
+
+Expected headers include:
+
+```http
+Cache-Control: private, max-age=300
+Content-Encoding: gzip
+Vary: Accept-Encoding
+```
+
+`curl` does not reproduce the browser's navigation cache unless an explicit curl cache is used.
+Repeated curl requests therefore reach the server and can trigger repeated manifest checks.
+
+When verifying a publish, check all of the following:
+
+- the manifest has a new `snapshot_id`;
+- every referenced file exists;
+- hashes match the published contents;
+- the Space logs contain no bucket validation errors;
+- the first route navigation after browser cache expiration shows the new snapshot.
+
+## Implementation map
+
+| Responsibility                               | File                                                                                                   |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| HTTP bucket client and server-only token     | `src/lib/server/hf-bucket/client.ts`                                                                   |
+| Regular manifest cache and in-flight request | `src/lib/server/hf-bucket/cache.ts`                                                                    |
+| Ranking snapshot download and validation     | `src/lib/server/hf-bucket/ranking-snapshot.ts`                                                         |
+| Shared details snapshot                      | `src/lib/server/hf-bucket/details-snapshot.ts`                                                         |
+| Visualization snapshot download              | `src/lib/server/hf-bucket/tools-snapshot.ts`                                                           |
+| Adapted Ranking cache                        | `src/lib/server/hf-bucket/ranking-cache.ts`                                                            |
+| Adapted Details cache                        | `src/lib/server/hf-bucket/details-cache.ts`                                                            |
+| Raw and adapted Tools caches                 | `src/lib/server/hf-bucket/tools-cache.ts`                                                              |
+| Browser cache headers and gzip               | `src/hooks.server.ts`                                                                                  |
+| Root public bucket status                    | `src/routes/+layout.server.ts`                                                                         |
+| Route orchestration                          | `src/routes/+page.server.ts`, `src/routes/details/+page.server.ts`, `src/routes/tools/+page.server.ts` |

docs/data-loading-cache_ru.md

@@ -0,0 +1,355 @@
+# Загрузка данных и кеширование
+
+Этот документ описывает текущую реализацию загрузки данных и кеширования во frontend
+HiveTrace Guardrail Leaderboard.
+
+У реализации три основные цели:
+
+- хранить приватный Hugging Face token только на сервере SvelteKit;
+- не скачивать и не адаптировать повторно неизменившиеся payload-файлы bucket;
+- ускорить повторные переходы между страницами и сохранить предсказуемое окно актуальности
+  данных.
+
+## Архитектура
+
+```text
+Browser
+  -> SvelteKit page или __data.json request
+  -> Node process в Hugging Face Space
+  -> private Hugging Face bucket
+       -> latest/manifest.json
+       -> payload-файлы, указанные в manifest
+```
+
+Браузер не обращается к приватному bucket напрямую. Все запросы в bucket выполняет сервер
+SvelteKit с помощью server-only переменной `HF_TOKEN`.
+
+## Источник данных
+
+Bucket настраивается runtime-переменными:
+
+```text
+HF_TOKEN=<private read token>
+HF_BUCKET_ID=hivetrace/leaderboard_frontend_v2
+HF_BUCKET_PREFIX=latest
+HF_BUCKET_REQUEST_TIMEOUT_MS=10000
+HF_BUCKET_ENDPOINT=https://huggingface.co
+```
+
+`HF_BUCKET_ENDPOINT` и `HF_BUCKET_REQUEST_TIMEOUT_MS` опциональны. Выше указаны их значения по
+умолчанию.
+
+`HF_BUCKET_CACHE_TTL_MS` по-прежнему управляет обычным in-memory кешем manifest и прямым helper
+Tools snapshot. Основной поток page data для Ranking, Details и Visualizations после промаха
+браузерного кеша явно обновляет manifest, поэтому эта переменная не добавляет еще одну задержку
+актуальности при обычных переходах по страницам.
+
+## Manifest как указатель версии
+
+`latest/manifest.json` является единственным указателем версии для frontend. Основные поля:
+
+- `snapshot_id`: идентификатор опубликованного набора данных;
+- `files`: пути ко всем payload-файлам;
+- `hashes`: SHA-256 хеши payload-файлов;
+- `schema_version`: версия контракта bucket;
+- количества моделей, групп и датасетов для валидации.
+
+Frontend определяет изменение payload по `snapshot_id`. Каждая новая публикация обязана иметь
+новый уникальный `snapshot_id`.
+
+Изменение payload-файлов или хешей без изменения `snapshot_id` не поддерживается. В таком случае
+frontend считает snapshot прежним и может использовать старый in-memory payload до перезапуска
+процесса Space.
+
+## Маршруты и payload-файлы
+
+| Маршрут        | Server loader               | Данные bucket                                                                                                  |
+| -------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `/`            | `getHfBucketRankingState()` | catalog, leaderboard и details matrix                                                                          |
+| `/details`     | `getHfBucketDetailsState()` | catalog, leaderboard и details matrix                                                                          |
+| `/tools`       | `getHfBucketToolsState()`   | catalog, leaderboard, drilldown index, radar, scatter, heatmap, grouped bars, Pareto, performance и robustness |
+| `/methodology` | нет bucket page loader      | payload из bucket не используется                                                                              |
+
+Ranking также использует details matrix, потому что статус модели `partial` вычисляется по
+условию `metrics_evaluated_samples < sample_count`.
+
+Корневой `+layout.server.ts` отдельно читает manifest и возвращает публичный статус bucket:
+дату snapshot, количество моделей и другие общие поля. Этот статус использует обычный кеш
+manifest. Он является метаданными layout и не управляет актуальностью page data.
+
+## Клиентская навигация
+
+SvelteKit перехватывает ��нутренние ссылки главного меню и запрашивает данные маршрутов через
+endpoint вида:
+
+```text
+/__data.json
+/details/__data.json
+/tools/__data.json
+```
+
+Локализованные варианты также распознаются, например `/ru/details/__data.json`.
+
+Оптимизация response в `src/hooks.server.ts` применяется только к этим трем page-data
+маршрутам. Она не применяется к Methodology, статическим файлам, ошибкам и произвольным API
+response.
+
+### Браузерный кеш
+
+Успешный page-data response получает заголовок:
+
+```http
+Cache-Control: private, max-age=300
+```
+
+Это означает:
+
+- браузер может повторно использовать response маршрута в течение пяти минут;
+- response не попадает в общий CDN или shared proxy cache;
+- окно `stale-while-revalidate` отсутствует;
+- после пяти минут следующий переход обязан обратиться к серверу SvelteKit до отрисовки
+  маршрута.
+
+Кеш привязан к URL response, включая внутренние query-параметры SvelteKit. Поэтому Ranking,
+Details и Visualizations имеют отдельные записи браузерного кеша.
+
+Уже открытая страница сама не обновляется. Новые данные применяются при следующем переходе или
+полной перезагрузке страницы.
+
+### Gzip-сжатие
+
+Тот же hook сжимает page-data response, когда выполнены все условия:
+
+- response успешный и содержит body;
+- заявленный размер не меньше 1 024 bytes;
+- клиент поддерживает `gzip`.
+
+Сжатый response содержит:
+
+```http
+Content-Encoding: gzip
+Vary: Accept-Encoding
+```
+
+`Content-Length` удаляется, потому что сжатый body передается потоком. Клиенты без поддержки
+gzip получают исходный body с тем же приватным кешем на пять минут.
+
+Примерные измеренные размеры для текущего набора данных:
+
+| Данные маршрута | Без сжатия |   Gzip |
+| --------------- | ---------: | -----: |
+| Ranking         |     171 KB |  58 KB |
+| Details         |     643 KB | 158 KB |
+| Visualizations  |     709 KB | 122 KB |
+
+Размеры зависят от содержимого bucket и будут меняться при добавлении моделей и датасетов.
+
+## Поток server request
+
+Если в браузере нет свежего page-data response, сервер выполняет следующие шаги:
+
+1. Page loader вызывает соответствующую state-функцию Ranking, Details или Tools.
+2. State-функция вызывает `fetchBucketRankingSnapshot({ refreshManifest: true })`.
+3. `refreshManifest: true` обходит обычный TTL manifest и читает актуальный небольшой
+   `manifest.json` из Hugging Face.
+4. Если полученный `snapshot_id` совпадает с in-memory ranking snapshot, catalog и leaderboard
+   используются повторно без скачивания payload.
+5. Если `snapshot_id` изменился, catalog и leaderboard скачиваются параллельно, проверяются их
+   хеши и schema, после чего ranking snapshot заменяется.
+6. Данные конкретного маршрута переиспользуются или пересобираются для нового `snapshot_id`.
+7. SvelteKit сериализует адаптированные данные маршрута, а server hook добавляет приватный кеш и
+   gzip-сжатие.
+
+Разница между параметрами snapshot:
+
+- `refreshManifest: true` всегда проверяет manifest, но переиспользует payload при неизменном
+  `snapshot_id`;
+- `forceRefresh: true` также отключает переиспользование payload и пересобирает ranking snapshot.
+
+Обычные переходы по страницам используют `refreshManifest`, а не `forceRefresh`.
+
+## In-memory кеши сервера
+
+Все серверные кеши хранятся в памяти работающего Node process. Они принадлежат одному replica
+Space и очищаются при перезапуске, засыпании контейнера или новом deploy.
+
+### Кеш manifest
+
+`src/lib/server/hf-bucket/cache.ts` хранит:
+
+- распарсенный manifest;
+- время его получения;
+- время истечения кеша;
+- один общий in-flight request manifest.
+
+Обычные callers используют `HF_BUCKET_CACHE_TTL_MS`, по умолчанию пять минут. Page-data refresh
+использует принудительное чтение manifest, описанное выше. Одновременные принудительные проверки
+подключаются к одному in-flight request, если пересекаются по времени.
+
+### Ranking snapshot
+
+Ranking snapshot содержит manifest, catalog и leaderboard. Он кешируется по `snapshot_id`.
+
+Одновременные загрузки одного snapshot используют общий promise. In-flight request также
+привязан к `snapshot_id`, поэтому запрос нового опубликованного snapshot не использует по ошибке
+загрузку предыдущего snapshot.
+
+### Details snapshot
+
+Details snapshot добавляет `details_matrix` к ranking snapshot и кешируется по `snapshot_id`.
+
+Этот кеш общий для Ranking и Details. Ranking использует matrix для определения `partial`, поэтому
+после открытия Ranking страница Details не скачивает и не валидирует `details_matrix` повторно.
+Одновременные запросы одного details snapshot также используют общий promise.
+
+### Адаптированные Ranking и Details
+
+Готовые для UI объекты Ranking и Details кешируются по `snapshot_id`. Если manifest не изменился,
+сервер возвращает уже адаптированный объект. Новый snapshot парсится, валидируется и адаптируется
+один раз на Node process.
+
+### Visualizations snapshot и адаптированный Tools dataset
+
+Для нового snapshot файлы визуализаций скачиваются параллельно. Raw visualization snapshot и
+адаптированный Tools dataset кешируются отдельно по `snapshot_id`.
+
+Прямой helper `getHfBucketToolsSnapshot()` сохраняет свой быстрый путь на основе TTL. Страница
+`/tools` использует state-путь, который обновляет manifest после промаха браузерного кеша.
+
+## Валидация
+
+Payload используется повторно только после проверки версии manifest. Новый payload проходит:
+
+- JSON parsing;
+- schema parsing;
+- проверку SHA-256 при наличии хеша;
+- сверку количеств из manifest;
+- проверку ссылок на модели, группы и датасеты;
+- проверку полноты matrix и дублирующихся пар;
+- проверку ссылок в данных визуализаций.
+
+Ошибка валидации обрабатывается так же, как другая ошибка обновления.
+
+## Гарантия актуальности данных
+
+Предположим, что корректный новый snapshot опубликован в момент `T`, а bucket доступен.
+
+### Response маршрута уже находится в браузерном кеше
+
+Старый response может использоваться до истечения его индивидуального `max-age` в пять минут.
+Первый переход на этот маршрут после истечения кеша читает свежий manifest. Если `snapshot_id`
+изменился, тот же переход ожидает загрузку нового payload и получает новые данные.
+
+Ожидаемая гарантия:
+
+> Не позднее первого перехода после истечения пятиминутного браузерного кеша маршрута
+> пользователь получает новый snapshot.
+
+Дополнительного окна выдачи stale response нет.
+
+### Response маршрута отсутствует в браузерном кеше
+
+Переход сразу обращается к серверу и проверяет manifest. Если новый payload уже находится в
+памяти сервера, он используется повторно. Иначе переход ожидает скачивание и адаптацию нового
+snapshot.
+
+### Полная перезагрузка страницы
+
+Пятиминутная политика применяется к SvelteKit navigation response `__data.json`. Обычный полный
+HTML request не покрывается этим page-data кешем и снова запускает server page loader.
+
+### Исключения
+
+Пятиминутное ожидание неприменимо, если:
+
+- Hugging Face или сеть недоступны;
+- новый payload не проходит parsing, проверку хеша или валидацию;
+- publisher повторно использовал старый `snapshot_id`;
+- manifest опубликован раньше, чем стали доступны все указанные в нем файлы.
+
+## Поведение при ошибках
+
+Кеш также обеспечивает устойчивость:
+
+- если refresh завершился ошибкой и готовые данные маршрута существуют, сервер возвращает кеш;
+- если новый manifest доступен, но новый payload невалиден или недоступен, route state становится
+  `stale`, и UI может показать предупреждение;
+- если пригодного кеша нет, маршрут возвращает состояние `unavailable` с пустым fallback dataset;
+- одновременные запросы используют общую in-flight работу и не дублируют загрузку bucket.
+
+Важная деталь текущей реализации: если принудительное чтение manifest завершилось ошибкой, но в
+памяти есть предыдущий manifest, слой manifest может вернуть его как stale. После этого сервер
+продолжит выдавать предыдущие route data. Текущий route state не во всех случаях пробрасывает
+именно этот fallback manifest как видимое предупреждение `stale`.
+
+## Публикация нового snapshot
+
+Producer должен выполнять публикацию атомарно с точки зрения frontend:
+
+1. Сгенерировать все payload-файлы.
+2. По возможности использовать immutable или snapshot-specific пути.
+3. Рассчитать и записать SHA-256 хеши.
+4. Загрузить каждый payload-файл и проверить, что он доступен для чтения.
+5. Создать manifest с новым уникальным `snapshot_id`, корректными путями, хешами, количествами и
+   версией schema.
+6. Последним загрузить `latest/manifest.json`.
+
+Публикация manifest последним не позволяет frontend увидеть новую версию, которая ссылается на
+еще недоступные файлы.
+
+## Cold start и replicas
+
+После перезапуска или cold start Space in-memory snapshot отсутствует. Первый request должен
+прочитать manifest и все payload-файлы, необходимые выбранному маршруту. Следующие запросы
+используют подготовленные данные повторно.
+
+Если Space работает с несколькими replicas, каждая имеет собственный кеш в памяти и прогревается
+независимо. Браузерный кеш остается локальным для каждого пользователя.
+
+## Операционная проверка
+
+Для проверки заголовков page-data response нужен авторизованный запрос к Space:
+
+```bash
+curl -sS \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  -H "Accept-Encoding: gzip" \
+  -D - \
+  -o /dev/null \
+  "https://<space-domain>/details/__data.json"
+```
+
+Ожидаемые заголовки:
+
+```http
+Cache-Control: private, max-age=300
+Content-Encoding: gzip
+Vary: Accept-Encoding
+```
+
+`curl` не воспроизводит navigation cache браузера без отдельной настройки собственного кеша.
+Поэтому повторные curl-запросы доходят до сервера и могут повторно запускать проверку manifest.
+
+При проверке новой публикации нужно убедиться, что:
+
+- manifest содержит новый `snapshot_id`;
+- каждый указанный файл существует;
+- хеши соответствуют опубликованному содержимому;
+- в логах Space нет ошибок валидации bucket;
+- первый переход после истечения браузерного кеша показывает новый snapshot.
+
+## Карта реализации
+
+| Ответственность                          | Файл                                                                                                   |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| HTTP client bucket и server-only token   | `src/lib/server/hf-bucket/client.ts`                                                                   |
+| Обычный кеш manifest и in-flight request | `src/lib/server/hf-bucket/cache.ts`                                                                    |
+| Загрузка и валидация Ranking snapshot    | `src/lib/server/hf-bucket/ranking-snapshot.ts`                                                         |
+| Общий Details snapshot                   | `src/lib/server/hf-bucket/details-snapshot.ts`                                                         |
+| Загрузка Visualization snapshot          | `src/lib/server/hf-bucket/tools-snapshot.ts`                                                           |
+| Кеш адаптированного Ranking              | `src/lib/server/hf-bucket/ranking-cache.ts`                                                            |
+| Кеш адаптированного Details              | `src/lib/server/hf-bucket/details-cache.ts`                                                            |
+| Raw и адаптированный кеш Tools           | `src/lib/server/hf-bucket/tools-cache.ts`                                                              |
+| Заголовки браузерного кеша и gzip        | `src/hooks.server.ts`                                                                                  |
+| Публичный статус bucket в root layout    | `src/routes/+layout.server.ts`                                                                         |
+| Оркестрация маршрутов                    | `src/routes/+page.server.ts`, `src/routes/details/+page.server.ts`, `src/routes/tools/+page.server.ts` |

src/hooks.server.ts

@@ -1,17 +1,82 @@
 import type { Handle } from '@sveltejs/kit';
-import { getTextDirection } from '$lib/paraglide/runtime';
+import { getTextDirection, isLocale } from '$lib/paraglide/runtime';
 import { paraglideMiddleware } from '$lib/paraglide/server';
 
+const DATA_CACHE_CONTROL = 'private, max-age=300';
+const MIN_GZIP_SIZE_BYTES = 1024;
+
+function isBucketDataRequest(request: Request) {
+	const segments = new URL(request.url).pathname.split('/').filter(Boolean);
+	if (segments.at(-1) !== '__data.json') return false;
+
+	segments.pop();
+	if (segments[0] && isLocale(segments[0])) segments.shift();
+
+	const route = segments.join('/');
+	return route === '' || route === 'details' || route === 'tools';
+}
+
+function acceptsGzip(request: Request) {
+	return (request.headers.get('accept-encoding') ?? '').split(',').some((entry) => {
+		const [encoding, ...parameters] = entry.trim().toLowerCase().split(';');
+		if (encoding !== 'gzip' && encoding !== '*') return false;
+
+		const quality = parameters
+			.map((parameter) => parameter.trim())
+			.find((parameter) => parameter.startsWith('q='));
+		return quality ? Number(quality.slice(2)) > 0 : true;
+	});
+}
+
+function appendVary(headers: Headers, value: string) {
+	const values = new Set(
+		(headers.get('vary') ?? '')
+			.split(',')
+			.map((item) => item.trim())
+			.filter(Boolean)
+	);
+	values.add(value);
+	headers.set('vary', [...values].join(', '));
+}
+
+function optimizeBucketDataResponse(request: Request, response: Response) {
+	if (!response.ok || !response.body || !isBucketDataRequest(request)) return response;
+
+	const headers = new Headers(response.headers);
+	headers.set('cache-control', DATA_CACHE_CONTROL);
+	appendVary(headers, 'Accept-Encoding');
+
+	const contentLength = Number(headers.get('content-length') ?? 0);
+	if (request.method === 'HEAD' || contentLength < MIN_GZIP_SIZE_BYTES || !acceptsGzip(request)) {
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers
+		});
+	}
+
+	headers.delete('content-length');
+	headers.set('content-encoding', 'gzip');
+
+	return new Response(response.body.pipeThrough(new CompressionStream('gzip')), {
+		status: response.status,
+		statusText: response.statusText,
+		headers
+	});
+}
+
 const handleParaglide: Handle = ({ event, resolve }) =>
-	paraglideMiddleware(event.request, ({ request, locale }) => {
+	paraglideMiddleware(event.request, async ({ request, locale }) => {
 		event.request = request;
 
-		return resolve(event, {
+		const response = await resolve(event, {
 			transformPageChunk: ({ html }) =>
 				html
 					.replace('%paraglide.lang%', locale)
 					.replace('%paraglide.dir%', getTextDirection(locale))
 		});
+
+		return optimizeBucketDataResponse(request, response);
 	});
 
 export const handle: Handle = handleParaglide;

src/lib/server/hf-bucket/details-cache.ts

@@ -1,4 +1,3 @@
-import { env } from '$env/dynamic/private';
 import type { BucketDataState } from '$lib/types/bucket-state';
 import type { DetailsDataset } from '$lib/types/details-data';
 import { adaptBucketDetails } from './adapt-details';
@@ -7,28 +6,19 @@ import { emptyDetailsDataset } from './fallback-data';
 import { toPublicBucketError } from './public-error';
 import { fetchBucketRankingSnapshot } from './ranking-snapshot';
 
-const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
-
-let cached: { value: DetailsDataset; snapshotId: string; expiresAt: number } | undefined;
+let cached: { value: DetailsDataset; snapshotId: string } | undefined;
 let inFlight: Promise<DetailsDataset> | undefined;
 
-function cacheTtlMs() {
-	const configured = Number(env.HF_BUCKET_CACHE_TTL_MS);
-	return Number.isInteger(configured) && configured > 0 ? configured : DEFAULT_CACHE_TTL_MS;
-}
-
 async function refreshDetails() {
-	const rankingSnapshot = await fetchBucketRankingSnapshot();
+	const rankingSnapshot = await fetchBucketRankingSnapshot({ refreshManifest: true });
 	if (cached?.snapshotId === rankingSnapshot.manifest.snapshot_id) {
-		cached.expiresAt = Date.now() + cacheTtlMs();
 		return cached.value;
 	}
 
 	const value = adaptBucketDetails(await fetchBucketDetailsSnapshot(rankingSnapshot));
 	cached = {
 		value,
-		snapshotId: rankingSnapshot.manifest.snapshot_id,
-		expiresAt: Date.now() + cacheTtlMs()
+		snapshotId: rankingSnapshot.manifest.snapshot_id
 	};
 	return value;
 }
@@ -40,14 +30,6 @@ export async function getHfBucketDetails() {
 }
 
 export async function getHfBucketDetailsState(): Promise<BucketDataState<DetailsDataset>> {
-	if (cached && cached.expiresAt > Date.now()) {
-		return {
-			status: 'ok',
-			source: 'cache',
-			data: cached.value
-		};
-	}
-
 	if (!inFlight) {
 		inFlight = refreshDetails().finally(() => {
 			inFlight = undefined;

src/lib/server/hf-bucket/details-snapshot.ts

@@ -3,6 +3,9 @@ import { parseBucketDetailsMatrix } from './details-payload';
 import { fetchBucketRankingSnapshot, verifyBucketFileHash } from './ranking-snapshot';
 import type { BucketDetailsSnapshot, BucketRankingSnapshot } from './types';
 
+let cachedSnapshot: BucketDetailsSnapshot | undefined;
+let inFlight: { snapshotId: string; promise: Promise<BucketDetailsSnapshot> } | undefined;
+
 function parseJson(text: string, path: string) {
 	try {
 		return JSON.parse(text) as unknown;
@@ -72,6 +75,26 @@ export async function fetchBucketDetailsSnapshot(
 	rankingSnapshot?: BucketRankingSnapshot
 ): Promise<BucketDetailsSnapshot> {
 	rankingSnapshot ??= await fetchBucketRankingSnapshot();
+	const snapshotId = rankingSnapshot.manifest.snapshot_id;
+
+	if (cachedSnapshot?.manifest.snapshot_id === snapshotId) return cachedSnapshot;
+	if (inFlight?.snapshotId === snapshotId) return inFlight.promise;
+
+	const promise = fetchRemoteDetailsSnapshot(rankingSnapshot);
+	const currentRequest = { snapshotId, promise };
+	inFlight = currentRequest;
+
+	try {
+		cachedSnapshot = await promise;
+		return cachedSnapshot;
+	} finally {
+		if (inFlight === currentRequest) inFlight = undefined;
+	}
+}
+
+async function fetchRemoteDetailsSnapshot(
+	rankingSnapshot: BucketRankingSnapshot
+): Promise<BucketDetailsSnapshot> {
 	const path = rankingSnapshot.manifest.files.details_matrix;
 	const text = await fetchHfBucketText(path);
 	verifyBucketFileHash(rankingSnapshot.manifest, 'details_matrix', text);

src/lib/server/hf-bucket/ranking-cache.ts

@@ -1,4 +1,3 @@
-import { env } from '$env/dynamic/private';
 import type { BucketDataState } from '$lib/types/bucket-state';
 import type { RankingDataset } from '$lib/types/ranking-data';
 import { adaptBucketRanking } from './adapt-ranking';
@@ -7,28 +6,19 @@ import { emptyRankingDataset } from './fallback-data';
 import { toPublicBucketError } from './public-error';
 import { fetchBucketRankingSnapshot } from './ranking-snapshot';
 
-const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
-
-let cached: { value: RankingDataset; snapshotId: string; expiresAt: number } | undefined;
+let cached: { value: RankingDataset; snapshotId: string } | undefined;
 let inFlight: Promise<RankingDataset> | undefined;
 
-function cacheTtlMs() {
-	const configured = Number(env.HF_BUCKET_CACHE_TTL_MS);
-	return Number.isInteger(configured) && configured > 0 ? configured : DEFAULT_CACHE_TTL_MS;
-}
-
 async function refreshRanking() {
-	const snapshot = await fetchBucketRankingSnapshot();
+	const snapshot = await fetchBucketRankingSnapshot({ refreshManifest: true });
 	if (cached?.snapshotId === snapshot.manifest.snapshot_id) {
-		cached.expiresAt = Date.now() + cacheTtlMs();
 		return cached.value;
 	}
 
 	const value = adaptBucketRanking(await fetchBucketDetailsSnapshot(snapshot));
 	cached = {
 		value,
-		snapshotId: snapshot.manifest.snapshot_id,
-		expiresAt: Date.now() + cacheTtlMs()
+		snapshotId: snapshot.manifest.snapshot_id
 	};
 	return value;
 }
@@ -40,14 +30,6 @@ export async function getHfBucketRanking() {
 }
 
 export async function getHfBucketRankingState(): Promise<BucketDataState<RankingDataset>> {
-	if (cached && cached.expiresAt > Date.now()) {
-		return {
-			status: 'ok',
-			source: 'cache',
-			data: cached.value
-		};
-	}
-
 	if (!inFlight) {
 		inFlight = refreshRanking().finally(() => {
 			inFlight = undefined;

src/lib/server/hf-bucket/ranking-snapshot.ts

@@ -90,7 +90,7 @@ function verifySnapshot(snapshot: BucketRankingSnapshot) {
 }
 
 let cachedSnapshot: BucketRankingSnapshot | undefined;
-let inFlight: Promise<BucketRankingSnapshot> | undefined;
+let inFlight: { snapshotId: string; promise: Promise<BucketRankingSnapshot> } | undefined;
 
 async function fetchRemoteRankingSnapshot(
 	manifest: HfBucketManifest
@@ -123,23 +123,26 @@ async function fetchRemoteRankingSnapshot(
 
 export async function fetchBucketRankingSnapshot(options?: {
 	forceRefresh?: boolean;
+	refreshManifest?: boolean;
 }): Promise<BucketRankingSnapshot> {
-	const { manifest } = await getHfBucketManifest({ forceRefresh: options?.forceRefresh });
+	const { manifest } = await getHfBucketManifest({
+		forceRefresh: options?.forceRefresh || options?.refreshManifest
+	});
 
 	if (!options?.forceRefresh && cachedSnapshot?.manifest.snapshot_id === manifest.snapshot_id) {
 		return cachedSnapshot;
 	}
 
-	if (!inFlight) {
-		inFlight = fetchRemoteRankingSnapshot(manifest)
-			.then((snapshot) => {
-				cachedSnapshot = snapshot;
-				return snapshot;
-			})
-			.finally(() => {
-				inFlight = undefined;
-			});
-	}
+	if (inFlight?.snapshotId === manifest.snapshot_id) return inFlight.promise;
+
+	const promise = fetchRemoteRankingSnapshot(manifest);
+	const currentRequest = { snapshotId: manifest.snapshot_id, promise };
+	inFlight = currentRequest;
 
-	return inFlight;
+	try {
+		cachedSnapshot = await promise;
+		return cachedSnapshot;
+	} finally {
+		if (inFlight === currentRequest) inFlight = undefined;
+	}
 }

src/lib/server/hf-bucket/tools-cache.ts

@@ -21,7 +21,7 @@ function cacheTtlMs() {
 }
 
 async function refreshToolsSnapshot() {
-	const rankingSnapshot = await fetchBucketRankingSnapshot();
+	const rankingSnapshot = await fetchBucketRankingSnapshot({ refreshManifest: true });
 	if (cached?.snapshotId === rankingSnapshot.manifest.snapshot_id) {
 		cached.expiresAt = Date.now() + cacheTtlMs();
 		return cached.value;
@@ -62,14 +62,6 @@ export async function getHfBucketToolsSnapshot() {
 async function getHfBucketToolsSnapshotState(): Promise<
 	BucketDataState<BucketVisualizationSnapshot>
 > {
-	if (cached && cached.expiresAt > Date.now()) {
-		return {
-			status: 'ok',
-			source: 'cache',
-			data: cached.value
-		};
-	}
-
 	if (!inFlight) {
 		inFlight = refreshToolsSnapshot().finally(() => {
 			inFlight = undefined;