<?xml version="1.0" encoding="UTF-8"?>
<spec xmlns="https://vibevm.org/spec/1">
  <title id="root">Прослеживаемость: спецификации, код и карта</title>
  <status stage="doc" state="work" audience="dev"/>
  <p p="1">Каждый публичный кусок кода в vibe указывает на правило, которое он воплощает, а сгенерированная карта отвечает в обе стороны: какой код стоит за этим правилом, какому правилу отвечает этот код.</p>
  <example ref="explain" p="2"/>
  <section id="marks" title="Пометки в коде">
    <p p="3">Элемент Rust, который воплощает правило, несёт атрибут с адресом правила; тест, который его проверяет, несёт проверяющий атрибут; модуль, который обслуживает целый раздел, объявляет область. Связи живут в коде, рядом с тем, что описывают, и потому едут с каждым рефакторингом и каждой копией. Глаголы: `implements`, `verifies`, `documents`, `deviates` и `informs`; отклонение обязано сказать почему.</p>
    <rule ref="spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#FORCE-EDGES-TRAVEL-WITH-THE-ARTEFACTS" p="4"/>
    <rule ref="spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#RULE-VERBS-AND-MANDATORY-REASON" p="5"/>
    <p p="6">`implements` — утверждение о коде, который выполняется. Объявление типа его не несёт: ребро от объявления неотличимо от покрытия, и карта, которая считала бы объявления, была бы зелёной ни о чём.</p>
    <rule ref="spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#RULE-IMPLEMENTS-IS-A-CLAIM-ABOUT-CODE-THAT-RUNS" p="7"/>
  </section>
  <section id="the-map" title="Карта">
    <p p="8">`cargo xtask specmap` обходит крейты в поисках пометок и дерево [спецификаций](../glossary/index.xml#specification) в поисках единиц и пишет `specmap.json`: узлы для каждой единицы спецификации с её ревизией и хешем содержимого, узлы для каждого помеченного элемента кода и рёбра между ними. Карта закоммичена, и `cargo xtask specmap --check` падает, когда дерево сдвинулось, а карта нет. Политика того, что сканируется, какие крейты под воротами, а какие освобождены, живёт в `specmap.toml`; сам движок поставляется с пакетом дисциплины и вендорится, никогда не правится на месте.</p>
    <rule ref="spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#FORCE-INVARIANTS-ARE-MACHINE-CHECKED" p="9"/>
    <p p="10">Карту стерегут трое ворот. *Храповик сирот*: публичный элемент в крейте под воротами без пометки проваливает проверку, если только он не диспозиционирован с идентификатором долга. *Ворота разрешения*: каждое ребро в собственное пространство имён этого проекта должно приземлиться на существующий [якорь](../glossary/index.xml#anchor). *Правило подозрения*: когда ревизия единицы спецификации поднимается, каждое ребро, закреплённое за старой ревизией, становится подозрительным, и проверка его называет, чтобы код перечитали против правила, которое сдвинулось.</p>
    <rule ref="spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#INVALIDATION-SPEC-BUMP-MAKES-EDGES-SUSPECT" p="11"/>
    <p p="12">Сгенерированный код исключён из ворот сирот; пометки вместо него несёт вход генератора, схема, и их читает сканер схем.</p>
    <rule ref="spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#RULE-GENERATED-CODE-IS-EXCLUDED" p="13"/>
  </section>
  <section id="asking" title="Как спросить карту">
    <p p="14">Команды ниже работают в чекауте самого vibe, чьи спецификации несут карту; установленный пакет отвечает, только если поставил свою. `vibe explain "spec://…#anchor"` строит карту заново в памяти и печатает подграф одной цели: что её воплощает, проверяет или документирует. `vibe query` фильтрует карту по адресу, символу или виду и возвращает множество подходящих узлов. `vibe select --where "lacks:verifies scope:spec://…"` обходит граф с предикатом: каждое правило без проверяющего, элементы, которые воплощают правило, и один переход вокруг них. `--json` отдаёт каждый ответ агенту.</p>
    <example ref="select" p="15"/>
  </section>
  <section id="documentation-edges" title="Документация на карте">
    <p p="16">Это руководство входит в ту же карту. Каждый блок `rule` на странице — ребро `documents` от страницы к правилу, которое она цитирует, просканированное на стороне хоста через шов сканера движка. Ребро не несёт пина ревизии: цитата живая, страница показывает текущий текст правила, и единственная проверка — что якорь существует. Устарела ли проза вокруг цитаты — вопрос к человеку, а не флаг подозрения.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#PIPE-EDGES-HOST-SIDE" p="17"/>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#OBS-RULE-EDGE-UNPINNED" p="18"/>
  </section>
  <section id="edge-cases" title="Особые случаи и правила">
    <p p="19">Единицы бывают четырёх видов, и у каждого своё ребро по умолчанию: требование воплощают и проверяют, дизайн информирует, руководство документирует; предложение решает, и это пока не глагол, который система несёт.</p>
    <rule ref="spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#DECISION-FOUR-UNIT-KINDS" p="20"/>
    <p p="21">Карту носят, а не генерируют: соответствие между прозой и кодом нельзя вывести, только написать и проверить, и потому пометки в коде, а ворота в сборке.</p>
    <rule ref="spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#CONSEQUENCE-MAPPING-IS-CARRIED-NOT-GENERATED" p="22"/>
    <p p="23">Пакет может нести собственную карту, `package.specmap.json`, сгенерированную `vibe specmap` перед публикацией, так что потребитель спрашивает установленный пакет, не пересобирая его.</p>
  </section>
</spec>
