@wowok/agent-mcp 2.6.0 → 2.6.3

package/dist/schema/query/index.js

@@ -5,14 +5,23 @@ import { SemanticSummarySchema } from "../call/index.js";
 import { isValidPermissionIndex } from '../utils/permission-index-utils.js';
 import { isValidGuardQueryId, isValidGuardQueryIdOrName, isValidWitnessType } from '../utils/guard-query-utils.js';
 import { ENTITY_LINKER_ADDRESS, ENTITY_REGISTRAR_ADDRESS, isWitnessType, } from "@wowok/wowok";
-import { DiscountType as WDiscountType } from "@wowok/wowok";
 import { QueryEnvSchema } from "../common/index.js";
 const MAX_MULTI_OPERANDS = 8;
 const VALUE_TYPE_DESCRIPTION = "Value type: can be specified as a string name (e.g., 'U64', 'Address', 'String') or a number (0-18). Supported types: Bool=0/'Bool', Address=1/'Address', String=2/'String', U8=3/'U8', U16=4/'U16', U32=5/'U32', U64=6/'U64', U128=7/'U128', U256=8/'U256', VecBool=9/'VecBool', VecAddress=10/'VecAddress', VecString=11/'VecString', VecU8=12/'VecU8', VecU16=13/'VecU16', VecU32=14/'VecU32', VecU64=15/'VecU64', VecU128=16/'VecU128', VecU256=17/'VecU256', VecVecU8=18/'VecVecU8'. Note: Value=19 is an INTERNAL type for wowok system use only and should NOT be used directly by users. String format is recommended for better readability.";
 const tolerantNumber = z.union([z.number(), z.string()]);
 const tolerantStringNullable = z.union([z.string(), z.null(), z.undefined()]);
 const tolerantNumberNullable = z.union([z.number(), z.string(), z.null(), z.undefined()]);
