Идентичность на ULID: download_infohash, guarded-дедуп, миграция (ulid-identity)

Все сущности переехали с INTEGER AUTOINCREMENT на TEXT ULID (lowercase,
internal/ident — единая точка генерации и разбора; oklog/ulid). Инфохэши
загрузки — множество (download_infohash, v1/v2 гибридных торрентов): дедуп
и сопоставление в поллинге по любому из хешей, magnet-парсер отдаёт оба
хеша гибридной ссылки, усечённый v2-хеш v2-only раздач не хранится.

Инвариант «не более одной активной загрузки на infohash» вместо снятого
unique-индекса держат guarded-методы store в одной write-транзакции
(_txlock=immediate): CreateDownloadIfNoActive (приём/adopt, с доносом
недостающих хешей), ActivateIfNoOtherActive (retry/recovery/relink, отказ
до побочных эффектов), guarded AddInfohashes; SetDownloadState отклоняет
терминал→активное как механический бэкстоп.

Миграция 0006 — первая Go-миграция goose: пересоздание таблиц при
включённых FK, backfill ULID с timestamp из created_at (хронология id
сохранена), разнос infohash, удаление idempotency_key. BREAKING: формат id
в URL/логах/Telegram, REST-поля id (string) и infohashes (список).

Новая конвенция docs/conventions/database.md (без числовых PK), корреляция
в логах grep'ом по голому ULID, ER-схема обновлена. Спеки: новая capability
identity, MODIFIED в state-reconciliation; change заархивирован. Пройдены
ревью дизайна и кода (по 8 углов), все находки исправлены с
регрессионными тестами.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/conventions/README.md

@@ -16,3 +16,6 @@
   (Ansible+Vault), валидация на старте.
 - [errors.md](errors.md) — ошибки: stdlib, обёртка `%w`, `errors.Is`/`As`,
   трансляция на внешней границе.
+- [database.md](database.md) — БД и идентификаторы: TEXT ULID PK через
+  `internal/ident` (без AUTOINCREMENT), lowercase + нормализация на границах,
+  естественные ключи у деталей.

docs/conventions/database.md

@@ -0,0 +1,47 @@
+# Конвенция: база данных и идентификаторы
+
+Как мы устраиваем таблицы и ключи в SQLite. Актуальная схема —
+[../specs/database.md](../specs/database.md); обоснование выбора ULID —
+`openspec/changes/ulid-identity/design.md` (после архивации — в истории git).
+
+## Первичные ключи — ULID, не автоинкремент
+
+- **PK сущности — TEXT ULID** (26 символов Crockford base32), генерируется
+  **приложением** в момент создания записи. `INTEGER PRIMARY KEY
+  AUTOINCREMENT` в новых таблицах не используем.
+- Почему ULID: сортируем по времени создания (`ORDER BY id` = хронология),
+  компактен и удобен в URL/логах (без дефисов — grep и двойной клик берут id
+  целиком), глобально уникален across таблиц — поиск по голому id находит
+  все записи сущности в логах.
+- **Единственная точка генерации и разбора — `internal/ident`**:
+  `ident.NewID()` при создании (в Create-методах `store`), `ident.Parse()`
+  на входных границах. Никаких самодельных генераторов.
+
+## Канонический вид — lowercase
+
+- Генерим и храним id в **нижнем регистре**. Сравнение строк в SQLite
+  побайтовое, поэтому любой внешний id (URL, форма, callback-data)
+  ОБЯЗАТЕЛЬНО проходит `ident.Parse` до запроса к БД — он валидирует формат
+  и нормализует регистр (base32 ULID case-insensitive при декодировании).
+- Синтаксически невалидный id трактуем как несуществующую сущность (404),
+  без похода в БД.
+
+## Естественные и составные ключи — для деталей
+
+- У таблиц-деталей/связей допустим естественный или составной ключ вместо
+  ULID, когда он есть по природе данных: `download_infohash` — PK
+  `(infohash, download_id)`, `override` — `UNIQUE(download_id, field)`.
+  Отдельный ULID там — мёртвый вес.
+- Прочие генерируемые идентификаторы (например, `apply_batch_id`) — тоже
+  через `ident.NewID()`: единый формат, сортируемость, корреляция в логах.
+
+## Прочее
+
+- Enum-поля (`state`, `kind`, …) — обычный `TEXT` без `CHECK`; допустимые
+  значения держит код (`internal/store`).
+- Временные метки — `TEXT DEFAULT (datetime('now'))` (UTC), формат
+  `store.ParseTime`/`FormatTime`.
+- Миграции — goose (`internal/store/migrations`): SQL-файлы для DDL;
+  Go-миграции (`goose.AddMigrationContext`) — когда нужен код (генерация
+  id, backfill). При изменении структуры обновляем ER-схему
+  [../specs/database.md](../specs/database.md) в том же change.

docs/conventions/logging.md

