@wowok/agent-mcp 2.4.3 → 2.5.0

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

@@ -0,0 +1,37 @@
+export type ArbRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type ArbRiskCategory = "structural" | "lifecycle" | "semantic" | "permission" | "knowledge";
+export type ArbStakeholder = "principal" | "arbitrator" | "voter" | "system";
+export interface ArbRisk {
+    id: string;
+    level: ArbRiskLevel;
+    category: ArbRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: ArbStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    auto_fixable: boolean;
+}
+export interface ArbRiskCheckContext {
+    status?: number;
+    invalid_transition?: boolean;
+    withdraw_too_early?: boolean;
+    proposition_count?: number;
+    votor_count?: number;
+    voting_deadline_none?: boolean;
+    expects_proposition_event?: boolean;
+    indemnity_none?: boolean;
+    weight_concentrated?: boolean;
+    expects_status_enum?: boolean;
+    order_mismatch?: boolean;
+    constants_synced?: boolean;
+}
+export declare const ARB_RISK_RULES: {
+    rule: ArbRisk;
+    check: (ctx: ArbRiskCheckContext) => ArbRisk | null;
+}[];
+export declare const ARB_RISK_VERSION = "1.0.0";
+export declare function checkArbRisks(ctx: ArbRiskCheckContext): ArbRisk[];
+export declare function getArbRiskById(id: string): ArbRisk | undefined;

package/dist/knowledge/arb-risk.js

