@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/arbitration-puzzle.js

@@ -0,0 +1,304 @@
+import { MAX_VOTING_GUARD_COUNT, } from "@wowok/wowok";
+import { getDualGuardMatrixEntry, isValidArbStatusTransition, } from "./arbitration-ledger.js";
+export function initPuzzleFromIntent(intent) {
+    const puzzle = {};
+    if (intent.action || intent.rule_sentence) {
+        puzzle.intent = {
+            action: intent.action ?? "create_arbitration",
+            target_arb: intent.target_arb,
+            target_order: intent.target_order,
+            rule_sentence: intent.rule_sentence ?? "",
+            failure_conditions: intent.failure_conditions ?? [],
+        };
+    }
+    puzzle.constraints = {
+        F_AB_01_coin_type_valid: true,
+        F_AB_02_permission_address_valid: true,
+        F_AB_03_bPaused_default_true: true,
+        F_AB_04_fee_u64_nonneg: true,
+        F_AB_05_voting_guard_count_le_50: true,
+        F_AB_06_voting_guard_no_duplicate: true,
+        F_AB_07_usage_guard_single: true,
+        F_AB_08_arb_status_transition_valid: true,
+        F_AB_09_arb_belongs_to_arbitration: true,
+        F_AB_10_order_op_permission: true,
+        F_AB_11_dispute_fee_sufficient: true,
+        F_AB_12_dual_guard_coherent: true,
+    };
+    puzzle.voting_guard = {
+        guards: [],
+        weight_mode: "none",
+    };
+    puzzle.usage_guard = {
+        guard: null,
+        passport_required: false,
+        filter_rules: [],
+    };
+    return puzzle;
+}
+export function checkPuzzleCompleteness(puzzle) {
+    const missing = [];
+    const missing_details = [];
+    if (!puzzle.intent) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "Intent not specified (action + rule_sentence)" });
+    }
+    else if (!puzzle.intent.rule_sentence) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "rule_sentence is empty" });
+    }
+    else {
+        const action = puzzle.intent.action;
+        if ((action === "file_dispute" || action === "vote" || action === "confirm_materials" ||
+            action === "provide_feedback" || action === "make_ruling" || action === "reset_arbitration" ||
+            action === "withdraw_fees") && !puzzle.intent.target_arb && !puzzle.intent.target_order) {
+            missing.push("A");
+            missing_details.push({ dimension: "A", reason: `${action} requires target_arb or target_order` });
+        }
+        if (action === "file_dispute" && !puzzle.intent.target_order) {
+            missing.push("A");
+            missing_details.push({ dimension: "A", reason: "file_dispute requires target_order" });
+        }
+    }
+    if (!puzzle.arbitration_config) {
+        const needsConfig = puzzle.intent?.action === "create_arbitration" ||
+            puzzle.intent?.action === "configure";
+        if (needsConfig) {
+            missing.push("B");
+            missing_details.push({ dimension: "B", reason: "Arbitration config not specified" });
+        }
+    }
+    else if (puzzle.intent?.action === "create_arbitration") {
+        if (!puzzle.arbitration_config.coin_type) {
+            missing.push("B");
+            missing_details.push({ dimension: "B", reason: "coin_type (generic T) required for create_arbitration" });
+        }
+        if (!puzzle.arbitration_config.permission_address) {
+            missing.push("B");
+            missing_details.push({ dimension: "B", reason: "permission_address required for create_arbitration" });
+        }
+    }
+    if (!puzzle.voting_guard) {
+        if (puzzle.intent?.action === "configure_voting_guard" || puzzle.intent?.action === "vote") {
+            missing.push("C");
+            missing_details.push({ dimension: "C", reason: "voting_guard config not specified" });
+        }
+    }
+    else if (puzzle.intent?.action === "vote" && puzzle.voting_guard.guards.length > 0) {
+        if (puzzle.voting_guard.weight_mode === "none") {
+            missing.push("C");
+            missing_details.push({ dimension: "C", reason: "weight_mode must be set when guards non-empty" });
+        }
+    }
+    if (!puzzle.usage_guard) {
+        if (puzzle.intent?.action === "configure_usage_guard" || puzzle.intent?.action === "file_dispute") {
+            missing.push("D");
+            missing_details.push({ dimension: "D", reason: "usage_guard config not specified" });
+        }
+    }
+    if (!puzzle.arbiter_config) {
+        if (puzzle.intent?.action === "vote" || puzzle.intent?.action === "make_ruling") {
+            missing.push("E");
+            missing_details.push({ dimension: "E", reason: "Arbiter config not specified" });
+        }
+    }
+    else if (puzzle.intent?.action === "vote" && puzzle.arbiter_config.arbitrators.length === 0) {
+        missing.push("E");
+        missing_details.push({ dimension: "E", reason: "At least one arbitrator required for voting" });
+    }
+    if (!puzzle.constraints) {
+        missing.push("F");
+        missing_details.push({ dimension: "F", reason: "Constraints not checked" });
+    }
+    else {
+        const arbActions = ["confirm_materials", "vote", "provide_feedback", "make_ruling", "reset_arbitration", "withdraw_fees"];
+        if (puzzle.intent && arbActions.includes(puzzle.intent.action)) {
+            if (!puzzle.current_arb_status) {
+                missing.push("F");
+                missing_details.push({ dimension: "F", reason: "current_arb_status required for Arb operations" });
+            }
+            if (!puzzle.expected_arb_status && puzzle.intent.action !== "provide_feedback") {
+                missing.push("F");
+                missing_details.push({ dimension: "F", reason: "expected_arb_status required (non-feedback Arb ops)" });
+            }
+        }
+    }
+    return {
+        dimensions: ["A", "B", "C", "D", "E", "F"],
+        missing,
+        missing_details,
+        complete: missing.length === 0,
+        next_step: missing.length === 0
+            ? "Puzzle complete — ready for confirmation text generation"
+            : `Next: complete dimension ${missing[0]} — ${missing_details[0].reason}`,
+    };
+}
+export function validateConstraints(puzzle) {
+    const violations = [];
+    if (puzzle.voting_guard && puzzle.voting_guard.guards.length > MAX_VOTING_GUARD_COUNT) {
+        violations.push({
+            constraint_id: "F-AB-05",
+            severity: "HIGH",
+            message: `voting_guard count ${puzzle.voting_guard.guards.length} exceeds MAX_VOTING_GUARD_COUNT ${MAX_VOTING_GUARD_COUNT}`,
+            current_value: puzzle.voting_guard.guards.length,
+            limit: MAX_VOTING_GUARD_COUNT,
+        });
+    }
+    if (puzzle.voting_guard && puzzle.voting_guard.guards.length > 0) {
+        const addrs = puzzle.voting_guard.guards.map(g => g.guard);
+        const dupes = addrs.filter((a, i) => addrs.indexOf(a) !== i);
+        if (dupes.length > 0) {
+            violations.push({
+                constraint_id: "F-AB-06",
+                severity: "MEDIUM",
+                message: `Duplicate voting_guard addresses: ${dupes.join(", ")}`,
+                current_value: dupes.join(","),
+            });
+        }
+    }
+    if (puzzle.current_arb_status && puzzle.expected_arb_status) {
+        if (puzzle.current_arb_status !== puzzle.expected_arb_status &&
+            !isValidArbStatusTransition(puzzle.current_arb_status, puzzle.expected_arb_status)) {
+            violations.push({
+                constraint_id: "F-AB-08",
+                severity: "CRITICAL",
+                message: `Invalid Arb status transition: ${puzzle.current_arb_status} → ${puzzle.expected_arb_status}`,
+                current_value: `${puzzle.current_arb_status} → ${puzzle.expected_arb_status}`,
+            });
+        }
+    }
+    if (puzzle.intent?.action === "file_dispute" && puzzle.arbitration_config?.fee) {
+        if (puzzle.arbitration_config.fee === "0") {
+            violations.push({
+                constraint_id: "F-AB-11",
+                severity: "HIGH",
+                message: "Dispute fee is 0 — likely below arbitration.fee threshold",
+                current_value: "0",
+            });
+        }
+    }
+    if (puzzle.voting_guard && puzzle.usage_guard) {
+        const matrix = getDualGuardMatrixEntry(puzzle.voting_guard.guards.length === 0, puzzle.usage_guard.guard === null);
+        if (puzzle.intent?.action === "file_dispute") {
+            if (puzzle.usage_guard.guard !== null && !puzzle.usage_guard.passport_required) {
+                violations.push({
+                    constraint_id: "F-AB-12",
+                    severity: "HIGH",
+                    message: "usage_guard is Some but passport_required=false — dispute will fail with E_NEED_PASSPORT",
+                });
+            }
+        }
+        if (puzzle.intent?.action === "vote") {
+            if (puzzle.voting_guard.guards.length > 0 && !puzzle.intent.target_arb) {
+                violations.push({
+                    constraint_id: "F-AB-12",
+                    severity: "HIGH",
+                    message: "voting_guard is non-empty but vote target_arb missing — must use vote_with_voting_guard",
+                });
+            }
+        }
+    }
+    if (puzzle.intent?.action === "file_dispute") {
+    }
+    return violations;
+}
+export function generateConfirmationText(puzzle) {
+    const lines = [];
+    lines.push("═══ Arbitration Confirmation ═══");
+    lines.push("");
+    if (puzzle.intent) {
+        lines.push(`Action: ${puzzle.intent.action}`);
+        if (puzzle.intent.target_arb)
+            lines.push(`Target Arb: ${puzzle.intent.target_arb}`);
+        if (puzzle.intent.target_order)
+            lines.push(`Target Order: ${puzzle.intent.target_order}`);
+        lines.push(`Rule: ${puzzle.intent.rule_sentence}`);
+        if (puzzle.intent.failure_conditions.length > 0) {
+            lines.push("Failure conditions:");
+            for (const fc of puzzle.intent.failure_conditions)
+                lines.push(`  - ${fc}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.arbitration_config) {
+        lines.push("─ Arbitration Config ──────────────");
+        const c = puzzle.arbitration_config;
+        if (c.description)
+            lines.push(`Description: ${c.description}`);
+        if (c.location)
+            lines.push(`Location: ${c.location}`);
+        if (c.fee !== undefined)
+            lines.push(`Fee: ${c.fee}`);
+        if (c.bPaused !== undefined)
+            lines.push(`bPaused: ${c.bPaused} (default true on creation)`);
+        if (c.coin_type)
+            lines.push(`Coin type (T): ${c.coin_type}`);
+        if (c.permission_address)
+            lines.push(`Permission: ${c.permission_address}`);
+        if (c.um !== undefined)
+            lines.push(`UM: ${c.um ?? "(none)"}`);
+        lines.push("");
+    }
+    if (puzzle.voting_guard && puzzle.voting_guard.guards.length > 0) {
+        lines.push("─ voting_guard Config ──────────────");
+        lines.push(`Count: ${puzzle.voting_guard.guards.length} / ${MAX_VOTING_GUARD_COUNT}`);
+        lines.push(`Weight mode: ${puzzle.voting_guard.weight_mode}`);
+        for (const g of puzzle.voting_guard.guards) {
+            const w = "GuardIdentifier" in g.vote_weight
+                ? `GuardIdentifier(${g.vote_weight.GuardIdentifier})`
+                : `FixedValue(${g.vote_weight.FixedValue})`;
+            lines.push(`  ${g.guard}: ${w}`);
+        }
+        if (puzzle.voting_guard.cooperation_matrix) {
+            lines.push(`Cooperation: ${puzzle.voting_guard.cooperation_matrix.scenario}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.usage_guard && puzzle.usage_guard.guard !== null) {
+        lines.push("─ usage_guard Config ──────────────");
+        lines.push(`Guard: ${puzzle.usage_guard.guard}`);
+        lines.push(`Passport required: ${puzzle.usage_guard.passport_required}`);
+        if (puzzle.usage_guard.filter_rules.length > 0) {
+            lines.push("Filter rules:");
+            for (const r of puzzle.usage_guard.filter_rules)
+                lines.push(`  - ${r}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.arbiter_config && puzzle.arbiter_config.arbitrators.length > 0) {
+        lines.push("─ Arbiter Config ──────────────");
+        lines.push(`Arbitrators (${puzzle.arbiter_config.arbitrators.length}): ${puzzle.arbiter_config.arbitrators.join(", ")}`);
+        lines.push(`Vote distribution: ${puzzle.arbiter_config.vote_distribution}`);
+        lines.push(`Ruling authority: ${puzzle.arbiter_config.ruling_authority}`);
+        if (puzzle.arbiter_config.fees_split) {
+            lines.push("Fees split:");
+            const fs = puzzle.arbiter_config.fees_split;
+            if (fs.allocation)
+                lines.push(`  → Allocation: ${fs.allocation}`);
+            if (fs.treasury)
+                lines.push(`  → Treasury: ${fs.treasury}`);
+            if (fs.remark)
+                lines.push(`  Remark: ${fs.remark}`);
+            if (fs.payment_index !== undefined)
+                lines.push(`  Payment index: ${fs.payment_index}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.current_arb_status || puzzle.expected_arb_status) {
+        lines.push("─ 7-State Flow ──────────────");
+        if (puzzle.current_arb_status)
+            lines.push(`Current: ${puzzle.current_arb_status}`);
+        if (puzzle.expected_arb_status)
+            lines.push(`Expected after: ${puzzle.expected_arb_status}`);
+        lines.push("");
+    }
+    const violations = validateConstraints(puzzle);
+    if (violations.length > 0) {
+        lines.push("─ Constraint Violations ──────────────");
+        for (const v of violations) {
+            lines.push(`  [${v.severity}] ${v.constraint_id}: ${v.message}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,112 @@
+import { type ArbStatus } from "./arbitration-ledger.js";
+export type RiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+export type RiskCategory = "structural" | "semantic" | "authority" | "lifecycle" | "cross_object";
+export interface ArbitrationRisk {
+    id: string;
+    level: RiskLevel;
+    category: RiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: ArbitrationStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+}
+export type ArbitrationStakeholder = "owner" | "arbiter" | "voter" | "disputant" | "system";
+export interface RiskRule {
+    id: string;
+    category: RiskCategory;
+    trigger: string;
+    check: (ctx: RiskCheckContext) => ArbitrationRisk | null;
+}
+export interface RiskCheckContext {
+    object?: string | null;
+    description?: string;
+    location?: string;
+    fee?: string | number;
+    pause?: boolean;
+    dispute?: {
+        order: string;
+        description: string;
+        proposition: string[];
+        fee: {
+            type?: string;
+            balance?: string | number;
+        } | unknown;
+    };
+    confirm?: {
+        arb: string;
+        voting_deadline: number | null;
+    };
+    voting_deadline_change?: {
+        arb: string;
+        voting_deadline: number | null;
+    };
+    vote?: {
+        arb: string;
+        votes: number[];
+        voting_guard?: string;
+    };
+    feedback?: {
+        arb: string;
+        feedback: string;
+    };
+    arbitration?: {
+        arb: string;
+        feedback: string;
+        indemnity: number;
+    };
+    reset?: {
+        arb: string;
+        feedback: string;
+    };
+    arb_withdraw?: {
+        arb: string;
+    };
+    fees_transfer?: {
+        to: {
+            allocation: string;
+        } | {
+            treasury: string;
+        };
+        payment_remark: string;
+        payment_index: number;
+    };
+    usage_guard?: string | null;
+    voting_guard?: {
+        op: "add" | "set";
+        guards: {
+            guard: string;
+            vote_weight: unknown;
+        }[];
+    } | {
+        op: "remove";
+        guards: string[];
+    } | {
+        op: "clear";
+    };
+    um?: string | null;
+    builder?: string;
+    current_arb_status?: ArbStatus;
+    expected_arb_status?: ArbStatus;
+    current_voting_guard_count?: number;
+    current_voting_guard_addresses?: string[];
+    current_arbitration_fee?: string | number;
+    current_bPaused?: boolean;
+    current_voting_deadline?: number | null;
+    current_timestamp_ms?: number;
+    target_objects_types?: string[];
+}
+export declare const ARBITRATION_RISK_VERSION = "1.0.0";
+export declare function getAllRiskRules(): RiskRule[];
+export declare function getRiskRulesCount(): number;
+export declare function getRiskRulesByCategory(category: RiskCategory): RiskRule[];
+export interface ArbitrationRiskAssessment {
+    summary: string;
+    risks: ArbitrationRisk[];
+    overall_risk: RiskLevel;
+    risks_by_category: Partial<Record<RiskCategory, number>>;
+    stakeholder_advice: Partial<Record<ArbitrationStakeholder, string[]>>;
+    needs_human_review: boolean;
+}
+export declare function assessArbitrationRisks(ctx: RiskCheckContext): ArbitrationRiskAssessment;