api-contract-guard

name	api-contract-guard
description	detect-images の応答形・エラーコード・HTTP ステータス・エラー優先順位・部分成功不変条件に後方互換を壊す変更が無いかを検査する。PR 前や API 周辺を変更した後に使う。
disable-model-invocation	true
context	fork
allowed-tools	Read, Grep, Glob, Bash

api-contract-guard — 外部消費者（Misskey 本体）向け API 契約の破壊検出

このサービスの応答は Misskey 本体の judgePrediction（FileInfoService.ts の find(x => x.className === 'Sexy' / 'Porn')）が直接参照する。形・コード・ステータス・ 部分成功の挙動を壊すと本体が無言で誤動作する。 現在の差分を正本と突き合わせ、破壊的変更を洗い出す。

エンドポイントは POST /v1/detect-images（multipart/form-data・バッチ） の 1 本。 複数の正規化済み画像を一括推論し、各パーツの生予測値を順序保持で返す。

差分（自動注入）

• 変更ファイル一覧: !git diff --name-only main...HEAD
• API/契約関連の差分: !git diff main...HEAD -- apps/server/src packages/core/src README.md

正本（これらを基準に判定する）

• 応答型: packages/core/src/types.ts
  • Prediction = { className:string; probability:number }（ONNX Runtime 生出力・確率降順。 PredictionType を re-export しつつ className を string に緩めた契約）。
  • BatchItemResult = { success:true; predictions: Prediction[] } ｜ { success:false; error:{ code:DetectErrorCode; message:string } }（パーツ単位の結果）。
  • DetectImageSuccessResult / DetectFailedResult は core 内部の単一推論型（detectImage）であり、 HTTP 応答の形ではない点に注意。
• HTTP 応答形（apps/server/src/routes/detect-images.ts / app.ts）:
  • 成功（200）= { success:true, result:{ results: BatchItemResult[] } }。 results の順序はリクエストパーツ順と一致する。
  • リクエスト全体の失敗（4xx）= { success:false, error:{ code, message } }。
• エラーコード: DetectErrorCode（7 種）と HTTP ステータス表 STATUS_BY_CODE （apps/server/src/lib/error-mapping.ts）。7 種 = AUTHENTICATION_REQUIRED(401) / INVALID_REQUEST(400) / UNSUPPORTED_MEDIA_TYPE(415) / REQUEST_TOO_LARGE(413) / IMAGE_DECODE_FAILED(422) / MODEL_UNAVAILABLE(503) / DETECTION_FAILED(500)。
• リクエスト全体の優先順位（先勝ち。app.ts のミドルウェア順 ＋ detect-images.ts）: 認証(401) → bodyLimit 超過 413(maxBodySize) → 非 multipart 415 → multipart パース失敗 400 → パーツ 0 件 400 → パーツ数超過 413(maxParts)。
• パーツ単位の検査順（detect-images.ts 内、各パーツ毎・全体は 200 のまま results[i].error に格納）: 非 File 400 → 非対応 part Content-Type 415 → 空ボディ 400 → サイズ超過 413(maxBinarySize) → dimensions 読取失敗 422(IMAGE_DECODE_FAILED) → dimensions 上限超過 413 (maxImageWidth/maxImageHeight/maxImagePixels) → 推論。
• 受理する パーツの Content-Type: image/png|jpeg|gif|bmp （detect-images.ts の ACCEPTED_CONTENT_TYPES）。リクエスト全体は multipart/form-data。
• README.md の API 表。

破壊的変更とみなすもの（❌ で報告）

• result.results[] 構造の変更・BatchItemResult のキー改名・predictions の形変更・ 確率降順保証の喪失。
• 部分成功不変条件の破壊: パーツ単位の失敗で全体を 4xx にする、results の順序保証の喪失、 パーツ失敗を 200 以外で返す。
• DetectErrorCode の削除・改名、STATUS_BY_CODE のステータス変更。
• リクエスト全体／パーツ単位いずれかのエラー優先順位の入れ替え。
• success フラグの廃止・意味変更、error.code 以外での分岐を強要する変更。
• 受理する Content-Type（リクエスト=multipart / パーツ=image/*）の縮小。

報告

各論点を ✅(影響なし) / ⚠️(要確認) / ❌(後方互換破壊) で列挙し、❌ は 「どのファイルのどの変更が・本体の何を壊すか・どう直すか」まで一行で示す。 新規エンドポイントの追加など既存契約を変えない拡張は ✅（scope-guard の判断軸に従う）。