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 }
);