@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/allocation-ledger.js

@@ -0,0 +1,463 @@
+import { MAX_SHARING_COUNT, MAX_ALLOCATOR_COUNT } from "@wowok/wowok";
+export { MAX_ALLOCATOR_COUNT };
+export const ALLOCATION_MAX_SHARING_COUNT = MAX_SHARING_COUNT;
+export const ALLOCATION_MODE_AMOUNT = 0;
+export const ALLOCATION_MODE_RATE = 1;
+export const ALLOCATION_MODE_SURPLUS = 2;
+export const RATE_TOTAL_FULL = 10000;
+export const ALLOCATION_ERROR_CODES = {
+    ERECIPIENT_IDENTIFIER_NOT_ADDRESS: 1,
+    EALLOCATOR_COUNT_EXCEEDED: 2,
+    ENO_ALLOCATOR: 3,
+    ERATE_NOT_10000: 4,
+    EMULTIPLE_SURPLUS: 5,
+    ERATE_EXCEEDS_10000: 6,
+    EINSUFFICIENT_BALANCE: 7,
+    EALLOCATORS_EMPTY: 8,
+    ENO_PAYMENT_INFO: 9,
+    ESHARING_COUNT_EXCEEDED: 10,
+    ESHARING_MODE_INVALID: 11,
+    EAMOUNT_BELOW_THRESHOLD: 12,
+    EAMOUNT_EXCEEDS_MAX: 13,
+};
+export const ORDER_ALLOCATION_ALREADY_SPECIFIED = "E_ALLOCATION_ALREADY_SPECIFIED";
+export const ALLOCATION_SCENES = [
+    {
+        id: "allocation_standard_three_way_split",
+        name: "Standard three-way split (merchant / platform / logistics)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "pure_rate",
+        coin_type_note: "All three Treasury objects must use the same Coin<T> type as the Allocation",
+        typical_allocator_count: 1,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Rate"],
+        guard_requirement: "required",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "Single Allocator, 3 Rate sharing items, sum(rates) === 10000",
+            "Each sharing.who=Entity points to a Treasury address",
+            "Guard verifies order.service binding (query 1563) to prevent cross-project bypass",
+            "Guard verifies progress.current_node === 'Complete'",
+        ],
+        dependencies: ["Service", "Treasury", "Guard", "Order", "Progress", "Machine", "Payment"],
+        key_constraints: [
+            "F-A-05: sum(rates) === 10000 (pure Rate mode)",
+            "Treasury Permission should match Service Permission (R-A-12)",
+            "order_allocators immutable after Service publish (R-A-10)",
+        ],
+        recommended_templates: ["T-A-02"],
+    },
+    {
+        id: "allocation_merchant_full_payment",
+        name: "Merchant full payment (single recipient, 100%)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "pure_rate",
+        coin_type_note: "Simplest configuration — single Treasury or personal address",
+        typical_allocator_count: 1,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Rate"],
+        guard_requirement: "single_relaxed",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "Single Allocator, 1 Rate sharing = 10000",
+            "Guard only verifies order status (no complex conditions)",
+            "who=Entity can be either Treasury or personal wallet",
+        ],
+        dependencies: ["Service", "Guard", "Order", "Payment"],
+        key_constraints: [
+            "Simplest allocation configuration",
+            "No multi-party coordination required",
+        ],
+        recommended_templates: ["T-A-01"],
+    },
+    {
+        id: "allocation_refund_first_surplus_to_merchant",
+        name: "Refund first + surplus to merchant (Amount + Surplus hybrid)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "amount_plus_surplus",
+        coin_type_note: "Refund amount must match Coin<T> precision",
+        typical_allocator_count: 1,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Amount", "Surplus"],
+        guard_requirement: "required",
+        non_zero_threshold: true,
+        uses_max: false,
+        common_patterns: [
+            "Single Allocator, 2 sharing items",
+            "sharing[0]: Amount=refund_value, who=Entity(customer_address)",
+            "sharing[1]: Surplus, who=Entity(merchant_treasury)",
+            "fix = refund_value (cached Amount sum)",
+            "threshold = refund_value (ensure sufficient balance for Amount)",
+        ],
+        dependencies: ["Service", "Treasury", "Guard", "Order", "Payment"],
+        key_constraints: [
+            "F-A-04: at most 1 Surplus per Allocator",
+            "F-A-07: fix >= threshold (Amount sum must cover threshold)",
+            "fix must precisely match the refund amount",
+        ],
+        recommended_templates: ["T-A-03"],
+    },
+    {
+        id: "allocation_treasury_personal_alternatives",
+        name: "Treasury + Personal alternative strategies (caller-specified guard)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "first_match_alternatives",
+        coin_type_note: "Both target addresses must accept the same Coin<T>",
+        typical_allocator_count: 2,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Rate"],
+        guard_requirement: "multiple_unique",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "2 Allocators, each with 1 Rate=10000 sharing",
+            "Allocator[0]: guard=guard_treasury, who=Entity(treasury_address)",
+            "Allocator[1]: guard=guard_personal, who=Entity(personal_address)",
+            "Two Guard objects must be different addresses (R-A-11)",
+            "caller-specified guard: caller selects Treasury or Personal path via alloc_by_guard; passport::result_for_guard hard-validates (failure aborts with E_VERIFY_FAILED; caller must switch guard and retry)",
+        ],
+        dependencies: ["Service", "Treasury", "Guard", "Order", "Payment"],
+        key_constraints: [
+            "F-A-14: allocators[].guard must be unique",
+            "Treasury Permission should match Service Permission (R-A-12)",
+            "Guard A and Guard B may share root/table but must differ in description",
+        ],
+        recommended_templates: ["T-A-04"],
+    },
+    {
+        id: "allocation_tiered_by_order_amount",
+        name: "Tiered split by order amount (multi-Allocator amount-threshold switch)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "tiered_by_amount",
+        coin_type_note: "Amount threshold uses Coin<T> smallest unit (e.g. MIST for WOW)",
+        typical_allocator_count: 2,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Rate"],
+        guard_requirement: "multiple_unique",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "2 Allocators triggered by mutually exclusive Guard conditions",
+            "Allocator[0]: guard verifies order.amount < threshold, Rate=10000 to merchant",
+            "Allocator[1]: guard verifies order.amount >= threshold, Rate=8000/2000 split",
+            "caller-specified guard: caller selects the matching Allocator based on order amount; allocator order is irrelevant",
+            "Guard queries order.amount (query 1561)",
+        ],
+        dependencies: ["Service", "Treasury", "Guard", "Order", "Payment"],
+        key_constraints: [
+            "Guard conditions must be mutually exclusive (R-A-4-02 design clarity)",
+            "Caller must select correct guard based on order.amount (no auto-fallback)",
+        ],
+        recommended_templates: ["T-A-05"],
+    },
+    {
+        id: "allocation_dynamic_recipient",
+        name: "Multi-role split with dynamic recipient (GuardIdentifier)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "dynamic_recipient",
+        coin_type_note: "Passport table must contain address-typed entry at the referenced identifier",
+        typical_allocator_count: 1,
+        sharing_who_types: ["Entity", "GuardIdentifier"],
+        modes_used: ["Rate"],
+        guard_requirement: "required",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "Single Allocator, 3 Rate sharing items",
+            "sharing[0]: Rate=8000, who=Entity(merchant_treasury)",
+            "sharing[1]: Rate=1000, who=Entity(platform_treasury)",
+            "sharing[2]: Rate=1000, who=GuardIdentifier(0) — resolves from Passport table",
+            "Customer submits Passport with referrer address at identifier=0",
+        ],
+        dependencies: ["Service", "Treasury", "Guard", "Passport", "Order", "Payment"],
+        key_constraints: [
+            "F-A-13: Passport table[identifier] must be address type (else ERECIPIENT_IDENTIFIER_NOT_ADDRESS)",
+            "Guard must verify Passport completeness",
+            "Customer order must include Passport with referrer address",
+        ],
+        recommended_templates: ["T-A-06"],
+    },
+    {
+        id: "allocation_arbitration_fees",
+        name: "Arbitration fees split (arbitrator / platform)",
+        trigger_source: "arbitration_fees",
+        distribution_strategy: "pure_rate",
+        coin_type_note: "Coin<T> must match Arbitration's fee Coin type",
+        typical_allocator_count: 1,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Rate"],
+        guard_requirement: "required",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "Triggered by Arbitration.fees_alloc (permission 365) or fees_alloc_with_passport",
+            "Single Allocator, 2 Rate sharing items: 8000 arbitrator / 2000 platform",
+            "payment_info reuses Arbitration's payment_info",
+            "Caller must hold ARBITRATION_FEES_ALLOC=365 permission",
+        ],
+        dependencies: ["Arbitration", "Treasury", "Guard", "Payment"],
+        key_constraints: [
+            "Independent from Service-order Allocation",
+            "Requires ARBITRATION_FEES_ALLOC=365 permission",
+        ],
+        recommended_templates: ["T-A-08"],
+    },
+    {
+        id: "allocation_refund_to_order",
+        name: "Refund Allocator (100% to Order object)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "refund_to_order",
+        coin_type_note: "who=Entity must be the Order object address (NOT a personal wallet)",
+        typical_allocator_count: 1,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Rate"],
+        guard_requirement: "required",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "Single Allocator, 1 Rate=10000 sharing",
+            "who=Entity(order_address) — funds flow back to Order, not personal wallet",
+            "Guard verifies customer refund request and eligibility",
+            "Customer-side risk assessment adds 8-point weight (customer/risk-assessment.ts)",
+        ],
+        dependencies: ["Service", "Guard", "Order", "Payment"],
+        key_constraints: [
+            "who=Entity MUST be Order object address (not personal address)",
+            "Customer due-diligence rewards this configuration (8-point weight)",
+            "Refund funds return to Order for downstream handling",
+        ],
+        recommended_templates: ["T-A-07"],
+    },
+    {
+        id: "allocation_max_capped_retain",
+        name: "Max-capped allocation (retain residual balance)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "max_capped",
+        coin_type_note: "max field uses Coin<T> smallest unit",
+        typical_allocator_count: 1,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Amount", "Rate"],
+        guard_requirement: "required",
+        non_zero_threshold: true,
+        uses_max: true,
+        common_patterns: [
+            "Single Allocator with max field set",
+            "max triple role: Amount cap + Rate base + Surplus cap",
+            "Amount sharing consumes fix; Rate sharing uses (max - fix) as base",
+            "Residual balance remains in Allocation for subsequent alloc() calls",
+        ],
+        dependencies: ["Service", "Treasury", "Guard", "Order", "Payment"],
+        key_constraints: [
+            "F-A-08: Amount sum <= max (EAMOUNT_EXCEEDS_MAX)",
+            "max - fix becomes Rate base (NOT balance - fix)",
+            "Residual balance may be claimed by re-triggering alloc()",
+        ],
+        recommended_templates: [],
+    },
+    {
+        id: "allocation_multi_node_trigger",
+        name: "Multi-Machine-node triggered allocation (Complete / Refund / Lost)",
+        trigger_source: "service_order_allocators",
+        distribution_strategy: "multi_node_trigger",
+        coin_type_note: "All Allocators share the same Allocation's Coin<T>",
+        typical_allocator_count: 3,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Rate"],
+        guard_requirement: "multiple_unique",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "3 Allocators mapped to Machine terminal nodes (Complete/Refund/Lost)",
+            "Each Allocator's Guard verifies progress.current_node == <node_name>",
+            "Mutually exclusive Guard conditions (only one terminal node active at a time)",
+            "Machine.required_allocators[] describes each trigger_node mapping",
+        ],
+        dependencies: ["Service", "Treasury", "Guard", "Order", "Progress", "Machine", "Payment"],
+        key_constraints: [
+            "Guard conditions must be mutually exclusive",
+            "Sequence-sensitive: business-flow order",
+            "Machine.required_allocators[trigger_node] must map to Allocator indices",
+        ],
+        recommended_templates: [],
+    },
+    {
+        id: "allocation_standalone_periodic_split",
+        name: "Standalone periodic split (investment dividends / shared income)",
+        trigger_source: "standalone",
+        distribution_strategy: "periodic_split",
+        coin_type_note: "Coin<T> must match the asset being distributed (e.g. profit token)",
+        typical_allocator_count: 1,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Rate"],
+        guard_requirement: "required",
+        non_zero_threshold: false,
+        uses_max: false,
+        common_patterns: [
+            "Single Allocator, N Rate sharing items, sum(rates) === 10000",
+            "Each sharing.who=Entity points to a beneficiary wallet (not Treasury)",
+            "Guard verifies time-based trigger (e.g. context(Clock).timestamp >= next_release) or signer authorization",
+            "User calls receive() to deposit funds, then alloc() to trigger distribution",
+            "No Service/Order/Progress/Machine context required",
+        ],
+        dependencies: ["Treasury", "Guard", "Payment"],
+        key_constraints: [
+            "F-A-05: sum(rates) === 10000 (pure Rate mode)",
+            "R-A-3-04: standalone mode has no Service-layer access control — Guard + Passport MUST be sufficient",
+            "Caller is fully responsible for receive → alloc lifecycle (no auto-trigger)",
+            "Guard should bind Signer to prevent unauthorized alloc() calls",
+        ],
+        recommended_templates: ["T-A-09"],
+    },
+    {
+        id: "allocation_standalone_vesting",
+        name: "Standalone vesting release (time-locked multi-stage unlock)",
+        trigger_source: "standalone",
+        distribution_strategy: "time_locked_vesting",
+        coin_type_note: "Coin<T> must match the vested asset (e.g. locked team tokens)",
+        typical_allocator_count: 3,
+        sharing_who_types: ["Entity"],
+        modes_used: ["Amount", "Rate", "Surplus"],
+        guard_requirement: "multiple_unique",
+        non_zero_threshold: true,
+        uses_max: true,
+        common_patterns: [
+            "N Allocators, each mapped to a vesting stage (e.g. 25% at month 12, 25% at month 24, 50% surplus at month 36)",
+            "Each Allocator's Guard verifies context(Clock).timestamp >= stage_unlock_time",
+            "Amount sharing per stage with max field capping the cumulative release",
+            "Final Allocator uses Surplus to drain remaining balance after last vesting stage",
+            "Mutually exclusive Guard conditions (only one stage active at a time, based on timestamp)",
+            "User calls receive() to deposit locked tokens, then alloc() at each vesting milestone",
+        ],
+        dependencies: ["Treasury", "Guard", "Passport", "Payment"],
+        key_constraints: [
+            "F-A-04: at most 1 Surplus per Allocator (final stage uses Surplus to drain remainder)",
+            "F-A-08: Amount sum <= max (EAMOUNT_EXCEEDS_MAX)",
+            "R-A-3-04: standalone mode has no Service-layer access control — Guard time-lock MUST be enforced",
+            "Guard conditions must be mutually exclusive by timestamp (R-A-4-02)",
+            "Caller must wait for time-lock expiry before alloc() succeeds; otherwise alloc() silently returns (R-A-4-01)",
+        ],
+        recommended_templates: ["T-A-10"],
+    },
+];
+export const ALLOCATION_LEDGER_VERSION = "1.0.0";
+export function getScenesByTriggerSource(source) {
+    return ALLOCATION_SCENES.filter(s => s.trigger_source === source);
+}
+export function getScenesByMode(mode) {
+    return ALLOCATION_SCENES.filter(s => s.modes_used.includes(mode));
+}
+export function getScenesByStrategy(strategy) {
+    return ALLOCATION_SCENES.filter(s => s.distribution_strategy === strategy);
+}
+export function findSceneById(id) {
+    return ALLOCATION_SCENES.find(s => s.id === id);
+}
+export function inferSceneFromIntent(intent) {
+    const lower = intent.toLowerCase();
+    if (lower.includes("arbitration") || lower.includes("fees_alloc")) {
+        return findSceneById("allocation_arbitration_fees");
+    }
+    if (lower.includes("standalone") || lower.includes("periodic split") ||
+        lower.includes("investment dividend") || lower.includes("shared income") || lower.includes("dividend")) {
+        return findSceneById("allocation_standalone_periodic_split");
+    }
+    if (lower.includes("vesting") || lower.includes("time-lock") || lower.includes("unlock period") ||
+        lower.includes("locked release") || lower.includes("token unlock")) {
+        return findSceneById("allocation_standalone_vesting");
+    }
+    if (lower.includes("refund")) {
+        if (lower.includes("order") || lower.includes("100%")) {
+            return findSceneById("allocation_refund_to_order");
+        }
+        if (lower.includes("surplus") || lower.includes("merchant")) {
+            return findSceneById("allocation_refund_first_surplus_to_merchant");
+        }
+    }
+    if (lower.includes("alternative") || lower.includes("priority") || (lower.includes("treasury") && lower.includes("personal"))) {
+        return findSceneById("allocation_treasury_personal_alternatives");
+    }
+    if (lower.includes("tiered") || lower.includes("threshold switch")) {
+        return findSceneById("allocation_tiered_by_order_amount");
+    }
+    if (lower.includes("dynamic recipient") || lower.includes("referrer") || lower.includes("guardidentifier")) {
+        return findSceneById("allocation_dynamic_recipient");
+    }
+    if (lower.includes("retain") || lower.includes("max")) {
+        return findSceneById("allocation_max_capped_retain");
+    }
+    if (lower.includes("multi-node") || lower.includes("multi machine") || lower.includes("multi_node")) {
+        return findSceneById("allocation_multi_node_trigger");
+    }
+    const roleCount = (intent.match(/%/g) || []).length;
+    if (roleCount <= 1) {
+        return findSceneById("allocation_merchant_full_payment");
+    }
+    if (roleCount >= 2) {
+        return findSceneById("allocation_standard_three_way_split");
+    }
+    return undefined;
+}
+export function getAllScenes() {
+    return [...ALLOCATION_SCENES];
+}
+export function getScenesCount() {
+    return ALLOCATION_SCENES.length;
+}
+export function allocationModeToNumber(mode) {
+    switch (mode) {
+        case "Amount": return ALLOCATION_MODE_AMOUNT;
+        case "Rate": return ALLOCATION_MODE_RATE;
+        case "Surplus": return ALLOCATION_MODE_SURPLUS;
+    }
+}
+export function allocationModeFromNumber(n) {
+    switch (n) {
+        case ALLOCATION_MODE_AMOUNT: return "Amount";
+        case ALLOCATION_MODE_RATE: return "Rate";
+        case ALLOCATION_MODE_SURPLUS: return "Surplus";
+        default: throw new Error(`Invalid AllocationMode number: ${n}`);
+    }
+}
+export function getRecipientType(who) {
+    if ("GuardIdentifier" in who)
+        return "GuardIdentifier";
+    if ("Entity" in who)
+        return "Entity";
+    return "Signer";
+}
+export function isSignerRecipient(who) {
+    return "Signer" in who;
+}
+export function isEntityRecipient(who) {
+    return "Entity" in who;
+}
+export function isGuardIdentifierRecipient(who) {
+    return "GuardIdentifier" in who;
+}
+export function getErrorName(code) {
+    for (const [name, c] of Object.entries(ALLOCATION_ERROR_CODES)) {
+        if (c === code)
+            return name;
+    }
+    return undefined;
+}
+export function getErrorDescription(code) {
+    const descriptions = {
+        1: "GuardIdentifier resolved value is not an address type",
+        2: "Allocator count exceeds MAX_ALLOCATOR_COUNT (100)",
+        3: "No Allocator in the allocators vector",
+        4: "Pure Rate mode sum != 10000 (no Surplus to absorb remainder)",
+        5: "Multiple Surplus sharing in a single Allocator",
+        6: "Rate + Surplus sum > 10000",
+        7: "balance < threshold (insufficient balance to trigger alloc)",
+        8: "allocators.allocators is empty",
+        9: "payment_info is None when alloc() is called",
+        10: "sharing count exceeds MAX_SHARING_COUNT (100)",
+        11: "sharing mode is not 0 (Amount) / 1 (Rate) / 2 (Surplus)",
+        12: "Amount sum (fix) < threshold",
+        13: "Amount sum (fix) > max",
+    };
+    return descriptions[code];
+}

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

