Что такое Evidence Package?

#Как устроен файл

Evidence Package

Один JSON-документ, произведённый одним анализом. У него есть версия схемы и версия протокола, он привязан к одному заданию на сканирование и несёт девять разделов, которые вместе описывают систему и уверенность, с которой держится каждая часть этого описания.

Если проще Файл, который пишет ваш кодовый агент: структурированное описание системы, где под каждым утверждением стоит ссылка на источник.

{
  "schema": "1adk.evidence-package/1",
  "protocol_version": "1",
  "scan_job_id": "…",
  "generated_by": { "agent": "claude-code", "version": "…" },
  "source": { "kind": "AGENT_SCAN", "title": "Static scan", "revision": "9f3c1a2" },

  "coverage":       [ … ],
  "limitations":    [ … ],
  "entities":       [ … ],
  "structure":      [ … ],
  "relations":      [ … ],
  "interfaces":     [ … ],
  "data_objects":   [ … ],
  "representations":[ … ],
  "data_flows":     [ … ],
  "mappings":       [ … ],
  "evidence":       [ … ],
  "claims":         [ … ],
  "unknowns":       [ … ]
}

#Зачем нужен каждый раздел

Приоритета выше «высокого» намеренно нет. То, что срочнее, — это риск, о котором один человек говорит другому, а не строка в сгенерированном файле.

#Идентичность и почему её требуют явно

Самое дальнобойное требование во всём формате.

От каждой сущности требуется что-то устойчивое, по чему её можно будет узнать в следующем анализе:

• repository_path — где лежит файл или каталог, относительно корня;
• fully_qualified_name — однозначное имя в терминах самого языка;
• external_id — выбранная и сохранённая метка для того, у чего нет ни первого, ни второго: базы, очереди, среды развёртывания, облачного ресурса.

Имя — это не идентичность. Переименуйте класс — это тот же класс; назовите две разные вещи «Основная база» — это по-прежнему две разные вещи. Сущность, у которой нет ни одного из трёх, для каждого анализа новая, и её история каждый раз начинается заново.

Снимки и изменения — о том, что построено поверх этого, и почему именно эта часть решает, способен ли инструмент вообще следить за архитектурой во времени.

#Поведение и алгоритмы

У операции на интерфейсе могут быть ещё две вещи, и обе существуют из-за одной и той же проблемы: знание, что эндпоинт есть, почти ничего не говорит о том, безопасно ли на него опираться.

• Поведение — аутентификация, авторизация, таймаут, повторы, идемпотентность. Пять свойств, которые владельцу нужны на самом деле, когда он спрашивает «а что будет, если это упадёт».
• Алгоритм — вложенные шаги, описывающие, что операция делает: проверить, условие, записать, отказать, вызвать. Не псевдокод и не переписывание кода, а читаемый рассказ о принимаемых решениях.

"algorithm": {
  "name": "Create payment",
  "steps": [
    { "type": "VALIDATE",  "description": "The amount and the currency are checked." },
    { "type": "CONDITION", "condition": "the amount is above the limit",
      "children": [ { "type": "FAIL", "description": "The request is refused." } ] },
    { "type": "WRITE",     "description": "A payment row is created." }
  ]
}

#Для чего в формате нет поля

Пустоты здесь и есть конструкция.

• Содержимое файлов. Нет поля, в которое могло бы поместиться тело функции.
• Значения конфигурации. Имя настройки появиться может; её значению жить негде.
• Данные. Ни строк, ни дампов, ни SQL, ни фикстур.
• Абсолютные пути. Запрещены инструкцией и бессмысленны в схеме, у которой корень — корень репозитория.
• Учётные данные. Поля нет, а свободный текст, несущий формы секретов, отклоняется на входе.

Инструкция подпирает это с другой стороны: описания должны быть обычными фразами, а не отформатированным выводом, и поле, которое читается как исходник, отклоняется вместе со всем пакетом. Между схемой, куда код положить некуда, и валидатором, отвергающим текст в форме кода, вставить тело файла без сознательного обхода обоих непрактично.

#Что происходит с пакетом, нарушившим правило

Ему отказывают целиком. Нет ни частичного приёма, ни «хорошее мы оставили», ни карантина с починкой: пакет, не прошедший проверку, не записывает ничего, и хранилище проекта остаётся нетронутым.

Причины, по которым пакету отказывают:

• он не соответствует схеме или объявляет версию, которую сервер не обслуживает;
• он превышает предел размера, указанный в его же задании;
• он заявляет задание, под которое не был выдан, или задание с истёкшим сроком;
• он ссылается на ключ, которого сам не объявляет;
• его свободный текст несёт форму учётных данных.

#Пределы формата