@wowok/agent-mcp 2.4.1 → 2.5.0

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

@@ -0,0 +1,58 @@
+import { type AllocationScene, type AllocationMode, type TriggerSource } from "./allocation-ledger.js";
+import { type AllocationTemplate } from "./allocation-templates.js";
+import { type SemanticToSchemaRule } from "./allocation-translation.js";
+import { type AllocationRiskRule, type AllocationRiskAssessment, type AllocationStakeholder } from "./allocation-risk.js";
+import { type AllocationPuzzle, type AllocationPuzzleCompleteness } from "./allocation-puzzle.js";
+import { type ChecklistItem, type ConfirmationQuestion, type AllocationJsonForConfirm } from "./allocation-confirm.js";
+export declare const ALLOCATION_CONTEXT_VERSION = "1.0.0";
+export type AllocationInjectionMode = "initial_design" | "mid_design_review" | "pre_publish" | "post_publish_modify" | "stakeholder_review" | "apply_check";
+export type AllocationStakeholderPerspective = AllocationStakeholder | "system";
+export interface AllocationContextBundle {
+    version: string;
+    mode: AllocationInjectionMode;
+    stakeholder_perspective?: AllocationStakeholderPerspective;
+    matched_scene?: AllocationScene;
+    matched_template?: AllocationTemplate;
+    matched_pattern?: SemanticToSchemaRule;
+    puzzle_state?: AllocationPuzzle;
+    puzzle_completeness?: AllocationPuzzleCompleteness;
+    relevant_risks: AllocationRiskRule[];
+    risk_assessment?: AllocationRiskAssessment;
+    relevant_checklist: ChecklistItem[];
+    relevant_questions: ConfirmationQuestion[];
+    cross_object_refs: AllocationCrossObjectRef[];
+    onchain_constraints: AllocationOnchainConstraint[];
+    rendering_hints: AllocationRenderingHints;
+}
+export interface AllocationCrossObjectRef {
+    object: "Service" | "Order" | "Arbitration" | "Treasury" | "Guard" | "Passport" | "Progress" | "Machine" | "Payment";
+    field: string;
+    scene_id: string;
+    description: string;
+}
+export interface AllocationOnchainConstraint {
+    name: string;
+    value: string | number;
+    description: string;
+}
+export interface AllocationRenderingHints {
+    include_puzzle_template: boolean;
+    include_risk_details: boolean;
+    include_questions: boolean;
+    include_immutability_warning: boolean;
+    include_trigger_warning: boolean;
+    include_rate_overflow_warning: boolean;
+    max_length: number;
+}
+export interface BuildAllocationContextInput {
+    mode: AllocationInjectionMode;
+    intent?: string;
+    allocation_json?: AllocationJsonForConfirm;
+    stakeholder?: AllocationStakeholderPerspective;
+    target_trigger_source?: TriggerSource;
+    target_mode?: AllocationMode;
+    max_length?: number;
+}
+export declare function buildAllocationContext(input: BuildAllocationContextInput): AllocationContextBundle;
+export declare function buildPromptFromAllocationContext(bundle: AllocationContextBundle): string;
+export declare function getAllocationContextSummary(bundle: AllocationContextBundle): string;

package/dist/knowledge/allocation-context.js

