diff --git a/docs/release/sofiia-console-v1-announcement.md b/docs/release/sofiia-console-v1-announcement.md new file mode 100644 index 00000000..6211ff6d --- /dev/null +++ b/docs/release/sofiia-console-v1-announcement.md @@ -0,0 +1,71 @@ +# Sofiia Console v1.0 — Technical Release Announcement + +Sofiia Console v1 переходить у production-controlled стан: релізний процес відтворюваний, операційні перевірки формалізовані, ключові ризики закриті технічними контролями. + +## 1) Scope of This Release + +- Redis-backed idempotent send (multi-instance safe). +- Per-chat and per-operator rate limiting. +- Structured audit trail (write + query endpoint). +- Strict authentication for `/api/audit`. +- Cursor pagination hardening (tie-breaker safe). +- Structured JSON logging. +- `/metrics` endpoint for operational visibility. +- Audit retention (default 90 days) + pruning script. +- Preflight checks + release runbook + release evidence generator. + +## 2) New Guarantees (What is now true) + +### Reliability + +- Duplicate `send` requests are safe across instances. +- Pagination remains stable even with identical timestamps. +- Multi-node routing is verified by E2E tests. + +### Security + +- `/api/audit` requires explicit API key (no localhost bypass). +- Rate limits are enforced both per chat and per operator. +- Operator actions are captured in structured audit trail. + +### Operational Control + +- Release process is reproducible via runbook and scripts. +- Preflight checks catch key misconfigurations before deploy. +- Audit DB growth is controlled through retention + pruning. + +## 3) What Changes for Operators + +- `/api/audit` now requires API key even on localhost. +- Excessive sends may return `429 rate_limited`. +- Audit trail is queryable for incident investigations. +- Retention pruning should be scheduled (cron recommended). + +## 4) Known Limitations + +- Chat index remains local (not Redis-backed yet). +- Rate-limit backend defaults to inmemory unless Redis is enabled. +- No automatic alerting dashboards yet (manual metric review required). +- Audit DB is SQLite (single-node storage model). + +## 5) Release-Day Expectations (On-Call) + +During first release window: + +- Run preflight with strict mode: + - `STRICT=1 bash ops/preflight_sofiia_console.sh` +- Execute full smoke: + - health and metrics checks + - Redis idempotency A/B smoke +- Verify: + - audit write and read paths + - rate-limit counters increment as expected +- Monitor first 5-10 minutes for: + - 5xx error spikes + - unexpected rate-limit spikes + - replay spikes + +Rollback procedure: +- `docs/runbook/release-runbook-sofiia-console.md` + +> Sofiia Console v1 is production-controlled and operationally reproducible.