@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/arbitration-risk.js

@@ -0,0 +1,433 @@
+import { MAX_VOTING_GUARD_COUNT, } from "@wowok/wowok";
+import { isTerminalArbStatus, isValidArbStatusTransition, } from "./arbitration-ledger.js";
+const R_AB_1_01 = {
+    id: "R-AB-1-01",
+    category: "structural",
+    trigger: "voting_guard count exceeds MAX_VOTING_GUARD_COUNT (50)",
+    check: (ctx) => {
+        if (!ctx.voting_guard)
+            return null;
+        if (ctx.voting_guard.op === "add" || ctx.voting_guard.op === "set") {
+            const newCount = ctx.voting_guard.op === "set"
+                ? ctx.voting_guard.guards.length
+                : (ctx.current_voting_guard_count ?? 0) + ctx.voting_guard.guards.length;
+            if (newCount > MAX_VOTING_GUARD_COUNT) {
+                return {
+                    id: "R-AB-1-01",
+                    level: "HIGH",
+                    category: "structural",
+                    title: "voting_guard count exceeds limit",
+                    description: `voting_guard would have ${newCount} entries, exceeds MAX_VOTING_GUARD_COUNT ${MAX_VOTING_GUARD_COUNT}`,
+                    affected_stakeholders: ["owner", "arbiter"],
+                    scenario: "Adding too many voting guards",
+                    mitigation: `Remove unused guards before adding new ones; max ${MAX_VOTING_GUARD_COUNT}`,
+                    evidence: `count=${newCount}`,
+                };
+            }
+        }
+        return null;
+    },
+};
+const R_AB_1_02 = {
+    id: "R-AB-1-02",
+    category: "structural",
+    trigger: "Dispute fee below arbitration.fee threshold",
+    check: (ctx) => {
+        if (!ctx.dispute || ctx.current_arbitration_fee === undefined)
+            return null;
+        const feeRequired = typeof ctx.current_arbitration_fee === "string"
+            ? BigInt(ctx.current_arbitration_fee)
+            : BigInt(ctx.current_arbitration_fee);
+        const feeProvided = typeof ctx.dispute.fee === "object" && ctx.dispute.fee !== null && "balance" in ctx.dispute.fee
+            ? BigInt(ctx.dispute.fee.balance ?? 0)
+            : BigInt(0);
+        if (feeProvided < feeRequired) {
+            return {
+                id: "R-AB-1-02",
+                level: "CRITICAL",
+                category: "structural",
+                title: "Dispute fee insufficient (E_FEE_NOT_ENOUGH)",
+                description: `Provided fee ${feeProvided.toString()} < required ${feeRequired.toString()}`,
+                affected_stakeholders: ["disputant"],
+                scenario: "Filing dispute with insufficient fee",
+                mitigation: `Increase dispute.fee.balance to >= ${feeRequired.toString()}`,
+                evidence: `provided=${feeProvided.toString()}, required=${feeRequired.toString()}`,
+            };
+        }
+        return null;
+    },
+};
+const R_AB_1_03 = {
+    id: "R-AB-1-03",
+    category: "structural",
+    trigger: "Arbitration paused (bPaused=true) — dispute will fail with E_PAUSED",
+    check: (ctx) => {
+        if (ctx.dispute && ctx.current_bPaused === true) {
+            return {
+                id: "R-AB-1-03",
+                level: "HIGH",
+                category: "structural",
+                title: "Arbitration paused — cannot file dispute",
+                description: "Arbitration.bPaused=true; dispute() will abort with E_PAUSED",
+                affected_stakeholders: ["disputant"],
+                scenario: "Filing dispute against a paused Arbitration",
+                mitigation: "Call pause(false) (requires ARBITRATION_PAUSE=356) to resume",
+                evidence: `bPaused=true`,
+            };
+        }
+        return null;
+    },
+};
+const R_AB_1_04 = {
+    id: "R-AB-1-04",
+    category: "structural",
+    trigger: "voting_deadline in the past — vote will be rejected",
+    check: (ctx) => {
+        const deadline = ctx.confirm?.voting_deadline ?? ctx.voting_deadline_change?.voting_deadline;
+        if (deadline !== undefined && deadline !== null && ctx.current_timestamp_ms !== undefined) {
+            if (deadline < ctx.current_timestamp_ms) {
+                return {
+                    id: "R-AB-1-04",
+                    level: "HIGH",
+                    category: "structural",
+                    title: "voting_deadline in the past",
+                    description: `Deadline ${deadline} is before current time ${ctx.current_timestamp_ms}`,
+                    affected_stakeholders: ["voter", "arbiter"],
+                    scenario: "Setting voting deadline to an already-elapsed timestamp",
+                    mitigation: "Use a future timestamp (e.g. now + 7 days in ms)",
+                    evidence: `deadline=${deadline}, now=${ctx.current_timestamp_ms}`,
+                };
+            }
+        }
+        return null;
+    },
+};
+const R_AB_2_01 = {
+    id: "R-AB-2-01",
+    category: "semantic",
+    trigger: "voting_guard misconfiguration — dispute cannot be resolved",
+    check: (ctx) => {
+        if (ctx.vote && ctx.vote.voting_guard) {
+            if (!ctx.current_voting_guard_addresses || ctx.current_voting_guard_addresses.length === 0) {
+                return {
+                    id: "R-AB-2-01",
+                    level: "HIGH",
+                    category: "semantic",
+                    title: "voting_guard misconfiguration — dispute cannot be resolved",
+                    description: "vote.voting_guard provided but Arbitration.voting_guard is empty; E_VOTING_GUARD_NOT_FOUND will abort",
+                    affected_stakeholders: ["voter", "arbiter", "disputant"],
+                    scenario: "voting_guard misconfiguration prevents vote — dispute stuck",
+                    mitigation: "Either add the Guard to voting_guard list (354) or use open vote() without voting_guard",
+                    evidence: `vote.voting_guard=${ctx.vote.voting_guard}`,
+                };
+            }
+            if (!ctx.current_voting_guard_addresses.includes(ctx.vote.voting_guard)) {
+                return {
+                    id: "R-AB-2-01",
+                    level: "HIGH",
+                    category: "semantic",
+                    title: "voting_guard misconfiguration — dispute cannot be resolved",
+                    description: `vote.voting_guard ${ctx.vote.voting_guard} not in Arbitration.voting_guard list`,
+                    affected_stakeholders: ["voter", "arbiter", "disputant"],
+                    scenario: "Voter's Guard not registered — vote will fail with E_VOTING_GUARD_NOT_FOUND",
+                    mitigation: `Add guard ${ctx.vote.voting_guard} via voting_guard_add (354), or use a registered guard`,
+                    evidence: `provided=${ctx.vote.voting_guard}, registered=${ctx.current_voting_guard_addresses.join(",")}`,
+                };
+            }
+        }
+        return null;
+    },
+};
+const R_AB_2_02 = {
+    id: "R-AB-2-02",
+    category: "semantic",
+    trigger: "usage_guard set but dispute without passport — E_NEED_PASSPORT",
+    check: (ctx) => {
+        if (ctx.dispute && ctx.current_voting_guard_addresses !== undefined) {
+        }
+        return null;
+    },
+};
+const R_AB_2_03 = {
+    id: "R-AB-2-03",
+    category: "semantic",
+    trigger: "VoteValue.GuardIdentifier with non-numeric Guard submission type",
+    check: (ctx) => {
+        if (ctx.voting_guard && (ctx.voting_guard.op === "add" || ctx.voting_guard.op === "set")) {
+            for (const g of ctx.voting_guard.guards) {
+                const vw = g.vote_weight;
+                if ("GuardIdentifier" in vw && vw.GuardIdentifier !== undefined) {
+                    if (vw.GuardIdentifier > 255) {
+                        return {
+                            id: "R-AB-2-03",
+                            level: "HIGH",
+                            category: "semantic",
+                            title: "GuardIdentifier index > u8::max (255)",
+                            description: `GuardIdentifier ${vw.GuardIdentifier} exceeds u8 max (255)`,
+                            affected_stakeholders: ["owner"],
+                            scenario: "Setting GuardIdentifier index beyond u8 range",
+                            mitigation: "Use GuardIdentifier index 0-255",
+                            evidence: `identifier=${vw.GuardIdentifier}`,
+                        };
+                    }
+                }
+                if ("FixedValue" in vw && vw.FixedValue !== undefined) {
+                    if (vw.FixedValue > 4294967295) {
+                        return {
+                            id: "R-AB-2-03",
+                            level: "HIGH",
+                            category: "semantic",
+                            title: "FixedValue > u32::max (4294967295)",
+                            description: `FixedValue ${vw.FixedValue} exceeds u32 max`,
+                            affected_stakeholders: ["owner"],
+                            scenario: "Setting FixedValue beyond u32 range",
+                            mitigation: "Use FixedValue 0-4294967295",
+                            evidence: `fixed=${vw.FixedValue}`,
+                        };
+                    }
+                }
+            }
+        }
+        return null;
+    },
+};
+const R_AB_3_01 = {
+    id: "R-AB-3-01",
+    category: "authority",
+    trigger: "Arbiter collusion — single voter controls >50% of total weight",
+    check: (ctx) => {
+        if (!ctx.voting_guard || ctx.voting_guard.op !== "add" && ctx.voting_guard.op !== "set")
+            return null;
+        const guards = ctx.voting_guard.guards;
+        if (guards.length < 2)
+            return null;
+        const fixedWeights = guards
+            .filter(g => "FixedValue" in g.vote_weight && g.vote_weight.FixedValue !== undefined)
+            .map(g => g.vote_weight.FixedValue);
+        if (fixedWeights.length === 0)
+            return null;
+        const total = fixedWeights.reduce((a, b) => a + b, 0);
+        const max = Math.max(...fixedWeights);
+        if (total > 0 && max / total > 0.5) {
+            return {
+                id: "R-AB-3-01",
+                level: "MEDIUM",
+                category: "authority",
+                title: "Arbiter collusion risk — single guard controls >50% weight",
+                description: `One voting_guard has ${max} of ${total} total weight (${((max / total) * 100).toFixed(1)}%)`,
+                affected_stakeholders: ["owner", "disputant"],
+                scenario: "Weighted voting with dominant arbiter — can single-handedly decide rulings",
+                mitigation: "Distribute weight more evenly, or require multi-arbiter consensus",
+                evidence: `max=${max}, total=${total}, ratio=${((max / total) * 100).toFixed(1)}%`,
+            };
+        }
+        return null;
+    },
+};
+const R_AB_3_02 = {
+    id: "R-AB-3-02",
+    category: "authority",
+    trigger: "Permission over-concentration — single admin (owner)",
+    check: (ctx) => {
+        if (ctx.builder) {
+            return {
+                id: "R-AB-3-02",
+                level: "HIGH",
+                category: "authority",
+                title: "Arbitration ownership transfer — IRREVERSIBLE",
+                description: `Transferring Arbitration to ${ctx.builder}; original owner loses all control permanently`,
+                affected_stakeholders: ["owner"],
+                scenario: "Transferring Arbitration ownership",
+                mitigation: "1) Verify new owner twice. 2) Confirm new owner has 350-368 permissions configured. 3) Coordinate before transfer.",
+                evidence: `new_owner=${ctx.builder}`,
+            };
+        }
+        return null;
+    },
+};
+const R_AB_3_03 = {
+    id: "R-AB-3-03",
+    category: "authority",
+    trigger: "ARBITRATION_ARBITRATION (359) granted to wide audience",
+    check: (ctx) => {
+        if (ctx.arbitration && !ctx.current_voting_guard_addresses?.length) {
+            return {
+                id: "R-AB-3-03",
+                level: "MEDIUM",
+                category: "authority",
+                title: "Ruling without voting_guard — single-arbiter can rule unchallenged",
+                description: "make_ruling (359) without voting_guard means any permission holder can unilaterally decide",
+                affected_stakeholders: ["disputant", "voter"],
+                scenario: "Single-arbiter Arbitration without consensus check",
+                mitigation: "Configure voting_guard (354) to require multi-arbiter consensus before ruling",
+                evidence: `voting_guard=empty`,
+            };
+        }
+        return null;
+    },
+};
+const R_AB_4_01 = {
+    id: "R-AB-4-01",
+    category: "lifecycle",
+    trigger: "Invalid Arb status transition (7-state flow violation)",
+    check: (ctx) => {
+        if (!ctx.current_arb_status || !ctx.expected_arb_status)
+            return null;
+        if (ctx.current_arb_status === ctx.expected_arb_status)
+            return null;
+        if (!isValidArbStatusTransition(ctx.current_arb_status, ctx.expected_arb_status)) {
+            return {
+                id: "R-AB-4-01",
+                level: "CRITICAL",
+                category: "lifecycle",
+                title: "Invalid Arb status transition",
+                description: `${ctx.current_arb_status} → ${ctx.expected_arb_status} is not a valid 7-state flow transition`,
+                affected_stakeholders: ["arbiter", "disputant"],
+                scenario: "Attempting operation out of order (e.g. vote before confirm)",
+                mitigation: "Follow the 7-state flow: Principal_confirming → Arbitrator_confirming → Voting → Arbitrated → Objectionable → Finished/Withdrawn",
+                evidence: `${ctx.current_arb_status} → ${ctx.expected_arb_status}`,
+            };
+        }
+        return null;
+    },
+};
+const R_AB_4_02 = {
+    id: "R-AB-4-02",
+    category: "lifecycle",
+    trigger: "Operation on terminal Arb status (Finished/Withdrawn)",
+    check: (ctx) => {
+        if (!ctx.current_arb_status)
+            return null;
+        if (isTerminalArbStatus(ctx.current_arb_status)) {
+            const allowedOpOnTerminal = ctx.arb_withdraw;
+            if (!allowedOpOnTerminal && (ctx.vote || ctx.confirm || ctx.arbitration || ctx.reset || ctx.feedback)) {
+                return {
+                    id: "R-AB-4-02",
+                    level: "HIGH",
+                    category: "lifecycle",
+                    title: "Operation on terminal Arb status — irreversible",
+                    description: `Arb is in terminal status ${ctx.current_arb_status}; only arb_withdraw is allowed`,
+                    affected_stakeholders: ["arbiter", "disputant"],
+                    scenario: "Voting/ruling/reset on a Finished or Withdrawn Arb",
+                    mitigation: "Open a new Arb case via dispute() if further arbitration is needed",
+                    evidence: `status=${ctx.current_arb_status}`,
+                };
+            }
+        }
+        return null;
+    },
+};
+const R_AB_4_03 = {
+    id: "R-AB-4-03",
+    category: "lifecycle",
+    trigger: "reset operation — may indefinitely extend arbitration",
+    check: (ctx) => {
+        if (!ctx.reset)
+            return null;
+        return {
+            id: "R-AB-4-03",
+            level: "MEDIUM",
+            category: "lifecycle",
+            title: "reset operation — arbitration lifecycle extended",
+            description: `reset on Arb ${ctx.reset.arb} restarts lifecycle to Principal_confirming; feedback required`,
+            affected_stakeholders: ["arbiter", "disputant"],
+            scenario: "Disputant objects to ruling and resubmits materials",
+            mitigation: "Track reset count — consider capping resets to prevent abuse",
+            evidence: `arb=${ctx.reset.arb}`,
+        };
+    },
+};
+const R_AB_5_01 = {
+    id: "R-AB-5-01",
+    category: "cross_object",
+    trigger: "fees_alloc/fees_transfer unfair distribution — destination not verified",
+    check: (ctx) => {
+        if (!ctx.fees_transfer)
+            return null;
+        const dest = "allocation" in ctx.fees_transfer.to
+            ? `Allocation ${ctx.fees_transfer.to.allocation}`
+            : `Treasury ${ctx.fees_transfer.to.treasury}`;
+        return {
+            id: "R-AB-5-01",
+            level: "MEDIUM",
+            category: "cross_object",
+            title: "fees_alloc/fees_transfer — verify destination fairness",
+            description: `All Arbitration.balance will be transferred to ${dest}; ensure destination policy is fair to arbiters`,
+            affected_stakeholders: ["arbiter", "owner"],
+            scenario: "Distributing arbitration fees without verifying allocation rules",
+            mitigation: `Verify ${dest} has fair distribution policy; consider allocating to arbiters' Allocation`,
+            evidence: `dest=${dest}, remark=${ctx.fees_transfer.payment_remark}`,
+        };
+    },
+};
+const R_AB_5_02 = {
+    id: "R-AB-5-02",
+    category: "cross_object",
+    trigger: "Dispute filed but Order op permission not verified — E_OP_PERMISSION",
+    check: (ctx) => {
+        if (!ctx.dispute)
+            return null;
+        return {
+            id: "R-AB-5-02",
+            level: "HIGH",
+            category: "cross_object",
+            title: "Order op permission required for dispute",
+            description: `dispute on Order ${ctx.dispute.order} requires order::assert_op_permission; signer must have Order's dispute permission`,
+            affected_stakeholders: ["disputant"],
+            scenario: "Filing dispute without Order op permission",
+            mitigation: "Ensure signer has Order's dispute operation permission (custom index or builtin)",
+            evidence: `order=${ctx.dispute.order}`,
+        };
+    },
+};
+const ALL_RULES = [
+    R_AB_1_01, R_AB_1_02, R_AB_1_03, R_AB_1_04,
+    R_AB_2_01, R_AB_2_02, R_AB_2_03,
+    R_AB_3_01, R_AB_3_02, R_AB_3_03,
+    R_AB_4_01, R_AB_4_02, R_AB_4_03,
+    R_AB_5_01, R_AB_5_02,
+];
+export const ARBITRATION_RISK_VERSION = "1.0.0";
+export function getAllRiskRules() {
+    return [...ALL_RULES];
+}
+export function getRiskRulesCount() {
+    return ALL_RULES.length;
+}
+export function getRiskRulesByCategory(category) {
+    return ALL_RULES.filter(r => r.category === category);
+}
+export function assessArbitrationRisks(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"),
+    };
+}

