@wowok/agent-mcp 2.7.1 → 2.7.3

package/dist/knowledge/payment-risk.js

@@ -1,249 +1 @@
-import { MAX_RECIPIENT_COUNT } from "@wowok/wowok";
-const R_P_01 = {
-    rule: {
-        id: "R-PAYMENT-01",
-        level: "HIGH",
-        category: "permission",
-        title: "unwrap() performs no Payment match check — may unwrap wrong CoinWrapper",
-        description: "unwrap(wrapper, ctx) (payment.move:50) returns (Coin, payment_address) without " +
-            "verifying that wrapper.payment matches any expected Payment. Callers who use unwrap " +
-            "instead of unwrap_with_check can unwrap a CoinWrapper that was minted for a different " +
-            "Payment, leading to fund loss or accounting corruption. unwrap_with_check(payment_check) " +
-            "exists specifically to enforce the match (payment.move:54).",
-        affected_stakeholders: ["signer", "recipient"],
-        scenario: "Caller uses unwrap on a wrapper from a different Payment; funds are released anyway",
-        mitigation: "SDK should force callers to use unwrap_with_check and deprecate direct unwrap calls. " +
-            "The only safe use of unwrap is when the caller has already verified the match off-chain.",
-        related_move_error: "EPAYMENT_NOT_MATCH (3) — only raised by unwrap_with_check",
-        auto_fixable: false,
-    },
-    check: (ctx) => {
-        if (!ctx.uses_unsafe_unwrap)
-            return null;
-        return { ...R_P_01.rule, evidence: "uses_unsafe_unwrap=true (no Payment match check)" };
-    },
-};
-const R_P_02 = {
-    rule: {
-        id: "R-PAYMENT-02",
-        level: "MEDIUM",
-        category: "structural",
-        title: `MAX_RECIPIENT_COUNT=${MAX_RECIPIENT_COUNT} permissive — gas and confirmation cost`,
-        description: `A single Payment may carry up to MAX_RECIPIENT_COUNT=${MAX_RECIPIENT_COUNT} recipients ` +
-            `(payment.move:14). The limit aborts with ERECIPIENT_COUNT_EXCEEDED (1) only at the boundary. ` +
-            `200 recipients in one transaction inflates gas, slows finalization, and complicates ` +
-            `retry on partial failure.`,
-        affected_stakeholders: ["signer", "recipient"],
-        scenario: "Caller submits a Payment with 200 recipients; transaction is heavy and slow",
-        mitigation: "Business layer should self-limit recipient count (e.g. ≤50). For mass payouts, split " +
-            "across multiple Payment objects in separate transactions.",
-        related_move_error: "ERECIPIENT_COUNT_EXCEEDED (1)",
-        auto_fixable: false,
-    },
-    check: (ctx) => {
-        if (ctx.recipient_count === undefined)
-            return null;
-        if (ctx.recipient_count < MAX_RECIPIENT_COUNT)
-            return null;
-        return { ...R_P_02.rule, evidence: `recipient_count=${ctx.recipient_count}, limit=${MAX_RECIPIENT_COUNT}` };
-    },
-};
-const R_P_03 = {
-    rule: {
-        id: "R-PAYMENT-03",
-        level: "LOW",
-        category: "lifecycle",
-        title: "Payment is immutable after create — errors cannot be corrected",
-        description: "create() calls transfer::freeze_object(payment) (payment.move:160). All fields " +
-            "(amount, time, info, from_object, signer, record) are permanently fixed. There is no " +
-            "update, refund, or void API on the Payment object itself — correction requires a new " +
-            "Payment (and off-chain reconciliation).",
-        affected_stakeholders: ["signer", "consumer"],
-        scenario: "Signer mistypes a recipient address; the Payment cannot be edited post-create",
-        mitigation: "Verify all fields before calling create. For refunds, create a new Payment in the " +
-            "opposite direction. Off-chain systems should treat Payment as an immutable receipt.",
-        auto_fixable: false,
-    },
-    check: (ctx) => {
-        if (!ctx.expects_mutation)
-            return null;
-        return { ...R_P_03.rule, evidence: "expects_mutation=true (Payment is frozen at create)" };
-    },
-};
-const R_P_04 = {
-    rule: {
-        id: "R-PAYMENT-04",
-        level: "MEDIUM",
-        category: "structural",
-        title: "CoinWrapper suppresses coin_field lint — Balance<T> stored in a struct field",
-        description: "CoinWrapper<phantom T> stores Balance<T> directly in a struct field and uses " +
-            "#[allow(lint(coin_field))] to suppress the Wow lint (payment.move:43-48). The lint " +
-            "normally warns against storing Balance in arbitrary structs because of object " +
-            "lifecycle concerns. The suppression is intentional but should be reviewed whenever " +
-            "the Wow framework updates its coin_field rules.",
-        affected_stakeholders: ["system"],
-        scenario: "Wow framework tightens coin_field lint semantics; CoinWrapper becomes non-compliant",
-        mitigation: "Review the coin_field suppression on each Wow upgrade. Confirm that Balance<T> " +
-            "ownership transfer in unwrap/unwrap_with_check is correct.",
-        auto_fixable: false,
-    },
-    check: (ctx) => {
-        if (ctx.coin_field_lint_reviewed)
-            return null;
-        return { ...R_P_04.rule, evidence: "coin_field_lint_reviewed=false (needs review)" };
-    },
-};
-const R_P_05 = {
-    rule: {
-        id: "R-PAYMENT-05",
-        level: "LOW",
-        category: "semantic",
-        title: "PaymentInfo has 4 constructor variants — caller may pick the wrong one",
-        description: "PaymentInfo can be built via payment_info (for_object+remark+index), payment_info2 " +
-            "(remark+index, no for_object), payment_info_with_guard (for_object+for_guard+remark+index), " +
-            "or payment_info2_with_guard (for_guard+remark+index, no for_object). Selecting the " +
-            "wrong variant leaves for_object/for_guard as None, breaking downstream lookups.",
-        affected_stakeholders: ["signer", "consumer"],
-        scenario: "Caller uses payment_info2 when they meant payment_info_with_guard; for_object is lost",
-        mitigation: "Document each variant's use case clearly. SDK should pick the variant automatically " +
-            "based on which optional fields the caller provides.",
-        auto_fixable: true,
-    },
-    check: (ctx) => null,
-};
-const R_P_06 = {
-    rule: {
-        id: "R-PAYMENT-06",
-        level: "MEDIUM",
-        category: "cross_object",
-        title: "Registrar registration filters recipients by is_object_address — user addresses skipped",
-        description: "create() iterates recipients and only calls registrar.affiliation for addresses that " +
-            "pass util::is_object_address (payment.move:147-161). User addresses (EOAs) are not " +
-            "registered in the Registrar dependency graph. Callers who expect every recipient to " +
-            "appear in affiliation queries will miss EOA recipients.",
-        affected_stakeholders: ["signer", "consumer"],
-        scenario: "Caller queries Registrar for all Payment recipients; EOA recipients are missing",
-        mitigation: "Document that affiliation is registered only for object-address recipients. Off-chain " +
-            "systems should track EOA recipients via the NewPaymentEvent record, not via Registrar.",
-        auto_fixable: false,
-    },
-    check: (ctx) => {
-        if (!ctx.expects_user_recipient_registered)
-            return null;
-        return { ...R_P_06.rule, evidence: "expects_user_recipient_registered=true (EOAs are skipped)" };
-    },
-};
-const R_P_07 = {
-    rule: {
-        id: "R-PAYMENT-07",
-        level: "LOW",
-        category: "semantic",
-        title: "Payment.signer records payer — useful for provenance but not authorization",
-        description: "Payment.signer is set to ctx.sender() at creation (payment.move). It can be read via " +
-            "payment_signer<T>(payment) for provenance (e.g. 'who paid for this order'). It is " +
-            "purely informational — it does NOT authorize any later operation. Consumers must not " +
-            "treat signer as a permission grant.",
-        affected_stakeholders: ["consumer"],
-        scenario: "Consumer treats Payment.signer as authorizing a refund; signer is just provenance",
-        mitigation: "Use Payment.signer only for audit/provenance. Authorization must come from the " +
-            "referencing object's own Permission, not from Payment.signer.",
-        auto_fixable: false,
-    },
-    check: (ctx) => {
-        if (!ctx.uses_signer_for_provenance)
-            return null;
-        return { ...R_P_07.rule, evidence: "uses_signer_for_provenance=true (informational only)" };
-    },
-};
-const R_P_08 = {
-    rule: {
-        id: "R-PAYMENT-08",
-        level: "MEDIUM",
-        category: "semantic",
-        title: "Payment scene binding (for_object + for_guard + index) — anti-reuse for exception branches",
-        description: "PaymentInfo supports for_object (binds to specific Order), for_guard (binds to specific Guard), " +
-            "and index (binds to specific Progress step) — payment.move#L66-71. When all three are set via " +
-            "payment_info_with_guard (payment.move#L82-86), the Payment is scene-bound: it can ONLY be used " +
-            "in the specific order + guard + progress context. This is the anti-reuse design for exception " +
-            "branch compensation (e.g., delivery delay >30min triggers auto-compensation). " +
-            "Payment is immutable (freeze_object, payment.move#L160) — binding cannot be altered. " +
-            "VERIFIER-EVIDENCE DESIGN: customer submits Payment, Guard verifies binding fields match current context.",
-        affected_stakeholders: ["signer", "recipient", "consumer"],
-        scenario: "Treasury creates compensation Payment with PaymentInfo(for_object=order, for_guard=exception_guard, index=current_progress) for delivery delay",
-        mitigation: "Use payment_info_with_guard for all exception branch Payments. Ensure for_object, for_guard, and index " +
-            "all match the intended context. Use tpl_payment_exception_compensation (guard-templates.ts) as design template.",
-        auto_fixable: false,
-    },
-    check: (ctx) => {
-        if (!ctx.uses_scene_binding)
-            return null;
-        const missing = [];
-        if (!ctx.has_for_object)
-            missing.push("for_object not set (Order binding missing)");
-        if (!ctx.has_for_guard)
-            missing.push("for_guard not set (Guard binding missing)");
-        if (!ctx.has_index)
-            missing.push("index not set (Progress step binding missing)");
-        if (missing.length === 0)
-            return null;
-        return { ...R_P_08.rule, evidence: `incomplete scene binding: ${missing.join(", ")}` };
-    },
-};
-const R_P_09 = {
-    rule: {
-        id: "R-PAYMENT-09",
-        level: "LOW",
-        category: "semantic",
-        title: "PaymentInfo variant selection — use payment_info_with_guard for exception branches",
-        description: "PaymentInfo has 4 constructor variants (payment.move#L66-86): " +
-            "payment_info (for_object+remark+index, no for_guard), " +
-            "payment_info2 (remark+index, no for_object/for_guard), " +
-            "payment_info_with_guard (for_object+for_guard+remark+index — FULL binding), " +
-            "payment_info2_with_guard (for_guard+remark+index, no for_object). " +
-            "For exception branch compensation, ALWAYS use payment_info_with_guard to get full scene binding. " +
-            "Using payment_info (without for_guard) or payment_info2 (without for_object) weakens anti-reuse protection.",
-        affected_stakeholders: ["signer", "consumer"],
-        scenario: "Caller uses payment_info instead of payment_info_with_guard for exception compensation; for_guard is lost",
-        mitigation: "For exception branch Payments: always use payment_info_with_guard(for_object, for_guard, remark, index). " +
-            "For simple Payments without scene binding: payment_info or payment_info2 is fine. " +
-            "SDK should auto-select the variant based on which fields are provided.",
-        auto_fixable: true,
-    },
-    check: (ctx) => {
-        if (!ctx.uses_scene_binding)
-            return null;
-        if (ctx.payment_info_variant === "payment_info_with_guard")
-            return null;
-        return {
-            ...R_P_09.rule,
-            evidence: `uses_scene_binding=true but variant=${ctx.payment_info_variant ?? "unknown"} (should be payment_info_with_guard)`,
-        };
-    },
-};
-export const PAYMENT_RISK_RULES = [
-    R_P_01,
-    R_P_02,
-    R_P_03,
-    R_P_04,
-    R_P_05,
-    R_P_06,
-    R_P_07,
-    R_P_08,
-    R_P_09,
-];
-export const PAYMENT_RISK_VERSION = "1.0.0";
-export function checkPaymentRisks(ctx) {
-    const risks = [];
-    for (const rule of PAYMENT_RISK_RULES) {
-        const r = rule.check(ctx);
-        if (r)
-            risks.push(r);
-    }
-    if (!risks.find(r => r.id === "R-PAYMENT-05")) {
-        risks.push(R_P_05.rule);
-    }
-    return risks;
-}
-export function getPaymentRiskById(id) {
-    return PAYMENT_RISK_RULES.find(r => r.rule.id === id)?.rule;
-}
+import{MAX_RECIPIENT_COUNT}from'@wowok/wowok';const R_P_01={'rule':{'id':'R-PAYMENT-01','level':'HIGH','category':'permission','title':'unwrap()\x20performs\x20no\x20Payment\x20match\x20check\x20—\x20may\x20unwrap\x20wrong\x20CoinWrapper','description':'unwrap(wrapper,\x20ctx)\x20(payment.move:50)\x20returns\x20(Coin,\x20payment_address)\x20without\x20'+'verifying\x20that\x20wrapper.payment\x20matches\x20any\x20expected\x20Payment.\x20Callers\x20who\x20use\x20unwrap\x20'+'instead\x20of\x20unwrap_with_check\x20can\x20unwrap\x20a\x20CoinWrapper\x20that\x20was\x20minted\x20for\x20a\x20different\x20'+'Payment,\x20leading\x20to\x20fund\x20loss\x20or\x20accounting\x20corruption.\x20unwrap_with_check(payment_check)\x20'+'exists\x20specifically\x20to\x20enforce\x20the\x20match\x20(payment.move:54).','affected_stakeholders':['signer','recipient'],'scenario':'Caller\x20uses\x20unwrap\x20on\x20a\x20wrapper\x20from\x20a\x20different\x20Payment;\x20funds\x20are\x20released\x20anyway','mitigation':'SDK\x20should\x20force\x20callers\x20to\x20use\x20unwrap_with_check\x20and\x20deprecate\x20direct\x20unwrap\x20calls.\x20'+'The\x20only\x20safe\x20use\x20of\x20unwrap\x20is\x20when\x20the\x20caller\x20has\x20already\x20verified\x20the\x20match\x20off-chain.','related_move_error':'EPAYMENT_NOT_MATCH\x20(3)\x20—\x20only\x20raised\x20by\x20unwrap_with_check','auto_fixable':![]},'check':a=>{if(!a['uses_unsafe_unwrap'])return null;return{...R_P_01['rule'],'evidence':'uses_unsafe_unwrap=true\x20(no\x20Payment\x20match\x20check)'};}},R_P_02={'rule':{'id':'R-PAYMENT-02','level':'MEDIUM','category':'structural','title':'MAX_RECIPIENT_COUNT='+MAX_RECIPIENT_COUNT+'\x20permissive\x20—\x20gas\x20and\x20confirmation\x20cost','description':'A\x20single\x20Payment\x20may\x20carry\x20up\x20to\x20MAX_RECIPIENT_COUNT='+MAX_RECIPIENT_COUNT+'\x20recipients\x20'+'(payment.move:14).\x20The\x20limit\x20aborts\x20with\x20ERECIPIENT_COUNT_EXCEEDED\x20(1)\x20only\x20at\x20the\x20boundary.\x20'+'200\x20recipients\x20in\x20one\x20transaction\x20inflates\x20gas,\x20slows\x20finalization,\x20and\x20complicates\x20'+'retry\x20on\x20partial\x20failure.','affected_stakeholders':['signer','recipient'],'scenario':'Caller\x20submits\x20a\x20Payment\x20with\x20200\x20recipients;\x20transaction\x20is\x20heavy\x20and\x20slow','mitigation':'Business\x20layer\x20should\x20self-limit\x20recipient\x20count\x20(e.g.\x20≤50).\x20For\x20mass\x20payouts,\x20split\x20'+'across\x20multiple\x20Payment\x20objects\x20in\x20separate\x20transactions.','related_move_error':'ERECIPIENT_COUNT_EXCEEDED\x20(1)','auto_fixable':![]},'check':a=>{if(a['recipient_count']===undefined)return null;if(a['recipient_count']<MAX_RECIPIENT_COUNT)return null;return{...R_P_02['rule'],'evidence':'recipient_count='+a['recipient_count']+',\x20limit='+MAX_RECIPIENT_COUNT};}},R_P_03={'rule':{'id':'R-PAYMENT-03','level':'LOW','category':'lifecycle','title':'Payment\x20is\x20immutable\x20after\x20create\x20—\x20errors\x20cannot\x20be\x20corrected','description':'create()\x20calls\x20transfer::freeze_object(payment)\x20(payment.move:160).\x20All\x20fields\x20'+'(amount,\x20time,\x20info,\x20from_object,\x20signer,\x20record)\x20are\x20permanently\x20fixed.\x20There\x20is\x20no\x20'+'update,\x20refund,\x20or\x20void\x20API\x20on\x20the\x20Payment\x20object\x20itself\x20—\x20correction\x20requires\x20a\x20new\x20'+'Payment\x20(and\x20off-chain\x20reconciliation).','affected_stakeholders':['signer','consumer'],'scenario':'Signer\x20mistypes\x20a\x20recipient\x20address;\x20the\x20Payment\x20cannot\x20be\x20edited\x20post-create','mitigation':'Verify\x20all\x20fields\x20before\x20calling\x20create.\x20For\x20refunds,\x20create\x20a\x20new\x20Payment\x20in\x20the\x20'+'opposite\x20direction.\x20Off-chain\x20systems\x20should\x20treat\x20Payment\x20as\x20an\x20immutable\x20receipt.','auto_fixable':![]},'check':a=>{if(!a['expects_mutation'])return null;return{...R_P_03['rule'],'evidence':'expects_mutation=true\x20(Payment\x20is\x20frozen\x20at\x20create)'};}},R_P_04={'rule':{'id':'R-PAYMENT-04','level':'MEDIUM','category':'structural','title':'CoinWrapper\x20suppresses\x20coin_field\x20lint\x20—\x20Balance<T>\x20stored\x20in\x20a\x20struct\x20field','description':'CoinWrapper<phantom\x20T>\x20stores\x20Balance<T>\x20directly\x20in\x20a\x20struct\x20field\x20and\x20uses\x20'+'#[allow(lint(coin_field))]\x20to\x20suppress\x20the\x20Wow\x20lint\x20(payment.move:43-48).\x20The\x20lint\x20'+'normally\x20warns\x20against\x20storing\x20Balance\x20in\x20arbitrary\x20structs\x20because\x20of\x20object\x20'+'lifecycle\x20concerns.\x20The\x20suppression\x20is\x20intentional\x20but\x20should\x20be\x20reviewed\x20whenever\x20'+'the\x20Wow\x20framework\x20updates\x20its\x20coin_field\x20rules.','affected_stakeholders':['system'],'scenario':'Wow\x20framework\x20tightens\x20coin_field\x20lint\x20semantics;\x20CoinWrapper\x20becomes\x20non-compliant','mitigation':'Review\x20the\x20coin_field\x20suppression\x20on\x20each\x20Wow\x20upgrade.\x20Confirm\x20that\x20Balance<T>\x20'+'ownership\x20transfer\x20in\x20unwrap/unwrap_with_check\x20is\x20correct.','auto_fixable':![]},'check':a=>{if(a['coin_field_lint_reviewed'])return null;return{...R_P_04['rule'],'evidence':'coin_field_lint_reviewed=false\x20(needs\x20review)'};}},R_P_05={'rule':{'id':'R-PAYMENT-05','level':'LOW','category':'semantic','title':'PaymentInfo\x20has\x204\x20constructor\x20variants\x20—\x20caller\x20may\x20pick\x20the\x20wrong\x20one','description':'PaymentInfo\x20can\x20be\x20built\x20via\x20payment_info\x20(for_object+remark+index),\x20payment_info2\x20'+'(remark+index,\x20no\x20for_object),\x20payment_info_with_guard\x20(for_object+for_guard+remark+index),\x20'+'or\x20payment_info2_with_guard\x20(for_guard+remark+index,\x20no\x20for_object).\x20Selecting\x20the\x20'+'wrong\x20variant\x20leaves\x20for_object/for_guard\x20as\x20None,\x20breaking\x20downstream\x20lookups.','affected_stakeholders':['signer','consumer'],'scenario':'Caller\x20uses\x20payment_info2\x20when\x20they\x20meant\x20payment_info_with_guard;\x20for_object\x20is\x20lost','mitigation':'Document\x20each\x20variant\x27s\x20use\x20case\x20clearly.\x20SDK\x20should\x20pick\x20the\x20variant\x20automatically\x20'+'based\x20on\x20which\x20optional\x20fields\x20the\x20caller\x20provides.','auto_fixable':!![]},'check':a=>null},R_P_06={'rule':{'id':'R-PAYMENT-06','level':'MEDIUM','category':'cross_object','title':'Registrar\x20registration\x20filters\x20recipients\x20by\x20is_object_address\x20—\x20user\x20addresses\x20skipped','description':'create()\x20iterates\x20recipients\x20and\x20only\x20calls\x20registrar.affiliation\x20for\x20addresses\x20that\x20'+'pass\x20util::is_object_address\x20(payment.move:147-161).\x20User\x20addresses\x20(EOAs)\x20are\x20not\x20'+'registered\x20in\x20the\x20Registrar\x20dependency\x20graph.\x20Callers\x20who\x20expect\x20every\x20recipient\x20to\x20'+'appear\x20in\x20affiliation\x20queries\x20will\x20miss\x20EOA\x20recipients.','affected_stakeholders':['signer','consumer'],'scenario':'Caller\x20queries\x20Registrar\x20for\x20all\x20Payment\x20recipients;\x20EOA\x20recipients\x20are\x20missing','mitigation':'Document\x20that\x20affiliation\x20is\x20registered\x20only\x20for\x20object-address\x20recipients.\x20Off-chain\x20'+'systems\x20should\x20track\x20EOA\x20recipients\x20via\x20the\x20NewPaymentEvent\x20record,\x20not\x20via\x20Registrar.','auto_fixable':![]},'check':a=>{if(!a['expects_user_recipient_registered'])return null;return{...R_P_06['rule'],'evidence':'expects_user_recipient_registered=true\x20(EOAs\x20are\x20skipped)'};}},R_P_07={'rule':{'id':'R-PAYMENT-07','level':'LOW','category':'semantic','title':'Payment.signer\x20records\x20payer\x20—\x20useful\x20for\x20provenance\x20but\x20not\x20authorization','description':'Payment.signer\x20is\x20set\x20to\x20ctx.sender()\x20at\x20creation\x20(payment.move).\x20It\x20can\x20be\x20read\x20via\x20'+'payment_signer<T>(payment)\x20for\x20provenance\x20(e.g.\x20\x27who\x20paid\x20for\x20this\x20order\x27).\x20It\x20is\x20'+'purely\x20informational\x20—\x20it\x20does\x20NOT\x20authorize\x20any\x20later\x20operation.\x20Consumers\x20must\x20not\x20'+'treat\x20signer\x20as\x20a\x20permission\x20grant.','affected_stakeholders':['consumer'],'scenario':'Consumer\x20treats\x20Payment.signer\x20as\x20authorizing\x20a\x20refund;\x20signer\x20is\x20just\x20provenance','mitigation':'Use\x20Payment.signer\x20only\x20for\x20audit/provenance.\x20Authorization\x20must\x20come\x20from\x20the\x20'+'referencing\x20object\x27s\x20own\x20Permission,\x20not\x20from\x20Payment.signer.','auto_fixable':![]},'check':a=>{if(!a['uses_signer_for_provenance'])return null;return{...R_P_07['rule'],'evidence':'uses_signer_for_provenance=true\x20(informational\x20only)'};}},R_P_08={'rule':{'id':'R-PAYMENT-08','level':'MEDIUM','category':'semantic','title':'Payment\x20scene\x20binding\x20(for_object\x20+\x20for_guard\x20+\x20index)\x20—\x20anti-reuse\x20for\x20exception\x20branches','description':'PaymentInfo\x20supports\x20for_object\x20(binds\x20to\x20specific\x20Order),\x20for_guard\x20(binds\x20to\x20specific\x20Guard),\x20'+'and\x20index\x20(binds\x20to\x20specific\x20Progress\x20step)\x20—\x20payment.move#L66-71.\x20When\x20all\x20three\x20are\x20set\x20via\x20'+'payment_info_with_guard\x20(payment.move#L82-86),\x20the\x20Payment\x20is\x20scene-bound:\x20it\x20can\x20ONLY\x20be\x20used\x20'+'in\x20the\x20specific\x20order\x20+\x20guard\x20+\x20progress\x20context.\x20This\x20is\x20the\x20anti-reuse\x20design\x20for\x20exception\x20'+'branch\x20compensation\x20(e.g.,\x20delivery\x20delay\x20>30min\x20triggers\x20auto-compensation).\x20'+'Payment\x20is\x20immutable\x20(freeze_object,\x20payment.move#L160)\x20—\x20binding\x20cannot\x20be\x20altered.\x20'+'VERIFIER-EVIDENCE\x20DESIGN:\x20customer\x20submits\x20Payment,\x20Guard\x20verifies\x20binding\x20fields\x20match\x20current\x20context.','affected_stakeholders':['signer','recipient','consumer'],'scenario':'Treasury\x20creates\x20compensation\x20Payment\x20with\x20PaymentInfo(for_object=order,\x20for_guard=exception_guard,\x20index=current_progress)\x20for\x20delivery\x20delay','mitigation':'Use\x20payment_info_with_guard\x20for\x20all\x20exception\x20branch\x20Payments.\x20Ensure\x20for_object,\x20for_guard,\x20and\x20index\x20'+'all\x20match\x20the\x20intended\x20context.\x20Use\x20tpl_payment_exception_compensation\x20(guard-templates.ts)\x20as\x20design\x20template.','auto_fixable':![]},'check':a=>{if(!a['uses_scene_binding'])return null;const b=[];if(!a['has_for_object'])b['push']('for_object\x20not\x20set\x20(Order\x20binding\x20missing)');if(!a['has_for_guard'])b['push']('for_guard\x20not\x20set\x20(Guard\x20binding\x20missing)');if(!a['has_index'])b['push']('index\x20not\x20set\x20(Progress\x20step\x20binding\x20missing)');if(b['length']===0x0)return null;return{...R_P_08['rule'],'evidence':'incomplete\x20scene\x20binding:\x20'+b['join'](',\x20')};}},R_P_09={'rule':{'id':'R-PAYMENT-09','level':'LOW','category':'semantic','title':'PaymentInfo\x20variant\x20selection\x20—\x20use\x20payment_info_with_guard\x20for\x20exception\x20branches','description':'PaymentInfo\x20has\x204\x20constructor\x20variants\x20(payment.move#L66-86):\x20'+'payment_info\x20(for_object+remark+index,\x20no\x20for_guard),\x20'+'payment_info2\x20(remark+index,\x20no\x20for_object/for_guard),\x20'+'payment_info_with_guard\x20(for_object+for_guard+remark+index\x20—\x20FULL\x20binding),\x20'+'payment_info2_with_guard\x20(for_guard+remark+index,\x20no\x20for_object).\x20'+'For\x20exception\x20branch\x20compensation,\x20ALWAYS\x20use\x20payment_info_with_guard\x20to\x20get\x20full\x20scene\x20binding.\x20'+'Using\x20payment_info\x20(without\x20for_guard)\x20or\x20payment_info2\x20(without\x20for_object)\x20weakens\x20anti-reuse\x20protection.','affected_stakeholders':['signer','consumer'],'scenario':'Caller\x20uses\x20payment_info\x20instead\x20of\x20payment_info_with_guard\x20for\x20exception\x20compensation;\x20for_guard\x20is\x20lost','mitigation':'For\x20exception\x20branch\x20Payments:\x20always\x20use\x20payment_info_with_guard(for_object,\x20for_guard,\x20remark,\x20index).\x20'+'For\x20simple\x20Payments\x20without\x20scene\x20binding:\x20payment_info\x20or\x20payment_info2\x20is\x20fine.\x20'+'SDK\x20should\x20auto-select\x20the\x20variant\x20based\x20on\x20which\x20fields\x20are\x20provided.','auto_fixable':!![]},'check':a=>{if(!a['uses_scene_binding'])return null;if(a['payment_info_variant']==='payment_info_with_guard')return null;return{...R_P_09['rule'],'evidence':'uses_scene_binding=true\x20but\x20variant='+(a['payment_info_variant']??'unknown')+'\x20(should\x20be\x20payment_info_with_guard)'};}};export const PAYMENT_RISK_RULES=[R_P_01,R_P_02,R_P_03,R_P_04,R_P_05,R_P_06,R_P_07,R_P_08,R_P_09];export const PAYMENT_RISK_VERSION='1.0.0';export function checkPaymentRisks(a){const b=[];for(const c of PAYMENT_RISK_RULES){const d=c['check'](a);if(d)b['push'](d);}return!b['find'](e=>e['id']==='R-PAYMENT-05')&&b['push'](R_P_05['rule']),b;}export function getPaymentRiskById(a){return PAYMENT_RISK_RULES['find'](b=>b['rule']['id']===a)?.['rule'];}

