@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/allocation-puzzle.js

@@ -0,0 +1,298 @@
+import { MAX_ALLOCATOR_COUNT, ALLOCATION_MAX_SHARING_COUNT, RATE_TOTAL_FULL, } from "./allocation-ledger.js";
+export function initPuzzleFromIntent(intent) {
+    const puzzle = {};
+    if (intent.action || intent.distribution_goal || intent.trigger_condition) {
+        puzzle.intent = {
+            action: intent.action ?? "create",
+            host_context: intent.host_context ?? "service_order_allocators",
+            trigger_condition: intent.trigger_condition ?? "",
+            distribution_goal: intent.distribution_goal ?? "",
+            failure_conditions: intent.failure_conditions ?? [],
+        };
+    }
+    puzzle.constraints = {
+        F_A_01_allocator_count_le_100: true,
+        F_A_02_sharing_count_le_100: true,
+        F_A_03_sharing_mode_valid: true,
+        F_A_04_at_most_1_surplus_per_allocator: true,
+        F_A_05_pure_rate_sum_eq_10000: true,
+        F_A_06_rate_plus_surplus_sum_le_10000: true,
+        F_A_07_amount_sum_ge_threshold: true,
+        F_A_08_amount_sum_le_max: true,
+        F_A_09_balance_ge_threshold_at_alloc: true,
+        F_A_10_payment_info_present: true,
+        F_A_11_allocators_not_empty: true,
+        F_A_12_order_at_most_1_allocation: true,
+        F_A_13_guard_identifier_is_address: true,
+        F_A_14_guard_addresses_unique: true,
+        F_A_15_order_allocators_immutable_after_publish: true,
+    };
+    return puzzle;
+}
+export function checkPuzzleCompleteness(puzzle) {
+    const missing = [];
+    const missing_details = [];
+    if (!puzzle.intent) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "Intent not specified (action + distribution_goal)" });
+    }
+    else if (!puzzle.intent.distribution_goal) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "distribution_goal is empty" });
+    }
+    else if (!puzzle.intent.host_context) {
+        missing.push("A");
+        missing_details.push({ dimension: "A", reason: "host_context (trigger source) must be specified" });
+    }
+    if (!puzzle.binding) {
+        missing.push("B");
+        missing_details.push({ dimension: "B", reason: "Binding not specified (coin_type + guard_objects)" });
+    }
+    else if (!puzzle.binding.coin_type) {
+        missing.push("B");
+        missing_details.push({ dimension: "B", reason: "coin_type is missing" });
+    }
+    else if (puzzle.binding.guard_objects.length === 0) {
+        missing.push("B");
+        missing_details.push({ dimension: "B", reason: "guard_objects list is empty — at least 1 Guard required" });
+    }
+    if (!puzzle.data_source && puzzle.intent?.action === "create") {
+        missing.push("C");
+        missing_details.push({ dimension: "C", reason: "Data source not specified (allocators_config + payment_info)" });
+    }
+    else if (puzzle.data_source && puzzle.data_source.allocators_config.allocators.length === 0) {
+        missing.push("C");
+        missing_details.push({ dimension: "C", reason: "allocators_config.allocators is empty" });
+    }
+    if (!puzzle.operations) {
+        missing.push("D");
+        missing_details.push({ dimension: "D", reason: "Operations not enumerated" });
+    }
+    if (!puzzle.logic) {
+        missing.push("E");
+        missing_details.push({ dimension: "E", reason: "Logic flow (7-step alloc) not defined" });
+    }
+    if (!puzzle.constraints) {
+        missing.push("F");
+        missing_details.push({ dimension: "F", reason: "Constraints not checked" });
+    }
+    return {
+        dimensions: ["A", "B", "C", "D", "E", "F"],
+        missing,
+        missing_details,
+        complete: missing.length === 0,
+        next_step: missing.length === 0
+            ? "Puzzle complete — ready for confirmation text generation"
+            : `Next: complete dimension ${missing[0]} — ${missing_details[0].reason}`,
+    };
+}
+export function validateConstraints(puzzle) {
+    const violations = [];
+    if (!puzzle.data_source)
+        return violations;
+    const cfg = puzzle.data_source.allocators_config;
+    if (cfg.allocators.length > MAX_ALLOCATOR_COUNT) {
+        violations.push({
+            constraint_id: "F-A-01",
+            severity: "CRITICAL",
+            message: `Allocator count ${cfg.allocators.length} exceeds MAX_ALLOCATOR_COUNT ${MAX_ALLOCATOR_COUNT}`,
+            current_value: cfg.allocators.length,
+            limit: MAX_ALLOCATOR_COUNT,
+            related_move_error: "EALLOCATOR_COUNT_EXCEEDED (2)",
+        });
+    }
+    if (cfg.allocators.length === 0) {
+        violations.push({
+            constraint_id: "F-A-11",
+            severity: "CRITICAL",
+            message: "allocators.allocators is empty — at least 1 Allocator required",
+            related_move_error: "EALLOCATORS_EMPTY (8) / ENO_ALLOCATOR (3)",
+        });
+    }
+    const guardAddrs = cfg.allocators.map(a => a.guard);
+    const uniqueGuards = new Set(guardAddrs);
+    if (uniqueGuards.size !== guardAddrs.length) {
+        violations.push({
+            constraint_id: "F-A-14",
+            severity: "MEDIUM",
+            message: `Duplicate Guard addresses in allocators (${guardAddrs.length} entries, ${uniqueGuards.size} unique) — alloc_by_guard address match only hits the first, subsequent duplicate Allocators are never reachable`,
+        });
+    }
+    for (const allocator of cfg.allocators) {
+        if (allocator.sharing.length > ALLOCATION_MAX_SHARING_COUNT) {
+            violations.push({
+                constraint_id: "F-A-02",
+                severity: "CRITICAL",
+                message: `Allocator ${allocator.guard} has ${allocator.sharing.length} sharing entries, exceeds MAX_SHARING_COUNT ${ALLOCATION_MAX_SHARING_COUNT}`,
+                current_value: allocator.sharing.length,
+                limit: ALLOCATION_MAX_SHARING_COUNT,
+                related_move_error: "ESHARING_COUNT_EXCEEDED (10)",
+            });
+        }
+        for (const s of allocator.sharing) {
+            if (!["Amount", "Rate", "Surplus"].includes(s.mode)) {
+                violations.push({
+                    constraint_id: "F-A-03",
+                    severity: "CRITICAL",
+                    message: `Invalid sharing mode: ${s.mode}`,
+                    related_move_error: "ESHARING_MODE_INVALID (11)",
+                });
+            }
+        }
+        const surplusCount = allocator.sharing.filter(s => s.mode === "Surplus").length;
+        if (surplusCount > 1) {
+            violations.push({
+                constraint_id: "F-A-04",
+                severity: "HIGH",
+                message: `Allocator ${allocator.guard} has ${surplusCount} Surplus sharing — at most 1 allowed`,
+                current_value: surplusCount,
+                limit: 1,
+                related_move_error: "EMULTIPLE_SURPLUS (5)",
+            });
+        }
+        const rateSum = allocator.sharing
+            .filter(s => s.mode === "Rate")
+            .reduce((sum, s) => sum + Number(s.sharing), 0);
+        const hasSurplus = surplusCount > 0;
+        if (!hasSurplus && rateSum > 0 && rateSum !== RATE_TOTAL_FULL) {
+            violations.push({
+                constraint_id: "F-A-05",
+                severity: "HIGH",
+                message: `Pure Rate mode (no Surplus) sum ${rateSum} != ${RATE_TOTAL_FULL}`,
+                current_value: rateSum,
+                limit: RATE_TOTAL_FULL,
+                related_move_error: "ERATE_NOT_10000 (4)",
+            });
+        }
+        if (hasSurplus && rateSum > RATE_TOTAL_FULL) {
+            violations.push({
+                constraint_id: "F-A-06",
+                severity: "HIGH",
+                message: `Rate + Surplus mode sum ${rateSum} > ${RATE_TOTAL_FULL}`,
+                current_value: rateSum,
+                limit: RATE_TOTAL_FULL,
+                related_move_error: "ERATE_EXCEEDS_10000 (6)",
+            });
+        }
+        const amountSum = allocator.sharing
+            .filter(s => s.mode === "Amount")
+            .reduce((sum, s) => sum + Number(s.sharing), 0);
+        const threshold = Number(cfg.threshold);
+        if (amountSum > 0 && amountSum < threshold) {
+            violations.push({
+                constraint_id: "F-A-07",
+                severity: "HIGH",
+                message: `Amount sum ${amountSum} < threshold ${threshold}`,
+                current_value: amountSum,
+                limit: threshold,
+                related_move_error: "EAMOUNT_BELOW_THRESHOLD (12)",
+            });
+        }
+        if (allocator.max != null && amountSum > Number(allocator.max)) {
+            violations.push({
+                constraint_id: "F-A-08",
+                severity: "MEDIUM",
+                message: `Amount sum ${amountSum} > max ${Number(allocator.max)}`,
+                current_value: amountSum,
+                limit: Number(allocator.max),
+                related_move_error: "EAMOUNT_EXCEEDS_MAX (13)",
+            });
+        }
+        const guardIdSharing = allocator.sharing.find(s => typeof s.who === "object" && "GuardIdentifier" in s.who);
+        if (guardIdSharing) {
+        }
+    }
+    return violations;
+}
+export function generateConfirmationText(puzzle) {
+    const lines = [];
+    lines.push("═══ Allocation Confirmation ═══");
+    lines.push("");
+    if (puzzle.intent) {
+        lines.push(`Action: ${puzzle.intent.action}`);
+        lines.push(`Host context: ${puzzle.intent.host_context}`);
+        lines.push(`Trigger: ${puzzle.intent.trigger_condition}`);
+        lines.push(`Distribution goal: ${puzzle.intent.distribution_goal}`);
+        if (puzzle.intent.failure_conditions.length > 0) {
+            lines.push("Failure conditions:");
+            for (const fc of puzzle.intent.failure_conditions)
+                lines.push(`  - ${fc}`);
+        }
+        lines.push("");
+    }
+    if (puzzle.binding) {
+        lines.push("─ Binding ──────────────");
+        lines.push(`Coin type: ${puzzle.binding.coin_type}`);
+        if (puzzle.binding.host_service)
+            lines.push(`Host Service: ${puzzle.binding.host_service}`);
+        if (puzzle.binding.host_arbitration)
+            lines.push(`Host Arbitration: ${puzzle.binding.host_arbitration}`);
+        if (puzzle.binding.bound_order)
+            lines.push(`Bound Order: ${puzzle.binding.bound_order}`);
+        if (puzzle.binding.trigger_node)
+            lines.push(`Trigger node: ${puzzle.binding.trigger_node}`);
+        lines.push(`Guard objects (${puzzle.binding.guard_objects.length}): ${puzzle.binding.guard_objects.join(", ")}`);
+        lines.push(`Payment info source: ${puzzle.binding.payment_info_source}`);
+        lines.push("");
+    }
+    if (puzzle.data_source) {
+        const cfg = puzzle.data_source.allocators_config;
+        lines.push("─ Data Source ──────────────");
+        lines.push(`Description: ${cfg.description}`);
+        lines.push(`Threshold: ${cfg.threshold}`);
+        lines.push(`Allocators: ${cfg.allocators.length}`);
+        cfg.allocators.forEach((a, i) => {
+            lines.push(`  [${i}] guard=${a.guard}, sharing=${a.sharing.length} items, fix=${a.fix ?? "0"}, max=${a.max ?? "null"}`);
+            a.sharing.forEach((s, j) => {
+                lines.push(`      (${j}) who=${JSON.stringify(s.who)}, sharing=${s.sharing}, mode=${s.mode}`);
+            });
+        });
+        lines.push(`Payment info for_object: ${puzzle.data_source.payment_info.for_object}`);
+        lines.push(`Coin source: ${puzzle.data_source.coin_source}`);
+        lines.push("");
+    }
+    if (puzzle.logic) {
+        lines.push("─ Logic ──────────────");
+        lines.push(`Guard matching: ${puzzle.logic.guard_matching_strategy}`);
+        lines.push(`alloc() flow (${puzzle.logic.alloc_flow.length} steps):`);
+        for (const step of puzzle.logic.alloc_flow) {
+            lines.push(`  ${step.step}. ${step.action}: ${step.description}`);
+        }
+        lines.push("");
+    }
+    const violations = validateConstraints(puzzle);
+    if (violations.length > 0) {
+        lines.push("─ Constraint Violations ──────────────");
+        for (const v of violations) {
+            lines.push(`  [${v.severity}] ${v.constraint_id}: ${v.message}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function buildDefaultAllocFlow() {
+    return [
+        { step: 1, action: "pre_check", description: "assert balance >= threshold, payment_info.is_some(), allocators not empty" },
+        { step: 2, action: "guard_lookup", description: "iterate allocators[], locate alloc.guard == alloc_by_guard address; on hit call passport::result_for_guard hard verification (failure aborts E_VERIFY_FAILED)" },
+        { step: 3, action: "rate_base_calc", description: "total_rates = max - fix (if max) else balance - fix" },
+        { step: 4, action: "sharing_distribution", description: "iterate sharing[], split by mode (Amount/Rate/Surplus placeholder)" },
+        { step: 5, action: "surplus_distribution", description: "withdraw_all to surplus_recipient (if any)" },
+        { step: 6, action: "recipient_resolution", description: "resolve address from GuardIdentifier(passport) / Entity(static) / Signer(tx sender)" },
+        { step: 7, action: "payment_creation", description: "create Payment object, push to self.payment vector" },
+    ];
+}
+export function buildDefaultRecipientRules() {
+    return [
+        { recipient_type: "GuardIdentifier", resolution_source: "passport_table", safety_level: "safe" },
+        { recipient_type: "Entity", resolution_source: "static_address", safety_level: "safe" },
+        { recipient_type: "Signer", resolution_source: "tx_sender", safety_level: "dangerous" },
+    ];
+}
+export function buildDefaultLogicPuzzle() {
+    return {
+        alloc_flow: buildDefaultAllocFlow(),
+        guard_matching_strategy: "caller_specified_guard",
+        recipient_resolution_rules: buildDefaultRecipientRules(),
+    };
+}
+export const ALLOCATION_PUZZLE_VERSION = "1.0.0";

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

@@ -0,0 +1,78 @@
+import { ALLOCATION_ERROR_CODES, type AllocationScene } from "./allocation-ledger.js";
+export type AllocationRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+export type AllocationRiskCategory = "structural" | "semantic" | "authority" | "lifecycle" | "cross_object";
+export interface AllocationRisk {
+    id: string;
+    level: AllocationRiskLevel;
+    category: AllocationRiskCategory;
+    title: string;
+    description: string;
+    affected_stakeholders: AllocationStakeholder[];
+    scenario: string;
+    mitigation: string;
+    evidence?: string;
+    related_move_error?: string;
+    related_guard_risk?: string;
+    auto_fixable: boolean;
+}
+export type AllocationStakeholder = "owner" | "allocator" | "recipient" | "service_provider" | "system";
+export interface AllocationRiskRule {
+    id: string;
+    category: AllocationRiskCategory;
+    trigger: string;
+    check: (ctx: AllocationRiskCheckContext) => AllocationRisk | null;
+}
+export interface AllocationRiskCheckContext {
+    object?: string | null;
+    allocators_config?: {
+        description?: string;
+        threshold: string | number;
+        allocators: {
+            guard: string;
+            sharing: {
+                who: {
+                    GuardIdentifier: number;
+                } | {
+                    Entity: string;
+                } | {
+                    Signer: "signer";
+                };
+                sharing: string | number;
+                mode: "Amount" | "Rate" | "Surplus";
+            }[];
+            fix?: string | number;
+            max?: string | number | null;
+        }[];
+    };
+    operation_type?: "create" | "receive" | "alloc_by_guard" | "query";
+    coin_type?: string;
+    has_payment_info?: boolean;
+    trigger_source?: "service_order_allocators" | "arbitration_fees" | "standalone";
+    host_service_published?: boolean;
+    host_service_permission?: string;
+    referenced_treasuries_permissions?: Record<string, string>;
+    guard_signer_bindings?: Record<string, boolean>;
+    guard_has_time_lock?: Record<string, boolean>;
+    passport_identifier_types?: Record<number, string>;
+    has_fallback_allocator?: boolean;
+    guard_conditions_mutually_exclusive?: boolean;
+    bound_order?: string;
+    order_already_has_allocation?: boolean;
+}
+export declare const ALLOCATION_RISK_VERSION = "1.0.0";
+export declare function getAllRiskRules(): AllocationRiskRule[];
+export declare function getRiskRulesCount(): number;
+export declare function getRiskRulesByCategory(category: AllocationRiskCategory): AllocationRiskRule[];
+export interface AllocationRiskAssessment {
+    summary: string;
+    scene?: AllocationScene;
+    risks: AllocationRisk[];
+    overall_risk: AllocationRiskLevel;
+    risks_by_category: Partial<Record<AllocationRiskCategory, number>>;
+    risks_by_level: Partial<Record<AllocationRiskLevel, number>>;
+    stakeholder_advice: Partial<Record<AllocationStakeholder, string[]>>;
+    needs_human_review: boolean;
+    blocks_publish: boolean;
+}
+export declare function assessAllocationRisks(ctx: AllocationRiskCheckContext): AllocationRiskAssessment;
+export { ALLOCATION_ERROR_CODES };