> Перевод даётся для удобства чтения. Нормативным является английский оригинал. # Обход модели и зарезервированные места **Спецификация Мета-Вселенной** **Идентификатор документа:** MU-V2-ARCH-017 **Название:** Стандарт архитектуры мета-моделей - обход без потерь и зарезервированные места **Класс документа:** нормативный **Версия:** 2.0 (черновик) **Статус:** рабочий черновик **Нормативные ссылки:** MMAS-Core, MMAS-Package, Versioning, Validation, Data-Mastership **Информативные ссылки:** Traceability, AI-Agent-Guide, Repository-Structure **Копирайт:** © Orkestron.AI **Лицензия:** Apache-2.0 --- # 1. Назначение [MMAS-Package](MMAS-Package.md) определяет, *где что лежит* в репозитории Мета-Модели. Этот документ определяет две гарантии, которых одна раскладка дать не может: 1. **Обход без потерь.** Читатель (человек или ИИ-агент) ОБЯЗАН иметь возможность пройти всю модель бандл за бандлом, слой за слоем, посетив **каждый файл ровно один раз**, зная, **что означает каждый файл**, и **доказав, что ничего не пропущено**. 2. **Зарезервированные места.** Содержимое, не являющееся смысловым определением (сырые исходные данные, канонические тексты источников, сгенерированные артефакты, инструкции по работе), ОБЯЗАНО лежать в зарезервированных местах с заранее заданным значением, чтобы читателю никогда не приходилось гадать, что это за файл. Вместе с [Data-Mastership](Data-Mastership.md), где объявляется, *кому принадлежит истина* по каждому набору данных, это делает Мета-Модель полностью механически читаемой: ничего не потеряно, ничего не двусмысленно, ничего с неизвестными полномочиями. --- # 2. Область действия Эта спецификация применяется к: - репозиториям Мета-Моделей и Смысловым пакетам распространения; - манифестам уровня репозитория, бандла и слоя; - всем файлам репозитория модели, без исключения; - обходчикам: любому инструменту или агенту, перечисляющему содержимое модели. Она не переопределяет семантику Объектов, Связей, Событий, Контрактов и Проекций; она задаёт, как находятся, упорядочиваются и классифицируются несущие их файлы. --- # 3. Принципы проектирования - **Одна точка входа.** Каждый обход начинается в одном и том же месте; никакого кулуарного знания о том, откуда начинать. - **Объявленный порядок.** Порядок чтения - это данные, а не соглашение: манифесты его объявляют, обходчики ему следуют. - **Полная классификация.** Классифицирован каждый файл. Файл, значение которого нельзя определить из манифестов и этой спецификации, - это дефект, а не любопытный случай. - **Смысл идёт вместе со структурой.** Каждая перечисленная единица несёт заявленное значение; читателю не должно требоваться открывать файл, чтобы понять, что это за вещь. - **Авторское, собранное и сгенерированное содержимое никогда не смешиваются.** У них разные правила жизненного цикла, поэтому и места разные. --- # 4. Точка входа Соответствующий репозиторий ОБЯЗАН читаться начиная ровно с двух файлов в его корне: 1. **`BOOTSTRAP.md`** - инструкции по работе: как читать эту модель, в каком порядке, какими инструментами, и что агенту здесь положено делать, а чего нельзя. Обходчику СЛЕДУЕТ прочитать его первым. `BOOTSTRAP.md` МОЖЕТ делегировать расширенные инструкции каталогу `bootstrap/` (промпты агентов, онбординг, чеклисты). Содержимое bootstrap НЕ ДОЛЖНО определять семантику; оно объясняет и никогда не объявляет. 2. **`manifest.yaml`** - машинная точка входа, определённая в [MMAS-Package](MMAS-Package.md) §5 и дополненная этим документом объявлением обхода (§5) и списком исключений (§7). Если `BOOTSTRAP.md` отсутствует, обходчик работает по одному манифесту; отсутствие манифеста делает репозиторий несоответствующим. Репозиториям, где уже используется входной файл, привычный для экосистемы (например `README.md`, `AGENTS.md` или `CLAUDE.md`), СЛЕДУЕТ сделать его тонким указателем на `BOOTSTRAP.md` и `manifest.yaml`, а не вторым источником истины. --- # 5. Объявление обхода Порядок обхода объявляется сверху вниз: - **Манифест репозитория** ОБЯЗАН объявлять упорядоченный список бандлов (`bundles:` в порядке чтения). - Каждый **манифест бандла** (`bundle.yaml`) ОБЯЗАН объявлять единственную смысловую зону ответственности бандла и упорядоченный список его слоёв. - Каждый **манифест слоя** (`layer.yaml`) ОБЯЗАН перечислять содержимое слоя: файлы или glob-шаблоны, каждый с **видом** (§8) и однострочным **значением**. Перечисление МОЖЕТ быть **централизованным вместо послойного**: репозиторий, где имена файлов несут вид по соглашению (например `{kind}-{id}-{memo}.md`), МОЖЕТ объявить классификацию один раз, упорядоченным списком правил сопоставления в манифесте репозитория (`kind_rules`): каждое правило сопоставляет glob-шаблон с видом и происхождением (§9); побеждает первое подошедшее правило. В таких правилах подстановка `{prefix}` обозначает сегмент имени файла до первого разделителя, поэтому одно правило вида `kind: "object/{prefix}"` классифицирует целое соглашение об именовании. Централизованные правила эквивалентны послойному перечислению для проверки покрытия (§7); файл, не подошедший ни одному правилу, в любом случае остаётся сиротой. Правила упорядочивания: - Бандлы ОБЯЗАНЫ быть упорядочены так, чтобы бандл шёл **после** каждого бандла, от которого он зависит (сначала основание). Циклические зависимости бандлов несоответствующи. - Слои внутри бандла ОБЯЗАНЫ упорядочиваться так же. - Прямые ссылки вперёд (файл упоминает понятие, определяемое позже в обходе) допустимы, но порядок *объявления* ОБЯЗАН оставаться «сначала зависимости», чтобы один последовательный проход читал определения до их активного использования. Обходчик, посещающий бандлы, затем слои, затем перечисленные файлы, каждый раз в объявленном порядке, выполняет **канонический обход**. Два обходчика, выполняющие канонический обход одной и той же версии репозитория, ОБЯЗАНЫ посетить одни и те же файлы в одном и том же порядке. --- # 6. Зарезервированные места Помимо структурных каталогов [MMAS-Package](MMAS-Package.md) §4 (`bundles/`, `imports/`, `mappings/`, `schemas/`, `examples/`, `diagrams/`, `docs/`, `tools/`), этот документ резервирует следующие места. У каждого фиксированное значение по умолчанию; обходчик МОЖЕТ на него полагаться без дополнительных объявлений. | Место | Значение | Жизненный цикл | |----------|---------|-----------| | `BOOTSTRAP.md`, `bootstrap/` | Инструкции по работе для читателей и агентов: как читать, обновлять и проверять эту модель | Авторское | | `canon/` | Канонические тексты источников, которые модель считает основой истины: доктрина, принятые решения, нормативные входы, исходные спецификации | Авторское или принятое; версионируется; никогда не генерируется | | `raw/` | Необработанные захваты из внешних систем: выгрузки, дампы, транскрипты, результаты обхода | Собранное; НИКОГДА не правится вручную | | `artifacts/` | Производные, восстановимые результаты: собранные представления, отрисованные документы, вычисленные индексы, отчёты | Сгенерированное; НИКОГДА не авторское | | `sources.yaml` | Реестр мастерства данных: система записи каждого набора данных (см. [Data-Mastership](Data-Mastership.md)) | Авторское | Правила: - **`canon/`** содержит тексты, *о которых* модель или *которыми она связана*, когда эти тексты должны путешествовать вместе с моделью. Слои ОБЯЗАНЫ ссылаться на файлы канона, а не пересказывать их; если утверждение слоя и текст канона расходятся, внутри этой модели побеждает текст канона. - **`raw/`** ОБЯЗАН быть организован как `raw/<система-источник>/<набор-данных>/...`. Каждый каталог набора данных ОБЯЗАН нести сопроводительный файл происхождения (`_provenance.yaml`: система-источник, объём, время извлечения, инструмент извлечения, число записей). Сырое содержимое - это свидетельство; ручная правка уничтожает его доказательную ценность и несоответствующа. Исправления делаются в системе-источнике (с последующим повторным сбором) или в смысловом слое (как размеченное отклонение). - Записи в **`artifacts/`** ОБЯЗАНЫ объявлять свой генератор и входы (достаточно сопроводительного файла или строки заголовка). Соответствующий репозиторий может удалить `artifacts/` целиком и пересобрать его; если не может, что-то лежит не там. - Репозиторию НЕ СЛЕДУЕТ выдумывать параллельные места под эти цели (`_raw/`, `generated/`, `sources/` и подобные). Там, где есть унаследованные раскладки, манифест ОБЯЗАН сопоставить их с зарезервированными значениями. --- # 7. Правило полноты (ни один файл не забыт) Каждый файл репозитория ОБЯЗАН попадать ровно в один из трёх классов: 1. **Перечисленный** - подошедший под объявление содержимого в манифесте слоя (§5) либо являющийся структурным каталогом MMAS-Package §4 со своей заданной ролью; 2. **Зарезервированный** - расположенный в зарезервированном месте из §6 и наследующий его значение по умолчанию; 3. **Исключённый** - подошедший под список исключений манифеста (`exclude:`), который перечисляет инфраструктурные файлы без смыслового содержания (внутренности системы контроля версий, конфигурация CI, настройки редактора, кеши сборки). **Проверка покрытия**: обходчик ОБЯЗАН иметь возможность сопоставить полный рекурсивный список файлов репозитория с объединением трёх классов. Файлы вне классов («сироты») и файлы более чем в одном классе («неоднозначные») являются отказами валидации. Проверка покрытия входит в **структурную валидацию (V1)** в [Validation](Validation.md). Список исключений - это объявление, а не свалка: исключить файл значит утверждать, что он **не несёт модельного смысла**. Исключать смысловое содержимое ради прохождения проверки покрытия несоответствующе. --- # 8. Виды файлов Каждый перечисленный файл ОБЯЗАН нести один вид. Базовый словарь: `object` · `relationship` · `event` · `contract` · `projection` · `canon` · `raw` · `artifact` · `mapping` · `import` · `schema` · `example` · `diagram` · `doc` · `tool` · `bootstrap` · `manifest` Виды отвечают на вопрос «что это за файл *в модели*», а не «какого он формата». CSV может быть `raw` (выгрузка), `artifact` (вычисленный индекс) или `object` (таблица определений); то, как читатель с ним обращается, решает вид, а не расширение. Экосистемы МОГУТ уточнять словарь подвидами (`object/policy`, `doc/adr`), но ОБЯЗАНЫ сохранять базовый вид как префикс. Подвиды МОГУТ выводиться механически из объявленных соглашений об именовании через подстановку `{prefix}` из §5. --- # 9. Авторское, собранное, сгенерированное Ортогонально виду, у каждого файла ровно одно **происхождение**: - **Авторское** - написано человеком или агентом в роли автора; правится на месте; рецензируется как код. - **Собранное** - захвачено из внешней системы конвейером; заменяется повторным сбором; никогда не правится на месте. - **Сгенерированное** - вычислено из других файлов этого репозитория; заменяется повторной генерацией; никогда не правится на месте. Для зарезервированных каталогов (§6) происхождение подразумевается местом, в остальных случаях оно ОБЯЗАНО объявляться в манифесте слоя. Правка собранных или сгенерированных файлов на месте несоответствующа: исправление относится к системе-источнику или к генератору. Именно это различие делает мастерство (см. [Data-Mastership](Data-Mastership.md)) практически исполнимым: происхождение файла сразу говорит читателю, может ли *эта* копия вообще быть истиной. --- # 10. Канонический обход (информативно) Соответствующий обходчик: 1. Читает `BOOTSTRAP.md` (контекст, ограничения, локальные соглашения). 2. Читает `manifest.yaml`: идентичность, версии, порядок бандлов, список исключений. 3. Читает `sources.yaml`: какие наборы данных мастерятся здесь, а какие являются зеркалами (со свежестью). 4. Посещает `canon/` в объявленном или упомянутом виде, чтобы основа истины была загружена до толкования. 5. Обходит бандлы в объявленном порядке; внутри каждого - слои в объявленном порядке; внутри каждого - перечисленные файлы, читая вид и значение до содержимого. 6. Разрешает `imports/` и `mappings/`, когда слой на них ссылается. 7. Относится к `raw/` как к свидетельству (сверяется, а не пересказывает), а к `artifacts/` - как к одноразовым представлениям. 8. Выполняет проверку покрытия (§7) и сообщает о сиротах, неоднозначностях и протухших зеркалах. Обход завершён, когда учтён каждый файл и известны полномочия по каждому набору данных. --- # 11. Требования ИИ-нативности Соответствующий репозиторий ОБЯЗАН позволять ИИ-агенту без внешних знаний: - найти точку входа и инструкции по работе; - перечислить всё содержимое в детерминированном порядке; - назвать для любого файла его вид, происхождение и однострочное значение; - доказать покрытие: назвать каждый файл, который он не читал, и почему (исключён, сгенерирован, сырое свидетельство); - отличать то, что ему можно править (авторское, в мастерстве модели), от того, что нельзя (собранное, сгенерированное, мастерящееся снаружи). Агенту, который не может выполнить последний пункт, СЛЕДУЕТ отказываться от операций записи в модель. --- # 12. Архитектурные инварианты Обход и раскладка ОБЯЗАНЫ сохранять: - смысловую идентичность и владение; - происхождение собранного и сгенерированного содержимого; - свойство единственной точки входа; - детерминированность канонического обхода; - соблюдение Конституции. Раскладка и обход НИКОГДА не должны переопределять смысловое значение; они лишь делают его достижимым. --- # 13. Дальнейшие направления Референсный обходчик (`mu-walk`) - естественный спутник существующих инструментов: он выполнял бы канонический обход, выдавал машиночитаемый отчёт обхода (файлы, виды, происхождения, результат покрытия, свежесть зеркал) и служил исполняемым определением этого документа. Отчёт обхода мог бы войти в Смысловой пакет распространения, позволяя потребителям проверить полноту до того, как довериться пакету. --- # Заключение Мета-Модель заслуживает ровно столько доверия, сколько у читателя есть возможности знать, что он увидел её целиком и понял, чем является каждая часть. Этот стандарт превращает такую возможность из добросовестности в контракт: одна точка входа, объявленный порядок, полная классификация файлов, зарезервированные места для инструкций, канона, сырых свидетельств и производных артефактов, и проверка покрытия, делающая молчаливую потерю невозможной.