@wowok/agent-mcp 2.4.3 → 2.5.0

package/dist/knowledge/treasury-translation.js

@@ -0,0 +1,498 @@
+import { isBuiltinTreasuryPermission, getBuiltinPermissionByIndex, findSceneByPermissionIndex, } from "./treasury-ledger.js";
+export const SEMANTIC_TO_SCHEMA_RULES = [
+    {
+        id: "T-T-01",
+        pattern_name: "Create new Treasury",
+        semantic_intent: "Create a new Treasury with a Coin type T and associated Permission",
+        match_keywords: ["create", "new"],
+        schema_fields: ["object (TypeNamedObjectWithPermission)", "description"],
+        example_json: {
+            object: {
+                name: "myteam_treasury",
+                type_parameter: "0x2::wow::WOW",
+                permission: {
+                    name: "myteam_treasury_permission",
+                    description: "Permission for myteam treasury",
+                },
+            },
+            description: "Team treasury for project X funding",
+        },
+        reverse_explanation: "object must be in OBJECT format (not STRING) for creation; type_parameter is the Coin type T; permission can be new or existing",
+    },
+    {
+        id: "T-T-02",
+        pattern_name: "Internal deposit (Permission path)",
+        semantic_intent: "Deposit funds to Treasury via Permission authorization",
+        match_keywords: ["deposit"],
+        schema_fields: ["object (string)", "deposit.coin", "deposit.payment_info"],
+        example_json: {
+            object: "myteam_treasury",
+            deposit: {
+                coin: { balance: "1000000000" },
+                payment_info: { remark: "Q3 budget allocation", index: 0 },
+            },
+        },
+        reverse_explanation: "deposit.by_external_deposit_guard omitted → Permission path (TREASURY_DEPOSIT=252); coin can be {balance} or {coin_object}",
+    },
+    {
+        id: "T-T-03",
+        pattern_name: "Internal withdraw (Permission path, fixed amount)",
+        semantic_intent: "Withdraw fixed amount from Treasury via Permission authorization",
+        match_keywords: ["withdraw"],
+        schema_fields: ["object (string)", "withdraw.amount.fixed", "withdraw.recipient", "withdraw.payment_info"],
+        example_json: {
+            object: "myteam_treasury",
+            withdraw: {
+                amount: { fixed: "500000000" },
+                recipient: "0xRECIPIENT",
+                payment_info: { remark: "Vendor payment", index: 1 },
+            },
+        },
+        reverse_explanation: "withdraw.amount.fixed → Permission path (TREASURY_WITHDRAW=254); amount is fixed u64; irreversible",
+    },
+    {
+        id: "T-T-04",
+        pattern_name: "External deposit (Guard + Passport path)",
+        semantic_intent: "External user deposits via preset Guard verification (no Permission needed)",
+        match_keywords: ["external deposit", "guard deposit"],
+        schema_fields: ["object (string)", "deposit.coin", "deposit.by_external_deposit_guard", "deposit.payment_info", "submission (Passport)"],
+        example_json: {
+            object: "myteam_treasury",
+            deposit: {
+                coin: { balance: "200000000" },
+                by_external_deposit_guard: "deposit_guard_v1",
+                payment_info: { remark: "External deposit via guard", index: 2 },
+            },
+        },
+        reverse_explanation: "deposit.by_external_deposit_guard present → Guard path (NO Permission check); Passport required via submission field; amount may split if coin > guard-specified",
+    },
+    {
+        id: "T-T-05",
+        pattern_name: "External withdraw (Guard + Passport path, amount from Guard)",
+        semantic_intent: "External user withdraws via preset Guard verification; amount determined by Guard table identifier",
+        match_keywords: ["external withdraw", "guard withdraw"],
+        schema_fields: ["object (string)", "withdraw.amount.by_external_withdraw_guard", "withdraw.recipient", "withdraw.payment_info", "submission (Passport)"],
+        example_json: {
+            object: "myteam_treasury",
+            withdraw: {
+                amount: { by_external_withdraw_guard: "withdraw_guard_v1" },
+                recipient: "0xRECIPIENT",
+                payment_info: { remark: "External withdraw via guard", index: 3 },
+            },
+        },
+        reverse_explanation: "withdraw.amount.by_external_withdraw_guard → Guard path (NO Permission check); amount comes from Guard table identifier (u8, required); irreversible",
+    },
+    {
+        id: "T-T-06",
+        pattern_name: "Manage external deposit/withdraw Guard (add/set/remove/clear)",
+        semantic_intent: "Add, set, remove, or clear external_deposit_guard / external_withdraw_guard lists",
+        match_keywords: ["guard add", "guard set", "guard remove", "guard clear"],
+        schema_fields: ["object (string)", "external_deposit_guard | external_withdraw_guard"],
+        example_json: {
+            object: "myteam_treasury",
+            external_deposit_guard: {
+                op: "add",
+                guards: [
+                    { guard: "deposit_guard_v1", identifier: 2, store_from_id: null },
+                ],
+            },
+        },
+        reverse_explanation: "op='add' (upsert) / 'set' (clear+add) / 'remove' (by guard address) / 'clear' (empty list); Permission index 255 (deposit) / 256 (withdraw) required",
+    },
+    {
+        id: "T-T-07",
+        pattern_name: "Receive CoinWrapper / owner_receive forward",
+        semantic_intent: "Receive CoinWrapper into balance, or forward received objects to Permission owner",
+        match_keywords: ["receive", "owner_receive", "forward"],
+        schema_fields: ["object (string)", "receive | owner_receive"],
+        example_json: {
+            object: "myteam_treasury",
+            receive: "recently",
+        },
+        reverse_explanation: "receive → TREASURY_RECEIVE=253, converts CoinWrapper to balance, writes Record; owner_receive → TREASURY_OWNER_RECEIVE=257, forwards to Permission.owner, no Record",
+    },
+    {
+        id: "T-T-08",
+        pattern_name: "Set UM / modify description",
+        semantic_intent: "Delegate User Manager (Contact object) or modify Treasury description",
+        match_keywords: ["um", "um_set", "um_none", "description", "delegate"],
+        schema_fields: ["object (string)", "um | description"],
+        example_json: {
+            object: "myteam_treasury",
+            um: "team_contact",
+        },
+        reverse_explanation: "um=address → TREASURY_UM=258 (um_set); um=null → TREASURY_UM=258 (um_none); description=string → TREASURY_DESCRIPTION=251",
+    },
+];
+export const SCHEMA_TO_SEMANTIC_RULES = [
+    {
+        element_type: "field",
+        type_name: "object",
+        semantic_explanation: "Treasury object reference. STRING=operate existing; OBJECT={name, type_parameter, permission}=create new",
+        constraints: ["type_parameter required at creation, immutable thereafter", "permission can be new (TypeNamedObject) or existing (string address)"],
+    },
+    {
+        element_type: "field",
+        type_name: "description",
+        semantic_explanation: "Human-readable description of Treasury purpose. Max 4000 chars (MAX_DESCRIPTION_LENGTH).",
+        constraints: ["<= 4000 chars", "Modifiable via TREASURY_DESCRIPTION (251)"],
+    },
+    {
+        element_type: "field",
+        type_name: "deposit",
+        semantic_explanation: "Deposit operation. Two access paths: (1) Permission path (by_external_deposit_guard omitted, requires TREASURY_DEPOSIT=252); (2) Guard path (by_external_deposit_guard set, requires Passport, no Permission)",
+    },
+    {
+        element_type: "field",
+        type_name: "deposit.coin",
+        semantic_explanation: "Coin to deposit. {balance: string} for amount; {coin_object: string} for existing Coin object. Type T must match Treasury's type_parameter.",
+    },
+    {
+        element_type: "field",
+        type_name: "deposit.by_external_deposit_guard",
+        semantic_explanation: "Guard address or name for external deposit path. Triggers Guard + Passport verification; bypasses Permission check.",
+        constraints: ["Guard must be in external_deposit_guard list (else E_EXTERNAL_DEPOSIT_GUARD_NOT_FOUND)", "Passport required"],
+    },
+    {
+        element_type: "field",
+        type_name: "withdraw",
+        semantic_explanation: "Withdraw operation. Two access paths: (1) Permission path (amount.fixed, requires TREASURY_WITHDRAW=254); (2) Guard path (amount.by_external_withdraw_guard, requires Passport, no Permission)",
+    },
+    {
+        element_type: "field",
+        type_name: "withdraw.amount.fixed",
+        semantic_explanation: "Fixed u64 withdraw amount (Permission path). Irreversible. Recipient specified separately.",
+        constraints: ["Must be <= balance (else E_WITHDRAW_INSUFFICIENT_AMOUNT)", "u64 format"],
+    },
+    {
+        element_type: "field",
+        type_name: "withdraw.amount.by_external_withdraw_guard",
+        semantic_explanation: "Guard address/name for external withdraw path. Amount determined by Guard table identifier (not caller-specified).",
+        constraints: ["Guard must be in external_withdraw_guard list", "Passport required", "Amount from Guard is authoritative"],
+    },
+    {
+        element_type: "field",
+        type_name: "external_deposit_guard",
+        semantic_explanation: "Manage external_deposit_guard list. op: add (upsert) / set (clear+add) / remove (by address) / clear (empty). Requires TREASURY_EXTERNAL_DEPOSIT_GUARD=255.",
+        constraints: ["Max 100 guards (MAX_EXTERNAL_DEPOSIT_GUARD_COUNT)", "identifier is Option<u8> (None = no amount limit)", "store_from_id is Option<u8>"],
+    },
+    {
+        element_type: "field",
+        type_name: "external_withdraw_guard",
+        semantic_explanation: "Manage external_withdraw_guard list. op: add/set/remove/clear. Requires TREASURY_EXTERNAL_WITHDRAW_GUARD=256.",
+        constraints: ["Max 200 guards (MAX_EXTERNAL_WITHDRAW_GUARD_COUNT)", "identifier is u8 (REQUIRED, not Option)", "store_from_id is Option<u8>"],
+    },
+    {
+        element_type: "field",
+        type_name: "receive",
+        semantic_explanation: "Receive CoinWrapper objects into balance. Requires TREASURY_RECEIVE=253. Writes Record(op=RECEIVE) to history.",
+        constraints: ["CoinWrapper type T must match Treasury's T", "'recently' resolves to all un-received CoinWrapper"],
+    },
+    {
+        element_type: "field",
+        type_name: "owner_receive",
+        semantic_explanation: "Unwrap received objects (CoinWrapper + others) and forward to Permission.owner. Requires TREASURY_OWNER_RECEIVE=257. Does NOT write to history.",
+        constraints: ["Irreversible (funds leave Treasury)", "Recipient is Permission.owner (resolved at tx time)"],
+    },
+    {
+        element_type: "field",
+        type_name: "um",
+        semantic_explanation: "User Manager (Contact object address). um=address → um_set; um=null → um_none. Requires TREASURY_UM=258.",
+        constraints: ["Must be a Contact object (not user wallet)", "UM ≠ admin (no permission management)"],
+    },
+    {
+        element_type: "op",
+        type_name: "add",
+        semantic_explanation: "Upsert semantics: if guard exists, update identifier/store_from_id; else append (after count check)",
+    },
+    {
+        element_type: "op",
+        type_name: "set",
+        semantic_explanation: "Replace entire list: clear first, then add. Use when wholesale replacement is intended.",
+    },
+    {
+        element_type: "op",
+        type_name: "remove",
+        semantic_explanation: "Remove specific guards by address. Count check uses MAX as upper bound (not subtractive).",
+    },
+    {
+        element_type: "op",
+        type_name: "clear",
+        semantic_explanation: "Empty the entire guard list. No count check needed.",
+    },
+];
+export const TREASURY_CONSTRAINT_RULES = [
+    {
+        id: "MC-T-01",
+        category: "structural",
+        rule: "description length <= MAX_DESCRIPTION_LENGTH (4000)",
+        applies_to: ["description"],
+    },
+    {
+        id: "MC-T-02",
+        category: "structural",
+        rule: "external_deposit_guard count <= MAX_EXTERNAL_DEPOSIT_GUARD_COUNT (100)",
+        applies_to: ["external_deposit_guard.guards"],
+    },
+    {
+        id: "MC-T-03",
+        category: "structural",
+        rule: "external_withdraw_guard count <= MAX_EXTERNAL_WITHDRAW_GUARD_COUNT (200)",
+        applies_to: ["external_withdraw_guard.guards"],
+    },
+    {
+        id: "MC-T-04",
+        category: "structural",
+        rule: "external_withdraw_guard.identifier is u8 (REQUIRED, not Option<u8>)",
+        applies_to: ["external_withdraw_guard.guards[].identifier"],
+    },
+    {
+        id: "MC-T-05",
+        category: "structural",
+        rule: "external_deposit_guard.identifier is Option<u8> (None means no amount limit)",
+        applies_to: ["external_deposit_guard.guards[].identifier"],
+    },
+    {
+        id: "MC-T-06",
+        category: "semantic",
+        rule: "Coin type T must match Treasury's type_parameter for all deposit/withdraw/receive operations",
+        applies_to: ["deposit.coin", "withdraw.amount.fixed", "receive"],
+    },
+    {
+        id: "MC-T-07",
+        category: "authority",
+        rule: "deposit via Permission path requires TREASURY_DEPOSIT (252); deposit via Guard path requires no Permission (Guard+Passport only)",
+        applies_to: ["deposit.by_external_deposit_guard"],
+    },
+    {
+        id: "MC-T-08",
+        category: "authority",
+        rule: "withdraw.amount.fixed requires TREASURY_WITHDRAW (254); withdraw.amount.by_external_withdraw_guard requires no Permission",
+        applies_to: ["withdraw.amount"],
+    },
+    {
+        id: "MC-T-09",
+        category: "authority",
+        rule: "external_deposit_guard management requires TREASURY_EXTERNAL_DEPOSIT_GUARD (255); external_withdraw_guard management requires TREASURY_EXTERNAL_WITHDRAW_GUARD (256)",
+        applies_to: ["external_deposit_guard", "external_withdraw_guard"],
+    },
+    {
+        id: "MC-T-10",
+        category: "lifecycle",
+        rule: "withdraw (fixed) and external_withdraw are IRREVERSIBLE; verify recipient and amount before execution",
+        applies_to: ["withdraw.amount.fixed", "withdraw.amount.by_external_withdraw_guard"],
+    },
+    {
+        id: "MC-T-11",
+        category: "lifecycle",
+        rule: "owner_receive forwards assets to Permission.owner and does NOT write to history; verify owner address is current",
+        applies_to: ["owner_receive"],
+    },
+    {
+        id: "MC-T-12",
+        category: "lifecycle",
+        rule: "um_set requires Contact object address (not user wallet); um_set vs um_none both use TREASURY_UM (258)",
+        applies_to: ["um"],
+    },
+    {
+        id: "MC-T-13",
+        category: "cross_object",
+        rule: "If Treasury is referenced by Allocator/Arbitration, TREASURY_RECEIVE (253) must be granted to a trusted operator for regular intake",
+        applies_to: ["receive"],
+    },
+    {
+        id: "MC-T-14",
+        category: "semantic",
+        rule: "external_deposit may split coin if value > guard-specified amount; excess refunded to sender",
+        applies_to: ["deposit.by_external_deposit_guard"],
+    },
+    {
+        id: "MC-T-15",
+        category: "semantic",
+        rule: "inflow/outflow are monotonic counters (never decrease); used for audit reconciliation: theoretical balance = inflow - outflow",
+        applies_to: ["(read-only audit fields)"],
+    },
+];
+export const TREASURY_TRANSLATION_VERSION = "1.0.0";
+export function matchSemanticPattern(userIntent) {
+    const lower = userIntent.toLowerCase();
+    const matches = [];
+    if (lower.includes("create") || lower.includes("new")) {
+        matches.push(SEMANTIC_TO_SCHEMA_RULES[0]);
+    }
+    if (lower.includes("deposit")) {
+        if (lower.includes("external") || lower.includes("guard")) {
+            matches.push(SEMANTIC_TO_SCHEMA_RULES[3]);
+        }
+        else {
+            matches.push(SEMANTIC_TO_SCHEMA_RULES[1]);
+        }
+    }
+    if (lower.includes("withdraw")) {
+        if (lower.includes("external") || lower.includes("guard")) {
+            matches.push(SEMANTIC_TO_SCHEMA_RULES[4]);
+        }
+        else {
+            matches.push(SEMANTIC_TO_SCHEMA_RULES[2]);
+        }
+    }
+    if (lower.includes("guard add") || lower.includes("guard set") || lower.includes("guard remove") ||
+        lower.includes("guard clear")) {
+        matches.push(SEMANTIC_TO_SCHEMA_RULES[5]);
+    }
+    if (lower.includes("receive") ||
+        lower.includes("owner_receive") || lower.includes("forward")) {
+        matches.push(SEMANTIC_TO_SCHEMA_RULES[6]);
+    }
+    if (lower.includes("um") || lower.includes("delegate") || lower.includes("user manager") ||
+        lower.includes("description")) {
+        matches.push(SEMANTIC_TO_SCHEMA_RULES[7]);
+    }
+    if (matches.length === 0) {
+        return [...SEMANTIC_TO_SCHEMA_RULES];
+    }
+    return matches;
+}
+export function explainTreasuryCallData(data) {
+    const lines = [];
+    if (data.object === null || data.object === undefined) {
+        lines.push("Operation: INVALID (object field required)");
+    }
+    else if (typeof data.object === "string") {
+        lines.push(`Operation: OPERATE existing Treasury at ${data.object}`);
+    }
+    else if (typeof data.object === "object") {
+        const obj = data.object;
+        lines.push(`Operation: CREATE new Treasury`);
+        if (obj.name)
+            lines.push(`  name: ${obj.name}`);
+        if (obj.type_parameter)
+            lines.push(`  type_parameter (T): ${obj.type_parameter}`);
+        if (obj.permission) {
+            if (typeof obj.permission === "string") {
+                lines.push(`  permission: existing ${obj.permission}`);
+            }
+            else {
+                lines.push(`  permission: new (TypeNamedObject)`);
+            }
+        }
+    }
+    if (data.description) {
+        lines.push(`- Set description: "${data.description}"`);
+    }
+    if (data.deposit) {
+        const d = data.deposit;
+        if (d.by_external_deposit_guard) {
+            lines.push(`- External deposit via guard: ${d.by_external_deposit_guard}`);
+            if (d.coin?.balance)
+                lines.push(`  coin balance: ${d.coin.balance} (may split if > guard limit)`);
+            if (d.coin?.coin_object)
+                lines.push(`  coin object: ${d.coin.coin_object}`);
+            lines.push(`  ⚠️ No Permission check; Passport required`);
+        }
+        else {
+            lines.push(`- Internal deposit via Permission (TREASURY_DEPOSIT=252)`);
+            if (d.coin?.balance)
+                lines.push(`  coin balance: ${d.coin.balance}`);
+            if (d.coin?.coin_object)
+                lines.push(`  coin object: ${d.coin.coin_object}`);
+        }
+        if (d.payment_info?.remark)
+            lines.push(`  payment remark: "${d.payment_info.remark}"`);
+    }
+    if (data.withdraw) {
+        const w = data.withdraw;
+        if (w.amount?.fixed) {
+            lines.push(`- Internal withdraw via Permission (TREASURY_WITHDRAW=254)`);
+            lines.push(`  amount: ${w.amount.fixed} (fixed, IRREVERSIBLE)`);
+        }
+        else if (w.amount?.by_external_withdraw_guard) {
+            lines.push(`- External withdraw via guard: ${w.amount.by_external_withdraw_guard}`);
+            lines.push(`  ⚠️ Amount determined by Guard table identifier (not caller-specified)`);
+            lines.push(`  ⚠️ IRREVERSIBLE; No Permission check; Passport required`);
+        }
+        if (w.recipient)
+            lines.push(`  recipient: ${w.recipient}`);
+        if (w.payment_info?.remark)
+            lines.push(`  payment remark: "${w.payment_info.remark}"`);
+    }
+    if (data.receive) {
+        if (data.receive === "recently") {
+            lines.push(`- Receive all recently-received CoinWrapper (TREASURY_RECEIVE=253)`);
+        }
+        else if (Array.isArray(data.receive)) {
+            lines.push(`- Receive ${data.receive.length} CoinWrapper object(s) (TREASURY_RECEIVE=253)`);
+        }
+    }
+    if (data.external_deposit_guard) {
+        const g = data.external_deposit_guard;
+        if (g.op === "clear") {
+            lines.push(`- Clear external_deposit_guard list (TREASURY_EXTERNAL_DEPOSIT_GUARD=255)`);
+        }
+        else if (g.op === "remove") {
+            lines.push(`- Remove ${g.guards.length} guard(s) from external_deposit_guard (Permission 255)`);
+        }
+        else {
+            const count = g.guards.length;
+            lines.push(`- ${g.op === "set" ? "Set (clear+add)" : "Add (upsert)"} ${count} external_deposit_guard(s) (Permission 255)`);
+        }
+    }
+    if (data.external_withdraw_guard) {
+        const g = data.external_withdraw_guard;
+        if (g.op === "clear") {
+            lines.push(`- Clear external_withdraw_guard list (TREASURY_EXTERNAL_WITHDRAW_GUARD=256)`);
+        }
+        else if (g.op === "remove") {
+            lines.push(`- Remove ${g.guards.length} guard(s) from external_withdraw_guard (Permission 256)`);
+        }
+        else {
+            const count = g.guards.length;
+            lines.push(`- ${g.op === "set" ? "Set (clear+add)" : "Add (upsert)"} ${count} external_withdraw_guard(s) (Permission 256)`);
+            lines.push(`  ⚠️ withdraw guard identifier is REQUIRED (u8, not Option)`);
+        }
+    }
+    if (data.owner_receive) {
+        if (data.owner_receive === "recently") {
+            lines.push(`- owner_receive: forward all recently-received objects to Permission.owner (TREASURY_OWNER_RECEIVE=257)`);
+        }
+        else if (Array.isArray(data.owner_receive)) {
+            lines.push(`- owner_receive: forward ${data.owner_receive.length} object(s) to Permission.owner (Permission 257)`);
+        }
+        lines.push(`  ⚠️ IRREVERSIBLE; does NOT write to history`);
+    }
+    if (data.um !== undefined) {
+        if (data.um === null) {
+            lines.push(`- UM revoke (um_none, TREASURY_UM=258)`);
+        }
+        else {
+            lines.push(`- UM set to ${data.um} (TREASURY_UM=258)`);
+        }
+    }
+    return lines.join("\n");
+}
+export function explainField(fieldName) {
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "field" && r.type_name === fieldName);
+}
+export function explainOp(opName) {
+    return SCHEMA_TO_SEMANTIC_RULES.find(r => r.element_type === "op" && r.type_name === opName);
+}
+export function getConstraintsByCategory(category) {
+    return TREASURY_CONSTRAINT_RULES.filter(r => r.category === category);
+}
+export function explainTreasuryPermissionIndex(index) {
+    if (isBuiltinTreasuryPermission(index)) {
+        const entry = getBuiltinPermissionByIndex(index);
+        const scene = findSceneByPermissionIndex(index);
+        return `${entry?.name ?? "Unknown"} (${index}) — ${entry?.description ?? ""} [scene: ${scene?.id ?? "unknown"}]`;
+    }
+    if (index === -1) {
+        return `Reserved (no Permission index) — external operations use Guard + Passport instead`;
+    }
+    if (index >= 1000) {
+        return `Custom permission (${index}) — must be documented via Permission.remark; not used by Treasury builtin operations`;
+    }
+    if (index === 259 || index === 260) {
+        return `STALE index ${index} — was pre-fix SDK value; canonical post-fix indexes are 255-258. See R-T-01.`;
+    }
+    return `Index ${index} — not a Treasury builtin permission (range 250-258)`;
+}

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

