BLUEPRINT

Глава 12: Гарантии Корректности

12.1 Обзор

Протокол определяет инварианты системы через формализованные Correctness Properties (свойства корректности). Эти свойства служат мостом между читаемыми спецификациями и машинно-верифицируемыми гарантиями корректности, валидируемыми через Property-Based Testing.

12.2 Список Свойств Корректности

Свойство 1: Структурная Целостность Skill Descriptor

Любой валидный объект SkillDescriptor должен содержать все обязательные поля: protocol (с version), id, name, version, capability_type, description, provider, endpoint, inputs, output, auth, access.

Свойство 2: Ограничения Области Значений Перечислимых Полей

  • capability_type ∈ ["plugin", "api", "knowledge", "task"]
  • access ∈ ["public", "restricted", "private"]
  • auth.type ∈ ["api_key", "oauth2", "custom", "none"]

Свойство 3: Согласованность Сериализации/Парсинга

parse(serialize(descriptor)) == descriptor

Свойство 4: Корректность Валидации Schema

  • Валидные документы должны быть успешно распарсены
  • Невалидные документы должны возвращать ошибки с указанием полей

Свойство 5: Уникальность Идентификатора Навыка

Все навыки в Skill Index должны иметь различные значения id.

Свойство 6: Корректность Индекса и Контроль Доступа

Неаутентифицированные запросы: включать все не-private навыки, исключать все private.

Свойство 7: Корректность Фильтрации по Типу

Фильтрация возвращает точно те навыки, которые соответствуют указанному типу.

Свойство 8: Структурная Целостность Сообщений Вызова

  • InvocationRequest: caller (с id и type), skill_id, inputs
  • InvocationResponse: execution_id, status, skill_id, timestamps

Свойство 9: Формат SemVer Версии Протокола

Поле version должно соответствовать формату MAJOR.MINOR.PATCH с неотрицательными целыми числами.

Свойство 10: Обнаружение Несовместимости Версий

MAJOR дескриптора > MAJOR потребителя → ошибка несовместимости.

Свойство 11: Семантическая Согласованность TypeScript и JSON Schema

Валидные экземпляры TypeScript должны проходить валидацию JSON Schema и наоборот.

12.3 Стратегия Тестирования

Двухтрековый Метод Тестирования

МетодЦельИнструмент
Модульные тестыПроверка конкретных примеров, граничных случаевvitest
Тесты свойствПроверка универсальных свойств на всех входахfast-check

Конфигурация Property-Based Testing

  • Минимум 100 итераций на каждый тест свойства
  • Библиотека fast-check для генерации случайных данных
  • Формат метки: Feature: skill-sharing-protocol, Property {N}: {description}

Пример Теста

import fc from 'fast-check';

fc.assert(
  fc.property(
    skillDescriptorArbitrary,
    (descriptor) => {
      // Feature: skill-sharing-protocol, Property 3: round-trip consistency
      const serialized = serialize(descriptor);
      const parsed = parse(serialized);
      expect(parsed).toEqual(descriptor);
    }
  ),
  { numRuns: 100 }
);