package/dist/knowledge/arbitration-templates.d.ts

@@ -0,0 +1,38 @@
+export type TemplateParamType = "address" | "string" | "number" | "string[]" | "object";
+export interface ArbitrationTemplateParam {
+    name: string;
+    type: TemplateParamType;
+    description: string;
+    required: boolean;
+    default?: string | number | string[] | object;
+}
+export interface ArbitrationTemplate {
+    id: string;
+    name: string;
+    description: string;
+    applicable_scenes: string[];
+    industry_tags: string[];
+    params: ArbitrationTemplateParam[];
+    body: (params: Record<string, string | number | string[] | object>) => object;
+    notes?: string[];
+}
+export declare const ARBITRATION_TEMPLATES: ArbitrationTemplate[];
+export declare const ARBITRATION_TEMPLATES_VERSION = "1.0.0";
+export declare function getAllTemplates(): ArbitrationTemplate[];
+export declare function getTemplateById(id: string): ArbitrationTemplate | undefined;
+export declare function getTemplatesByScene(sceneId: string): ArbitrationTemplate[];
+export declare function getTemplatesByIndustry(industry: string): ArbitrationTemplate[];
+export declare function suggestTemplateForScene(sceneId: string): ArbitrationTemplate | undefined;
+export declare function listTemplates(): {
+    id: string;
+    name: string;
+    description: string;
+    scenes: string[];
+}[];
+export declare function fillTemplate(templateId: string, params: Record<string, string | number | string[] | object>): {
+    ok: true;
+    body: object;
+} | {
+    ok: false;
+    error: string;
+};