@@ -0,0 +1,30 @@
+export type UtilRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export type UtilRiskCategory = "structural" | "semantic" | "lifecycle" | "cross_object" | "knowledge";
+export type UtilStakeholder = "caller" | "system";
+export interface UtilRisk {
+    id: string;
+    level: UtilRiskLevel;
+    category: UtilRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: UtilStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    auto_fixable: boolean;
+}
+export interface UtilRiskCheckContext {
+    uses_typo_function_name?: boolean;
+    assumes_stable_address_bytes?: boolean;
+    large_util_import?: boolean;
+    expects_util_events?: boolean;
+    bcs_manually_synced?: boolean;
+}
+export declare const UTIL_RISK_RULES: {
+    rule: UtilRisk;
+    check: (ctx: UtilRiskCheckContext) => UtilRisk | null;
+}[];
+export declare const UTIL_RISK_VERSION = "1.0.0";
+export declare function checkUtilRisks(ctx: UtilRiskCheckContext): UtilRisk[];
+export declare function getUtilRiskById(id: string): UtilRisk | undefined;

package/dist/knowledge/util-risk.js

@@ -0,0 +1,135 @@
+const USER_ADDRESS_BYTE_MAX = 0x06;
+const OBJECT_ADDRESS_BYTE = 0xf1;
+const CHILD_OBJECT_ADDRESS_BYTE = 0xf0;
+const R_U_01 = {
+    rule: {
+        id: "R-UTIL-01",
+        level: "LOW",
+        category: "semantic",
+        title: "is_chiild_object_address_byte has a typo ('chiild') — cannot be renamed post-publish",
+        description: "util.move:30 defines is_chiild_object_address_byte (note the 'chiild' typo). The " +
+            "function is already published on mainnet, so the name cannot be fixed without a " +
+            "breaking package upgrade. Callers must use the misspelled name exactly; SDK wrappers " +
+            "should expose a correctly-spelled alias and route to the typo function.",
+        affected_stakeholders: ["caller"],
+        scenario: "Caller writes is_child_object_address_byte; Move linker cannot resolve the symbol",
+        mitigation: "SDK should expose isChildObjectAddressByte as the public API and internally call the " +
+            "typo'd Move function. Document the typo so future maintainers don't 'fix' it.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.uses_typo_function_name)
+            return null;
+        return { ...R_U_01.rule, evidence: "uses_typo_function_name=true (must use 'chiild')" };
+    },
+};
+const R_U_02 = {
+    rule: {
+        id: "R-UTIL-02",
+        level: "MEDIUM",
+        category: "semantic",
+        title: "Address-byte thresholds are hardcoded — Wow protocol upgrades could invalidate them",
+        description: `util.move classifies addresses by first byte: user (≤ ${USER_ADDRESS_BYTE_MAX}), ` +
+            `object (${OBJECT_ADDRESS_BYTE}), child_object (${CHILD_OBJECT_ADDRESS_BYTE}). ` +
+            `These thresholds are hardcoded as Move constants, not configurable. If a future Wow ` +
+            `protocol upgrade changes the address byte layout (e.g. reserves a new prefix), Util ` +
+            `would silently misclassify addresses until the Move code is upgraded.`,
+        affected_stakeholders: ["caller", "system"],
+        scenario: "Wow protocol upgrade introduces a new address prefix; Util misclassifies it as user",
+        mitigation: "Track Wow protocol upgrades that touch address layout. When a change ships, upgrade " +
+            "util.move and the SDK in lockstep. Add a sync test that asserts the byte values.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.assumes_stable_address_bytes)
+            return null;
+        return { ...R_U_02.rule, evidence: `assumes_stable_address_bytes=true (hardcoded ${USER_ADDRESS_BYTE_MAX}/${OBJECT_ADDRESS_BYTE}/${CHILD_OBJECT_ADDRESS_BYTE})` };
+    },
+};
+const R_U_03 = {
+    rule: {
+        id: "R-UTIL-03",
+        level: "LOW",
+        category: "structural",
+        title: "util.ts is ~50KB — over-concentrated, hard to navigate",
+        description: "The SDK util.ts is ~50428 bytes, mixing BCS structure definitions, query condition " +
+            "builders, Guard query helpers, and address utilities. The size makes it hard to " +
+            "navigate and increases the risk of accidental circular imports. New contributors " +
+            "often import the wrong symbol because so many are exported from one file.",
+        affected_stakeholders: ["caller", "system"],
+        scenario: "Developer imports ProgressHistoryFindConditionsBCS and accidentally pulls in unrelated code",
+        mitigation: "Consider splitting util.ts into focused sub-modules (bcs.ts, query.ts, address.ts). " +
+            "Until then, prefer named imports over namespace imports to keep bundles lean.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.large_util_import)
+            return null;
+        return { ...R_U_03.rule, evidence: "large_util_import=true (consider sub-modules)" };
+    },
+};
+const R_U_04 = {
+    rule: {
+        id: "R-UTIL-04",
+        level: "LOW",
+        category: "lifecycle",
+        title: "Util emits no events — tool-call observability is caller's responsibility",
+        description: "Util functions are pure: they neither emit nor consume events. Callers cannot rely on " +
+            "an event stream to trace Util invocations. For audit and debugging, the calling " +
+            "module must record its own log entries around Util calls.",
+        affected_stakeholders: ["caller"],
+        scenario: "Auditor expects Util-call events; none exist, the call chain is invisible",
+        mitigation: "Callers should emit their own events or write logs around Util calls when auditability " +
+            "is required. Treat Util as an opaque library function.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (!ctx.expects_util_events)
+            return null;
+        return { ...R_U_04.rule, evidence: "expects_util_events=true (none emitted)" };
+    },
+};
+const R_U_05 = {
+    rule: {
+        id: "R-UTIL-05",
+        level: "MEDIUM",
+        category: "cross_object",
+        title: "SDK BCS structures must stay in sync with Move structs — drift breaks queries",
+        description: "util.ts defines BCS structures for Progress History / Session / Forward / Record " +
+            "query conditions. These must match the Move struct layouts byte-for-byte. If a Move " +
+            "struct adds a field and the SDK BCS is not regenerated, query submissions will " +
+            "deserialize incorrectly on-chain, producing silent failures or aborts.",
+        affected_stakeholders: ["caller", "system"],
+        scenario: "Progress struct adds a field; SDK BCS is stale; queries return wrong results",
+        mitigation: "Generate BCS structures from Move source via codegen, or run a sync test that " +
+            "compares SDK BCS layouts against Move structs on every release.",
+        auto_fixable: false,
+    },
+    check: (ctx) => {
+        if (ctx.bcs_manually_synced === undefined)
+            return null;
+        if (!ctx.bcs_manually_synced)
+            return null;
+        return { ...R_U_05.rule, evidence: "bcs_manually_synced=true (drift risk)" };
+    },
+};
+export const UTIL_RISK_RULES = [
+    R_U_01,
+    R_U_02,
+    R_U_03,
+    R_U_04,
+    R_U_05,
+];
+export const UTIL_RISK_VERSION = "1.0.0";
+export function checkUtilRisks(ctx) {
+    const risks = [];
+    for (const rule of UTIL_RISK_RULES) {
+        const r = rule.check(ctx);
+        if (r)
+            risks.push(r);
+    }
+    return risks;
+}
+export function getUtilRiskById(id) {
+    return UTIL_RISK_RULES.find(r => r.rule.id === id)?.rule;
+}