package/dist/knowledge/payment-translation.d.ts

@@ -0,0 +1,37 @@
+export declare const PAYMENT_TRANSLATION_VERSION = "1.0.0";
+export interface SemanticToPaymentSchemaRule {
+    id: string;
+    pattern_name: string;
+    semantic_intent: string;
+    match_keywords: string[];
+    required_fields: string[];
+    optional_fields: string[];
+    example: Record<string, unknown>;
+}
+export declare const SEMANTIC_TO_PAYMENT_SCHEMA_RULES: SemanticToPaymentSchemaRule[];
+export interface PaymentFieldTranslation {
+    field_name: string;
+    value_type: string;
+    semantic: string;
+    format_example: string;
+    validation_rules: string[];
+}
+export declare const PAYMENT_FIELD_TRANSLATIONS: PaymentFieldTranslation[];
+export interface PaymentConstraintRule {
+    id: string;
+    name: string;
+    description: string;
+    related_field: string;
+}
+export declare const PAYMENT_CONSTRAINT_RULES: PaymentConstraintRule[];
+export interface PaymentExplainInput {
+    recipient_count?: number;
+    payment_info_variant?: "payment_info" | "payment_info2" | "payment_info_with_guard" | "payment_info2_with_guard";
+    amount?: number;
+}
+export interface PaymentExplanation {
+    summary: string;
+    variant: string;
+    warnings: string[];
+}
+export declare function explainPayment(input: PaymentExplainInput): PaymentExplanation;

