docs: add optional cache layer plan

docs/commercial-boundaries.md

@@ -30,6 +30,7 @@
 - секреты, auth profiles, agent publishing, logs и usage;
 - статический ключ AI-агента;
 - контейнерное развертывание Community;
+- optional cache abstraction и Community fallback path без внешнего cache store;
 - документация, тесты и демо-сценарии Community.
 
 ## 4. Что считается коммерческим контуром
@@ -44,6 +45,7 @@
 - advanced streaming execution modes;
 - metering и billing;
 - cloud control plane;
+- managed shared cache layer defaults;
 - enterprise licensing and entitlement checks;
 - private operational tooling and support tooling.
 
@@ -104,6 +106,7 @@
 - edition flags;
 - protocol registry abstraction;
 - token issuer abstraction;
+- cache store abstraction;
 - feature availability checks.
 
 Private code должен подключаться как реализация этих контрактов, а не как условные ветки по всему коду Community.

docs/implementation-plan.md

@@ -179,7 +179,22 @@
 - build provenance и подпись артефактов документированы;
 - коммерческий код не требуется публиковать в public repository.
 
-## 13. Этап 10. Live staging and demo readiness
+## 13. Этап 10. Optional cache and coordination layer
+
+### Цель
+
+Подготовить optional cache/coordination layer так, чтобы платформа могла использовать `Valkey/Redis`,
+но не зависела от него для базового запуска.
+
+### DoD
+
+- определены абстракции для cache/coordination state;
+- Community может запускаться без внешнего cache store;
+- Community deployment path умеет поднимать optional `Valkey`;
+- Cloud использует shared cache layer как default managed runtime component;
+- Enterprise может подключать свой `Valkey/Redis` на уровне single-node или cluster deployment.
+
+## 14. Этап 11. Live staging and demo readiness
 
 ### Цель
 
@@ -192,7 +207,7 @@
 - demo user flow подтвержден на реальном окружении;
 - регрессии в publish/call/auth flow ловятся до релиза.
 
-## 14. Связанные документы
+## 15. Связанные документы
 
 - `docs/product-editions.md`
 - `docs/commercial-boundaries.md`

docs/product-editions.md

@@ -48,6 +48,7 @@ Crank развивается как три редакции:
 - статический ключ AI-агента;
 - только `security_level = standard`;
 - контейнерное развертывание;
+- optional cache layer на базе `Valkey`, если оператор хочет снизить нагрузку;
 - документация, демо-сценарий и базовый CI.
 
 ### 3.3. Что не входит
@@ -81,6 +82,7 @@ Crank развивается как три редакции:
 - `SSO`, `2FA`, расширенная `RBAC`, `audit log`;
 - `GraphQL`;
 - `gRPC unary`;
+- shared cache layer, если он нужен для self-hosted production load;
 - короткоживущие машинные токены;
 - одноразовые токены для критичных операций;
 - `security_level = elevated` и `security_level = strict`;
@@ -105,6 +107,7 @@ Crank развивается как три редакции:
 - usage metering;
 - тарифы и лимиты;
 - cloud control plane;
+- shared cache layer по умолчанию для снижения нагрузки и хранения ephemeral coordination state;
 - эксплуатационный мониторинг и обновления со стороны поставщика;
 - биллинг и tenant-oriented support tooling.
 
@@ -121,6 +124,7 @@ Crank развивается как три редакции:
 | WebSocket / SOAP / gRPC streaming | no | yes | yes |
 | Streaming modes | no | yes | yes |
 | Static agent key | yes | yes | yes |
+| Optional Valkey/Redis cache backend | yes | yes | yes |
 | Short-lived MCP token | no | yes | yes |
 | One-time MCP token | no | yes | selectively |
 | `security_level = standard` | yes | yes | yes |

docs/repository-split-map.md

@@ -46,6 +46,7 @@ Public repository.
   - static AI-agent key;
   - only `security_level = standard`;
 - `deploy/community/*`;
+- optional `Valkey` service definition для Community deployment;
 - public CI/CD for Community;
 - Community docs, smoke docs и demo flow.
 
@@ -74,6 +75,7 @@ Private repository.
   - `audit log`
 - premium protocol/runtime additions, если они не входят в Community;
 - enterprise deployment manifests;
+- optional cluster-aware cache integration для self-hosted production;
 - private container/release packaging;
 - enterprise operator docs.
 
@@ -88,6 +90,7 @@ Private repository.
 - billing;
 - hosted tenant management;
 - hosted operational tooling;
+- managed shared cache layer defaults and cache operations;
 - cloud-only delivery manifests;
 - cloud release pipeline;
 - hosted support/admin tooling.

docs/runtime-config.md

@@ -89,6 +89,9 @@ var/crank/
 
 - `CRANK_ADMIN_TOKEN`
 - `CRANK_DEMO_SEED`
+- `CRANK_CACHE_BACKEND`
+- `CRANK_CACHE_URL`
+- `CRANK_CACHE_DEFAULT_TTL_MS`
 
 Стартовое значение для refresh published tools:
 
@@ -146,8 +149,23 @@ Demo/deployment:
 - включенная app-level auth-защита admin-api;
 - стабильный `Streamable HTTP` endpoint для MCP.
 - containerized runtime через `Docker` и `docker-compose`.
+- optional shared cache layer через `Valkey/Redis`.
 - registry-backed image rollout через `GHCR` или совместимый registry.
 
+### Cache env
+
+Для optional cache/coordination layer должны быть предусмотрены:
+
+- `CRANK_CACHE_BACKEND`
+- `CRANK_CACHE_URL`
+- `CRANK_CACHE_DEFAULT_TTL_MS`
+
+Рекомендуемая модель:
+
+- `CRANK_CACHE_BACKEND=memory` по умолчанию;
+- `CRANK_CACHE_BACKEND=valkey` или `redis` при наличии внешнего cache store;
+- без этих переменных система должна оставаться полностью работоспособной.
+
 ### Auth env
 
 Для app-level auth нужны:
@@ -226,6 +244,7 @@ runtime env-переменной. Это значит, что:
 - `Dockerfile` для backend приложений;
 - `deploy/community/docker-compose.yml` как canonical Community deployment manifest;
 - `deploy/community/.env.example` как canonical Community env template;
+- optional `Valkey` service как рекомендованный, но не обязательный компонент Community deployment;
 - root `docker-compose.yml` и root `.env.example` только как local development convenience files;
 - healthcheck endpoints;
 - reverse proxy configuration examples.