tres-rollup-review

TRES Finance — ロールアップのレビュー

完全に指定されたロールアップルールを受け取り、適用されるすべてのフィルターを適用したうえで、そのルールが対象とするサブトランザクションを正確に特定し、実際の問題を指摘します。新しいロールアップを設計することはなく、変更操作も実行しません。

すべての GraphQL 実行はTRES Finance MCP コネクター（execute ツール）を介します。すべての変数キーとネストされた入力フィールドには、snake_case ではなく必ず camelCase を使用してください。

---

tres-rollup-rules に追加される機能

тres-rollup-rules の探索ステップでは、サブトランザクションを（ウォレット、資産、方向）のレベルでのみグループ化します。候補ごとのフィルターの完全な組み合わせ（手数料 + method_ids + subtx_type + 金額の上下限 + 取引相手 + excludeRollups）を適用することはありません。このスキルでは、subTransactionRollupRulePreview クエリ（エンジンの実際の query_sub_transactions を実行）を使って、ルールごとに次の処理を行います。

• 正確な一致件数の確認 → ゼロ件一致のゲート（何も一致しないルールを作成してはいけません）。
• 作成前に重複を把握し、ユーザーには実行可能な提案のみを表示します。

また、誰かが送信したルールのレビュー（モード B）にも単独で使用できます。これは探索スキルでは対応しないケースです。

---

2 つのモード

モード A — 作成前のゲート（tres-rollup-rules から呼び出し）

tres-rollup-rules がスキルツール経由でこのスキルを呼び出すと、候補ルールのオブジェクトをすでに保持している同じコンテキストにこれらの指示が読み込まれます。引数として渡されるのではなく、すでに会話の上部にあります。候補を1 つずつ処理し、それぞれについて以下のチェックを実行し、判定を 1 つだけ出力します。

• PASS — 問題がなく、提案可能です（サブトランザクション数と親トランザクション数を正確に含めます）。
• DROP — 一致するサブトランザクションが 0 件です。作成してはいけません。
• FIX — 設定に問題があります。具体的な変更内容も示します（例：「minAmount > maxAmount」、「INFLOW ルールに recipientIdentifier が指定されています。senderIdentifier にする必要があります」）。

重複は DROP／FIX ではなく注記として報告します（チェック 2 を参照）。候補ごとに判定行を 1 行ずつ出力した後、制御は tres-rollup-rules のステップ 2.5 に戻ります。

モード B — 単独レビュー（送信済み／保留中のルールのレビューを依頼された場合）

保留中のルールを取得してそれぞれをレビューし、ルールごとの所見を要約します。

query PendingRollupRules {
  subTransactionRollupRule(status: "Pending", limit: 50) {
    totalCount
    results { id name interval startDate endDate status rule createdBy createdAt }
  }
}

ステータスフィルターはタイトルケース（"Pending"、"Active"、"Disabled"）です。totalCount が 0 の場合は「この組織には保留中のロールアップリクエストはありません」と伝えて終了します。

---

正解 — ルールがサブトランザクションを選択する方法

ルールは、次の条件をすべて満たすサブトランザクションを対象とします（エンジンの query_sub_transactions の動作を反映しています）。

• belongsTo_In: [internal_account_id]、asset_In: [asset_id]（資産の KEY）、 platform が一致し、balanceFactor が balance_factor と一致する
• すでにロールアップ済み（excludeRollups）のサブトランザクション、および派生／ロック済み／同期済みのサブトランザクションは除外されます
• fees：EXCLUDE は GAS／FEE を除外し、ONLY は GAS／FEE のみを残し、INCLUDE はすべて残します
• 任意の絞り込み：method_ids、min_amount／max_amount、subtx_type、 sender_identifier／recipient_identifier、 original_sender_prefix／original_recipient_prefix

ルールの JSON（保存時／返却時）は snake_case を使用します。balance_factor = -1 はOUTFLOW、+1 はINFLOWです。正しく判定してください。誤ると、方向に関するすべてのチェックが逆になります。

確認済みの subTransaction フィルター名

