The adapter that adoption generates is schema-correct and inert: it is created with empty topics on purpose, so `context` on such a repository returns an empty bundle. That is the honest answer at apply time, but it leaves the repository without routing indefinitely, which is the whole point of a KDB -- so whether the adapter should stay or the legacy file should be rebuilt into one canonical index is a real open question, not a settled one. Recorded as research rather than as a runbook change: no decision was taken and no behaviour changed. The note argues against rebuilding, and identifies why the adapter cannot yet grow into a replacement -- runbook 11.1 offers `Topic.data.x-selector` as the way to index sections of a legacy source, and build_context assembles bundles from document ids and never reads it. Until that exists a topic can only reference a whole legacy file, so incremental migration has nowhere to start. Also names the question that precedes both options: whether the legacy file is a knowledge base in a foreign format or domain data that was called kdb, which adoption currently cannot distinguish and does not ask. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
8.7 KiB
documentId, documentVersion, status, normative, language
| documentId | documentVersion | status | normative | language |
|---|---|---|---|---|
| legacy-knowledge-base-treatment | 0.1.0 | research | false | ru |
Что делать с non-conformant KDB: адаптер или пересборка
Дата обсуждения: 2026-08-24
Статус: открытый вопрос, решение не принято, изменений в поведении repoctl по итогам не выполнялось
Нормативный источник: docs/adoption-runbook.md раздел 11.1 и docs/specification.md; этот документ их не заменяет
Вопрос
Когда adopt встречает knowledge base, не проходящую schema KnowledgeBase, есть два очевидных ответа:
- оставить файл как есть и создать рядом compatibility index (текущее поведение L1);
- пересобрать содержимое в один канонический
kdb/kdb.yaml.
Ниже — почему второй ответ отвергнут, чем неудовлетворителен первый в его нынешнем виде, и какой работой это лечится.
Три факта, которые определяют ответ
Адаптер сегодня инертен. _knowledge_base в src/stewardship/adoption.py создаёт индекс с topics: []. Это сделано намеренно — какие секции legacy source заслуживают отдельного intent, инструмент вывести не может. Но следствие в том, что repoctl context --intent <intent> на таком репозитории возвращает пустой bundle и предупреждение CONTEXT_INTENT_UNKNOWN о том, что index не объявляет ни одного intent. Adoption даёт schema-корректность и стабильный entrypoint, но ноль маршрутизации — ровно то, ради чего KDB существует.
Перезапись запрещена нормативно. Руннбук раздел 1: «adopt MUST NOT неявно превращаться в normalize или migrate». Спецификация требует для normalize явной стратегии, именованного recipe, полного rename/reference-rewrite плана и отдельного approval. На L1 ни --strategy normalize, ни --recipe не предлагаются CLI.
Обещанный мостик не реализован. Руннбук раздел 11.1 говорит, что compatibility index MAY ссылаться на секции legacy source через Topic.data.x-selector, и schema поле data допускает. Но build_context в src/stewardship/context.py собирает bundle из идентификаторов документов и x-selector не читает вообще. Механизм задекларирован и не поддержан ничем.
Почему пересборка в один канонический файл — неправильный ответ
Не только потому, что запрещена. Запрет разумен по четырём причинам:
- Преобразование неверифицируемо. Отображение произвольной legacy-структуры в topics/intents требует знать, какие секции соответствуют намерениям. Это суждение владельца; инструмент, который его угадывает, производит правдоподобный мусор.
- Ломается чужой интерфейс. Legacy-файл почти наверняка кто-то читает — скрипты, другие агенты, люди. Adoption не владеет этим контрактом и не может его переписывать.
- План перестаёт быть ревьюабельным. Diff вида «база знаний переписана целиком» невозможно осмысленно утвердить через
planHash; approval-граница превращается в фикцию. - Теряется provenance. После пересборки
verifyнечего сравнивать, а происхождение каждой строки утрачено.
Предлагаемое направление
Адаптер — правильный ответ на момент adoption, но он должен быть strangler-миграцией, а не парковкой навсегда. Сейчас он парковка, и в этом суть вопроса.
Шаг 1. Реализовать x-selector в context. Пока его нет, наращивать topics поверх legacy невозможно: topic может сослаться только на документ целиком, то есть на весь legacy-файл. С извлечением по yaml-path адаптер становится рабочим — один topic на одну секцию, topics добавляются по мере надобности, legacy-файл не трогается. Работа локальная: экстрактор yaml-path в context.py плюс поле в bundle. Альтернатива — убрать обещание из руннбука, но это хуже, механизм нужен.
Шаг 2. Пересборка становится осмысленной только после того, как topics покрыли секции. К этому моменту маршрутизация уже находится в каноническом файле, а за legacy source остаётся только контент, и операция превращается в normalize-recipe с настоящей rename map вместо догадки. Снятие forbiddenChanges с legacy-пути тогда становится осознанным исключением, а не побочным эффектом.
Вопрос, который стоит задать раньше обоих вариантов
Точно ли legacy-файл является базой знаний. Сейчас код спрашивает только «проходит ли schema KnowledgeBase? нет — значит wrap». Но «нет» покрывает два разных случая:
- это база знаний в чужом формате — адаптер уместен;
- это доменные данные, исторически названные kdb (списки хостов, состояние раскатки) — тогда это не knowledge вообще, а content root со своим authority, и правильный ход иной: объявить его content root'ом и написать рядом небольшой настоящий KDB.
Второй случай не лечится ни адаптером, ни пересборкой, а различить их автоматически нельзя. Это кандидат в вопросы фазы assess, рядом с уже существующим «Confirm repository type».
Что уже сделано и что осталось открытым
Реализовано и влито в master:
- формат knowledge-файла определяется валидацией содержимого, а не путём, и это правило распространяется на
ops/knowledge.yamlтак же, как наkdb/kdb.yaml; - при занятом каноническом пути index создаётся в свободном слоте, регистрирует все найденные legacy-источники и запрещает запись в них;
- тупик, когда оба канонических пути заняты non-conformant файлами, приводит к отказу
ADOPT_KNOWLEDGE_UNRESOLVED, а не к контракту, указывающему на невалидный файл.
Остаётся открытым:
x-selectorвcontext(шаг 1 выше) — не реализован;- вопрос «knowledge или доменные данные» в
assess— не задаётся; normalize-recipe для legacy KDB (шаг 2) — за пределами L1;- к какому из двух случаев относится реальный
Services/Antivirusкак пилот Wave 1 — не установлено.