@@ -0,0 +1,249 @@
+import { MAX_SHARING_COUNT } from "@wowok/wowok";
+import { ALLOCATION_SCENES, MAX_ALLOCATOR_COUNT, ALLOCATION_MAX_SHARING_COUNT, ALLOCATION_MODE_AMOUNT, ALLOCATION_MODE_RATE, ALLOCATION_MODE_SURPLUS, RATE_TOTAL_FULL, inferSceneFromIntent, getAllScenes, } from "./allocation-ledger.js";
+import { suggestTemplateForScene, } from "./allocation-templates.js";
+import { matchSemanticPattern, } from "./allocation-translation.js";
+import { getAllRiskRules, assessAllocationRisks, } from "./allocation-risk.js";
+import { initPuzzleFromIntent, checkPuzzleCompleteness, } from "./allocation-puzzle.js";
+import { ALLOCATION_PUBLISH_CHECKLIST, ALLOCATION_CONFIRMATION_QUESTIONS, } from "./allocation-confirm.js";
+export const ALLOCATION_CONTEXT_VERSION = "1.0.0";
+export function buildAllocationContext(input) {
+    const max_length = input.max_length ?? 4000;
+    let matched_scene;
+    if (input.intent) {
+        matched_scene = inferSceneFromIntent(input.intent);
+    }
+    if (!matched_scene && input.target_trigger_source) {
+        const scenes = getAllScenes().filter(s => s.trigger_source === input.target_trigger_source);
+        if (scenes.length > 0)
+            matched_scene = scenes[0];
+    }
+    if (!matched_scene && input.target_mode) {
+        const scenes = getAllScenes().filter(s => s.modes_used.includes(input.target_mode));
+        if (scenes.length > 0)
+            matched_scene = scenes[0];
+    }
+    let matched_template;
+    if (matched_scene) {
+        const tpl = suggestTemplateForScene(matched_scene.id);
+        if (tpl)
+            matched_template = tpl;
+    }
+    let matched_pattern;
+    if (input.intent) {
+        const patterns = matchSemanticPattern(input.intent);
+        if (patterns.length > 0)
+            matched_pattern = patterns[0];
+    }
+    let puzzle_state;
+    let puzzle_completeness;
+    if (input.mode === "initial_design" && input.intent) {
+        puzzle_state = initPuzzleFromIntent({ distribution_goal: input.intent });
+        puzzle_completeness = checkPuzzleCompleteness(puzzle_state);
+    }
+    const relevant_risks = filterRiskRules(input.mode, input.stakeholder, matched_scene);
+    let risk_assessment;
+    if (input.mode === "pre_publish" && input.allocation_json) {
+        const ctx = {
+            object: input.allocation_json.object,
+            allocators_config: input.allocation_json.allocators,
+            coin_type: typeof input.allocation_json.coin === "string"
+                ? input.allocation_json.coin
+                : input.allocation_json.coin?.name,
+            has_payment_info: !!input.allocation_json.payment_info,
+        };
+        risk_assessment = assessAllocationRisks(ctx);
+    }
+    const relevant_checklist = filterChecklist(input.mode);
+    const relevant_questions = filterQuestions(input.mode);
+    const cross_object_refs = buildCrossObjectRefs(matched_scene);
+    const onchain_constraints = buildOnchainConstraints();
+    const has_rate_mode = input.allocation_json?.allocators?.allocators?.some(a => a.sharing.some(s => s.mode === "Rate")) ?? false;
+    const has_trigger = !!matched_scene && matched_scene.trigger_source !== "standalone";
+    const rendering_hints = buildRenderingHints(input.mode, max_length, has_trigger, has_rate_mode);
+    return {
+        version: ALLOCATION_CONTEXT_VERSION,
+        mode: input.mode,
+        stakeholder_perspective: input.stakeholder,
+        matched_scene,
+        matched_template,
+        matched_pattern,
+        puzzle_state,
+        puzzle_completeness,
+        relevant_risks,
+        risk_assessment,
+        relevant_checklist,
+        relevant_questions,
+        cross_object_refs,
+        onchain_constraints,
+        rendering_hints,
+    };
+}
+function filterRiskRules(mode, stakeholder, scene) {
+    const rules = getAllRiskRules();
+    if (mode === "initial_design") {
+        return rules.filter(r => r.category === "structural");
+    }
+    if (mode === "pre_publish") {
+        return rules;
+    }
+    if (mode === "stakeholder_review" && stakeholder) {
+        if (stakeholder === "owner") {
+            return rules.filter(r => r.category === "structural" || r.category === "lifecycle");
+        }
+        if (stakeholder === "allocator") {
+            return rules.filter(r => r.category === "structural" || r.category === "semantic");
+        }
+        if (stakeholder === "recipient") {
+            return rules.filter(r => r.category === "semantic");
+        }
+        if (stakeholder === "service_provider") {
+            return rules.filter(r => r.category === "cross_object" || r.category === "lifecycle");
+        }
+    }
+    return rules;
+}
+function filterChecklist(mode) {
+    if (mode === "initial_design") {
+        return ALLOCATION_PUBLISH_CHECKLIST.filter(i => ["C-A-01", "C-A-02", "C-A-03", "C-A-04"].includes(i.id));
+    }
+    if (mode === "post_publish_modify") {
+        return ALLOCATION_PUBLISH_CHECKLIST.filter(i => ["C-A-09", "C-A-10", "C-A-11", "C-A-12"].includes(i.id));
+    }
+    return ALLOCATION_PUBLISH_CHECKLIST;
+}
+function filterQuestions(mode) {
+    if (mode === "pre_publish") {
+        return ALLOCATION_CONFIRMATION_QUESTIONS;
+    }
+    if (mode === "post_publish_modify") {
+        return ALLOCATION_CONFIRMATION_QUESTIONS.filter(q => ["QA4", "QA5", "QA6"].includes(q.id));
+    }
+    return [];
+}
+function buildCrossObjectRefs(scene) {
+    if (!scene)
+        return [];
+    const refs = [];
+    for (const s of ALLOCATION_SCENES) {
+        if (s.id === scene.id)
+            continue;
+        refs.push({
+            object: s.dependencies[0] ?? "Service",
+            field: "allocation",
+            scene_id: s.id,
+            description: `${s.name} (trigger: ${s.trigger_source})`,
+        });
+    }
+    return refs;
+}
+function buildOnchainConstraints() {
+    return [
+        { name: "MAX_SHARING_COUNT", value: MAX_SHARING_COUNT, description: "Maximum sharing entries per allocator (Move: allocation.move:17)" },
+        { name: "MAX_ALLOCATOR_COUNT", value: MAX_ALLOCATOR_COUNT, description: "Maximum allocators per Allocation object (Move: allocation.move:16)" },
+        { name: "ALLOCATION_MAX_SHARING_COUNT", value: ALLOCATION_MAX_SHARING_COUNT, description: "Alias of MAX_SHARING_COUNT (knowledge-layer mirror)" },
+        { name: "ALLOCATION_MODE_AMOUNT", value: ALLOCATION_MODE_AMOUNT, description: "Mode 0: fixed amount distribution" },
+        { name: "ALLOCATION_MODE_RATE", value: ALLOCATION_MODE_RATE, description: "Mode 1: percentage rate (basis points, total = RATE_TOTAL_FULL)" },
+        { name: "ALLOCATION_MODE_SURPLUS", value: ALLOCATION_MODE_SURPLUS, description: "Mode 2: surplus (remainder) distribution" },
+        { name: "RATE_TOTAL_FULL", value: RATE_TOTAL_FULL, description: "100% in basis points (10000) — Rate mode shares must sum to this" },
+    ];
+}
+function buildRenderingHints(mode, max_length, hasTrigger, hasRateMode) {
+    return {
+        include_puzzle_template: mode === "initial_design",
+        include_risk_details: mode === "pre_publish" || mode === "stakeholder_review",
+        include_questions: mode === "pre_publish",
+        include_immutability_warning: mode === "post_publish_modify",
+        include_trigger_warning: hasTrigger,
+        include_rate_overflow_warning: hasRateMode,
+        max_length,
+    };
+}
+export function buildPromptFromAllocationContext(bundle) {
+    const lines = [];
+    const h = bundle.rendering_hints;
+    lines.push(`═══ Allocation Context (mode: ${bundle.mode}) ═══`);
+    lines.push("");
+    if (bundle.matched_scene) {
+        lines.push(`Scene: ${bundle.matched_scene.name}`);
+        lines.push(`Trigger source: ${bundle.matched_scene.trigger_source}`);
+        lines.push(`Distribution strategy: ${bundle.matched_scene.distribution_strategy}`);
+        lines.push(`Typical allocator count: ${bundle.matched_scene.typical_allocator_count}`);
+        lines.push("");
+    }
+    if (bundle.matched_template) {
+        lines.push(`Suggested template: ${bundle.matched_template.id} — ${bundle.matched_template.name}`);
+        lines.push("");
+    }
+    if (h.include_puzzle_template && bundle.puzzle_completeness) {
+        const c = bundle.puzzle_completeness;
+        lines.push("─ Puzzle Completeness ──────────────");
+        lines.push(`Complete: ${c.complete ? "YES" : "NO"}`);
+        if (c.missing.length > 0) {
+            lines.push(`Missing: ${c.missing.join(", ")}`);
+        }
+        lines.push(`Next: ${c.next_step}`);
+        lines.push("");
+    }
+    if (h.include_risk_details && bundle.relevant_risks.length > 0) {
+        lines.push(`─ Relevant Risk Rules (${bundle.relevant_risks.length}) ──────────────`);
+        for (const r of bundle.relevant_risks.slice(0, 5)) {
+            lines.push(`  ${r.id} — ${r.trigger}`);
+        }
+        if (bundle.relevant_risks.length > 5) {
+            lines.push(`  ... and ${bundle.relevant_risks.length - 5} more`);
+        }
+        lines.push("");
+    }
+    if (bundle.risk_assessment) {
+        lines.push("─ Risk Assessment ──────────────");
+        lines.push(`Overall: ${bundle.risk_assessment.summary}`);
+        lines.push(`Detected: ${bundle.risk_assessment.risks.length} risk(s)`);
+        lines.push("");
+    }
+    if (h.include_trigger_warning) {
+        lines.push("⚠️ TRIGGER-AWARE — This Allocation is bound to a trigger source (Service/Arbitration).");
+        lines.push("   Funds flow is automated by on-chain events, not manual invocation.");
+        lines.push("");
+    }
+    if (h.include_rate_overflow_warning) {
+        lines.push("⚠️ RATE MODE — Sharing rates must sum to exactly RATE_TOTAL_FULL (10000 basis points).");
+        lines.push("   Underflow → remaining funds stuck; Overflow → transaction aborts.");
+        lines.push("");
+    }
+    if (h.include_immutability_warning) {
+        lines.push("⚠️ POST-PUBLISH OPERATE — Allocation object is on-chain.");
+        lines.push("   Only receive / alloc_by_guard operations are permitted; allocators are immutable.");
+        lines.push("");
+    }
+    if (bundle.onchain_constraints.length > 0) {
+        lines.push("─ On-chain Constraints ──────────────");
+        for (const c of bundle.onchain_constraints) {
+            lines.push(`  ${c.name} = ${c.value} — ${c.description}`);
+        }
+        lines.push("");
+    }
+    if (bundle.cross_object_refs.length > 0) {
+        lines.push(`─ Cross-object References (${bundle.cross_object_refs.length}) ──────────────`);
+        for (const ref of bundle.cross_object_refs.slice(0, 5)) {
+            lines.push(`  [${ref.object}] ${ref.scene_id}: ${ref.description}`);
+        }
+        if (bundle.cross_object_refs.length > 5) {
+            lines.push(`  ... and ${bundle.cross_object_refs.length - 5} more`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function getAllocationContextSummary(bundle) {
+    const parts = [
+        `mode=${bundle.mode}`,
+        `scene=${bundle.matched_scene?.id ?? "none"}`,
+        `risks=${bundle.relevant_risks.length}`,
+        `refs=${bundle.cross_object_refs.length}`,
+    ];
+    if (bundle.stakeholder_perspective)
+        parts.push(`stakeholder=${bundle.stakeholder_perspective}`);
+    if (bundle.risk_assessment)
+        parts.push(`summary=${bundle.risk_assessment.summary}`);
+    return parts.join(", ");
+}

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

@@ -0,0 +1,67 @@
+import { MAX_ALLOCATOR_COUNT } from "@wowok/wowok";
+export type AllocationMode = "Amount" | "Rate" | "Surplus";
+export type RecipientType = "GuardIdentifier" | "Entity" | "Signer";
+export type TriggerSource = "service_order_allocators" | "arbitration_fees" | "standalone";
+export interface AllocationScene {
+    id: string;
+    name: string;
+    trigger_source: TriggerSource;
+    distribution_strategy: "pure_rate" | "amount_plus_surplus" | "first_match_alternatives" | "tiered_by_amount" | "dynamic_recipient" | "refund_to_order" | "max_capped" | "multi_node_trigger" | "periodic_split" | "time_locked_vesting";
+    coin_type_note: string;
+    typical_allocator_count: number;
+    sharing_who_types: RecipientType[];
+    modes_used: AllocationMode[];
+    guard_requirement: "required" | "multiple_unique" | "single_relaxed" | "any";
+    non_zero_threshold: boolean;
+    uses_max: boolean;
+    common_patterns: string[];
+    dependencies: ("Service" | "Treasury" | "Guard" | "Passport" | "Order" | "Arbitration" | "Progress" | "Machine" | "Payment")[];
+    key_constraints: string[];
+    recommended_templates: string[];
+}
+export { MAX_ALLOCATOR_COUNT };
+export declare const ALLOCATION_MAX_SHARING_COUNT: 100;
+export declare const ALLOCATION_MODE_AMOUNT = 0;
+export declare const ALLOCATION_MODE_RATE = 1;
+export declare const ALLOCATION_MODE_SURPLUS = 2;
+export declare const RATE_TOTAL_FULL = 10000;
+export declare const ALLOCATION_ERROR_CODES: {
+    readonly ERECIPIENT_IDENTIFIER_NOT_ADDRESS: 1;
+    readonly EALLOCATOR_COUNT_EXCEEDED: 2;
+    readonly ENO_ALLOCATOR: 3;
+    readonly ERATE_NOT_10000: 4;
+    readonly EMULTIPLE_SURPLUS: 5;
+    readonly ERATE_EXCEEDS_10000: 6;
+    readonly EINSUFFICIENT_BALANCE: 7;
+    readonly EALLOCATORS_EMPTY: 8;
+    readonly ENO_PAYMENT_INFO: 9;
+    readonly ESHARING_COUNT_EXCEEDED: 10;
+    readonly ESHARING_MODE_INVALID: 11;
+    readonly EAMOUNT_BELOW_THRESHOLD: 12;
+    readonly EAMOUNT_EXCEEDS_MAX: 13;
+};
+export declare const ORDER_ALLOCATION_ALREADY_SPECIFIED = "E_ALLOCATION_ALREADY_SPECIFIED";
+export declare const ALLOCATION_SCENES: AllocationScene[];
+export declare const ALLOCATION_LEDGER_VERSION = "1.0.0";
+export declare function getScenesByTriggerSource(source: TriggerSource): AllocationScene[];
+export declare function getScenesByMode(mode: AllocationMode): AllocationScene[];
+export declare function getScenesByStrategy(strategy: AllocationScene["distribution_strategy"]): AllocationScene[];
+export declare function findSceneById(id: string): AllocationScene | undefined;
+export declare function inferSceneFromIntent(intent: string): AllocationScene | undefined;
+export declare function getAllScenes(): AllocationScene[];
+export declare function getScenesCount(): number;
+export declare function allocationModeToNumber(mode: AllocationMode): number;
+export declare function allocationModeFromNumber(n: number): AllocationMode;
+export type Recipient = {
+    GuardIdentifier: number;
+} | {
+    Entity: string;
+} | {
+    Signer: "signer";
+};
+export declare function getRecipientType(who: Recipient): RecipientType;
+export declare function isSignerRecipient(who: Recipient): boolean;
+export declare function isEntityRecipient(who: Recipient): boolean;
+export declare function isGuardIdentifierRecipient(who: Recipient): boolean;
+export declare function getErrorName(code: number): string | undefined;
+export declare function getErrorDescription(code: number): string | undefined;