@@ -18,7 +18,7 @@ OpenSpec-спеках (`### Requirement` с `SHALL`).
   фильтрацию и агрегацию через `jq`/DuckDB без регулярок.
 
 ```json
-{"time":"2026-06-28T11:23:45.123456Z","level":"INFO","msg":"download accepted","capability":"ingest","download_id":"a1b2","infohash":"…","media_type":"movie","title":"Дюна: Часть вторая"}
+{"time":"2026-06-28T11:23:45.123456Z","level":"INFO","msg":"download accepted","capability":"ingest","download_id":"01jz2k7f8q9r3s4t5v6w7x8y9z","infohash":"…","media_type":"movie","title":"Дюна: Часть вторая"}
 ```
 
 ## Сообщение
@@ -100,14 +100,16 @@ log.Info(fmt.Sprintf("download %s accepted as movie", id))
 Если когда-нибудь поедем в несколько инстансов, добавим `service.version`
 одной строкой при старте.
 
-## Корреляция по download_id
+## Корреляция по id сущности
 
-Отдельный случайный `trace_id` не заводим — у загрузки уже есть стабильный
-осмысленный ключ: `download_id` (и `infohash`), он лежит в SQLite.
+Отдельный случайный `trace_id` не заводим — у сущностей уже есть стабильные
+осмысленные ключи: ULID-идентификаторы (`download_id`, `recognition_id`,
+`batch_id`, см. [database.md](database.md)), они лежат в SQLite.
 
-- Заводим scoped-логгер на загрузку и протаскиваем его через
-  `context.Context` сквозь асинхронные стадии (приём → скачивание →
-  распознавание → раскладка), чтобы ключ дописывался на каждую запись сам:
+- Каждая запись, относящаяся к сущности, несёт её id в поле `<entity>_id`.
+  Для загрузки — scoped-логгер, протаскиваемый через `context.Context`
+  сквозь асинхронные стадии (приём → скачивание → распознавание →
+  раскладка), чтобы ключ дописывался на каждую запись сам:
 
 ```go
 log := log.With("download_id", id, "infohash", ih)
@@ -115,7 +117,10 @@ ctx = logctx.With(ctx, log) // достаём логгер из ctx в кажд
 ```
 
 - Все записи одной загрузки собираются одним фильтром:
-  `jq 'select(.download_id=="a1b2")' app.jsonl`.
+  `jq 'select(.download_id=="01jz2k7f8q9r3s4t5v6w7x8y9z")' app.jsonl`.
+- ULID глобально уникален across сущностей, поэтому штатно работает и
+  простой grep по голому id — он находит все упоминания сущности независимо
+  от имени поля: `grep 01jz2k7f8q9r3s4t5v6w7x8y9z app.jsonl`.
 
 ## Ошибки
 

docs/specs/database.md

@@ -10,15 +10,19 @@
 > документации.
 >
 > Состояние на: миграции `0001_init`, `0002_recognition_plan`,
-> `0003_source_miss_count`, `0004_candidate_url`, `0005_display_name`.
+> `0003_source_miss_count`, `0004_candidate_url`, `0005_display_name`,
+> `0006_ulid_identity` (Go-миграция: ULID-идентификаторы, `download_infohash`).
 
 Назначение таблиц и почему так — [architecture.md](architecture.md) →
 «Хранилище». Значения `state` и переходы — [workflow.md](workflow.md).