-export const AmountTypeSchema = z.enum(["GuardU64Identifier", "Fixed"]).describe("Amount type. GuardU64Identifier indicates the amount comes from U64 type data defined in Guard table (Identifier index), Fixed indicates using a fixed amount.");
+export const AmountTypeSchema = z.union([
+    z.enum(["GuardU64Identifier", "Fixed"]),
+    z.number().int().min(0).max(1).transform((n) => n === 0 ? "GuardU64Identifier" :
+        n === 1 ? "Fixed" :
+            "GuardU64Identifier"),
+]).describe("Amount type — determines how a payment amount is resolved. " +
+    "Accepts string ('GuardU64Identifier' or 'Fixed') or number (0='GuardU64Identifier', 1='Fixed'). String form is recommended for readability. " +
+    "• 'GuardU64Identifier' (0): the amount is NOT fixed — it is dynamically read from a U64 value stored in the Guard table at the specified Identifier index. Use this when the amount varies per order (e.g. milestone-based pricing, negotiated price). The Guard must have a matching U64 entry. " +
+    "• 'Fixed' (1): the amount is a fixed value set in the sale/price field. Use this for products with a static price (e.g. service fee = 50 SUI). " +
+    "Example: {price: 50000000000, stock: 100, amount_type: 'Fixed'} → fixed 50 SUI price. " +
+    "Example: {price: 0, stock: 100, amount_type: 'GuardU64Identifier'} → price read from Guard table U64 entry.");
 export const GuardQuerySchema = z.object({
     id: QueryIdSchema,
     name: z.string().describe("Name of the query instruction."),
@@ -29,9 +38,14 @@ export const GuardSubmissionSchema = z.object({
 }).describe("Guard submission");
 export const RecipientSchema = z.union([
     z.object({ GuardIdentifier: GuardIdentifierSchema }).describe("Guard verified recipient ID. Get recipient ID from specified data index in Guard table. The ID must be of address type."),
-    z.object({ Entity: AccountOrMark_AddressSchema }).describe("Determined ID"),
-    z.object({ Signer: z.literal("signer") }).describe("Current transaction signer ID"),
-]).describe("Recipient ID");
+    z.object({ Entity: AccountOrMark_AddressSchema }).describe("Static address resolved via LocalMark. " +
+        "Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."),
+    z.object({ Signer: z.literal("signer") }).describe("Current transaction signer (tx_context::sender) at the time of the alloc() call. " +
+        "For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."),
+]).describe("Recipient ID. Three forms:\n" +
+    "  - {GuardIdentifier: u8}  — DYNAMIC address resolved from Passport at alloc() time\n" +
+    "  - {Entity: {name_or_address: 'mark_name'}}  — FIXED static address via LocalMark (recommended)\n" +
+    "  - {Signer: 'signer'}  — transaction sender at alloc() time (e.g. self-refund; customer must call alloc_by_guard themselves)");
 export const RecordsInEntitySchema = z.object({
     name: z.string().describe("Record name"),
     value_type: ValueTypeSchema.describe("Value type"),
@@ -104,8 +118,11 @@ export const ServiceSaleSchema = z.object({
     price: BalanceTypeSchema.describe("Price of the product or service"),
     stock: BalanceTypeSchema.describe("Stock of the product or service"),
     suspension: z.boolean().describe("Whether sale is suspended"),
-    wip: z.string().describe("HTTP URL of wip file"),
-    wip_hash: z.string().describe(`Hash of WIP. If EMPTY string, the hash within wip will be automatically used; else, the consistency of the hash within wip will be verified with the provided hash.`),
+    wip: z.string().describe("WIP file URL. EMPTY string \"\" skips verification (TESTING ONLY). " +
+        "Production MUST use a real HTTP URL pointing to a .wip file generated by the wip_file tool. " +
+        "Example: \"https://cdn.example.com/products/phone_v1.wip\""),
+    wip_hash: z.string().describe("WIP file hash (hex string). EMPTY string \"\" skips hash comparison (TESTING ONLY). " +
+        "Production: fill with the hash you saw when viewing the product, to prevent merchant replacing the WIP file before order."),
 }).describe("Service sale");
 export const PurchasedItemSchema = z.object({
     name: LongNameSchema.describe("Name of the product or service"),
@@ -182,23 +199,99 @@ export const ObjectRewardSchema = ObjectBaseSchema.extend({
     um: z.union([z.string(), z.null()]).describe("Contact object"),
     permission: z.string().describe("Permission object ID"),
 }).describe("Reward object");
-export const AllocationModeSchema = z.enum(["Amount", "Rate", "Surplus"]).describe("Reward allocation mode. Amount indicates allocation by amount, Rate indicates allocation by proportion, Surplus indicates allocation by remaining amount. In a fund allocator, Amount will be allocated first, then remaining funds will be allocated by Rate (if no Surplus is defined, sum of all Rates must be 10000), and finally Surplus gets remaining amount (maximum one per fund allocator).");
+export const AllocationModeSchema = z.union([
+    z.enum(["Amount", "Rate", "Surplus"]),
+    z.number().int().min(0).max(2).transform((n) => n === 0 ? "Amount" :
+        n === 1 ? "Rate" :
+            n === 2 ? "Surplus" :
+                "Amount"),
+]).describe("Allocation mode — determines how the `sharing` field is interpreted. " +
+    "Three modes can be used individually OR combined within a single Allocator; " +
+    "when combined, allocation order is strictly: Amount first, then Rate, then Surplus. " +
+    "Understanding these modes allows modeling almost any fund distribution pattern.\n" +
+    "• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). " +
+    "Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. " +
+    "Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); " +
+    "when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n" +
+    "• Rate (1): `sharing` is a basis-points rate (10000 = 100%). " +
+    "Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, " +
+    "where total_rates = balance - fix (or max - fix if `max` is set). " +
+    "Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); " +
+    "when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n" +
+    "• Surplus (2): `sharing` is IGNORED (contract forces it to 0). " +
+    "Allocated LAST; receives the remaining balance after Amount + Rate allocations. " +
+    "Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). " +
+    "When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\n" +
+    "ALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate items (proportional to balance-fix) → Surplus item (remaining).\n" +
+    "RECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). " +
+    "Use Rate mode for proportional splits (requires sum == 10000 unless Surplus present). " +
+    "Use Surplus to capture remainder (e.g., platform fee + host gets rest). " +
+    "Accepts string ('Amount'/'Rate'/'Surplus', recommended) or number (0/1/2).");
 export const AllocationSharingSchema = z.object({
-    who: RecipientSchema.describe("Recipient ID"),
-    sharing: BalanceTypeSchema.describe("Reward allocation value"),
-    mode: AllocationModeSchema.describe("Reward allocation mode"),
-}).describe("Fund allocation item");
+    who: RecipientSchema.describe("Recipient of this allocation. Three forms — each resolves the address at a DIFFERENT time:\n" +
+        "• { GuardIdentifier: u8 } — DYNAMIC address resolved from Passport at alloc() time (contract calls passport::submission_get). " +
+        "Use 0 for Order owner in Service-integrated mode (Customer who created the Order). " +
+        "The identifier must match a Guard table entry with b_submission=true. " +
+        "If Passport has no matching submission, contract aborts with E_VERIFY_FAILED. " +
+        "Use when the recipient address is not known at config time and must be supplied via Guard submission data.\n" +
+        "• { Entity: { name_or_address: '...' } } — FIXED address resolved via LocalMark at SDK build time (passed to contract as a literal address). " +
+        "Use for known recipients (e.g., 'turo_host', or a Treasury object address). " +
+        "Use when the recipient is a stable, known address (e.g., operator receives rent, platform fee to treasury).\n" +
+        "• 'Signer' — the transaction sender at the time of the alloc() call (tx_context::sender). " +
+        "RESOLVED AT EXECUTION TIME, not at config time. " +
+        "For refunds: the customer (Order owner) must call alloc_by_guard THEMSELVES so that tx_context::sender resolves to THEIR address — " +
+        "if the operator calls alloc_by_guard, the operator becomes the recipient (Signer = operator), NOT the customer. " +
+        "Use when the recipient is whoever submits the allocation transaction (e.g., customer receives refund)."),
+    sharing: BalanceTypeSchema.describe("Allocation value. SEMANTICS DEPEND ON `mode`:\n" +
+        "• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). " +
+        "Allocated first; sum of Amount items cached as `fix`.\n" +
+        "• mode='Rate': basis-points rate, 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). " +
+        "When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n" +
+        "• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. " +
+        "Receives remaining balance after Amount + Rate allocations."),
+    mode: AllocationModeSchema,
+}).describe("Fund allocation item — one recipient's share of the Allocation balance. " +
+    "The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). " +
+    "Multiple items in the same Allocator are evaluated together: Amount items first, Rate items second, Surplus last.");
 export const AllocatorSchema = z.object({
-    guard: NameOrAddressSchema.describe("Guard object ID. If Guard verification passes, fund allocation will start automatically."),
-    sharing: z.array(AllocationSharingSchema).describe("Fund allocation item list. Each item represents a recipient and their corresponding reward allocation value."),
-    fix: BalanceTypeSchema.optional().describe("Fixed allocation amount. If specified, all recipients will receive the fixed allocation amount."),
-    max: z.union([BalanceTypeSchema, z.null()]).optional().describe("Maximum allocation amount. If specified, allocation amount cannot exceed maximum allocation amount."),
-}).describe("Fund allocator");
+    guard: NameOrAddressSchema.describe("Guard object ID or name. If Guard verification passes (via Passport), fund allocation for THIS Allocator fires. " +
+        "Each Allocator in an Allocators list can have a different Guard — the first Allocator whose Guard returns true wins. " +
+        "This enables mutually exclusive allocation paths (e.g., refund Guard on 'return_approved' node vs damage Guard on 'damage_confirmed' node)."),
+    sharing: z.array(AllocationSharingSchema).describe("Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. " +
+        "Items can mix modes (Amount + Rate + Surplus) within the same Allocator. " +
+        "ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix) → Surplus item (remaining). " +
+        "CONSTRAINTS: max ONE Surplus item per Allocator; Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); " +
+        "Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."),
+    fix: BalanceTypeSchema.optional().describe("OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. " +
+        "Computed by the contract during `allocator_add` — DO NOT set this field at creation. " +
+        "Used internally to compute `total_rates = balance - fix` for Rate allocation."),
+    max: z.union([BalanceTypeSchema, z.null()]).optional().describe("Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). " +
+        "Passed through to the contract as Option<u64> via allocator_add(): when null/omitted the contract treats it as `none` (no cap); " +
+        "when set, the contract enforces it. Has THREE effects when set:\n" +
+        "1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n" +
+        "2. Rate execution: total_rates = max - fix (instead of balance - fix)\n" +
+        "3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\n" +
+        "Use when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). " +
+        "SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort."),
+}).describe("Fund allocator — a complete allocation strategy triggered by a Guard. " +
+    "Contains a sharing[] array where items can mix Amount/Rate/Surplus modes. " +
+    "When the Guard passes, the contract allocates funds in strict order: Amount → Rate → Surplus.");
 export const AllocatorsSchema = z.object({
     description: DescriptionSchema.describe("Description of fund allocator list"),
-    threshold: BalanceTypeSchema.default(0).describe("Threshold. If defined, fund allocation will be triggered when amount in Allocation object reaches this threshold."),
-    allocators: z.array(AllocatorSchema).describe("Fund allocator list. Each fund allocator represents a fund allocation strategy."),
-}).describe("Fund allocator list");
+    threshold: BalanceTypeSchema.default(0).describe("Minimum balance required for allocation to fire. " +
+        "When the Allocation object's balance < threshold, allocation aborts with EINSUFFICIENT_BALANCE=7. " +
+        "Also: when an Allocator has only Amount items (no Rate, no Surplus), the sum of Amount items must be >= threshold (EAMOUNT_BELOW_THRESHOLD=12). " +
+        "Set to 0 (default) to allow any balance."),
+    allocators: z.array(AllocatorSchema).describe("Fund allocator list. Each allocator is evaluated in order; the FIRST allocator whose Guard passes wins. " +
+        "This enables mutually exclusive allocation paths (e.g., 3 allocators for 3 forward paths: refund / damage-deduct / arbitrate)."),
+}).describe("Fund allocator list — the top-level allocation configuration attached to an Order. " +
+    "Contains a threshold and a list of Allocators. When funds arrive at the Order, " +
+    "the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate → Surplus. " +
+    "MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). " +
+    "For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: " +
+    "(1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); " +
+    "(2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). " +
+    "Each tier's Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus).");
 export const ObjectServiceSchema = ObjectBaseSchema.extend({
     description: z.string().describe("Service object description"),
     location: z.string().describe("Service object location"),
@@ -210,7 +303,11 @@ export const ObjectServiceSchema = ObjectBaseSchema.extend({
     bPaused: z.boolean().describe("Whether service purchase is paused"),
     customer_required: z.array(z.string()).describe("Information required from customer. Such as phone, email, etc."),
     arbitrations: z.array(z.string()).describe("List of Arbitration objects supported by service. When order user needs arbitration, they can apply for arbitration with any Arbitration object in the list."),
-    compensation_fund: BalanceTypeSchema.describe("Compensation fund pool for arbitration results. Order users can receive compensation from this fund based on arbitration results."),
+    compensation_fund: BalanceTypeSchema.describe("Compensation fund BALANCE (NOT a Treasury address). " +
+        "This field reports the total amount of funds currently held in the Service's compensation pool. " +
+        "To ADD funds, use `service.compensation_fund_add`. To RECEIVE funds (as order owner after arbitration), use `service.compensation_fund_receive`. " +
+        "P2-03 clarification: this is a balance value (e.g. {balance: '1000000000', token_type: '0x2::wow::WOW'}), NOT the Treasury object address. " +
+        "The Treasury address (if bound) is queried separately via the Service's `repositories` or `order_allocators` configuration."),
     paused_time: z.union([z.number(), z.null()]).describe("Service purchase pause time. If not paused, it is null."),
     setting_lock_duration: z.union([z.string(), z.number(), z.bigint()]).describe("Lock duration for critical settings. After Service is published, modifications to 'order_allocators', 'rewards', 'arbitrations', 'machine', and withdrawal from 'compensation_fund' must exceed the 'setting_lock_duration' lock time."),
     order_allocators: z.union([AllocatorsSchema, z.null()]).describe("Order fund allocator list."),
@@ -257,9 +354,11 @@ export const ObjectArbSchema = ObjectBaseSchema.extend({
     time: z.number().describe("Arbitration time"),
 }).describe("Arb object");
 export const DiscountTypeSchema = z.union([
-    z.literal(WDiscountType.RATES).describe("Rate discount type"),
-    z.literal(WDiscountType.FIXED).describe("Fixed discount type")
-]).describe("Discount type");
+    z.enum(["RATES", "FIXED"]),
+    z.number().int().min(0).max(1).transform((n) => n === 0 ? "RATES" :
+        n === 1 ? "FIXED" :
+            "RATES"),
+]).describe("Discount type. Accepts string ('RATES' or 'FIXED') or number (0='RATES', 1='FIXED'). If rate(0/RATES), discount is based on proportion of product amount (e.g., 1000 means 10% discount); if fixed(1/FIXED), discount is based on fixed value of product amount (e.g., 100 means 100 yuan discount). String form is recommended.");
 export const ObjectDiscountSchema = ObjectBaseSchema.extend({
     name: z.string().describe("Discount name"),
     discount_type: DiscountTypeSchema.describe("Discount type. If rate(0), discount is based on proportion of product amount (e.g., 1000 means 10% discount); if fixed(1), discount is based on fixed value of product amount (e.g., 100 means 100 yuan discount)."),
@@ -429,7 +528,7 @@ export const GuardNodeSchema = z.lazy(() => z.discriminatedUnion('type', [
             identifier: GuardIdentifierSchema,
             convert_witness: WitnessTypeSchema.optional(),
         }).strict().describe("The object to query from the Guard table."),
-        parameters: z.array(GuardNodeSchema).describe("Parameters required by the query (must match the query's expected parameters type)."),
+        parameters: z.array(GuardNodeSchema).optional().describe("Parameters required by the query. Optional — defaults to empty array []. Many queries (e.g. progress.current, order.service) take no parameters; for those, this field can be omitted."),
     }).strict().describe(`Returns the result of executing a data query instruction on the specified object. The return type depends on the query being executed. SPECIAL NOTE for EntityLinker/EntityRegistrar queries: Use system addresses in the Guard table -${ENTITY_LINKER_ADDRESS} for EntityLinker queries, ${ENTITY_REGISTRAR_ADDRESS} for EntityRegistrar queries.`),
     z.object({
         type: z.literal('logic_as_u256_greater_or_equal'),
@@ -461,11 +560,11 @@ export const GuardNodeSchema = z.lazy(() => z.discriminatedUnion('type', [
     }).strict().describe("Returns Bool. Computed by inverting the boolean value of the child node (true -> false, false -> true)."),
     z.object({
         type: z.literal('logic_and'),
-        nodes: z.array(GuardNodeSchema),
+        nodes: z.array(GuardNodeSchema).min(2, `logic_and requires at least 2 child nodes. For a single condition, use the comparison node directly as root (e.g. logic_equal), do NOT wrap with logic_and.`).max(MAX_MULTI_OPERANDS, `logic_and allows at most ${MAX_MULTI_OPERANDS} child nodes.`),
     }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical AND on all child node values. Returns true if ALL are true, otherwise false.`),
     z.object({
         type: z.literal('logic_or'),
-        nodes: z.array(GuardNodeSchema),
+        nodes: z.array(GuardNodeSchema).min(2, `logic_or requires at least 2 child nodes. For a single condition, use the comparison node directly as root (e.g. logic_equal), do NOT wrap with logic_or.`).max(MAX_MULTI_OPERANDS, `logic_or allows at most ${MAX_MULTI_OPERANDS} child nodes.`),
     }).strict().describe(`Returns Bool. Requires 2-${MAX_MULTI_OPERANDS} boolean nodes. Computed by performing logical OR on all child node values. Returns true if ANY is true, otherwise false.`),
     z.object({
         type: z.literal('logic_string_contains'),
@@ -842,21 +941,61 @@ export const TableItem_DemandPresenterSchema = ObjectBaseSchema.extend({
     feedback_time: tolerantNumber.describe("Demand object feedback time"),
 }).describe("Demand object's Service recommendation record");
 export const MachineForwardGuardSchema = z.object({
-    guard: z.string().describe("Guard object ID"),
+    guard: z.string().describe("Guard object name or address (string). Example: 'my_attendance_guard' or '0x1234...'"),
     retained_submission: z.array(tolerantNumber).nullable().optional().describe("Data submitted by user during Guard object verification"),
-}).strict().describe("Record of Guard object in MachineForwardGuard object");
+}).strict().describe("Record of Guard object in MachineForwardGuard object. ALWAYS an OBJECT {guard: string, retained_submission?: number[]} — never a plain string. The inner 'guard' field is the Guard's name or address as a string.");
 export const MachineForwardSchema = z.object({
     name: z.string().describe("Forward name"),
     namedOperator: tolerantStringNullable.describe("Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders)."),
     permissionIndex: tolerantNumberNullable.describe("Forward operation permission 2: Permission index (one of the two must be specified); recommended if all Progress object operators are the same (e.g., same reward reviewers for all orders)."),
     weight: tolerantNumber.describe("Forward weight"),
-    guard: MachineForwardGuardSchema.nullable().optional().describe("Guard object ID, if defined, Guard verification must also pass to complete Forward (e.g., completed promised supply chain sub-order)."),
+    guard: z.preprocess((val) => {
+        if (typeof val === "string") {
+            return { guard: val };
+        }
+        return val;
+    }, z.union([
+        MachineForwardGuardSchema.describe("OBJECT form: {guard: '<guard_name_or_address>', retained_submission?: number[]}. " +
+            "Use this form when you need to pass retained_submission data alongside the Guard reference."),
+        z.string().describe("STRING form (shorthand): the Guard object's name or address as a plain string. " +
+            "Auto-wrapped to {guard: <string>} at runtime. Use this when you only need to reference a Guard without retained_submission."),
+    ]).nullable().optional()).describe("Guard reference for this forward. Accepts TWO formats:\n" +
+        "• STRING (preferred): \"my_guard_name\" — the Guard's name or address as a plain string.\n" +
+        "• OBJECT (only when retained_submission is needed): {guard: \"my_guard_name\", retained_submission: [1,2,3]}.\n" +
+        "FOLLOW THE SCHEMA FIELD STRUCTURE: A Guard reference is fundamentally a STRING (the Guard object's name or address). " +
+        "Provide a string when you only need to reference a Guard — do NOT wrap a bare string in an object structure. " +
+        "The OBJECT form {guard: \"...\", retained_submission: [...]} exists ONLY to carry additional `retained_submission` data " +
+        "alongside the string reference; inside the object, the `guard` field is STILL a string. " +
+        "In short: string-in for a string reference, object-in only when you need to pass extra data.\n" +
+        "COGNITIVE PRINCIPLE: Guard validation ALWAYS occurs BEFORE the forward operation. " +
+        "A Guard that queries state of the SAME Progress object this forward operates on " +
+        "(e.g. progress.current) will see the PRE-transition value (source node), NOT the target node. " +
+        "If the Guard checks progress.current == target_node, it will ALWAYS FAIL. " +
+        "Querying a DIFFERENT Progress object (cross-machine) is safe and reasonable — " +
+        "that progress is not modified by this forward. " +
+        "For target-node verification after transition, bind the Guard to the Allocator instead " +
+        "(allocation.alloc runs AFTER the state transition completes)."),
 }).strict().describe("Forward in Machine object");
 export const MachineNodePairSchema = z.object({
-    prev_node: z.string().describe("Previous node name"),
+    prev_node: z.string().describe("Previous node name. Empty string '' means initial entry node (the first node in the workflow)."),
     threshold: tolerantNumber.default(0).describe("Threshold to trigger node advancement. If total Forward weight is greater than or equal to threshold, node advancement is triggered."),
-    forwards: z.array(MachineForwardSchema).describe("Forward list"),
-}).strict().describe("Node pair in Machine object");
+    forwards: z.array(MachineForwardSchema).describe("Forward list — operations to ENTER THIS NODE from prev_node. " +
+        "SEMANTIC CLARIFICATION: forwards describe INCOMING transitions (how to ARRIVE at this node), " +
+        "NOT outgoing transitions. Think of each forward as an 'entry door' to this node. " +
+        "Example: pair {prev_node:'A', forwards:[{name:'Go'}]} means 'use Go to advance FROM A TO THIS NODE'. " +
+        "For initial node (prev_node=''), forwards are operations to enter this node from the start state. " +
+        "DIAGRAM: A --[Go]--> B means the pair belongs to node B (destination), with prev_node='A'. " +
+        "WARNING: forwards belong to the DESTINATION node's pair, NOT the source node. " +
+        "Placing a forward on the wrong pair will cause Progress to get stuck."),
+}).strict().describe("Node pair in Machine object")
+    .refine((pair) => {
+    if (pair.prev_node === "" && pair.forwards.length === 0) {
+        return false;
+    }
+    return true;
+}, {
+    message: "Initial node (prev_node='') must have at least one forward. Without a forward, Progress cannot advance from '' to this node, causing the order workflow to be permanently stuck.",
+});
 export const MachineNodeSchema = z.object({
     name: z.string().describe("Node name"),
     pairs: z.array(MachineNodePairSchema).describe("Node pair list"),
@@ -1161,11 +1300,12 @@ export const ConstantItemSchema = z.object({
     description: z.string().describe('Description')
 }).describe('Constant item');
 export const PermissionInfoTypeSchema = z.object({
-    index: z.number().describe('Permission index'),
-    name: z.string().describe('Name'),
-    description: z.string().describe('Description'),
-    object_type: z.string().describe('Object type')
-}).describe('Permission info type');
+    index: z.number().describe('Permission index (e.g. 315 for service.compensation_fund_deposit)'),
+    name: z.string().describe('Permission name (e.g. "service.compensation_fund_deposit")'),
+    description: z.string().describe('Description of what this permission allows'),
+    object_type: z.string().describe('Object type this permission belongs to (e.g. "Service", "Arbitration")'),
+    operation: z.optional(z.string()).describe('The SDK/MCP operation field name that triggers this permission check (e.g. "compensation_fund_add", "publish", "pause"). Undefined for permissions with no direct Call*_Data field (e.g. "*.new" permissions). Use this to answer: "What permission does operation X require?" by filtering with {operation: "compensation_fund_add"}.')
+}).describe('Permission info type — includes the operation field name that maps to this permission, so AI can look up required permissions by operation name.');
 export const GuardInstructSchema = z.object({
     name: z.string().describe('Name of the guard instruction'),
     id: z.number().int().describe('ID of the guard instruction (OperatorType or ContextType)'),
@@ -1194,8 +1334,23 @@ export const PermissionFilterSchema = z.object({
     objectType: z.optional(ObjectTypeSchema).describe('Object type filter'),
     name: z.optional(z.string()).describe('Name filter'),
     index: z.optional(PermissionIndexTypeSchema).describe('Index filter'),
-    description: z.optional(z.string()).describe('Description filter')
+    description: z.optional(z.string()).describe('Description filter'),
+    operation: z.optional(z.string()).describe('Filter by SDK/MCP operation field name (e.g. "compensation_fund_add"). Returns only permissions triggered by this operation. Use this to answer: "What permission does operation X require?"')
 }).describe('Permission filter');
+export const CommonMistakeInfoSchema = z.object({
+    object_type: z.string().describe('The object type this mistake applies to (e.g. "Service", "Arbitration")'),
+    operation: z.string().describe('The operation field name this mistake applies to (e.g. "compensation_fund_add", "voting_deadline")'),
+    category: z.enum(['field_name', 'unit', 'value_range', 'workflow', 'timing']).describe('Category of the mistake: field_name (wrong field name), unit (wrong unit like seconds vs ms), value_range (wrong expected value), workflow (wrong operation order), timing (wrong time constraint)'),
+    mistake: z.string().describe('Short description of the mistake'),
+    correct_usage: z.string().describe('The correct usage pattern'),
+    wrong_example: z.string().describe('Example of the wrong usage'),
+    correct_example: z.string().describe('Example of the correct usage')
+}).describe('A known common mistake for an on-chain operation. Use this to proactively warn users before they submit a transaction.');
+export const CommonMistakeFilterSchema = z.object({
+    object_type: z.optional(z.string()).describe('Filter by object type (e.g. "Service")'),
+    operation: z.optional(z.string()).describe('Filter by operation field name (e.g. "compensation_fund_add")'),
+    category: z.optional(z.enum(['field_name', 'unit', 'value_range', 'workflow', 'timing'])).describe('Filter by category (e.g. "field_name" for field-name mistakes, "unit" for unit mistakes)')
+}).describe('Filter for common mistakes. Use operation:"compensation_fund_add" to find mistakes for a specific operation.');
 export const BridgeTokenInfoSchema = z.object({
     tokenId: z.number().describe('On-chain token ID (mainnet: WBTC=1, ETH/WETH=2, USDC=3, USDT=4)'),
     symbol: z.string().describe('Token symbol/abbreviation (ETH, WETH, WBTC, USDC, USDT)'),
@@ -1212,8 +1367,12 @@ export const ProtocolInfoQuerySchema = z.discriminatedUnion('info', [
     }).strict().describe('Constants query'),
     z.object({
         info: z.literal('built-in permissions'),
-        filter: z.optional(PermissionFilterSchema).describe('Filter for built-in permissions')
-    }).strict().describe('Built-in permissions query'),
+        filter: z.optional(PermissionFilterSchema).describe('Filter for built-in permissions. Use operation:"compensation_fund_add" to find which permission a specific operation requires.')
+    }).strict().describe('Built-in permissions query. Each permission includes an optional "operation" field that maps to the SDK/MCP Call*_Data field name triggering it. Use this to answer: "What permission does operation X require?" — e.g. filter operation:"compensation_fund_add" returns permission index 315 (service.compensation_fund_deposit).'),
+    z.object({
+        info: z.literal('common mistakes'),
+        filter: z.optional(CommonMistakeFilterSchema).describe('Filter for common mistakes. Use operation:"compensation_fund_add" to find mistakes for a specific operation, or category:"field_name" for all field-name mistakes.')
+    }).strict().describe('Common mistakes query. Returns known field-name, unit, value-range, workflow, and timing pitfalls for on-chain operations. Use this to proactively warn users before submitting a transaction. Example: query operation:"compensation_fund_add" to learn about the {amount} vs {balance} field name mistake.'),
     z.object({
         info: z.literal('guard instructions'),
         filter: z.optional(GuardInstructFilterOptionsSchema).describe('Filter for guard instructions')
@@ -1238,7 +1397,11 @@ export const ProtocolInfoResultWrappedSchema = z.discriminatedUnion('info', [
     }),
     z.object({
         info: z.literal('built-in permissions'),
-        result: z.array(PermissionInfoTypeSchema).describe('Built-in permissions result')
+        result: z.array(PermissionInfoTypeSchema).describe('Built-in permissions result. Each item includes an optional "operation" field mapping to the SDK/MCP field name that triggers this permission.')
+    }),
+    z.object({
+        info: z.literal('common mistakes'),
+        result: z.array(CommonMistakeInfoSchema).describe('Common mistakes result. Each item documents a known pitfall (wrong field name, wrong unit, wrong workflow order, etc.) with wrong/correct examples.')
     }),
     z.object({
         info: z.literal('guard instructions'),

package/dist/schema/schema-query/index.d.ts

@@ -1,16 +1,25 @@
 import { z } from "zod";
 export declare const SchemaQueryInputSchema: z.ZodObject<{
-    action: z.ZodEnum<["list", "get", "get_output", "search", "list_operations"]>;
+    action: z.ZodEnum<["list", "get", "get_output", "search", "list_operations", "get_guard_templates", "get_field", "search_examples"]>;
     name: z.ZodOptional<z.ZodString>;
     query: z.ZodOptional<z.ZodString>;
+    field_path: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+    output_file: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    action: "get" | "search" | "list" | "get_output" | "list_operations";
+    action: "get" | "search" | "list" | "get_output" | "list_operations" | "get_guard_templates" | "get_field" | "search_examples";
     name?: string | undefined;
     query?: string | undefined;
+    field_path?: string | undefined;
+    template?: string | undefined;
+    output_file?: string | undefined;
 }, {
-    action: "get" | "search" | "list" | "get_output" | "list_operations";
+    action: "get" | "search" | "list" | "get_output" | "list_operations" | "get_guard_templates" | "get_field" | "search_examples";
     name?: string | undefined;
     query?: string | undefined;
+    field_path?: string | undefined;
+    template?: string | undefined;
+    output_file?: string | undefined;
 }>;
 export declare const SchemaQueryOutputSchema: z.ZodObject<{
     success: z.ZodBoolean;
@@ -27,27 +36,80 @@ export declare const SchemaQueryOutputSchema: z.ZodObject<{
         name: string;
         description?: string | undefined;
         title?: string | undefined;
+    }>, "many">, z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        tags: z.ZodArray<z.ZodString, "many">;
+        industry: z.ZodString;
+        operation_type: z.ZodString;
+        verified: z.ZodBoolean;
+        score: z.ZodNumber;
+        matched_fields: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        description: string;
+        title: string;
+        score: number;
+        tags: string[];
+        file: string;
+        industry: string;
+        operation_type: string;
+        verified: boolean;
+        matched_fields: string[];
+    }, {
+        description: string;
+        title: string;
+        score: number;
+        tags: string[];
+        file: string;
+        industry: string;
+        operation_type: string;
+        verified: boolean;
+        matched_fields: string[];
     }>, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodNull]>;
     message: z.ZodString;
     suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    output_file_path: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     message: string;
     data: Record<string, unknown> | {
         name: string;
         description?: string | undefined;
         title?: string | undefined;
+    }[] | {
+        description: string;
+        title: string;
+        score: number;
+        tags: string[];
+        file: string;
+        industry: string;
+        operation_type: string;
+        verified: boolean;
+        matched_fields: string[];
     }[] | null;
     success: boolean;
     action: string;
     suggestions?: string[] | undefined;
+    output_file_path?: string | undefined;
 }, {
     message: string;
     data: Record<string, unknown> | {
         name: string;
         description?: string | undefined;
         title?: string | undefined;
+    }[] | {
+        description: string;
+        title: string;
+        score: number;
+        tags: string[];
+        file: string;
+        industry: string;
+        operation_type: string;
+        verified: boolean;
+        matched_fields: string[];
     }[] | null;
     success: boolean;
     action: string;
     suggestions?: string[] | undefined;
+    output_file_path?: string | undefined;
 }>;

package/dist/schema/schema-query/index.js

@@ -8,16 +8,31 @@ export const SchemaQueryInputSchema = z
         "get_output",
         "search",
         "list_operations",
+        "get_guard_templates",
+        "get_field",
+        "search_examples",
     ])
-        .describe("Action to perform: 'list' to see all available schemas, 'get' to retrieve a specific input schema, 'get_output' to retrieve a tool's output schema, 'search' to find schemas by keyword, 'list_operations' to list all on-chain operations"),
+        .describe("Action to perform: 'list' (all schemas), 'get' (specific input schema), 'get_output' (tool output schema), 'get_field' (field-path query e.g. field_path='data.node'), 'search' (by keyword), 'list_operations' (on-chain operations), 'get_guard_templates' (Guard creation templates + best practices), 'search_examples' (search verified example files by keyword — matches title, description, tags, operation_type, industry)."),
     name: z
         .string()
         .optional()
-        .describe("Schema/tool name for 'get'/'get_output' action (e.g., 'onchain_operations', 'account_operation', 'onchain_operations_permission')"),
+        .describe("Schema/tool name for 'get'/'get_output'/'get_field' action (e.g., 'onchain_operations', 'onchain_operations_machine')."),
     query: z
         .string()
         .optional()
         .describe("Search query for 'search' action"),
+    field_path: z
+        .string()
+        .optional()
+        .describe("Dot-separated field path for 'get_field' action (e.g. 'data.node', 'data.node.nodes.0.pairs'). Navigates schema.properties.* and schema.items.*."),
+    template: z
+        .string()
+        .optional()
+        .describe("Guard template name for 'get_guard_templates' action. Omit to list all available templates. Available: signer_verification, progress_node_check, order_owner_verification, service_belonging_check, reward_not_claimed, combined_reward_guard."),
+    output_file: z
+        .string()
+        .optional()
+        .describe("When set, writes the response data to this file path (relative to cwd) and returns the path instead of inline data. Use for large schemas that would be truncated. Prefer workspace paths like '.trae/tmp/schema.json' so the Read tool can access them."),
 })
     .strict();
 const SchemaListItemSchema = z
@@ -27,6 +42,19 @@ const SchemaListItemSchema = z
     description: z.string().optional().describe("Short description, if known."),
 })
     .strict();
+const ExampleSearchResultSchema = z
+    .object({
+    file: z.string().describe("Example file name (e.g. 'rental-ziroom-service-create.json')."),
+    title: z.string().describe("Human-readable title from the example metadata."),
+    description: z.string().describe("Longer description from the example metadata."),
+    tags: z.array(z.string()).describe("Tags from the example metadata."),
+    industry: z.string().describe("Industry category (e.g. 'rental', 'retail', 'general')."),
+    operation_type: z.string().describe("Operation type (e.g. 'service', 'machine', 'guard', 'permission')."),
+    verified: z.boolean().describe("Whether the example is marked as verified."),
+    score: z.number().describe("Relevance score — number of fields that matched the query (0-5)."),
+    matched_fields: z.array(z.string()).describe("List of fields that matched the query."),
+})
+    .strict();
 export const SchemaQueryOutputSchema = z
     .object({
     success: z.boolean().describe("Whether the request was successful"),
@@ -34,14 +62,19 @@ export const SchemaQueryOutputSchema = z
     data: z
         .union([
         z.array(SchemaListItemSchema).describe("List of schema summaries (list/search/list_operations)."),
-        z.record(z.unknown()).describe("JSON Schema object (get/get_output)."),
-        z.null().describe("No data — lookup failed or returned nothing."),
+        z.array(ExampleSearchResultSchema).describe("List of matching examples (search_examples)."),
+        z.record(z.unknown()).describe("JSON Schema object (get/get_output/get_field) or Guard template data."),
+        z.null().describe("No data — lookup failed or returned nothing, or data was written to output_file."),
     ])
-        .describe("Response data — array of schema summaries for list-like actions, JSON Schema object for get/get_output, null on failure."),
+        .describe("Response data — array of schema summaries for list-like actions, array of example results for search_examples, JSON Schema object for get/get_output/get_field, Guard template data for get_guard_templates, null on failure or when output_file is used."),
     message: z.string().describe("Human-readable message describing the result"),
     suggestions: z
         .array(z.string())
         .optional()
         .describe("Suggested next steps or alternatives"),
+    output_file_path: z
+        .string()
+        .optional()
+        .describe("When output_file is used, contains the absolute file path where data was written."),
 })
     .strict();

package/dist/schema/utils/node-parser.js

@@ -1,5 +1,5 @@
 import { NodeSchema } from '../call/machine.js';
-import { MachineNodeSchema } from '../query/index.js';
+import { MachineNodeSchema, MachineNodePairSchema, MachineForwardSchema } from '../query/index.js';
 import { writeFileSync } from 'fs';
 function detectFormat(text) {
     const trimmed = text.trim();
@@ -249,6 +249,19 @@ export function parseMachineNodesFromText(text) {
     if (errors.length > 0) {
         return { success: false, errors };
     }
+    const hasEntryForward = nodes.some(node => node.pairs.some(pair => pair.prev_node === ""));
+    if (!hasEntryForward) {
+        return {
+            success: false,
+            errors: [{
+                    message: 'Machine has no entry forward. At least one node must have a pair with prev_node="" (empty string), ' +
+                        'which defines how Progress advances from the initial state (current="") to the first node. ' +
+                        'Without an entry forward, the workflow will be permanently stuck. ' +
+                        'Example: {name: "Subscribed", pairs: [{prev_node: "", forwards: [{name: "Subscribe", weight: 1}]}]}',
+                    path: '/',
+                }]
+        };
+    }
     return { success: true, data: nodes, errors: [] };
 }
 export function formatNodeErrors(errors) {
@@ -265,7 +278,7 @@ export function validateMachineNode(node) {
     return validateWithZod(MachineNodeSchema, node);
 }
 export function validateMachineNodePair(pair) {
-    const result = MachineNodeSchema.shape.pairs.element.safeParse(pair);
+    const result = MachineNodePairSchema.safeParse(pair);
     if (result.success) {
         return { success: true, errors: [] };
     }
@@ -276,7 +289,7 @@ export function validateMachineNodePair(pair) {
     return { success: false, errors };
 }
 export function validateMachineForward(forward) {
-    const result = MachineNodeSchema.shape.pairs.element.shape.forwards.element.safeParse(forward);
+    const result = MachineForwardSchema.safeParse(forward);
     if (result.success) {
         return { success: true, errors: [] };
     }
@@ -325,7 +338,10 @@ export function machineNodesToMarkdown(nodes, options = {}) {
                 for (const forward of pair.forwards) {
                     const namedOp = forward.namedOperator || '';
                     const permIdx = forward.permissionIndex?.toString() || '';
-                    const guard = forward.guard?.guard || '';
+                    const guardRaw = forward.guard;
+                    const guard = typeof guardRaw === 'string'
+                        ? guardRaw
+                        : (guardRaw?.guard || '');
                     md += `| ${forward.name} | ${forward.weight} | ${namedOp} | ${permIdx} | ${guard} |\n`;
                 }
                 md += `\n`;