package/dist/knowledge/payment-translation.js

@@ -0,0 +1 @@
+import{MAX_RECIPIENT_COUNT}from'@wowok/wowok';export const PAYMENT_TRANSLATION_VERSION='1.0.0';export const SEMANTIC_TO_PAYMENT_SCHEMA_RULES=[{'id':'P-PAYMENT-01','pattern_name':'Single-recipient\x20payment','semantic_intent':'Pay\x20a\x20single\x20recipient\x20(new_singleton\x20wraps\x20a\x20CoinWrapper).','match_keywords':['pay','single\x20payment','send\x20to'],'required_fields':['recipient','coin','info'],'optional_fields':[],'example':{'recipient':'0x...','coin':'0x...','info':{'remark':'refund','index':0x0}}},{'id':'P-PAYMENT-02','pattern_name':'Multi-recipient\x20payment','semantic_intent':'Split\x20coins\x20across\x20multiple\x20recipients\x20(new).','match_keywords':['batch\x20pay','multi\x20recipient','mass\x20payout'],'required_fields':['recipient','coin','info'],'optional_fields':[],'example':{'recipient':['0x...','0x...'],'coin':['0x...','0x...'],'info':{'remark':'split','index':0x0}}},{'id':'P-PAYMENT-03','pattern_name':'Scene-bound\x20compensation','semantic_intent':'Exception-branch\x20compensation\x20with\x20full\x20scene\x20binding\x20(for_object+for_guard+index).','match_keywords':['compensation','exception','auto\x20refund'],'required_fields':['recipient','coin','info'],'optional_fields':[],'example':{'recipient':'0x...','coin':'0x...','info':{'for_object':'0x...','for_guard':'0x...','remark':'delay','index':0x2}}}];export const PAYMENT_FIELD_TRANSLATIONS=[{'field_name':'amount','value_type':'u64','semantic':'Total\x20transferred\x20amount.','format_example':'1000000000','validation_rules':['derived\x20from\x20coin\x20values']},{'field_name':'time','value_type':'u64','semantic':'Creation\x20timestamp\x20(clock::timestamp_ms).','format_example':'1710000000000','validation_rules':['frozen\x20at\x20create']},{'field_name':'info','value_type':'PaymentInfo','semantic':'Context\x20binding:\x20for_object\x20/\x20for_guard\x20/\x20remark\x20/\x20index.','format_example':'{for_object,\x20for_guard,\x20remark,\x20index}','validation_rules':['remark\x20uses\x20common::NAME_ALLOW_EMPTY']},{'field_name':'from_object','value_type':'Option<address>','semantic':'Source\x20object\x20(set\x20via\x20from_object_set).','format_example':'0x...order...','validation_rules':['optional']},{'field_name':'signer','value_type':'address','semantic':'Payer\x20address\x20(provenance\x20only,\x20not\x20authorization).','format_example':'0x...payer...','validation_rules':['informational']},{'field_name':'record','value_type':'vector<Revenue>','semantic':'Recipient\x20list\x20(≤\x20MAX_RECIPIENT_COUNT\x20'+MAX_RECIPIENT_COUNT+');\x20Revenue{recipient,\x20amount}.','format_example':'[{recipient,\x20amount}]','validation_rules':['ERECIPIENT_EMPTY\x20(4)\x20when\x200','ERECIPIENT_COUNT_EXCEEDED\x20(1)\x20at\x20cap','EVECTOR_COUNT_NOT_EQUAL\x20(2)']}];export const PAYMENT_CONSTRAINT_RULES=[{'id':'PAYMENT_C_01','name':'recipient\x20count','description':'0\x20<\x20count\x20≤\x20MAX_RECIPIENT_COUNT\x20('+MAX_RECIPIENT_COUNT+').','related_field':'record'},{'id':'PAYMENT_C_02','name':'vector\x20length\x20match','description':'recipient\x20count\x20==\x20coin\x20count\x20(EVECTOR_COUNT_NOT_EQUAL\x202).','related_field':'record'},{'id':'PAYMENT_C_03','name':'unwrap\x20match','description':'unwrap_with_check\x20enforces\x20payment\x20match\x20(EPAYMENT_NOT_MATCH\x203).','related_field':'record'},{'id':'PAYMENT_C_04','name':'immutability','description':'create()\x20freezes\x20the\x20Payment;\x20no\x20post-create\x20edit.','related_field':'amount'}];export function explainPayment(a){const b=[],c=a['payment_info_variant']??'unknown';if(a['recipient_count']!==undefined){if(a['recipient_count']<=0x0)b['push']('recipient_count\x200\x20→\x20ERECIPIENT_EMPTY');if(a['recipient_count']>MAX_RECIPIENT_COUNT)b['push']('recipient_count\x20'+a['recipient_count']+'\x20>\x20'+MAX_RECIPIENT_COUNT);}return a['payment_info_variant']&&a['payment_info_variant']!=='payment_info_with_guard'&&b['push']('consider\x20payment_info_with_guard\x20for\x20scene-bound\x20exception\x20payments'),{'summary':'Payment\x20amount='+(a['amount']??'?')+'.\x20variant='+c+'.\x20'+(a['recipient_count']??'?')+'\x20recipients.','variant':c,'warnings':b};}