Перейти к основному содержимому

Индекс знаний устарел

Что это​

Канонические знания хранятся в неизменяемом реестре (ledger/CURRENT и поколения), а из них материализуются производные артефакты: страницы Markdown в knowledge/, полнотекстовый индекс FTS5 и графы. Если производная проекция отстала от текущего поколения, query может вернуть устаревший результат, а lint — пожаловаться на свежесть проекции (детерминированный LINT проверяет «projection freshness», docs/STATUS.md).

Когда использовать​

  • query возвращает данные, не соответствующие текущему поколению;
  • lint сообщает о несвежести проекции или расхождении индекса.

Предварительные условия​

Рабочий каталог проекта; возможность запускать uv run raytsystem ....

Пошагово: симптом → причина → диагностика → решение​

1. Подтвердите проблему свежести (безопасно, только чтение)​

uv run raytsystem lint --json

LINT ничего не переписывает в каноне; он лишь сообщает о расхождениях, включая несвежесть проекции.

2. Пересоберите производный индекс​

uv run raytsystem rebuild-index --json

FTS5, граф, страницы knowledge/, index.md и hot.md разделяют один хэш-закрытый маркер проекции и пересобираются из канона. Каждый производный артефакт можно удалить и пересобрать — это не трогает неизменяемый реестр.

3. Проверьте результат​

uv run raytsystem lint --json
uv run raytsystem query "ваш запрос" --json

LINT должен вернуть ноль находок по свежести, а query — актуальную цитату, привязанную к текущему поколению.

Ожидаемый результат​

После rebuild-index проекция снова соответствует ledger/CURRENT; query отдаёт актуальные, привязанные к поколению факты.

Ограничения и безопасность​

  • Никогда не редактируйте вручную _raw/, объекты реестра/поколения или сгенерированные страницы knowledge/ (AGENTS.md). Правильный путь восстановления — пересборка из канона.
  • rebuild-index пересобирает только производные артефакты; канон остаётся неизменным.

Частые ошибки​

  • Ручная правка сгенерированных страниц вместо пересборки — она будет затёрта и нарушает инварианты.
  • Гонка ledger/CURRENT во время запроса: один принудительный rebuild/retry допустим, смешивание поколений — нет.

Когда открыть issue​

Если после rebuild-index LINT продолжает сообщать о несвежести проекции или query по-прежнему отдаёт устаревшее поколение — откройте issue с выводом lint --json (без секретов).

Связанные страницы​

Источники истины​

  • docs/STATUS.md
  • config/raytsystem.toml
  • AGENTS.md