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: 열거형 필드 값 범위 제약

임의의 유효한 SkillDescriptor 객체에 대해:

  • capability_type의 값은 ["plugin", "api", "knowledge", "task"] 중 하나여야 함
  • access의 값은 ["public", "restricted", "private"] 중 하나여야 함
  • auth.type의 값은 ["api_key", "oauth2", "custom", "none"] 중 하나여야 함

속성 3: 직렬화/파싱 왕복 일관성

임의의 유효한 SkillDescriptor 객체에 대해, JSON 문서로 직렬화한 후 다시 객체로 파싱한 결과는 원본 객체와 의미적으로 동등해야 합니다:

parse(serialize(descriptor)) == descriptor

속성 4: Schema 유효성 검사 정확성

  • Schema에 부합하는 임의의 JSON 문서에 대해, Schema Validator는 성공적으로 파싱하고 구조화된 객체를 반환해야 함
  • Schema에 부합하지 않는 임의의 JSON 문서에 대해, Schema Validator는 구체적인 위반 필드명과 오류 이유를 포함하는 오류 정보를 반환해야 함

속성 5: 스킬 식별자 고유성

스킬 인덱스 내의 임의의 Skill Descriptor 컬렉션에 대해, 모든 스킬의 id 필드 값은 서로 달라야 합니다.

속성 6: 스킬 인덱스 정확성과 접근 제어

N개의 스킬을 포함하는 임의의 제공자 도메인에 대해, 미인증 요청이 Well-Known URI에 접근할 때:

  • 반환되는 스킬 인덱스는 access가 "private"가 아닌 모든 스킬을 포함해야 함
  • access가 "private"인 스킬을 포함해서는 안 됨
  • 인덱스 내 각 항목의 descriptor_url은 유효한 Skill Descriptor를 가리켜야 함

속성 7: 능력 유형 필터링 정확성

임의의 스킬 컬렉션과 임의의 CapabilityType 필터 값에 대해:

  • 필터링된 결과 세트의 각 스킬의 capability_type은 필터 값과 동일
  • 원본 컬렉션에서 해당 유형과 일치하는 모든 스킬이 결과 세트에 포함

속성 8: 호출 메시지 구조적 완전성

  • 임의의 유효한 InvocationRequest에 대해, caller(id와 type 포함), skill_id, inputs 필드를 포함해야 함
  • 임의의 유효한 InvocationResponse에 대해, execution_id, status, skill_id, timestamps 필드를 포함해야 함

속성 9: 프로토콜 버전 SemVer 형식

임의의 유효한 ProtocolVersion 객체에 대해, 그 version 필드는 MAJOR.MINOR.PATCH 형식을 준수해야 하며, MAJOR, MINOR, PATCH는 모두 음이 아닌 정수입니다.

속성 10: 버전 비호환 감지

임의의 Skill Descriptor 프로토콜 버전과 소비자가 지원하는 프로토콜 버전에 대해:

  • Descriptor의 메이저 버전(MAJOR)이 소비자가 지원하는 메이저 버전보다 큰 경우, 버전 비호환 오류를 반환
  • 메이저 버전이 동일한 경우, 정상 처리

속성 11: TypeScript와 JSON Schema의 의미적 일관성

  • TypeScript 타입 정의에서 생성된 임의의 유효한 SkillDescriptor 인스턴스에 대해, 해당 인스턴스는 JSON Schema 유효성 검사를 통과해야 함
  • JSON Schema 유효성 검사를 통과하는 임의의 JSON 문서에 대해, TypeScript 타입 시스템에 의해 수용되어야 함

12.3 테스트 전략

듀얼 트랙 테스트 방법

방법목적도구
단위 테스트구체적인 예시, 엣지 케이스, 오류 조건 검증vitest
속성 테스트모든 입력에 걸친 범용 속성 검증fast-check

속성 기반 테스트 설정

  • 각 속성 테스트는 최소 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 }
);