+Первичные ключи — ULID (TEXT, lowercase), генерятся приложением
+(`internal/ident`) — см. [конвенцию](../conventions/database.md).
 
 ## ER-диаграмма
 
 ```mermaid
 erDiagram
+    download ||--o{ download_infohash : "инфохэши (v1/v2)"
     download ||--o{ recognition : "распознавания"
     download ||--o{ hint : "подсказки"
     download ||--o{ override : "ручные правки"
@@ -26,14 +30,12 @@ erDiagram
     recognition ||--o{ metadata_candidate : "кандидаты базы"
 
     download {
-        INTEGER id PK "AUTOINCREMENT"
+        TEXT    id PK "ULID (lowercase), генерится приложением"
         TEXT    source_type "NOT NULL; magnet|torrent|url"
         TEXT    source_ref  "NOT NULL; magnet/url/путь"
         TEXT    display_name "NOT NULL DEFAULT ''; имя раздачи (rename qBittorrent), заголовок в UI (миграция 0005)"
         TEXT    context     "NOT NULL DEFAULT ''"
-        TEXT    infohash    "nullable; может появиться позже приёма"
-        TEXT    idempotency_key "nullable; UNIQUE если NOT NULL"
-        TEXT    state       "NOT NULL; см. workflow.md"
+        TEXT    state       "NOT NULL; см. workflow.md; активность выводится только из state"
         TEXT    error_code  "nullable"
         TEXT    error_msg   "nullable"
         INTEGER source_miss_count "NOT NULL DEFAULT 0; дебаунс пропажи источника (миграция 0003)"
@@ -42,9 +44,16 @@ erDiagram
         TEXT    updated_at  "NOT NULL DEFAULT datetime('now')"
     }
 
+    download_infohash {
+        TEXT download_id PK_FK "NOT NULL; ON DELETE CASCADE; PK(infohash, download_id)"
+        TEXT infohash    PK "NOT NULL; lowercase hex (40 — v1, 64 — v2)"
+        TEXT kind        "NOT NULL; v1|v2"
+        TEXT created_at  "NOT NULL DEFAULT datetime('now')"
+    }
+
     recognition {
-        INTEGER id PK "AUTOINCREMENT"
-        INTEGER download_id FK "NOT NULL; ON DELETE CASCADE"
+        TEXT    id PK "ULID"
+        TEXT    download_id FK "NOT NULL; ON DELETE CASCADE"
         INTEGER attempt_no    "NOT NULL DEFAULT 1"
         INTEGER is_current     "NOT NULL DEFAULT 1; 0/1"
         TEXT    media_type     "nullable; movie|series"
@@ -61,23 +70,23 @@ erDiagram
     }
 
     hint {
-        INTEGER id PK "AUTOINCREMENT"
-        INTEGER download_id FK "NOT NULL; ON DELETE CASCADE"
+        TEXT    id PK "ULID"
+        TEXT    download_id FK "NOT NULL; ON DELETE CASCADE"
         TEXT    text       "NOT NULL"
         TEXT    created_at "NOT NULL DEFAULT datetime('now')"
     }
 
     override {
-        INTEGER id PK "AUTOINCREMENT"
-        INTEGER download_id FK "NOT NULL; ON DELETE CASCADE"
+        TEXT    id PK "ULID"
+        TEXT    download_id FK "NOT NULL; ON DELETE CASCADE"
         TEXT    field      "NOT NULL; UNIQUE(download_id, field)"
         TEXT    value      "NOT NULL"
         TEXT    created_at "NOT NULL DEFAULT datetime('now')"
     }
 
     metadata_candidate {
-        INTEGER id PK "AUTOINCREMENT"
-        INTEGER recognition_id FK "NOT NULL; ON DELETE CASCADE"
+        TEXT    id PK "ULID"
+        TEXT    recognition_id FK "NOT NULL; ON DELETE CASCADE"
         TEXT    provider    "NOT NULL"
         TEXT    provider_id "NOT NULL"
         TEXT    title       "nullable"
@@ -88,8 +97,8 @@ erDiagram
     }
 
     file_link {
-        INTEGER id PK "AUTOINCREMENT"
-        INTEGER download_id FK "NOT NULL; ON DELETE CASCADE"
+        TEXT    id PK "ULID"
+        TEXT    download_id FK "NOT NULL; ON DELETE CASCADE"
         TEXT    apply_batch_id "NOT NULL; батч для точечного undo"
         TEXT    src_path "NOT NULL; исходный файл раздачи"
         TEXT    dst_path "NOT NULL; целевой хардлинк"
@@ -101,10 +110,16 @@ erDiagram
 
 ## Связи и кардинальность
 
-- `download` 1 — N `recognition` / `hint` / `override` / `file_link`;
-  `recognition` 1 — N `metadata_candidate`. Все дочерние — с
-  `ON DELETE CASCADE`: удаление загрузки уносит её распознавания, подсказки,
-  правки и ссылки.
+- `download` 1 — N `download_infohash` / `recognition` / `hint` / `override`
+  / `file_link`; `recognition` 1 — N `metadata_candidate`. Все дочерние — с
+  `ON DELETE CASCADE`: удаление загрузки уносит её хеши, распознавания,
+  подсказки, правки и ссылки.
+- `download_infohash` — множество хешей одной загрузки (v1/v2 гибридного
+  торрента); один и тот же infohash может принадлежать нескольким загрузкам
+  во времени (повторный приём после терминального состояния). Инвариант «не
+  более одной активной загрузки на infohash» держат guarded-методы store
+  (`CreateDownloadIfNoActive`/`ActivateIfNoOtherActive`) в одной
+  write-транзакции — на уровне схемы он не выражается (условие на `state`).
 - `download` ↔ `file_link` — один источник (раздача) ко многим разложенным
   файлам; внутри строки `file_link` связь `src_path → dst_path` — 1:1. Не
   каждый файл раздачи попадает в `file_link` (только распознанные медиа и
@@ -112,8 +127,9 @@ erDiagram
 
 ## Индексы и ограничения
 
-- `download`: `UNIQUE(idempotency_key) WHERE idempotency_key IS NOT NULL`;
-  индекс по `state`.
+- `download`: индекс по `state`.
+- `download_infohash`: PK `(infohash, download_id)` (он же индекс поиска по
+  хешу); индекс по `download_id`.
 - `recognition`: индекс по `download_id`.
 - `override`: `UNIQUE(download_id, field)`.
 - `metadata_candidate`: индекс по `recognition_id`.