SlangUA: Instructions file for Codex

AGENTS.md

Правила роботи в репозиторії SlangUA для AI-агентів і нових контриб'юторів.

Цей файл описує як тут працювати. Що саме побудовано — у README.md та plans/docs/README.md. Повний технічний контекст одним документом, який можна віддати сторонній моделі, — plans/SLANGUA-BRIEFING.md.

1. Перед початком роботи

1. Прочитай plans/docs/README.md → plans/architecture.md → plans/ROADMAP.md. Документація тут є контрактом, а не описом післяфактум.
2. Виконай git status один раз на початку. Незв'язані зміни, які вже були в робочій копії, — чужі: не комітити, не відкочувати, не «чистити».
3. Знайди поточну стадію в ROADMAP. Стадії виконуються послідовно; не перестрибуй наперед.
4. Перед зміною поведінки API або безпеки прочитай відповідний документ у plans/docs/ — там зафіксовано обґрунтування, і його потрібно оновити разом із кодом.

2. Непорушні інваріанти

Це не стильові побажання. Порушення будь-якого пункту — привід відкинути зміну.

• Не послаблювати age gate, автентифікацію, перевірку власності, rate limiting, захист від prompt injection і серверну валідацію заради спрощення UI. Ніколи.
• Age gate має єдину справжню точку перевірки для перекладу — TranslationService. Він порівнює ageRestricted стилю з user.ageConfirmedAdult до звернення до preview-кешу і до AI. GET /styles повертає всі увімкнені стилі разом із прапорцем ageRestricted (він не фільтрує), а UI лише блокує картку — щоб користувач бачив стиль і міг підтвердити вік. Клієнтське блокування не є захистом і не може його замінити. Окрема серверна перевірка того самого правила стоїть у POST /share/inline (шарити 18+ може лише підтверджений повнолітній) — це власний gate іншої дії, а не дублікат.
• Сервер ніколи не довіряє тексту від клієнта. POST /translate/save приймає лише previewId; POST /share/inline — лише previewId або translationId. Ні originalText, ні translatedText з клієнта не зберігаються і не надсилаються.
• Rate limiter падає закрито. Якщо Redis недоступний — 503 RATE_LIMITER_UNAVAILABLE. Сервіс не працює, вдаючи, що лімітів немає.
• Style Engine не має тихого fallback. Невідомий або вимкнений стиль завжди кидає помилку, яка перетворюється на 400 зі списком доступних стилів. Ніякого підставляння GEN_Z.
• Шеринг — лише всередині Telegram. Основний шлях: сервер рендерить текст (shareText), клієнт передає його у власний чат-пікер Telegram через openTelegramLink('t.me/share/url?...'); inline mode (switchInlineQuery) — резервний шлях. Заборонено: браузерний share sheet, будь-який неявно створений публічний URL з перекладом, а також будь-що в share-інтенті, крім самого тексту повідомлення (ні токена, ні previewId, ні внутрішнього посилання).
• Адмінка невидима для не-адмінів і не має ролі в базі. Доступ дають два незалежні фактори: Telegram-id у ADMIN_TELEGRAM_IDS і пароль (ADMIN_PASSWORD_HASH), який відкриває крок-ап сесію під X-Admin-Token. Кому не дозволено — усі /api/v1/admin/* віддають 404 з тим самим тілом, що й неіснуючий маршрут (не 401 і не 403: вони підтверджують існування панелі). Тому гейт — це хук onRequest, а не preHandler: Fastify валідує тіло раніше за preHandler, і 400 VALIDATION_ERROR виказував би маршрут так само. Прапорець isAdmin у /user/me — лише підказка клієнту, чи малювати кнопку, а не рішення про доступ. Ознаки адміна в Postgres немає навмисно: адмінство — конфігурація деплою, а рядок у БД міг би змінити будь-хто з правом запису, і відкат з бекапу воскресив би колишнього адміна.
• Кіл-світч провайдерів — не circuit breaker, і він не має TTL. Breaker відповідає на питання «чи провайдер зараз падає?» і сам себе лікує через CIRCUIT_BREAKER_RESET_MS; кіл-світч відповідає на питання «чи людина взагалі хоче туди трафік?» і не лікується ніколи — ні через кулдаун, ні через рестарт, ні через успішний пробний запит. Стан — один хеш Redis ai:provider:disabled (поле = id провайдера, значення = {by, at, reason}), без TTL: у пам'яті процесу він тихо ввімкнув би провайдера на наступному деплої, а з TTL — воскресив би його в довільний момент, коли ніхто не дивиться. AIService читає світч один раз на запит, перед breaker'ами, і вимкнений провайдер не потрапляє ні в ланцюг fallback, ні в пробний запит на відновлення, ні в явний виклик за id. Світч сильніший і за preview-кеш: TranslationService викликає aiService.hasPermittedProviders() до звернення до кешу на обох шляхах перекладу, тому при повністю вимкненому ланцюгу теплий кеш віддає той самий 503, а не власний вивід уже вбитого провайдера до кінця TTL — інакше оператор не може сказати, чи його рішення взагалі подіяло. Стан breaker'ів у цій точці навмисно не читається: breaker лікується сам, і під час справжнього збою кеш саме й має продовжувати відповідати. Читання падає закрито: помилка Redis перетворюється на звичний 503 AI_PROVIDER_UNAVAILABLE, бо трактувати її як «нічого не вимкнено» означало б відправити трафік саме туди, куди оператор заборонив. Наявність поля — це і є світч: нерозбірливе значення все одно вимикає провайдера (щоб HSET, зроблений руками під час інциденту, працював). Вимкнути все дозволено навмисно — інакше панель була б безсилою саме тоді, коли потрібна, — але наслідок озвучується заздалегідь: клієнт попереджає, сервер логує результат на рівні error з Telegram-id оператора, а користувач бачить той самий 503, у якому немає ні id провайдера, ні причини.
• Спостережуваність нічого не сповільнює і нічого не ідентифікує. Метрики й стрічка помилок пишуться в одному хуку onResponse — після того, як відповідь уже пішла, — тому обидва записи падають відкрито: помилка Redis коштує однієї точки на графіку і логується на рівні debug. Це не суперечить правилу «rate limiter падає закрито»: лімітер вирішує, чи пускати запит, і мусить відмовити, коли не може вирішити, а цей хук лише описує вже завершене. Читання, навпаки, падає закрито — сторінка з нулями читалася б як «трафіку немає», а не «даних немає». Що можна зберігати — це список дозволеного, а не фільтр: статус-код, шаблон маршруту (/api/v1/history/:id, ніколи конкретний шлях із id), наш код помилки, технічне повідомлення, обрізане до 300 символів, внутрішній id користувача і requestId. Ні тіла запиту, ні заголовків, ні тексту перекладу, ні Telegram-id: стрічка, що цитувала б текст користувача, відтворила б у Redis саме те, що розділення preview/save тримає подалі. Не рахуються OPTIONS, /health* і самі /api/v1/admin/* — панель опитує себе, і оператор, який дивиться на графік, не повинен його роздувати. Код і повідомлення в стрічку кладе captureErrorSnapshot(request, code, message): глобальний обробник помилок робить це для всього, що до нього доходить, а маршрути, які ловлять свої помилки самі (/translate/*, /share/inline), мусять викликати його явно — інакше найчастіший реальний збій виглядав би в стрічці як голий 5xx без причини.
• Аудіо голосового вводу не зберігається ніде і ніколи. POST /api/v1/transcribe отримує запис, передає його провайдеру й повертає текст: ні Postgres, ні Redis, ні тимчасовий файл, ні рядок логу. Транскрипт стає рядком Translation лише тоді, коли користувач сам зробить preview і збереже його — голос це спосіб набору, а не окремий шлях перекладу. Маршрут обов'язково автентифікований (відкритий ендпоінт транскрипції — це безкоштовний STT-проксі за кошт оператора) і має власний бюджет запитів, бо кожен виклик витрачає квоту провайдера, спільну для всього деплою. Ключі транскрипції — окремий пул (STT_API_KEY), а не ключі AI-шару. Деталі — plans/docs/06-security.md.
• Секрети лише через env. Ключі AI-провайдерів ніколи не потрапляють на клієнт.