@@ -0,0 +1,135 @@
+import { type AllocationMode, type Recipient, type TriggerSource } from "./allocation-ledger.js";
+export interface AllocationIntentPuzzle {
+    action: "create" | "operate" | "query";
+    host_context: TriggerSource;
+    trigger_condition: string;
+    distribution_goal: string;
+    failure_conditions: string[];
+}
+export interface AllocationBindingPuzzle {
+    coin_type: string;
+    host_service?: string;
+    host_arbitration?: string;
+    bound_order?: string;
+    trigger_node?: string;
+    guard_objects: string[];
+    payment_info_source: "service" | "arbitration" | "custom";
+}
+export interface AllocatorConfig {
+    guard: string;
+    sharing: {
+        who: Recipient;
+        sharing: string | bigint;
+        mode: AllocationMode;
+    }[];
+    fix?: string | bigint;
+    max?: string | bigint | null;
+}
+export interface AllocatorsConfig {
+    description: string;
+    threshold: string | bigint;
+    allocators: AllocatorConfig[];
+}
+export interface PaymentInfoConfig {
+    for_object: string;
+    source?: "service" | "arbitration" | "custom";
+}
+export interface AllocationDataSourcePuzzle {
+    allocators_config: AllocatorsConfig;
+    payment_info: PaymentInfoConfig;
+    coin_source: "order_payment" | "arbitration_fees" | "external_deposit";
+}
+export type AllocationOperation = {
+    type: "create";
+    name: string;
+    allocators: AllocatorsConfig;
+    coin: string;
+    payment_info: PaymentInfoConfig;
+} | {
+    type: "receive";
+    received_coins: "recently" | {
+        received: {
+            id: string;
+            payment: string;
+        }[];
+        token_type: string;
+    };
+} | {
+    type: "alloc_by_guard";
+    guard: string;
+    passport?: string;
+} | {
+    type: "query_balance";
+} | {
+    type: "query_allocators";
+} | {
+    type: "query_payment_history";
+};
+export interface AllocationOperationPuzzle {
+    operations: AllocationOperation[];
+}
+export interface AllocationLogicPuzzle {
+    alloc_flow: {
+        step: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+        action: "pre_check" | "guard_lookup" | "rate_base_calc" | "sharing_distribution" | "surplus_distribution" | "recipient_resolution" | "payment_creation";
+        description: string;
+    }[];
+    guard_matching_strategy: "caller_specified_guard" | "all_match";
+    recipient_resolution_rules: {
+        recipient_type: "GuardIdentifier" | "Entity" | "Signer";
+        resolution_source: "passport_table" | "static_address" | "tx_sender";
+        safety_level: "safe" | "dangerous" | "safe_with_guard_binding";
+    }[];
+}
+export interface AllocationConstraintChecklist {
+    F_A_01_allocator_count_le_100: boolean;
+    F_A_02_sharing_count_le_100: boolean;
+    F_A_03_sharing_mode_valid: boolean;
+    F_A_04_at_most_1_surplus_per_allocator: boolean;
+    F_A_05_pure_rate_sum_eq_10000: boolean;
+    F_A_06_rate_plus_surplus_sum_le_10000: boolean;
+    F_A_07_amount_sum_ge_threshold: boolean;
+    F_A_08_amount_sum_le_max: boolean;
+    F_A_09_balance_ge_threshold_at_alloc: boolean;
+    F_A_10_payment_info_present: boolean;
+    F_A_11_allocators_not_empty: boolean;
+    F_A_12_order_at_most_1_allocation: boolean;
+    F_A_13_guard_identifier_is_address: boolean;
+    F_A_14_guard_addresses_unique: boolean;
+    F_A_15_order_allocators_immutable_after_publish: boolean;
+}
+export type AllocationPuzzleDimension = "A" | "B" | "C" | "D" | "E" | "F";
+export interface AllocationPuzzle {
+    intent?: AllocationIntentPuzzle;
+    binding?: AllocationBindingPuzzle;
+    data_source?: AllocationDataSourcePuzzle;
+    operations?: AllocationOperationPuzzle;
+    logic?: AllocationLogicPuzzle;
+    constraints?: AllocationConstraintChecklist;
+}
+export interface AllocationPuzzleCompleteness {
+    dimensions: AllocationPuzzleDimension[];
+    missing: AllocationPuzzleDimension[];
+    missing_details: {
+        dimension: AllocationPuzzleDimension;
+        reason: string;
+    }[];
+    complete: boolean;
+    next_step: string;
+}
+export declare function initPuzzleFromIntent(intent: Partial<AllocationIntentPuzzle>): AllocationPuzzle;
+export declare function checkPuzzleCompleteness(puzzle: AllocationPuzzle): AllocationPuzzleCompleteness;
+export interface AllocationConstraintViolation {
+    constraint_id: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+    message: string;
+    current_value?: string | number;
+    limit?: string | number;
+    related_move_error?: string;
+}
+export declare function validateConstraints(puzzle: AllocationPuzzle): AllocationConstraintViolation[];
+export declare function generateConfirmationText(puzzle: AllocationPuzzle): string;
+export declare function buildDefaultAllocFlow(): AllocationLogicPuzzle["alloc_flow"];
+export declare function buildDefaultRecipientRules(): AllocationLogicPuzzle["recipient_resolution_rules"];
+export declare function buildDefaultLogicPuzzle(): AllocationLogicPuzzle;
+export declare const ALLOCATION_PUZZLE_VERSION = "1.0.0";