@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/reward-risk.js

@@ -0,0 +1,545 @@
+import { MAX_GUARD_COUNT_REWARD, MAX_RECORD_COUNT_REWARD, } from "./onchain-constants.js";
+import { resolveGuardConstructor, } from "./reward-ledger.js";
+const R_R_1_01 = {
+    id: "R-R-1-01",
+    category: "structural",
+    trigger: "guard_add would exceed MAX_GUARD_COUNT_REWARD (200)",
+    check: (ctx) => {
+        if (!ctx.guard_add || ctx.guard_add.length === 0)
+            return null;
+        const current = ctx.current_guard_count ?? 0;
+        const wouldAdd = ctx.guard_add.length;
+        if (current + wouldAdd > MAX_GUARD_COUNT_REWARD) {
+            return {
+                id: "R-R-1-01",
+                level: "HIGH",
+                category: "structural",
+                title: "guard_add would exceed MAX_GUARD_COUNT_REWARD",
+                description: `Reward has ${current} guards, adding ${wouldAdd} would total ${current + wouldAdd}, ` +
+                    `exceeds MAX_GUARD_COUNT_REWARD ${MAX_GUARD_COUNT_REWARD}. Move aborts with E_GUARD_COUNT_EXCEEDED (3).`,
+                affected_stakeholders: ["owner", "service_provider"],
+                scenario: "Adding too many guards to a single Reward (e.g. milestone reward with > 200 recipients)",
+                mitigation: "Split into multiple Reward objects, or use GuardIdentifier recipient to handle multiple recipients with a single guard.",
+                evidence: `current=${current}, add=${wouldAdd}`,
+                related_move_error: "E_GUARD_COUNT_EXCEEDED (3)",
+                auto_fixable: false,
+            };
+        }
+        return null;
+    },
+};
+const R_R_1_02 = {
+    id: "R-R-1-02",
+    category: "structural",
+    trigger: "claim would push recipient record count to MAX_RECORD_COUNT_REWARD (5200)",
+    check: (ctx) => {
+        if (!ctx.claim)
+            return null;
+        const current = ctx.current_record_count_for_recipient ?? 0;
+        if (current >= MAX_RECORD_COUNT_REWARD) {
+            return {
+                id: "R-R-1-02",
+                level: "HIGH",
+                category: "structural",
+                title: "claim blocked — recipient record count at limit",
+                description: `Recipient already has ${current} records, at MAX_RECORD_COUNT_REWARD ${MAX_RECORD_COUNT_REWARD}. ` +
+                    `Next claim will abort with E_RECORD_COUNT_EXCEEDED (8). The recipient can no longer claim from this Reward.`,
+                affected_stakeholders: ["claimer"],
+                scenario: "High-frequency claimer hits the 5200-record ceiling (e.g. cashback on every micro-order)",
+                mitigation: "Owner can create a new Reward for the same recipient, OR redesign the Guard to batch claims (larger amount per claim).",
+                evidence: `recipient_records=${current}`,
+                related_move_error: "E_RECORD_COUNT_EXCEEDED (8)",
+                auto_fixable: false,
+            };
+        }
+        return null;
+    },
+};
+const R_R_1_03 = {
+    id: "R-R-1-03",
+    category: "structural",
+    trigger: "guard_add batch size > MAX_GUARD_COUNT_REWARD (200) — schema-level overflow",
+    check: (ctx) => {
+        if (!ctx.guard_add)
+            return null;
+        if (ctx.guard_add.length > MAX_GUARD_COUNT_REWARD) {
+            return {
+                id: "R-R-1-03",
+                level: "CRITICAL",
+                category: "structural",
+                title: "guard_add batch exceeds absolute limit",
+                description: `Single guard_add call tries to add ${ctx.guard_add.length} guards in one transaction, ` +
+                    `exceeds MAX_GUARD_COUNT_REWARD ${MAX_GUARD_COUNT_REWARD}. SDK rejects this in operate().`,
+                affected_stakeholders: ["owner"],
+                scenario: "Bulk guard addition without splitting transactions",
+                mitigation: `Split into multiple transactions, each ≤ ${MAX_GUARD_COUNT_REWARD} new guards.`,
+                evidence: `batch_size=${ctx.guard_add.length}`,
+                auto_fixable: true,
+            };
+        }
+        return null;
+    },
+};
+const R_R_2_01 = {
+    id: "R-R-2-01",
+    category: "semantic",
+    trigger: "guard_add with GuardIdentifier recipient where identifier type is not address",
+    check: (ctx) => {
+        if (!ctx.guard_add)
+            return null;
+        for (let i = 0; i < ctx.guard_add.length; i++) {
+            const g = ctx.guard_add[i];
+            if ("GuardIdentifier" in g.recipient) {
+                const id = g.recipient.GuardIdentifier;
+                if (ctx.passport_identifier_is_address && ctx.passport_identifier_is_address[id] === false) {
+                    return {
+                        id: "R-R-2-01",
+                        level: "HIGH",
+                        category: "semantic",
+                        title: `guard_add[${i}]: recipient GuardIdentifier ${id} is not address-typed`,
+                        description: `RewardGuard constructor calls is_identifier_address(guard, ${id}). If the identifier type is not address, ` +
+                            `Move aborts with E_RECIPIENT_IDENTIFIER_NOT_ADDRESS (4).`,
+                        affected_stakeholders: ["owner"],
+                        scenario: "Misconfigured Guard — recipient identifier is u64/bool instead of address",
+                        mitigation: "Use a Guard with an address-typed identifier for recipient, OR switch to Entity/Signer recipient.",
+                        evidence: `guard_add[${i}].recipient.GuardIdentifier=${id}, is_address=false`,
+                        related_move_error: "E_RECIPIENT_IDENTIFIER_NOT_ADDRESS (4)",
+                        auto_fixable: false,
+                    };
+                }
+            }
+        }
+        return null;
+    },
+};
+const R_R_2_02 = {
+    id: "R-R-2-02",
+    category: "semantic",
+    trigger: "guard_add with GuardU64Identifier amount where identifier type is not u64",
+    check: (ctx) => {
+        if (!ctx.guard_add)
+            return null;
+        for (let i = 0; i < ctx.guard_add.length; i++) {
+            const g = ctx.guard_add[i];
+            const amountTypeStr = String(g.amount.type).toUpperCase();
+            if (amountTypeStr === "GUARDU64IDENTIFIER" || amountTypeStr === "GUARD_U64_IDENTIFIER") {
+                if (typeof g.amount.value !== "number")
+                    continue;
+                const id = g.amount.value;
+                if (ctx.passport_submission_value_types && ctx.passport_submission_value_types[id] !== "u64") {
+                    return {
+                        id: "R-R-2-02",
+                        level: "HIGH",
+                        category: "semantic",
+                        title: `guard_add[${i}]: amount GuardU64Identifier ${id} is not u64-typed`,
+                        description: `RewardGuard constructor calls get_submission_value_type(guard, ${id}); if None or ≠ TYPE_U64, ` +
+                            `Move aborts with E_AMOUNT_NOT_U64 (5).`,
+                        affected_stakeholders: ["owner"],
+                        scenario: "Misconfigured Guard — amount identifier is not u64-typed",
+                        mitigation: "Use a Guard with a u64-typed identifier for amount, OR switch to Fixed amount.",
+                        evidence: `guard_add[${i}].amount.value=${id}, value_type=${ctx.passport_submission_value_types[id] ?? "unknown"}`,
+                        related_move_error: "E_AMOUNT_NOT_U64 (5)",
+                        auto_fixable: false,
+                    };
+                }
+            }
+        }
+        return null;
+    },
+};
+const R_R_2_03 = {
+    id: "R-R-2-03",
+    category: "semantic",
+    trigger: "guard_add with store_from_id set but identifier is not number/address compatible",
+    check: (ctx) => {
+        if (!ctx.guard_add)
+            return null;
+        for (let i = 0; i < ctx.guard_add.length; i++) {
+            const g = ctx.guard_add[i];
+            if (g.store_from_id == null)
+                continue;
+            if (ctx.guard_store_from_id_compatible && ctx.guard_store_from_id_compatible[g.guard] === false) {
+                return {
+                    id: "R-R-2-03",
+                    level: "MEDIUM",
+                    category: "semantic",
+                    title: `guard_add[${i}]: store_from_id incompatible with guard`,
+                    description: `RewardGuard constructor with store_from_id=Some calls is_identifier_address_compatible(guard, store_from_id). ` +
+                        `If the identifier type is not number or address, Move aborts with E_STORE_FROM_ID_NOT_COMPATIBLE (12).`,
+                    affected_stakeholders: ["owner"],
+                    scenario: "Misconfigured Guard — store_from_id points to a non-address/non-number identifier",
+                    mitigation: "Use a compatible identifier, OR drop store_from_id (set to null) if cross-reference is not needed.",
+                    evidence: `guard=${g.guard}, store_from_id=${g.store_from_id}`,
+                    related_move_error: "E_STORE_FROM_ID_NOT_COMPATIBLE (12)",
+                    auto_fixable: true,
+                };
+            }
+        }
+        return null;
+    },
+};
+const R_R_2_04 = {
+    id: "R-R-2-04",
+    category: "semantic",
+    trigger: "guard_add with invalid Recipient × Amount pairing (no matching constructor)",
+    check: (ctx) => {
+        if (!ctx.guard_add)
+            return null;
+        const recipientTypeMap = {
+            GuardIdentifier: "GuardIdentifier",
+            Entity: "Entity",
+            Signer: "Signer",
+        };
+        for (let i = 0; i < ctx.guard_add.length; i++) {
+            const g = ctx.guard_add[i];
+            const recipientKey = Object.keys(g.recipient)[0];
+            const recipientType = recipientTypeMap[recipientKey];
+            const amountTypeStr = String(g.amount.type).toUpperCase();
+            const amountType = amountTypeStr === "FIXED" ? "Fixed" : "GuardU64Identifier";
+            const constructor = resolveGuardConstructor(recipientType, amountType);
+            if (!constructor) {
+                return {
+                    id: "R-R-2-04",
+                    level: "HIGH",
+                    category: "semantic",
+                    title: `guard_add[${i}]: invalid Recipient × Amount pairing`,
+                    description: `recipient=${recipientType}, amount=${amountType} — no matching Move constructor. ` +
+                        `SDK reward_guard() will W_ERROR with "Invalid recipient or amount type combination".`,
+                    affected_stakeholders: ["owner"],
+                    scenario: "Schema validation bypassed or stale client",
+                    mitigation: "Use one of the 6 valid pairings: guard_u8_u8, guard_u8_u64, guard_entity_u8, guard_entity_u64, guard_signer_u8, guard_signer_u64.",
+                    evidence: `recipient=${recipientType}, amount=${amountType}`,
+                    auto_fixable: false,
+                };
+            }
+        }
+        return null;
+    },
+};
+const R_R_3_01 = {
+    id: "R-R-3-01",
+    category: "permission",
+    trigger: "claim attempted without permission context — claim is passport-driven",
+    check: (ctx) => {
+        if (!ctx.claim)
+            return null;
+        return {
+            id: "R-R-3-01",
+            level: "MEDIUM",
+            category: "permission",
+            title: "claim is permission-free — anyone with a valid Passport can claim",
+            description: `reward::claim() does NOT assert any permission index. Eligibility is determined entirely by the ` +
+                `Guard verification (passport::result_for_guard). If the Guard is too permissive, funds can be drained by anyone.`,
+            affected_stakeholders: ["owner", "service_provider"],
+            scenario: "Loose Guard allows unauthorized claims (e.g. time-only Guard without service binding)",
+            mitigation: "1) Use Guards that bind to specific Service/Order context. 2) Set expiration_time. 3) Monitor balance and refill only what's needed.",
+            evidence: `claim=${ctx.claim}`,
+            auto_fixable: false,
+        };
+    },
+};
+const R_R_3_02 = {
+    id: "R-R-3-02",
+    category: "permission",
+    trigger: "owner_receive (156) — broad blast radius, owner can drain balance",
+    check: (ctx) => {
+        if (ctx.owner_receive == null)
+            return null;
+        return {
+            id: "R-R-3-02",
+            level: "HIGH",
+            category: "permission",
+            title: "owner_receive drains balance to Permission owner",
+            description: `reward::owner_receive (156 permission) unwraps Receiving<K> / CoinWrapper<K> and forwards to Permission owner. ` +
+                `If 156 is granted too broadly, any 156-holder can sweep receivables. (Note: owner_receive does NOT directly drain balance — ` +
+                `only Receiving<K> envelopes sent to the Reward's id.)`,
+            affected_stakeholders: ["owner", "service_provider"],
+            scenario: "Compromised 156-holder sweeps receivables before owner",
+            mitigation: "1) Grant 156 only to the Permission owner address. 2) Reconcile Receiving<K> inflows vs owner_receive events.",
+            evidence: `owner_receive set`,
+            auto_fixable: false,
+        };
+    },
+};
+const R_R_3_03 = {
+    id: "R-R-3-03",
+    category: "permission",
+    trigger: "guard_expiration_time_add (155) — can permanently lock guard additions",
+    check: (ctx) => {
+        if (ctx.guard_expiration_time === undefined)
+            return null;
+        if (ctx.guard_expiration_time !== null && ctx.current_clock_ms !== undefined) {
+            const lockDurationMs = ctx.guard_expiration_time - ctx.current_clock_ms;
+            const oneYearMs = 365 * 24 * 60 * 60 * 1000;
+            if (lockDurationMs > oneYearMs) {
+                return {
+                    id: "R-R-3-03",
+                    level: "MEDIUM",
+                    category: "permission",
+                    title: "guard_expiration_time_add locks guard additions for > 1 year",
+                    description: `Setting guard_not_added_expiration_time to ${ctx.guard_expiration_time} ` +
+                        `(> 1 year from now) effectively freezes the guard list. While this is sometimes intentional ` +
+                        `(milestone rewards), it cannot be undone without setting a new time (which itself requires 155 permission).`,
+                    affected_stakeholders: ["owner"],
+                    scenario: "Operator sets excessively long lock period by mistake",
+                    mitigation: "Confirm intent. If wrong, call guard_expiration_time_add again with a shorter time (must be ≥ current clock per E_GUARD_LOCKED_TIME_NOT_INCREASING).",
+                    evidence: `lock_until=${ctx.guard_expiration_time}, clock=${ctx.current_clock_ms}`,
+                    auto_fixable: false,
+                };
+            }
+        }
+        return null;
+    },
+};
+const R_R_4_01 = {
+    id: "R-R-4-01",
+    category: "lifecycle",
+    trigger: "claim on guard with expiration_time < now (E_GUARD_EXPIRED)",
+    check: (ctx) => {
+        if (!ctx.claim)
+            return null;
+        return null;
+    },
+};
+const R_R_4_02 = {
+    id: "R-R-4-02",
+    category: "lifecycle",
+    trigger: "claim: balance < amount (E_INSUFFICIENT_BALANCE)",
+    check: (ctx) => {
+        if (!ctx.claim)
+            return null;
+        if (ctx.current_balance !== undefined && ctx.current_guard_count !== undefined) {
+            const balance = BigInt(ctx.current_balance);
+            if (balance === 0n) {
+                return {
+                    id: "R-R-4-02",
+                    level: "HIGH",
+                    category: "lifecycle",
+                    title: "claim on Reward with zero balance",
+                    description: `Reward balance is 0. Any claim will abort with E_INSUFFICIENT_BALANCE (6). ` +
+                        `Owner must coin_add (153) or receive (154) to replenish.`,
+                    affected_stakeholders: ["claimer", "owner"],
+                    scenario: "Marketing campaign budget exhausted but guards remain active",
+                    mitigation: "1) Owner: coin_add to replenish. 2) Owner: guard_remove_expired + guard_expiration_time_add to deactivate. 3) Claimer: wait for replenishment.",
+                    evidence: `balance=0`,
+                    related_move_error: "E_INSUFFICIENT_BALANCE (6)",
+                    auto_fixable: false,
+                };
+            }
+        }
+        return null;
+    },
+};
+const R_R_4_03 = {
+    id: "R-R-4-03",
+    category: "lifecycle",
+    trigger: "guard_add while guard_not_added_expiration_time is Some and clock ≤ expiration (E_GUARD_LOCKED_TIME)",
+    check: (ctx) => {
+        if (!ctx.guard_add || ctx.guard_add.length === 0)
+            return null;
+        if (ctx.current_guard_not_added_expiration_time == null)
+            return null;
+        if (ctx.current_clock_ms === undefined)
+            return null;
+        if (ctx.current_clock_ms <= ctx.current_guard_not_added_expiration_time) {
+            return {
+                id: "R-R-4-03",
+                level: "HIGH",
+                category: "lifecycle",
+                title: "guard_add blocked by time-lock (guard_not_added_expiration_time)",
+                description: `guard_not_added_expiration_time is Some(${ctx.current_guard_not_added_expiration_time}); ` +
+                    `clock is ${ctx.current_clock_ms}. Move asserts clock > expiration_time ` +
+                    `(E_GUARD_LOCKED_TIME = 10).`,
+                affected_stakeholders: ["owner"],
+                scenario: "Trying to add guards during a flash sale lock period",
+                mitigation: "1) Wait until clock > expiration_time. 2) Call guard_expiration_time_add (155) to extend the lock (cannot shorten below current clock).",
+                evidence: `lock_until=${ctx.current_guard_not_added_expiration_time}, clock=${ctx.current_clock_ms}`,
+                related_move_error: "E_GUARD_LOCKED_TIME (10)",
+                auto_fixable: false,
+            };
+        }
+        return null;
+    },
+};
+const R_R_4_04 = {
+    id: "R-R-4-04",
+    category: "lifecycle",
+    trigger: "guard_expiration_time_add regression (new time < current clock)",
+    check: (ctx) => {
+        if (ctx.guard_expiration_time === undefined)
+            return null;
+        if (ctx.guard_expiration_time === null)
+            return null;
+        if (ctx.current_clock_ms === undefined)
+            return null;
+        if (ctx.guard_expiration_time <= ctx.current_clock_ms) {
+            return {
+                id: "R-R-4-04",
+                level: "HIGH",
+                category: "lifecycle",
+                title: "guard_expiration_time_add: new time must be in the future",
+                description: `New guard_not_added_expiration_time = ${ctx.guard_expiration_time} ≤ clock ${ctx.current_clock_ms}. ` +
+                    `Move aborts with E_GUARD_LOCKED_TIME_INVALID (11).`,
+                affected_stakeholders: ["owner"],
+                scenario: "Operator sets lock time in the past by mistake",
+                mitigation: `Set guard_expiration_time to a value > ${ctx.current_clock_ms} (current clock).`,
+                evidence: `new_time=${ctx.guard_expiration_time}, clock=${ctx.current_clock_ms}`,
+                related_move_error: "E_GUARD_LOCKED_TIME_INVALID (11)",
+                auto_fixable: true,
+            };
+        }
+        return null;
+    },
+};
+const R_R_5_01 = {
+    id: "R-R-5-01",
+    category: "cross_object",
+    trigger: "claim: guard not found in self.guards (E_GUARD_NOT_FOUND)",
+    check: (ctx) => {
+        if (!ctx.claim)
+            return null;
+        if (!ctx.target_guard_addresses)
+            return null;
+        if (!ctx.target_guard_addresses.includes(ctx.claim)) {
+            return {
+                id: "R-R-5-01",
+                level: "HIGH",
+                category: "cross_object",
+                title: "claim: supplied guard not in Reward.guards",
+                description: `Guard ${ctx.claim} is not in the Reward's guard list. Move iterates self.guards and ` +
+                    `aborts with E_GUARD_NOT_FOUND (7) if no match.`,
+                affected_stakeholders: ["claimer"],
+                scenario: "Claimer uses the wrong Guard object (typo or wrong Service)",
+                mitigation: "1) Verify the Guard address via query ObjectReward. 2) Ensure the Guard was added via guard_add (152).",
+                evidence: `claim_guard=${ctx.claim}, known_guards=${ctx.target_guard_addresses.join(",")}`,
+                related_move_error: "E_GUARD_NOT_FOUND (7)",
+                auto_fixable: false,
+            };
+        }
+        return null;
+    },
+};
+const R_R_5_02 = {
+    id: "R-R-5-02",
+    category: "cross_object",
+    trigger: "coin_add: coin type T mismatch with Reward<T>",
+    check: (ctx) => {
+        if (!ctx.coin_add || !ctx.reward_type)
+            return null;
+        if (ctx.coin_add.coin_type !== ctx.reward_type) {
+            return {
+                id: "R-R-5-02",
+                level: "CRITICAL",
+                category: "cross_object",
+                title: "coin_add: coin type T mismatch",
+                description: `Reward is Reward<${ctx.reward_type}> but coin_add passes Coin<${ctx.coin_add.coin_type}>. ` +
+                    `Move type-system mismatch; SDK W_ERROR in operate().`,
+                affected_stakeholders: ["owner"],
+                scenario: "Operator tries to deposit wrong coin type (e.g. USDC into a WOW Reward)",
+                mitigation: `Use Coin<${ctx.reward_type}> for coin_add.`,
+                evidence: `reward_type=${ctx.reward_type}, coin_type=${ctx.coin_add.coin_type}`,
+                auto_fixable: false,
+            };
+        }
+        return null;
+    },
+};
+const R_R_5_03 = {
+    id: "R-R-5-03",
+    category: "cross_object",
+    trigger: "receive: Payment<T> type mismatch with Reward<T>",
+    check: (ctx) => {
+        if (!ctx.receive || !ctx.reward_type)
+            return null;
+        if (ctx.receive.token_type !== ctx.reward_type) {
+            return {
+                id: "R-R-5-03",
+                level: "CRITICAL",
+                category: "cross_object",
+                title: "receive: Payment token_type mismatch",
+                description: `Reward is Reward<${ctx.reward_type}> but receive's Payment<CoinWrapper<${ctx.receive.token_type}>>. ` +
+                    `SDK W_ERROR in operate().`,
+                affected_stakeholders: ["owner"],
+                scenario: "Operator tries to receive wrong-token Payment",
+                mitigation: `Use Payment<${ctx.reward_type}> for receive.`,
+                evidence: `reward_type=${ctx.reward_type}, payment_token=${ctx.receive.token_type}`,
+                auto_fixable: false,
+            };
+        }
+        return null;
+    },
+};
+const ALL_RULES = [
+    R_R_1_01, R_R_1_02, R_R_1_03,
+    R_R_2_01, R_R_2_02, R_R_2_03, R_R_2_04,
+    R_R_3_01, R_R_3_02, R_R_3_03,
+    R_R_4_01, R_R_4_02, R_R_4_03, R_R_4_04,
+    R_R_5_01, R_R_5_02, R_R_5_03,
+];
+export const REWARD_RISK_VERSION = "1.0.0";
+export function getAllRewardRiskRules() {
+    return [...ALL_RULES];
+}
+export function getRewardRiskRulesCount() {
+    return ALL_RULES.length;
+}
+export function getRewardRiskRulesByCategory(category) {
+    return ALL_RULES.filter(r => r.category === category);
+}
+export function assessRewardRisks(ctx) {
+    const risks = [];
+    for (const rule of ALL_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    const overall = risks.length === 0
+        ? "LOW"
+        : risks.some(r => r.level === "CRITICAL") ? "CRITICAL"
+            : risks.some(r => r.level === "HIGH") ? "HIGH"
+                : risks.some(r => r.level === "MEDIUM") ? "MEDIUM"
+                    : "LOW";
+    const byCategory = {};
+    for (const r of risks) {
+        byCategory[r.category] = (byCategory[r.category] ?? 0) + 1;
+    }
+    const advice = {};
+    for (const r of risks) {
+        for (const s of r.affected_stakeholders) {
+            if (!advice[s])
+                advice[s] = [];
+            advice[s].push(`${r.id}: ${r.mitigation}`);
+        }
+    }
+    return {
+        summary: `Assessed ${risks.length} risk(s) across ${Object.keys(byCategory).length} categories`,
+        risks,
+        overall_risk: overall,
+        risks_by_category: byCategory,
+        stakeholder_advice: advice,
+        needs_human_review: risks.some(r => r.level === "CRITICAL" || r.level === "HIGH"),
+    };
+}
+export const REWARD_STAKEHOLDERS = [
+    "owner",
+    "claimer",
+    "service_provider",
+    "system",
+];
+export function getRewardRiskRulesByStakeholder(stakeholder) {
+    return ALL_RULES.filter(rule => {
+        if (stakeholder === "owner") {
+            return ["structural", "permission", "lifecycle"].includes(rule.category);
+        }
+        if (stakeholder === "claimer") {
+            return rule.id.startsWith("R-R-4-0") || rule.id === "R-R-5-01" || rule.id === "R-R-1-02";
+        }
+        if (stakeholder === "service_provider") {
+            return rule.id === "R-R-4-02" || rule.id === "R-R-3-01" || rule.id === "R-R-3-02";
+        }
+        if (stakeholder === "system") {
+            return rule.category === "cross_object";
+        }
+        return false;
+    });
+}

package/dist/knowledge/reward-translation.d.ts

@@ -0,0 +1,58 @@
+export interface RewardSemanticToSchemaRule {
+    id: string;
+    pattern_name: string;
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_fields: string[];
+    example_json: object;
+    reverse_explanation: string;
+}
+export interface RewardSchemaToSemanticRule {
+    element_type: "field" | "op" | "phase" | "constructor";
+    type_name: string;
+    semantic_explanation: string;
+    constraints?: string[];
+}
+export interface RewardConstraintRule {
+    id: string;
+    category: "structural" | "semantic" | "permission" | "lifecycle" | "cross_object";
+    rule: string;
+    applies_to: string[];
+}
+export declare const REWARD_SEMANTIC_TO_SCHEMA_RULES: RewardSemanticToSchemaRule[];
+export declare const REWARD_SCHEMA_TO_SEMANTIC_RULES: RewardSchemaToSemanticRule[];
+export declare const REWARD_CONSTRAINT_RULES: RewardConstraintRule[];
+export declare const REWARD_TRANSLATION_VERSION = "1.0.0";
+export declare function matchSemanticPattern(userIntent: string): RewardSemanticToSchemaRule[];
+export interface RewardCallDataForExplanation {
+    object?: string | null;
+    claim?: string;
+    description?: string;
+    coin_add?: {
+        amount: string | number;
+        coin_type: string;
+    };
+    receive?: {
+        token_type: string;
+    };
+    guard_add?: Array<{
+        guard: string;
+        recipient: Record<string, unknown>;
+        amount: {
+            type: string;
+            value: number | string;
+        };
+        expiration_time?: number;
+        store_from_id?: number | null;
+    }>;
+    guard_remove_expired?: boolean;
+    guard_expiration_time?: number | null;
+    owner_receive?: unknown;
+    um?: string | null;
+}
+export declare function explainRewardCallData(data: RewardCallDataForExplanation): string;
+export declare function explainField(fieldName: string): RewardSchemaToSemanticRule | undefined;
+export declare function explainOp(opName: string): RewardSchemaToSemanticRule | undefined;
+export declare function explainConstructor(constructorName: string): RewardSchemaToSemanticRule | undefined;
+export declare function getConstraintsByCategory(category: RewardConstraintRule["category"]): RewardConstraintRule[];
+export declare function explainPermissionIndex(index: number): string;