意図	フィルター
ウォレット	belongsTo_In: [ID]
キーによるアセット	asset_In: [ID]
方向	balanceFactor: Float（-1 / 1）
最小／最大金額	amount_Gte / amount_Lte
送信者／受取人	sender_Identifier_In: [String] / recipient_Identifier_In: [String]
メソッド ID	tx_MethodId: String（単一） / tx_Classification_MethodId_In: [String]
Sub-tx の種類	type: String / type_In: [String]（小文字の FinancialAction 値）
すでにロールアップされたものを除外	excludeRollups: true
ガス／手数料を除外	excludeGasFees: true
日付	timestamp_Gte / timestamp_Lte（DateTime）

type / type_In には、FinancialAction の小文字の値（"gas"、"fee"、 "reward"、…）を指定します。ルールの UPPERCASE の subtxType enum とは大文字小文字が逆です。そのため、 subtx_type は正確にカウント可能（type: "<value>"）で、fees: ONLY は type_In: ["gas", "fee"] とほぼ同等です。

注意点：fees: ONLY はすでに GAS+FEE を選択するため、ガス／手数料のロールアップには fees: ONLY だけを指定します。さらに subtxType: GAS を追加すると冗長になり（FEE が除外され、GAS のみに絞られます）。

ここでは typeId はルールのフィルターではありません。 type_id がロールアップルールの ID を表すのは、type_In: ["rollup", "rollup_fee"] と組み合わせた場合のみです。それ以外のタイプでは、まったく別の意味になります。既存のロールアップルールが生成したものを確認するには、 type_In: ["rollup","rollup_fee"], typeId: "<rule_id>" をクエリします。typeId 単独では決してクエリしないでください。

センチネル日付（運用上の注意）： startDate == "0001-01-01" または endDate == "9999-12-31" の場合、その境界値は省略します（センチネル値を渡さないでください。解析に失敗する可能性があります）。 日付の範囲を指定しないことは通常のことであり、推奨されます。問題として報告する必要はありません。

証拠： オンチェーンハッシュは tx.identifier です（tx { identifier } サブセレクト）。typeId ではありません。 例では、amount、sender { identifier }、 recipient { identifier }、asset { symbol key } も取得します。

---

対象範囲 — DISABLED ルールは対象外です

有効なルールは Active と Pending のみです。DISABLED ルールは（旧バージョンに置き換えられているため）決してクエリ、比較、問題として報告しないでください。

---

チェック内容

チェック 1 — 影響の正確な把握（中核。必ず実行）

subTransactionRollupRulePreview クエリを使って、エンジンから正確な件数を取得します。このクエリは実際の query_sub_transactions を実行し、ルールのフィルターをすべてサーバー側で適用するため、フィルターを手動で組み立て直す必要はありません。

query RollupPreview($rule: RollupRuleInputType!, $startDate: Date, $endDate: Date, $interval: Interval) {
  subTransactionRollupRulePreview(rule: $rule, startDate: $startDate, endDate: $endDate, interval: $interval) {
    subTransactionCount
    transactionCount
  }
}

候補のルールオブジェクトは、$rule としてそのまま渡してください。作成ミューテーションと同じ camelCase 形式（internalAccountId、assetId、platform、balanceFactor、fees は OUTFLOW／ONLY などの列挙型の名前で指定し、必要に応じて methodIds／subtxType／minAmount／maxAmount／識別子も指定）を使います。必ず $interval も渡してください。これは候補ルールの期間（DAY または MONTH）とします。期間は対象期間の境界を正規化する際に使われるため、同じデータでも MONTH ルールと DAY ルールでは件数が異なる場合があります。startDate／endDate は省略可能で、形式は YYYY-MM-DD です。省略すると、ルールの全期間が対象になります。

この件数は、ルールが次回実行時に実際にロールアップする件数であり、全期間の生の一致件数ではありません。エンジンは独自の適格性判定に基づいて期間を絞り込むため、現在進行中の未完了期間と、未同期／バッファ分の末尾データは除外されます。 transactionCount は重複のない親トランザクション数です。（すでにロールアップされたサブトランザクションも除外されます。既存ルールがすでに生成した件数については、以下の既存ルールのセクションを参照してください。）

