@wowok/agent-mcp 2.7.1 → 2.7.2

package/dist/knowledge/arb-risk.js

@@ -1,210 +1 @@
-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;
-}
+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\x20machine\x20—\x20invalid\x20transitions\x20can\x20deadlock\x20the\x20arbitration','description':'Arb\x20has\x20a\x207-state\x20machine:\x20Principal_confirming(0)\x20→\x20Arbitrator_confirming(1)\x20→\x20'+'Voting(2)\x20→\x20Arbitrated(3)\x20→\x20Objectionable(4)\x20→\x20Finished(5)\x20→\x20Withdrawn(6).\x20reset()\x20'+'can\x20revert\x20from\x20{1,\x204}\x20back\x20to\x200.\x20Each\x20op\x20asserts\x20the\x20current\x20status;\x20calling\x20an\x20op\x20'+'out\x20of\x20order\x20aborts\x20with\x20E_STATUS_NOT_MATCH\x20(3).\x20Repeated\x20mis-calls\x20leave\x20the\x20Arb\x20'+'stuck\x20in\x20a\x20non-terminal\x20state\x20with\x20no\x20automatic\x20recovery.','affected_stakeholders':['principal','arbitrator','voter'],'scenario':'Caller\x20calls\x20vote()\x20when\x20status\x20is\x20still\x20Arbitrator_confirming;\x20abort\x20blocks\x20progress','mitigation':'Strictly\x20validate\x20the\x20current\x20status\x20before\x20submitting\x20any\x20Arb\x20op.\x20The\x20SDK\x20should\x20'+'expose\x20a\x20status-aware\x20state\x20machine\x20helper.\x20Provide\x20a\x20recovery\x20path\x20(reset)\x20for\x20'+'Arbitrator_confirming\x20and\x20Objectionable\x20states.','related_move_error':'E_STATUS_NOT_MATCH\x20(3)','auto_fixable':![]},'check':a=>{if(!a['invalid_transition'])return null;return{...R_A_01['rule'],'evidence':'invalid_transition=true\x20(status='+(a['status']??'?')+')'};}},R_A_02={'rule':{'id':'R-ARB-02','level':'MEDIUM','category':'lifecycle','title':'WITHDRAW_DURATION_TIME='+WITHDRAW_DURATION_TIME+'ms\x20(30\x20days)\x20—\x20funds\x20locked','description':'After\x20arbitration,\x20the\x20fee\x20Balance\x20can\x20only\x20be\x20withdrawn\x20after\x20'+('WITHDRAW_DURATION_TIME='+WITHDRAW_DURATION_TIME+'ms\x20(30\x20days)\x20when\x20status\x20is\x20')+'Arbitrated(3)\x20or\x20Objectionable(4).\x20From\x20Finished(5),\x20withdraw\x20is\x20immediate.\x20'+'The\x2030-day\x20lock\x20is\x20a\x20dispute-window\x20safeguard,\x20but\x20it\x20locks\x20funds\x20for\x20a\x20long\x20time\x20'+'and\x20users\x20may\x20not\x20understand\x20why.','affected_stakeholders':['principal','arbitrator'],'scenario':'Arbitrator\x20finishes\x20a\x20case\x20but\x20must\x20wait\x2030\x20days\x20to\x20claim\x20the\x20fee','mitigation':'Surface\x20the\x20unlock\x20timestamp\x20in\x20the\x20UI.\x20To\x20shorten\x20the\x20lock,\x20drive\x20the\x20case\x20to\x20'+'Finished(5)\x20via\x20finish()\x20rather\x20than\x20leaving\x20it\x20in\x20Arbitrated/Objectionable.','related_move_error':'E_WITHDRAW_DURATION_TIME_NOT_PASSED\x20(8)','auto_fixable':![]},'check':a=>{if(!a['withdraw_too_early'])return null;return{...R_A_02['rule'],'evidence':'withdraw_too_early=true\x20(limit='+WITHDRAW_DURATION_TIME+'ms)'};}},R_A_03={'rule':{'id':'R-ARB-03','level':'MEDIUM','category':'structural','title':'MAX_VOTOR_COUNT='+MAX_VOTOR_COUNT+'\x20permissive\x20—\x20voting\x20efficiency\x20cost','description':'A\x20single\x20Arb\x20may\x20record\x20up\x20to\x20MAX_VOTOR_COUNT='+MAX_VOTOR_COUNT+'\x20voters\x20(arb.move:236).\x20'+'The\x20limit\x20aborts\x20with\x20E_MAX_VOTOR_COUNT\x20(6)\x20only\x20at\x20the\x20boundary.\x20520\x20voters\x20in\x20one\x20'+'Arb\x20inflates\x20the\x20voted\x20vector,\x20slowing\x20tally\x20and\x20gas,\x20and\x20complicates\x20weighted-quorum\x20'+'reasoning.','affected_stakeholders':['voter','arbitrator'],'scenario':'Arbitration\x20allows\x20520\x20voters;\x20tallying\x20the\x20vote\x20vector\x20is\x20slow\x20and\x20gas-heavy','mitigation':'Business\x20layer\x20should\x20self-limit\x20voter\x20count\x20based\x20on\x20the\x20Arbitration\x20rule\x27s\x20quorum.\x20'+'For\x20large\x20juries,\x20shard\x20across\x20multiple\x20Arb\x20instances\x20or\x20aggregate\x20off-chain.','related_move_error':'E_MAX_VOTOR_COUNT\x20(6)','auto_fixable':![]},'check':a=>{if(a['votor_count']===undefined)return null;if(a['votor_count']<MAX_VOTOR_COUNT)return null;return{...R_A_03['rule'],'evidence':'votor_count='+a['votor_count']+',\x20limit='+MAX_VOTOR_COUNT};}},R_A_04={'rule':{'id':'R-ARB-04','level':'LOW','category':'semantic','title':'proposition_change\x20may\x20not\x20emit\x20a\x20discrete\x20event\x20—\x20indexers\x20must\x20infer','description':'proposition_change\x20(arb.move)\x20updates\x20the\x20proposition\x20vector\x20in\x20place.\x20Unlike\x20'+'state\x20transitions\x20(which\x20emit\x20ArbEvent),\x20proposition\x20edits\x20may\x20not\x20produce\x20a\x20'+'discrete\x20event\x20—\x20indexers\x20must\x20infer\x20changes\x20by\x20diffing\x20the\x20proposition\x20vector\x20'+'across\x20polls.','affected_stakeholders':['arbitrator','voter'],'scenario':'Indexer\x20expects\x20a\x20PropositionChangedEvent;\x20none\x20is\x20emitted,\x20UI\x20fails\x20to\x20refresh','mitigation':'External\x20indexers\x20should\x20poll\x20the\x20proposition\x20vector.\x20UI\x20should\x20display\x20\x27propositions\x20'+'may\x20have\x20changed\x27\x20on\x20each\x20poll\x20rather\x20than\x20relying\x20on\x20event-driven\x20refresh.','auto_fixable':![]},'check':a=>{if(!a['expects_proposition_event'])return null;return{...R_A_04['rule'],'evidence':'expects_proposition_event=true\x20(poll\x20instead)'};}},R_A_05={'rule':{'id':'R-ARB-05','level':'MEDIUM','category':'semantic','title':'voting_deadline\x20is\x20Option<u64>\x20—\x20None\x20means\x20open-ended\x20vote','description':'voting_deadline\x20is\x20Option<u64>.\x20When\x20None,\x20voting\x20has\x20no\x20deadline\x20(open-ended)\x20and\x20'+'E_VOTING_DEADLINE_PASSED\x20(7)\x20never\x20triggers.\x20When\x20Some(t),\x20vote()\x20aborts\x20if\x20'+'clock.timestamp_ms()\x20>\x20t.\x20Callers\x20who\x20assume\x20a\x20default\x20deadline\x20may\x20be\x20surprised\x20by\x20'+'an\x20open-ended\x20vote\x20that\x20never\x20finalizes.','affected_stakeholders':['voter','arbitrator'],'scenario':'Voter\x20assumes\x20a\x20deadline;\x20voting_deadline\x20is\x20None\x20and\x20the\x20case\x20stalls\x20indefinitely','mitigation':'Document\x20that\x20None\x20means\x20open-ended.\x20Arbitrators\x20should\x20set\x20an\x20explicit\x20deadline\x20via\x20'+'arbitrator_confirm\x20unless\x20they\x20intend\x20an\x20open\x20vote.\x20SDK\x20should\x20surface\x20voting_deadline\x20'+'prominently.','related_move_error':'E_VOTING_DEADLINE_PASSED\x20(7)\x20/\x20E_VOTING_DEADLINE_NOT_PASSED\x20(4)','auto_fixable':![]},'check':a=>{if(!a['voting_deadline_none'])return null;return{...R_A_05['rule'],'evidence':'voting_deadline_none=true\x20(open-ended\x20vote)'};}},R_A_06={'rule':{'id':'R-ARB-06','level':'LOW','category':'semantic','title':'indemnity\x20is\x20Option<Indemnity>\x20—\x20None\x20means\x20no\x20compensation','description':'indemnity\x20is\x20Option<Indemnity>.\x20When\x20None,\x20the\x20arbitration\x20produces\x20no\x20compensation\x20'+'(e.g.\x20a\x20pure\x20declaratory\x20ruling).\x20Consumers\x20who\x20assume\x20a\x20non-null\x20indemnity\x20will\x20'+'mis-handle\x20None\x20cases.\x20finish()\x20returns\x20the\x20indemnity\x20amount\x20(0\x20when\x20None).','affected_stakeholders':['principal'],'scenario':'Principal\x20expects\x20compensation;\x20indemnity\x20is\x20None\x20and\x20finish()\x20returns\x200','mitigation':'Document\x20that\x20None\x20means\x20no\x20compensation.\x20UI\x20should\x20show\x20\x27no\x20compensation\x20awarded\x27\x20'+'rather\x20than\x20\x27compensation\x20pending\x27.','auto_fixable':![]},'check':a=>{if(!a['indemnity_none'])return null;return{...R_A_06['rule'],'evidence':'indemnity_none=true\x20(no\x20compensation)'};}},R_A_07={'rule':{'id':'R-ARB-07','level':'MEDIUM','category':'permission','title':'Voted.weight\x20is\x20set\x20by\x20the\x20Arbitration\x20rule\x20—\x20concentrated\x20weight\x20risk','description':'Voted.weight\x20(u32)\x20is\x20assigned\x20by\x20the\x20Arbitration\x20object\x27s\x20voting_guard\x20logic,\x20not\x20'+'by\x20the\x20voter.\x20If\x20the\x20Arbitration\x20rule\x20concentrates\x20weight\x20in\x20one\x20voter\x20(e.g.\x20an\x20'+'admin\x20with\x20weight\x201000\x20vs.\x20others\x20with\x20weight\x201),\x20a\x20single\x20voter\x20can\x20dictate\x20the\x20'+'outcome.\x20The\x20Arb\x20contract\x20itself\x20does\x20not\x20detect\x20concentration\x20—\x20that\x20is\x20the\x20'+'Arbitration\x20designer\x27s\x20responsibility.','affected_stakeholders':['voter','arbitrator'],'scenario':'Arbitration\x20rule\x20gives\x20one\x20voter\x20weight\x201000;\x20that\x20voter\x20single-handedly\x20decides\x20the\x20case','mitigation':'When\x20designing\x20the\x20Arbitration\x20rule,\x20cap\x20individual\x20voter\x20weight\x20and\x20require\x20a\x20'+'quorum.\x20Audit\x20the\x20voting_guard\x20to\x20ensure\x20no\x20single\x20voter\x20can\x20exceed\x20the\x20quorum\x20alone.','auto_fixable':![]},'check':a=>{if(!a['weight_concentrated'])return null;return{...R_A_07['rule'],'evidence':'weight_concentrated=true\x20(rule-level\x20risk)'};}},R_A_08={'rule':{'id':'R-ARB-08','level':'LOW','category':'semantic','title':'Status\x20uses\x20u8\x20constants\x20—\x20Move\x20enum\x20is\x20commented\x20out','description':'The\x207\x20statuses\x20are\x20defined\x20as\x20u8\x20constants\x20(Status_Principal_confirming=0,\x20etc.).\x20'+'The\x20Move\x20enum\x20definition\x20is\x20commented\x20out\x20(arb.move).\x20Consumers\x20cannot\x20rely\x20on\x20a\x20'+'type-safe\x20enum\x20and\x20must\x20compare\x20against\x20magic\x20numbers.\x20A\x20future\x20Wow\x20release\x20enabling\x20'+'the\x20enum\x20would\x20be\x20a\x20breaking\x20change\x20to\x20downstream\x20code.','affected_stakeholders':['system'],'scenario':'Developer\x20expects\x20a\x20Status\x20enum;\x20only\x20u8\x20constants\x20are\x20available,\x20causing\x20type\x20errors','mitigation':'SDK\x20should\x20expose\x20a\x20TypeScript\x20enum\x20mirroring\x20the\x20u8\x20constants.\x20Document\x20that\x20the\x20'+'Move\x20enum\x20is\x20intentionally\x20disabled\x20and\x20may\x20be\x20enabled\x20in\x20a\x20future\x20version.','auto_fixable':![]},'check':a=>{if(!a['expects_status_enum'])return null;return{...R_A_08['rule'],'evidence':'expects_status_enum=true\x20(only\x20u8\x20constants\x20exist)'};}};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(a){const b=[];for(const c of ARB_RISK_RULES){const d=c['check'](a);if(d)b['push'](d);}return b;}export function getArbRiskById(a){return ARB_RISK_RULES['find'](b=>b['rule']['id']===a)?.['rule'];}