@@ -0,0 +1,210 @@
+import { MAX_VOTOR_COUNT, WITHDRAW_DURATION_TIME, } from "@wowok/wowok";
+const R_A_01 = {
+    rule: {
+        id: "R-ARB-01",
+        level: "HIGH",
+        category: "lifecycle",
+        title: "7-state machine — invalid transitions can deadlock the arbitration",
+        description: "Arb has a 7-state machine: Principal_confirming(0) → Arbitrator_confirming(1) → " +
+            "Voting(2) → Arbitrated(3) → Objectionable(4) → Finished(5) → Withdrawn(6). reset() " +
+            "can revert from {1, 4} back to 0. Each op asserts the current status; calling an op " +
+            "out of order aborts with E_STATUS_NOT_MATCH (3). Repeated mis-calls leave the Arb " +
+            "stuck in a non-terminal state with no automatic recovery.",
+        affected_stakeholders: ["principal", "arbitrator", "voter"],
+        scenario: "Caller calls vote() when status is still Arbitrator_confirming; abort blocks progress",
+        mitigation: "Strictly validate the current status before submitting any Arb op. The SDK should " +
+            "expose a status-aware state machine helper. Provide a recovery path (reset) for " +
+            "Arbitrator_confirming and Objectionable states.",
+        related_move_error: "E_STATUS_NOT_MATCH (3)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.invalid_transition)
+            return null;
+        return { ...R_A_01.rule, evidence: `invalid_transition=true (status=${ctx.status ?? "?"})` };
+    },
+};
+const R_A_02 = {
+    rule: {
+        id: "R-ARB-02",
+        level: "MEDIUM",
+        category: "lifecycle",
+        title: `WITHDRAW_DURATION_TIME=${WITHDRAW_DURATION_TIME}ms (30 days) — funds locked`,
+        description: `After arbitration, the fee Balance can only be withdrawn after ` +
+            `WITHDRAW_DURATION_TIME=${WITHDRAW_DURATION_TIME}ms (30 days) when status is ` +
+            `Arbitrated(3) or Objectionable(4). From Finished(5), withdraw is immediate. ` +
+            `The 30-day lock is a dispute-window safeguard, but it locks funds for a long time ` +
+            `and users may not understand why.`,
+        affected_stakeholders: ["principal", "arbitrator"],
+        scenario: "Arbitrator finishes a case but must wait 30 days to claim the fee",
+        mitigation: "Surface the unlock timestamp in the UI. To shorten the lock, drive the case to " +
+            "Finished(5) via finish() rather than leaving it in Arbitrated/Objectionable.",
+        related_move_error: "E_WITHDRAW_DURATION_TIME_NOT_PASSED (8)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.withdraw_too_early)
+            return null;
+        return { ...R_A_02.rule, evidence: `withdraw_too_early=true (limit=${WITHDRAW_DURATION_TIME}ms)` };
+    },
+};
+const R_A_03 = {
+    rule: {
+        id: "R-ARB-03",
+        level: "MEDIUM",
+        category: "structural",
+        title: `MAX_VOTOR_COUNT=${MAX_VOTOR_COUNT} permissive — voting efficiency cost`,
+        description: `A single Arb may record up to MAX_VOTOR_COUNT=${MAX_VOTOR_COUNT} voters (arb.move:236). ` +
+            `The limit aborts with E_MAX_VOTOR_COUNT (6) only at the boundary. 520 voters in one ` +
+            `Arb inflates the voted vector, slowing tally and gas, and complicates weighted-quorum ` +
+            `reasoning.`,
+        affected_stakeholders: ["voter", "arbitrator"],
+        scenario: "Arbitration allows 520 voters; tallying the vote vector is slow and gas-heavy",
+        mitigation: "Business layer should self-limit voter count based on the Arbitration rule's quorum. " +
+            "For large juries, shard across multiple Arb instances or aggregate off-chain.",
+        related_move_error: "E_MAX_VOTOR_COUNT (6)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.votor_count === undefined)
+            return null;
+        if (ctx.votor_count < MAX_VOTOR_COUNT)
+            return null;
+        return { ...R_A_03.rule, evidence: `votor_count=${ctx.votor_count}, limit=${MAX_VOTOR_COUNT}` };
+    },
+};
+const R_A_04 = {
+    rule: {
+        id: "R-ARB-04",
+        level: "LOW",
+        category: "semantic",
+        title: "proposition_change may not emit a discrete event — indexers must infer",
+        description: "proposition_change (arb.move) updates the proposition vector in place. Unlike " +
+            "state transitions (which emit ArbEvent), proposition edits may not produce a " +
+            "discrete event — indexers must infer changes by diffing the proposition vector " +
+            "across polls.",
+        affected_stakeholders: ["arbitrator", "voter"],
+        scenario: "Indexer expects a PropositionChangedEvent; none is emitted, UI fails to refresh",
+        mitigation: "External indexers should poll the proposition vector. UI should display 'propositions " +
+            "may have changed' on each poll rather than relying on event-driven refresh.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.expects_proposition_event)
+            return null;
+        return { ...R_A_04.rule, evidence: "expects_proposition_event=true (poll instead)" };
+    },
+};
+const R_A_05 = {
+    rule: {
+        id: "R-ARB-05",
+        level: "MEDIUM",
+        category: "semantic",
+        title: "voting_deadline is Option<u64> — None means open-ended vote",
+        description: "voting_deadline is Option<u64>. When None, voting has no deadline (open-ended) and " +
+            "E_VOTING_DEADLINE_PASSED (7) never triggers. When Some(t), vote() aborts if " +
+            "clock.timestamp_ms() > t. Callers who assume a default deadline may be surprised by " +
+            "an open-ended vote that never finalizes.",
+        affected_stakeholders: ["voter", "arbitrator"],
+        scenario: "Voter assumes a deadline; voting_deadline is None and the case stalls indefinitely",
+        mitigation: "Document that None means open-ended. Arbitrators should set an explicit deadline via " +
+            "arbitrator_confirm unless they intend an open vote. SDK should surface voting_deadline " +
+            "prominently.",
+        related_move_error: "E_VOTING_DEADLINE_PASSED (7) / E_VOTING_DEADLINE_NOT_PASSED (4)",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.voting_deadline_none)
+            return null;
+        return { ...R_A_05.rule, evidence: "voting_deadline_none=true (open-ended vote)" };
+    },
+};
+const R_A_06 = {
+    rule: {
+        id: "R-ARB-06",
+        level: "LOW",
+        category: "semantic",
+        title: "indemnity is Option<Indemnity> — None means no compensation",
+        description: "indemnity is Option<Indemnity>. When None, the arbitration produces no compensation " +
+            "(e.g. a pure declaratory ruling). Consumers who assume a non-null indemnity will " +
+            "mis-handle None cases. finish() returns the indemnity amount (0 when None).",
+        affected_stakeholders: ["principal"],
+        scenario: "Principal expects compensation; indemnity is None and finish() returns 0",
+        mitigation: "Document that None means no compensation. UI should show 'no compensation awarded' " +
+            "rather than 'compensation pending'.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.indemnity_none)
+            return null;
+        return { ...R_A_06.rule, evidence: "indemnity_none=true (no compensation)" };
+    },
+};
+const R_A_07 = {
+    rule: {
+        id: "R-ARB-07",
+        level: "MEDIUM",
+        category: "permission",
+        title: "Voted.weight is set by the Arbitration rule — concentrated weight risk",
+        description: "Voted.weight (u32) is assigned by the Arbitration object's voting_guard logic, not " +
+            "by the voter. If the Arbitration rule concentrates weight in one voter (e.g. an " +
+            "admin with weight 1000 vs. others with weight 1), a single voter can dictate the " +
+            "outcome. The Arb contract itself does not detect concentration — that is the " +
+            "Arbitration designer's responsibility.",
+        affected_stakeholders: ["voter", "arbitrator"],
+        scenario: "Arbitration rule gives one voter weight 1000; that voter single-handedly decides the case",
+        mitigation: "When designing the Arbitration rule, cap individual voter weight and require a " +
+            "quorum. Audit the voting_guard to ensure no single voter can exceed the quorum alone.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.weight_concentrated)
+            return null;
+        return { ...R_A_07.rule, evidence: "weight_concentrated=true (rule-level risk)" };
+    },
+};
+const R_A_08 = {
+    rule: {
+        id: "R-ARB-08",
+        level: "LOW",
+        category: "semantic",
+        title: "Status uses u8 constants — Move enum is commented out",
+        description: "The 7 statuses are defined as u8 constants (Status_Principal_confirming=0, etc.). " +
+            "The Move enum definition is commented out (arb.move). Consumers cannot rely on a " +
+            "type-safe enum and must compare against magic numbers. A future Wow release enabling " +
+            "the enum would be a breaking change to downstream code.",
+        affected_stakeholders: ["system"],
+        scenario: "Developer expects a Status enum; only u8 constants are available, causing type errors",
+        mitigation: "SDK should expose a TypeScript enum mirroring the u8 constants. Document that the " +
+            "Move enum is intentionally disabled and may be enabled in a future version.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.expects_status_enum)
+            return null;
+        return { ...R_A_08.rule, evidence: "expects_status_enum=true (only u8 constants exist)" };
+    },
+};
+export const ARB_RISK_RULES = [
+    R_A_01,
+    R_A_02,
+    R_A_03,
+    R_A_04,
+    R_A_05,
+    R_A_06,
+    R_A_07,
+    R_A_08,
+];
+export const ARB_RISK_VERSION = "1.0.0";
+export function checkArbRisks(ctx) {
+    const risks = [];
+    for (const rule of ARB_RISK_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    return risks;
+}
+export function getArbRiskById(id) {
+    return ARB_RISK_RULES.find(r => r.rule.id === id)?.rule;
+}

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

@@ -0,0 +1,135 @@
+import { type ArbStatus } from "./arbitration-ledger.js";
+import { type ArbitrationRiskAssessment } from "./arbitration-risk.js";
+export type ConfirmGateStatus = "approved" | "blocked_checklist" | "blocked_risk" | "blocked_user" | "blocked_environment";
+export interface ConfirmGateResult {
+    status: ConfirmGateStatus;
+    checklist_result: ChecklistResult;
+    risk_result?: ArbitrationRiskAssessment;
+    user_confirmation?: UserConfirmation;
+    environment_result?: EnvironmentResult;
+    confirmation_text?: string;
+    block_reason?: string;
+    decision_record: DecisionRecord;
+}
+export interface ChecklistResult {
+    all_passed: boolean;
+    items: ChecklistItem[];
+}
+export interface ChecklistItem {
+    id: string;
+    description: string;
+    passed: boolean;
+    message: string;
+}
+export interface UserConfirmation {
+    questions_asked: ConfirmationQuestion[];
+    responses: ConfirmationResponse[];
+    all_confirmed: boolean;
+}
+export interface ConfirmationQuestion {
+    id: string;
+    question: string;
+    requires_explicit_yes: boolean;
+    related_risk_ids?: string[];
+}
+export interface ConfirmationResponse {
+    question_id: string;
+    response: "yes" | "no" | "skip";
+}
+export interface EnvironmentResult {
+    passed: boolean;
+    checks: {
+        name: string;
+        passed: boolean;
+        message: string;
+    }[];
+}
+export interface DecisionRecord {
+    timestamp: string;
+    gate_version: string;
+    final_status: ConfirmGateStatus;
+    layers_passed: string[];
+    layers_failed: string[];
+}
+export interface ArbitrationJsonForConfirm {
+    object?: string | null | object;
+    description?: string;
+    location?: string;
+    fee?: string | number;
+    pause?: boolean;
+    dispute?: {
+        order: string;
+        description?: string;
+        proposition: string[];
+        fee?: 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: string;
+        guards?: unknown[];
+    };
+    um?: string | null;
+    builder?: string;
+}
+export interface ConfirmGateInput {
+    arbitration_json: ArbitrationJsonForConfirm;
+    intent?: 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_timestamp_ms?: number;
+    target_objects_types?: string[];
+    skip_user_confirmation?: boolean;
+    skip_environment_check?: boolean;
+}
+export declare const ARBITRATION_OPERATION_CHECKLIST: ChecklistItem[];
+export declare const ARBITRATION_CONFIRMATION_QUESTIONS: ConfirmationQuestion[];
+export declare const ARBITRATION_CONFIRM_VERSION = "1.0.0";
+export declare function runArbitrationConfirmGate(input: ConfirmGateInput): ConfirmGateResult;
+export interface ProgressiveCheckResult {
+    stage: "checklist" | "risk" | "confirmation" | "environment" | "complete";
+    status: "pass" | "fail" | "pending";
+    message: string;
+    next_action?: string;
+}
+export declare function progressiveArbitrationCheck(input: ConfirmGateInput): ProgressiveCheckResult;