• subTransactionCount == 0 → DROP（Mode A）／ブロッキングフラグ（Mode B）：「設定された条件に一致するサブトランザクションは 0 件」です。0 件になるフィルターを示します（よくある原因は、minAmount > maxAmount、方向が異なる識別子、または開始日と終了日の順序が逆になっていることです）。重要なのはその理由です。

この組織の MCP スキーマに subTransactionRollupRulePreview がない場合（validate_query または introspect で確認してください）は、フィルターをすべて適用した件数クエリに切り替えます。つまり、上記の検証済みフィルター名の表を使って、ルールのフィルターをすべて適用した単一の subTransaction(... excludeRollups: true ...) を実行し、totalCount だけを選択します。エンジンのプレビューより精度はやや低く（未完了期間／バッファ分の末尾データが除外されません）、件数を報告する際にはその旨を伝え、~ 接頭辞を付けてください。

チェック 2 — 重複（参考情報。厳格な制限ではありません）

同じ internalAccountId ＋ assetId ＋ platform ＋ balanceFactor を持ち、日付が重複し、フィルターが互いに排他的でない別の Active/Pending ルール（または別の候補）が、一部の同じサブトランザクションを対象にする可能性があります。これはブロッキング要因ではありません。エンジンはルールを ID（PK）順に 1 つずつ処理するため、複数のルールに一致するサブトランザクションは、常に同じルールに割り当てられます。ユーザーが把握できるよう、メモとして示してください（別のルール名と ID、トランザクションハッシュの例を最大 3 件）。重複だけを理由に DROP したり、分割を強制したりしてはいけません。

設定の検証を別途行う必要はありません。 日付の順序、方向が異なる識別子、相互排他的なプレフィックス、不正な cutoffTime は、作成ミューテーションで検証され（ブロッキング要因となる validationIssues として返されます）。ここで再検証しないでください。ロックされた期間を解除するために開始日を設定するのは適切な使い方であり、フラグ対象ではありません（終了日は未指定のままにします）。

既存ルールの影響（Mode B — Active/Pending ルールのレビュー）

チェック 1 の件数が少ないからといって、既存ルールを無用と判断してはいけません。実行中のルールはすでに対象のサブトランザクションをロールアップしており、それらはチェック 1 から除外されます。そのため、正常に機能しているルールでも、まだロールアップされていない最近のサブトランザクションが数件だけ表示されることがあります。さらに、そのルールが生成した件数も数えます。 subTransaction(type_In: ["rollup","rollup_fee"], typeId: "<rule_id>") { totalCount }。 両方を報告します。「現在、新しいサブトランザクション N 件に一致。これまでに M 件のロールアップを生成済み」。ルールが機能していないと判断するのは、生成件数がほぼなく、かつ現在の一致件数もほぼない場合だけです。（フィルターが古くなっているように見える場合、たとえば methodId が新しいトランザクションに一致しなくなっている場合は、「無用」と言うのではなく、生成件数と現在の一致件数を示したうえで、その点を伝えてください。）

---

出力

モード A： 候補ごとに1行で tres-rollup-rules に返します： <#> <name>: PASS (<subtx>/<tx> sub-txs) ／ DROP — <reason> ／ FIX — <change>、および該当する重複に関する注記。

モード B： ルールごとに1つの指摘ブロックを出力します。フラットな箇条書きにし、各項目には具体的な根拠を記載します。該当がなかったチェックは省略します。影響行は必ず含めます。問題がない場合： 「Reviewed (id ) — matches ~ sub-txs across ~ txs. No issues.」

---

ルール

• DISABLED のルールは、照会、比較、指摘の対象にしないでください。
• 新しいロールアップや最適化を提案しないでください。それは tres-rollup-rules の担当です。影響を計算して問題を指摘するだけです。
• 変更操作は実行しないでください。
• すべての指摘に根拠（件数、日付、設定値、または tx ハッシュ）を添えてください。