feat(utf8): переход движка на символьную семантику и UTF-8 (#3681)

.gitattributes

@@ -1,6 +1,7 @@
-/src/**           working-tree-encoding=KOI8-R eol=lf
-/tests/**         working-tree-encoding=KOI8-R eol=lf
-/tests/**/*.py    working-tree-encoding=UTF-8 eol=lf
+# Исходники в UTF-8 (issue #3681). До флипа тут стояло working-tree-encoding=KOI8-R:
+# в git блобы всегда лежали в UTF-8, а в рабочее дерево выкладывались в KOI8-R.
+/src/**           eol=lf
+/tests/**         eol=lf
 *.md              working-tree-encoding=UTF-8 eol=lf
 /.githooks/**     working-tree-encoding=UTF-8 eol=lf
 /lib.template/**  working-tree-encoding=KOI8-R eol=lf

.githooks/pre-commit

@@ -5,7 +5,7 @@
 # ============================================================================
 # Блокирует коммит если:
 # 1. Найден символ замены U+FFFD (О©╫)
-# 2. Файл должен быть KOI8-R, но находится в UTF-8
+# 2. Файл должен быть KOI8-R, но находится в UTF-8 (данные мира; исходники наоборот -- UTF-8)
 # 3. Найдены типичные паттерны битой кодировки
 # ============================================================================
 
@@ -97,8 +97,21 @@ for FILE in $FILES; do
         fi
 
         echo "  ✅ Кодировка правильная"
+    elif [[ "$FILE" == src/* || "$FILE" == tests/* ]]; then
+        # Исходники после флипа (issue #3681) обязаны быть валидным UTF-8. Файл, случайно
+        # сохранённый редактором в KOI8-R, внешне выглядит нормально, но ломает литералы.
+        if ! iconv -f utf-8 -t utf-8 "$FILE" >/dev/null 2>&1; then
+            echo "📄 $FILE"
+            echo "  ❌ ОШИБКА: не UTF-8. Исходники должны быть в UTF-8."
+            ERROR_FOUND=1
+            continue
+        fi
+        if grep -q "$BAD_CHAR" "$FILE" 2>/dev/null; then
+            echo "❌ [BLOCKER] Символ замены (О©╫) найден в: $FILE"
+            ERROR_FOUND=1
+        fi
     else
-        # Для не-KOI8-R файлов проверяем только символ замены
+        # Для остальных файлов проверяем только символ замены
         if grep -q "$BAD_CHAR" "$FILE" 2>/dev/null; then
             echo "❌ [BLOCKER] Символ замены (О©╫) найден в: $FILE"
             ERROR_FOUND=1

CLAUDE.md

@@ -213,46 +213,14 @@ Access world state via `MUD::` namespace functions:
 - Telnet protocol with MSDP (Mud Server Data Protocol) and MCCP compression
 - Multiple codepage support (Alt, Win, UTF-8, KOI8-R)
 
-## Development Guidelines (from CONTRIBUTING.md)
+## Development Guidelines
 
-### Code Style
-- **Standard**: C++20 (C++17 minimum)
-- **Indentation**: Tabs (size 4), no spaces for indentation
-- **Braces**: An opening brace on the same line separated by a space
-```cpp
-if (condition) {
-    // code here
-}
-```
-- **One statement per line** (applies to variable declarations too)
-- **Always use braces** for if/else/for/while bodies, even single statements
-- **Pointers/References**: `*` and `&` attached to type, space after
-```cpp
-const char* message = "example";
-const auto& reference = message;
-```
-
-### File Management
-- All new files must be added to `meson.build` (sources go into `main_sources` / `library_sources`, depending on the section)
-- Include vim modeline at end of files:
-```cpp
-// vim: ts=4 sw=4 tw=0 noet syntax=cpp :
-```
-
-### Memory Management
-- Prefer `new`/`delete` over `malloc`/`free`
-- Use smart pointers (`CharData::shared_ptr`, `ObjData::shared_ptr`) where possible
-- Avoid raw pointers for ownership
-
-### Testing
-- Run unit tests before committing: `./build/tests/tests`
-- Write tests for new code using GoogleTest framework
-- Tests are in `tests/` directory, named by module (e.g., `char.affects.cpp`, `fight.penalties.cpp`)
+**Правила разработки живут в [CONTRIBUTING.md](CONTRIBUTING.md) — читай его перед тем, как
+править код, и следуй ему.** Здесь их копии нет намеренно: две копии расходятся, и потом
+непонятно, какая верна.
 
-### Compiler Warnings
-- Must compile on Windows, Linux, and Cygwin
-- Fix all compiler warnings, especially in new code
-- Build with `-Wall -Wextra` enabled
+Там про стиль (отступы табами, скобки, по одному объявлению в строке), добавление новых файлов
+в `meson.build`, работу с памятью, unit-тесты и требование к сборке без предупреждений.
 
 ## Common Development Patterns
 
@@ -367,12 +335,12 @@ The heartbeat system includes built-in profiling:
 
 ## Critical Notes
 
-- **File Encoding**: All project source files MUST be in KOI8-R encoding (not UTF-8). This is critical for proper Russian text handling in the codebase. Use `iconv` to convert if needed: `iconv -f utf8 -t koi8-r input.cpp > output.cpp`
+- **File Encoding**: All project source files are UTF-8 (issue #3681). Edit them directly — no iconv dance. The world data on disk (`lib/`, `lib.template/`) is still KOI8-R; see `.gitattributes` for exactly which trees.
 - **Thread Safety**: Main game loop is single-threaded; use `BlockingQueue` for cross-thread communication
 - **Shared Pointers**: Always use `CharData::shared_ptr` and `ObjData::shared_ptr` to prevent use-after-free
 - **Pulse Timing**: Never use wall-clock delays; register actions with heartbeat system
 - **Script Depth**: DG Scripts limited to 512 recursion depth to prevent stack overflow
-- **Runtime Encoding**: While source files are KOI8-R, runtime text can be multiple encodings (Alt, Win, UTF-8, KOI8-R) based on client settings
+- **Runtime Encoding**: The engine holds text in UTF-8 and works on it per character (`utils/native_text.*`). Client codepages (Alt, Win, KOI8-R, UTF-8) are converted at the network boundary only; the disk boundary (`from_disk_text` / `to_disk`) keeps world files in KOI8-R.
 
 ## Claude Code Workflow Rules
 
@@ -401,33 +369,40 @@ meson setup build_otel \
 ninja -C build_otel -j$(($(nproc)/2))
 ```
 
-### File Encoding - CRITICAL
-**Proper workflow for editing KOI8-R files:**
+### File Encoding
+Sources are UTF-8. Edit `.cpp`/`.h` directly with the Edit tool — the KOI8-R conversion dance is
+gone (issue #3681). Git always stored these blobs as UTF-8; what changed is that the working tree
+no longer converts them on checkout.
 
-For files marked as `working-tree-encoding=KOI8-R` in .gitattributes (all files in /src/**, /tests/**):
+**Переключились на ветку с флипом в уже существующем дереве — перевыкачайте исходники:**
 
 ```bash
-# 1. Convert to UTF-8 for editing
-iconv -f koi8-r -t utf-8 src/file.cpp > /tmp/file_utf8.cpp
+rm -rf src tests && git checkout -- src tests
+```
+
+`working-tree-encoding` применяется во время checkout'а, а содержимое блоба при флипе не менялось,
+поэтому git оставляет ранее выкаченные файлы в KOI8-R и считает дерево чистым — `git status` молчит.
+Собранный из такого дерева бинарь получает кои-восьмые строковые литералы при движке, который
+считает весь текст UTF-8: расходятся сравнения имён, доски, кодировка лога, а запись на диск гонит
+такие литералы через словарь транслита. `meson setup` теперь это проверяет и отказывается собирать.
 
-# 2. Edit the UTF-8 version with Edit tool or text editor
-# (make your changes here)
+Still KOI8-R on disk, and still needing care: the world and configs (`lib/`, `lib.template/`,
+`/lib/cfg/**`, `/lib/misc/**`, `/lib/text/help/**`, `/lib/etc/board/**`). For those the old rule
+holds — convert, edit, convert back:
 
-# 3. Convert back to KOI8-R
-iconv -f utf-8 -t koi8-r /tmp/file_utf8.cpp > src/file.cpp
+```bash
+iconv -f koi8-r -t utf-8 lib/cfg/some.xml > /tmp/some_utf8.xml
+# edit /tmp/some_utf8.xml
+iconv -f utf-8 -t koi8-r /tmp/some_utf8.xml > lib/cfg/some.xml
 ```
 
-**NEVER use the Edit tool directly on existing .cpp/.h files that contain Russian text.**
-Only use Edit for:
-- Newly created files that will be pure ASCII/English
-- Temporary UTF-8 converted files (in /tmp)
-- Files in .gitattributes marked as UTF-8 (e.g., Python files)
+The pre-commit hook enforces both directions: sources must parse as UTF-8, world files must stay
+in the encoding `.gitattributes` declares.
 
 **NEVER use sed for editing source files.** Sed has tendency to:
 - Modify files in unexpected places (matching wrong lines)
 - Lead to file corruption detection and accidental `git checkout` (losing all uncommitted work)
 - Cause cumulative errors from multiple sed operations
-- Corrupt KOI8-R encoding
 
 **Alternative: unified diff patches** - for small targeted changes:
 ```bash

CONTRIBUTING.md

@@ -7,7 +7,7 @@
 При написании кода вы должны следовать правилу "одна команда - одна строка".
 Желательно это же правило распространять и на объявления переменных.
 
-Былины используют стандарт C++17.
+Былины используют стандарт C++20 (задан в meson.build: cpp_std=c++20).
 
 Тела конструкций if, if ... else for, while, do ... while всегда должны быть
 заключены в символы '{', '}'.
@@ -22,10 +22,27 @@
 
     using meat_mapping_t = std::pair<ObjVnum, ObjVnum>;
 
-Код должен быть компилируемым на Windows, Linux. При компиляции вы должны
-уделять особое внимание предупреждениям компилятора и исправлять их при первой
-же возможности. Особенно если предупреждения появились вследствие добавленного
-вами кода.
+Код должен быть компилируемым на Windows, Linux.
+
+**Перед коммитом сборка должна быть без единого предупреждения.** Достаточно
+проверить на своей платформе; смотреть сборки CI не обязательно, хотя и полезно.
+
+Предупреждения надо чинить по существу — понять, от чего оно, и устранить
+причину. Заглушать нельзя: ни понижением уровня говорливости компилятора, ни
+`-Wno-…`, ни `#pragma diagnostic ignored`, ни приведением типа ради тишины.
+
+Предупреждение компилятора — это бесплатный статический анализ, который знает
+то, чего не найти ни глазами, ни поиском по тексту. Живой пример: два падения
+боевого сервера (issue #3751 и #3752) компилятор назвал заранее строкой
+`directive writing 170 bytes into a region of size 162` — русский текст в UTF-8
+занимает вдвое больше, чем занимал в KOI8-R, и фраза перестала влезать в буфер.
+Предупреждение лежало в логе сборки всё время, пока по нему не начали падать
+процессы. С тех пор именно это переполнение — уже ошибка сборки, а не
+предупреждение (`-Werror=format-overflow` в meson.build).
+
+Имейте в виду: **инкрементальная сборка предупреждения прячет** — уже собранные
+файлы не перекомпилируются, и лог выглядит чистым. Когда важно увидеть весь лог,
+собирайте с нуля в отдельном каталоге.
 
 Старайтесь перед коммитом своих изменений запускать unit-тесты. Старайтесь
 писать свои unit-тесты для написанного вами кода. Часто ошибки можно обнаружить

Dockerfile

@@ -34,6 +34,12 @@ ARG WITH_OTEL=false
 ARG WITH_ADMIN_API=false
 ARG WITH_YAML=true
 ARG WITH_SQLITE=false
+# Ревизия и счётчик коммитов: внутри контейнера git бесполезен (контекст может быть worktree,
+# где .git -- файл-ссылка наружу, или распакованный архив), поэтому пробрасываем их снаружи:
+#   --build-arg GIT_REV=$(git rev-parse --short HEAD) \
+#   --build-arg GIT_COUNT=$(git rev-list --count HEAD)
+ARG GIT_REV=
+ARG GIT_COUNT=
 
 RUN apk add --no-cache \
     build-base make meson ninja git cmake samurai \
@@ -61,6 +67,9 @@ RUN if [ "$WITH_SQLITE" = "true" ]; then apk add --no-cache sqlite-dev; fi
 WORKDIR /mud/mud
 COPY . /mud/mud
 
+ENV BYLINS_GIT_REV=${GIT_REV} \
+    BYLINS_COMMIT_COUNT=${GIT_COUNT}
+
 RUN OTEL_OPT=$([ "$WITH_OTEL" = "true" ] && echo system || echo disabled); \
     ADMIN_OPT=$([ "$WITH_ADMIN_API" = "true" ] && echo true || echo false); \
     YAML_OPT=$([ "$WITH_YAML" = "true" ] && echo builtin || echo disabled); \

meson.build

@@ -58,6 +58,18 @@ if cpp.get_argument_syntax() == 'gcc'
         project_args += ['-Ofast']
     endif
     project_args += ['-Wno-format-truncation']
+
+    # Переполнение буфера строкой формата -- ошибка, а не предупреждение. Компилятор считает,
+    # сколько байт запишет sprintf, и сравнивает с размером буфера; предупреждение об этом
+    # входит в -Wall и лежало в логе сборки, пока по нему не начали падать боевые процессы
+    # (#3751, #3752): русский текст в UTF-8 занимает вдвое больше, чем занимал в KOI8-R,
+    # и фразы, укладывавшиеся впритык, перестали влезать. Числа в коде при этом нет -- растёт
+    # сам литерал, поэтому глазами и грепом такое не ищется, а компилятором ищется даром.
+    #
+    # Уровень по умолчанию, не =2: тот цепляется к теоретической оценке ширины %f.
+    if cpp.has_argument('-Werror=format-overflow')
+        project_args += ['-Werror=format-overflow']
+    endif
     if fortify_source
         # -U на случай, если тулчейн уже определил _FORTIFY_SOURCE (иначе redefine-варнинг)
         project_args += ['-U_FORTIFY_SOURCE', '-D_FORTIFY_SOURCE=3']
@@ -88,9 +100,6 @@ if host_system == 'windows'
     endif
 endif
 
-if cpp.get_id() == 'clang'
-    project_args += '-Wno-invalid-source-encoding'
-endif
 
 cpu = host_machine.cpu_family()
 # GNU-driver compilers only. clang-cl (get_id()=='clang-cl') takes its arch from the MSVC
@@ -108,12 +117,7 @@ if host_system == 'windows'
     if cpp.get_argument_syntax() == 'msvc'   # MSVC and clang-cl
         project_args += ['/MP', '/bigobj', '-DFMT_UNICODE=0', '/external:anglebrackets', '/external:W0']
         if cpp.get_id() == 'msvc'
-            # MSVC accepts the KOI8-R codepage (20866) for source/exec charset.
-            project_args += ['/source-charset:koi8-r', '/execution-charset:koi8-r']
-        else
-            # clang-cl rejects non-UTF-8 /source-charset ('invalid value koi8-r'); it keeps narrow-literal
-            # bytes as-is, so just silence the KOI8-R source-encoding warnings (as for the GNU clang driver).
-            project_args += ['-Wno-invalid-source-encoding']
+            project_args += ['/source-charset:utf-8', '/execution-charset:utf-8']
         endif
     elif cpp.get_id() == 'gcc' or cpp.get_id() == 'clang'
         project_args += ['-Wa,-mbig-obj', '-D__USE_MINGW_ANSI_STDIO=1']
@@ -357,6 +361,15 @@ endif
 subdir('src/third_party_libs/libfort')
 dependencies += [fmt_dep, fort_dep]
 
+# Исходники обязаны быть в UTF-8 (issue #3681). Дерево, выкаченное до флипа, при
+# переключении ветки остаётся в KOI8-R -- git молчит, дерево числится чистым, а
+# собранный отсюда бинарь получает кои-восьмые строковые литералы, и движок расходится
+# сам с собой. Ловим это здесь, а не по кракозябрам в логе боевого сервера.
+encoding_check = run_command(py3, files('tools/meson/check_sources_utf8.py'), meson.project_source_root(), check: false)
+if encoding_check.returncode() != 0
+    error(encoding_check.stdout().strip())
+endif
+
 git = find_program('git', required: false)
 git_rev = 'unknown'
 if git.found()
@@ -645,7 +658,10 @@ main_sources = files(
   'src/gameplay/mechanics/title.cpp',
   'src/gameplay/statistics/top.cpp',
   'src/utils/utils.cpp',
+  'src/utils/utf8.cpp',
+  'src/utils/native_text.cpp',
   'src/utils/utils_encoding.cpp',
+  'src/utils/translit_koi8.cpp',
   'src/gameplay/mechanics/weather.cpp',
   'src/engine/olc/zedit.cpp',
   'src/utils/utils_string.cpp',

meson_options.txt

@@ -10,6 +10,9 @@ option('lua_formatter', type: 'boolean', value: true, description: 'Build the em
 option('with_asan', type: 'boolean', value: false, description: 'Build with Address Sanitizer')
 option('use_pch', type: 'boolean', value: true, description: 'Use precompiled headers for circle.library')
 
+# KOI8-R -> UTF-8 migration (issue #3681). Selects the engine's native runtime string encoding.
+# koi8r = current byte semantics (default); utf8 = character semantics via the utf8:: helpers.
+
 # Options for Admin API and Web features
 option('admin_api', type: 'boolean', value: false, description: 'Enable Admin API and JSON-related features')
 

src/administration/accounts.cpp

@@ -3,6 +3,7 @@
 * 2018 (c) bodrich
 */
 #include "accounts.h"
+#include "utils/native_text.h"
 #include "password.h"
 #include "engine/entities/zone.h"
 #include <sstream>
@@ -85,7 +86,7 @@ void Account::show_players(CharData *ch) {
 	ss << "Данные аккаунта: " << this->email << "\r\n";
 	for (auto &x : this->players_list) {
 		std::string name = GetNameByUnique(x);
-		name[0] = UPPER(name[0]);
+		native_text::capitalize_first(name);
 		ss << count << ") " << name << "\r\n";
 		count++;
 	}
@@ -101,7 +102,7 @@ void Account::list_players(DescriptorData *d) {
 	for (auto &x : this->players_list) {
 		std::string name = GetNameByUnique(x);
 		iosystem::write_to_output((std::to_string(count) + ") ").c_str(), d);
-		name[0] = UPPER(name[0]);
+		native_text::capitalize_first(name);
 		iosystem::write_to_output(name.c_str(), d);
 		iosystem::write_to_output("\r\n", d);
 		count++;
@@ -244,7 +245,10 @@ void Account::set_password(const std::string &password) {
 }
 
 bool Account::compare_password(const std::string &password) {
-	return CompareParam(this->hash_password, CRYPT(password.c_str(), this->hash_password.c_str()), true);
+	// Тот же приём, что в Password::compare_password: хэш посчитан по дисковым байтам,
+	// поэтому пароль приводим к дисковой кодировке перед crypt (issue #3681).
+	return CompareParam(this->hash_password,
+						CRYPT(native_text::to_disk(password).c_str(), this->hash_password.c_str()), true);
 }
 
 bool Account::quest_is_available(int id) {