output-contract-enforcer

出力コントラクトの強制

下流ノードに渡す前に、DAG ノードの出力が宣言済みの JSON スキーマに適合しているかを検証します。マルチエージェント DAG の信頼性を高める要です。これがないと、下流ノードが予測できない入力を受け取り、DAG が破綻します。

---

使用する場面

✅ 次の用途に使用します：

• ノードの出力が宣言済みのスキーマに適合しているか検証する
• 自然言語による出力の説明から出力スキーマを生成する
• 下流ノードが入力を拒否した原因をデバッグする
• 接続されたノード間のコントラクト互換性を確保する

❌ 次の用途には使用しません：

• コンテンツの品質や正確性を評価する（dag-quality を使用）
• スキルの品質を評価する（skill-grader を使用）
• DAG のコンテキスト外で一般的な JSON スキーマを扱う

---

検証プロセス

flowchart TD
  O[Node output] --> P[Parse as JSON]
  P -->|Parse error| E1[FAIL: Not valid JSON]
  P -->|Valid JSON| S[Check against schema]
  S --> R{Required fields?}
  R -->|Missing| E2[FAIL: Missing required field X]
  R -->|Present| T{Type check?}
  T -->|Wrong type| E3[FAIL: Field X expected string, got number]
  T -->|Correct| C{Constraints?}
  C -->|Violated| E4[FAIL: Field X violates constraint Y]
  C -->|Met| V[PASS: Contract satisfied]

チェック項目

チェック	例	エラーメッセージ
JSON として解析可能	{broken json	"出力は有効な JSON ではありません"
必須フィールド	status がない	"必須フィールドがありません：status"
フィールドの型	status: 42（文字列が必要）	"フィールド 'status' は文字列が必要ですが、数値が指定されています"
列挙値	status: "maybe"	"フィールド 'status' は次のいずれかである必要があります：pass、warn、fail"
文字列の制約	summary: ""（minLength: 1）	"フィールド 'summary' は minLength 1 以上である必要があります"
数値の制約	score: 1.5（maximum: 1.0）	"フィールド 'score' は ≤ 1.0 である必要があります"
配列の制約	items: []（minItems: 1）	"フィールド 'items' には少なくとも 1 つの項目が必要です"
ネストされたオブジェクト	サブフィールドがない	"フィールド 'metadata.cost' は必須です"

標準出力コントラクト

すべての DAG ノードは、この基本スキーマに適合する出力を生成する必要があります（フィールドは拡張できます）。

{
  "type": "object",
  "required": ["status", "summary"],
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pass", "warn", "fail"]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "description": "1-3 sentence description of what was produced"
    },
    "artifacts": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of files created or modified"
    },
    "data": {
      "type": "object",
      "description": "Node-specific output data (schema varies per node)"
    },
    "risks": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Remaining risks or assumptions"
    }
  }
}

コントラクトの互換性チェック

Node A の出力を Node B の入力に接続する際は、次を確認します：

1. B が必要とするすべてのフィールドが A の出力スキーマに含まれている
2. 型が一致している（A が文字列を生成し、B が文字列を期待する）
3. A の出力制約が B の入力制約と互換性がある
4. A が生成する任意フィールドを B が必須としている場合、互換性がない

Node A output: { status: string, recommendations: string[] }
Node B input:  { status: string, recommendations: string[], priority: number }

Result: INCOMPATIBLE — Node B requires 'priority' but Node A doesn't produce it.
Fix: Add 'priority' to Node A's output, or add a transformer node between A and B.

---

スキーマの生成

ノードの説明に「優先度付きの推奨事項のリストを生成する」とある場合、次のように生成します。

{
  "type": "object",
  "required": ["status", "summary", "data"],
  "properties": {
    "status": { "type": "string", "enum": ["pass", "warn", "fail"] },
    "summary": { "type": "string", "minLength": 1 },
    "data": {
      "type": "object",
      "required": ["recommendations"],
      "properties": {
        "recommendations": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": ["text", "priority"],
            "properties": {
              "text": { "type": "string" },
              "priority": { "type": "integer", "minimum": 1, "maximum": 5 }
            }
          }
        }
      }
    }
  }
}

---

アンチパターン

コントラクトがまったくない

誤り：ノードがスキーマなしで自由形式のテキストを生成します。 理由：下流ノードが入力を確実に解析できません。DAG が脆弱になります。 正しい方法：すべてのノードで出力スキーマを宣言します。すべての出力を下流に渡す前に検証します。

コントラクトが厳しすぎる

誤り：文字数を厳密に指定したり、特定の書式や実行時の状況によって変わるフィールド値を必須にしたりします。 正しい方法：内容ではなく、構造（型、必須フィールド）を制約します。内容の評価は dag-quality に任せます。

任意フィールドを無視する

誤り：すべてのフィールドを必須として扱います。 正しい方法：下流ノードが絶対に必要とするフィールドにのみ required を使用します。それ以外はすべて任意として指定します。