@wowok/agent-mcp 2.3.16 → 2.4.1

package/dist/knowledge/glossary.js

@@ -3,7 +3,7 @@ export const CONCEPT_GLOSSARY = [
         term: "Permission",
         definition: "Organization-wide permission object. indices 0-999 builtin, 1000-65535 custom. " +
             "Shared across all Progress instances of a Service. Use for internal staff roles.",
-        aliases: ["permission object", "权限对象"],
+        aliases: ["permission object"],
         category: "permission",
     },
     {
@@ -17,7 +17,7 @@ export const CONCEPT_GLOSSARY = [
         term: "OrderHolder",
         definition: "The order holder and their agents. Represented by namedOperator=\"\" (empty string) " +
             "on a Forward. Lets the customer operate their own order.",
-        aliases: ["order owner", "orderholder", "订单持有人"],
+        aliases: ["order owner", "orderholder", "order holder"],
         category: "permission",
     },
     {
@@ -25,139 +25,139 @@ export const CONCEPT_GLOSSARY = [
         definition: "A state-transition edge in a Machine. Carries weight, a permission " +
             "(Permission index / NamedOperator / OrderHolder), and an optional Guard. " +
             "Every Forward MUST define at least one permission.",
-        aliases: ["迁移", "transition"],
+        aliases: ["transition"],
         category: "operation",
     },
     {
         term: "Pair",
         definition: "A prev_node → next_node transition group in a Machine with a threshold. " +
             "When the cumulative weight of executed Forwards meets the threshold, the Pair fires.",
-        aliases: ["迁移对", "transition pair"],
+        aliases: ["transition pair"],
         category: "operation",
     },
     {
         term: "Machine",
         definition: "Workflow blueprint (directed graph). Becomes immutable after publish. " +
             "A Progress instance is created per order from the Machine.",
-        aliases: ["工作流模板", "machine template"],
+        aliases: ["machine template"],
         category: "object",
     },
     {
         term: "Progress",
         definition: "A workflow instance bound to one order. Advances via Forwards; " +
             "carries retained_submission values for Guard verification.",
-        aliases: ["流程实例", "progress instance"],
+        aliases: ["progress instance"],
         category: "object",
     },
     {
         term: "Guard",
         definition: "Immutable static validation rule. Verifies submissions and on-chain object data. " +
             "Returns boolean. Cannot be mutated after creation.",
-        aliases: ["守卫", "guard object"],
+        aliases: ["guard object"],
         category: "acceptance",
     },
     {
         term: "Repository",
         definition: "Mutable dynamic acceptance store. Keyed by (name, entity). " +
             "Used for data that can change over time (e.g. SLA config, review records).",
-        aliases: ["仓库", "repository object"],
+        aliases: ["repository object"],
         category: "acceptance",
     },
     {
         term: "Acceptance",
         definition: "The verification standard for a process step. Composed of static Guard + " +
             "dynamic Repository. Drives whether a Forward can execute.",
-        aliases: ["验收标准", "acceptance standard"],
+        aliases: ["acceptance standard"],
         category: "acceptance",
     },
     {
         term: "Service",
         definition: "A merchant's service listing. References Machine, order_allocators, arbitrations, " +
             "compensation_fund, rewards, buy_guard. machine & order_allocators lock after publish.",
-        aliases: ["服务", "service object"],
+        aliases: ["service object"],
         category: "object",
     },
     {
         term: "Order",
         definition: "An order against a Service. Funds are escrowed; released via Progress + Allocation. " +
             "Arb cases attach to orders for dispute resolution.",
-        aliases: ["订单"],
+        aliases: ["order instance"],
         category: "object",
     },
     {
         term: "Allocator",
         definition: "Fund distribution rules. Priority: Amount → Rate → Surplus. first-Guard-wins. " +
             "Locked on Service publish (order_allocators).",
-        aliases: ["分账器", "allocation"],
+        aliases: ["allocation"],
         category: "fund",
     },
     {
         term: "Allocation",
         definition: "The act of distributing escrowed funds to recipients per an Allocator. " +
             "Executed by the order holder or Permission holder.",
-        aliases: ["分账"],
+        aliases: ["allocation act"],
         category: "fund",
     },
     {
         term: "Arbitration",
         definition: "Independent arbitration service object. Configured with voting_guard, usage_guard, " +
             "fee. Generates Arb cases per dispute. Third-party preferred over self-built.",
-        aliases: ["仲裁服务", "arb service"],
+        aliases: ["arb service"],
         category: "object",
     },
     {
         term: "Arb",
         definition: "A single dispute case instance of an Arbitration. Has a state machine " +
             "(dispute → confirm → vote → verdict → settle).",
-        aliases: ["仲裁案", "arb case"],
+        aliases: ["arb case"],
         category: "object",
     },
     {
         term: "compensation_fund",
         definition: "A fund attached to a Service. Arbitration indemnity is drawn from it. " +
             "Adequacy is a key trust signal for customers.",
-        aliases: ["赔偿基金", "赔偿金"],
+        aliases: ["compensation fund"],
         category: "fund",
     },
     {
         term: "buy_guard",
         definition: "A Guard attached to a Service that gates purchasing. Validates customer eligibility.",
-        aliases: ["购买守卫"],
+        aliases: ["buy guard"],
         category: "acceptance",
     },
     {
         term: "Sub-Order",
         definition: "A child order in a cross-Machine supply chain. Introduced at a node with transparent " +
             "suppliers; verified by Guard to originate from one of the declared suppliers.",
-        aliases: ["采购子订单", "suborder", "sub order"],
+        aliases: ["suborder", "sub order"],
         category: "object",
     },
     {
         term: "Reward",
         definition: "Incentive pool. claim is Guard-gated. guard_add supports Fixed or GuardU64Identifier " +
             "(dynamic). Used for marketing (first-order, cumulative, referral).",
-        aliases: ["奖励", "reward pool"],
+        aliases: ["reward pool"],
         category: "fund",
     },
     {
         term: "Demand",
         definition: "A user's posted service request with optional reward. presenters submit proposals; " +
             "Guard filters them. Matches Services for personalized acquisition.",
-        aliases: ["需求"],
+        aliases: ["demand request"],
         category: "object",
     },
     {
         term: "Personal",
         definition: "Permanently public on-chain identity profile. Social links, reputation (likes/dislikes), " +
             "personal info records. CRITICAL: everything here is PUBLIC forever.",
-        aliases: ["公开身份", "personal profile"],
+        aliases: ["personal profile"],
         category: "object",
     },
     {
         term: "Contact",
         definition: "Bridges a Service's um (contact) and the Messenger ims (messaging). Enables " +
             "off-chain encrypted communication for pre-order negotiation & evidence.",
-        aliases: ["联系"],
+        aliases: ["contact bridge"],
         category: "object",
     },
 ];

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

@@ -0,0 +1,19 @@
+export interface GuardScene {
+    id: string;
+    name: string;
+    host_object: "Service" | "Machine" | "Arbitration" | "Reward" | "Repository" | "Progress" | "Demand" | "Standalone";
+    binding_field: string;
+    validation_scene: string;
+    pass_result: string;
+    fail_result: string;
+    submission_source: string;
+    special_constraints: string[];
+    common_patterns: string[];
+    mutable_after_publish: boolean;
+    r_rounds_focus: string[];
+}
+export declare const GUARD_SCENES: GuardScene[];
+export declare function findScene(host_object: string, binding_field: string): GuardScene | undefined;
+export declare function inferSceneFromAction(action: "buy" | "forward" | "allocate" | "claim_reward" | "vote" | "dispute" | "write_repository" | "submit_progress" | "gen_passport"): GuardScene | undefined;
+export declare function getImmutableScenes(): GuardScene[];
+export declare function getNumericIdentifierScenes(): GuardScene[];

package/dist/knowledge/guard-ledger.js

@@ -0,0 +1,246 @@
+export const GUARD_SCENES = [
+    {
+        id: "service_buy_guard",
+        name: "Service purchase validation (buy_guard)",
+        host_object: "Service",
+        binding_field: "buy_guard",
+        validation_scene: "When a customer places an order to purchase a service, the Guard validates whether the customer is eligible to purchase (identity/permission/condition)",
+        pass_result: "Create the Order object; the customer enters the payment flow",
+        fail_result: "Transaction rejected; Order is not created; the customer cannot purchase",
+        submission_source: "Customer (signer address, credentials, Passport, etc.)",
+        special_constraints: [
+            "The Guard table must declare all data the customer needs to submit",
+            "The name of b_submission=true entries must be a natural-language description (the contract the customer sees)",
+            "If the Guard references the Service itself, use the circular reference pattern (CREATE Service → CREATE Guard → MODIFY Service)",
+            "buy_guard can still be modified after Service is published (via MODIFY Service)",
+        ],
+        common_patterns: [
+            "Identity check: context(Signer) + logic_equal (single address) / vec_contains_address (whitelist)",
+            "Membership validation: query EntityRegistrar(0xaab) + logic_and combination",
+            "Time limit: context(Clock) + logic_as_u256_greater_or_equal",
+            "Multi-condition: logic_and combining multiple checks",
+        ],
+        mutable_after_publish: true,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R7", "R9"],
+    },
+    {
+        id: "service_order_allocators_guard",
+        name: "Allocation strategy selection validation (order_allocators[].guard)",
+        host_object: "Service",
+        binding_field: "order_allocators",
+        validation_scene: "When an order is completed or allocation conditions are met, the system evaluates each Allocator's Guard in order_allocators order. " +
+            "The first Allocator whose Guard passes executes the allocation",
+        pass_result: "Execute that Allocator's allocation strategy (distribute funds by ratio/condition)",
+        fail_result: "Skip this Allocator and try the next (first-match-wins). If all Allocators fail, funds are not distributed",
+        submission_source: "System auto-derives from Progress state (no explicit customer submission needed)",
+        special_constraints: [
+            "order_allocators is order-sensitive: the first Allocator whose Guard passes executes allocation",
+            "order_allocators cannot be modified after Service is published (immutable)",
+            "Guard usually queries Order/Progress state to determine allocation conditions",
+            "Common queries: order.amount, progress.current_node, order.completed, etc.",
+            "GuardIdentifier can be used for dynamic amounts (extract u64 value from table as allocation ratio)",
+        ],
+        common_patterns: [
+            "Node state check: query(Progress.current_node) + logic_equal('Completed')",
+            "Amount threshold: query(Order.amount) + logic_as_u256_greater_or_equal(threshold)",
+            "Multi-condition combination: logic_and (node state + amount + time)",
+            "GuardIdentifier dynamic ratio: table[u64] extracts allocation ratio",
+        ],
+        mutable_after_publish: false,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R6", "R7"],
+    },
+    {
+        id: "machine_forward_guard",
+        name: "Workflow node advancement validation (Forward.guard)",
+        host_object: "Machine",
+        binding_field: "Forward.guard",
+        validation_scene: "When a customer or provider executes a Forward operation to advance the workflow, the Guard validates whether advancement to the next node is allowed",
+        pass_result: "Progress advances to next_node; session accumulates weight",
+        fail_result: "Forward is blocked; Progress stays at the current node. Optional retained_submission retains audit data",
+        submission_source: "The party executing Forward (Customer or Provider, depending on Forward configuration)",
+        special_constraints: [
+            "Forward.guard cannot be modified after Machine is published (a new Machine must be created)",
+            "Optional retained_submission: stores submission data in Progress for later audit",
+            "retained_submission indices must correspond to the Guard table",
+            "Common queries: progress.current_node, progress.session_forward, order.service, etc.",
+            "Time lock: context(Clock) + calc_number_add(progress.entry_time, duration) tested with 1000ms",
+        ],
+        common_patterns: [
+            "Identity check: context(Signer) + logic_equal (only specific parties can advance)",
+            "Time lock: context(Clock) + calc_number_add + logic_as_u256_greater_or_equal",
+            "Prior Forward completion: query_progress_history_find + logic_equal(accomplished=true)",
+            "Submission data validation: identifier(submission) + logic_equal(expected_value)",
+            "Cross-object query: convert_witness=TypeOrderProgress(100) queries Progress from Order",
+        ],
+        mutable_after_publish: false,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R6", "R7", "R8", "R9"],
+    },
+    {
+        id: "progress_submission_guard",
+        name: "Progress submission data validation (submission guard)",
+        host_object: "Progress",
+        binding_field: "submission",
+        validation_scene: "Whether the data (e.g. signature, credential, confirmation) submitted during Forward execution satisfies the Guard condition",
+        pass_result: "Forward completes; node advances after session accumulates weight to threshold",
+        fail_result: "Forward does not complete; waits for resubmission or condition satisfaction",
+        submission_source: "The party submitting data (Customer or Provider)",
+        special_constraints: [
+            "Works in concert with Forward.guard: Forward.guard validates eligibility, submission guard validates data",
+            "retained_submission stores submission data in Progress session for audit",
+            "Common queries: progress.session_forward, progress.session_weight, etc.",
+        ],
+        common_patterns: [
+            "Signature validation: identifier(signature_submission) + logic_equal(expected)",
+            "Credential validation: query(Repository.data) + logic_equal(submission_proof)",
+            "Confirmation validation: identifier(confirm_submission) + logic_equal(true)",
+        ],
+        mutable_after_publish: false,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R6", "R8"],
+    },
+    {
+        id: "reward_guard",
+        name: "Reward claim validation (Reward.guard)",
+        host_object: "Reward",
+        binding_field: "guard",
+        validation_scene: "When a user claims from a reward pool, the Guard validates eligibility to claim",
+        pass_result: "Reward is distributed to the Claimant and recorded in reward_record",
+        fail_result: "Claim rejected; reward is not distributed",
+        submission_source: "Claimant (address, credentials, Passport)",
+        special_constraints: [
+            "Common query_reward_record_count prevents duplicate claims (one-time claim)",
+            "Guard usually queries history records + time conditions + identity validation",
+            "If the Reward references a Service, use the circular reference pattern",
+        ],
+        common_patterns: [
+            "One-time claim: query_reward_record_count(recipient) + logic_equal(0)",
+            "Time window: context(Clock) + logic_as_u256_greater_or_equal(start_time)",
+            "Identity validation: context(Signer) + vec_contains_address(allowlist)",
+            "Multi-condition: logic_and (identity + time + not claimed before)",
+        ],
+        mutable_after_publish: true,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R7", "R8", "R9"],
+    },
+    {
+        id: "repository_write_guard",
+        name: "Repository write validation (write_guard)",
+        host_object: "Repository",
+        binding_field: "write_guard",
+        validation_scene: "When writing to on-chain storage, the Guard validates write eligibility and optionally extracts data",
+        pass_result: "Write succeeds; optional id_from_submission extracts the entity ID, data_from_submission extracts the data value",
+        fail_result: "Write rejected",
+        submission_source: "Writer/Reader",
+        special_constraints: [
+            "The table entry referenced by id_from_submission must be of Address type",
+            "The table entry referenced by data_from_submission must match the Repository's value_type",
+            "Type mismatch leads to write failure or data corruption",
+            "Commonly used for oracle data writes, third-party credential attestation, etc.",
+        ],
+        common_patterns: [
+            "Authorized writer: context(Signer) + vec_contains_address(authorized_writers)",
+            "Data format validation: identifier(data_submission) + logic_string_contains(expected_prefix)",
+            "ID extraction: id_from_submission + data_from_submission combination",
+        ],
+        mutable_after_publish: true,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R6", "R7"],
+    },
+    {
+        id: "arbitration_usage_guard",
+        name: "Dispute initiation validation (usage_guard)",
+        host_object: "Arbitration",
+        binding_field: "usage_guard",
+        validation_scene: "When a customer initiates a dispute against an order, the Guard validates whether the customer is eligible to initiate the dispute",
+        pass_result: "Create an Arb case and enter the arbitration flow",
+        fail_result: "Dispute rejected; Arb is not created",
+        submission_source: "Customer (Passport credential)",
+        special_constraints: [
+            "When Arbitration bPaused=true, it blocks first (before the Guard check)",
+            "The customer must first generate a Passport (gen_passport passes usage_guard)",
+            "Common queries: order.completed, order.service, entity.has, etc.",
+            "Guard validates customer identity + order status + dispute eligibility",
+        ],
+        common_patterns: [
+            "Order status validation: query(Order.status) + logic_equal('completed')",
+            "Membership validation: query(EntityRegistrar) + logic_and",
+            "Time window: query(Order.time) + calc_number_add + context(Clock)",
+            "Passport credential: identifier(passport_submission) + context(Signer)",
+        ],
+        mutable_after_publish: true,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R7", "R8", "R9"],
+    },
+    {
+        id: "arbitration_voting_guard",
+        name: "Arbitration voting weight validation (voting_guard[])",
+        host_object: "Arbitration",
+        binding_field: "voting_guard",
+        validation_scene: "When an arbitrator votes, the Guard validates voting eligibility and extracts the voting weight (u32) from GuardIdentifier",
+        pass_result: "Vote is counted; weight is the value extracted by GuardIdentifier",
+        fail_result: "Vote rejected",
+        submission_source: "Voter (Passport credential with weight data)",
+        special_constraints: [
+            "The table entry referenced by GuardIdentifier must be of a numeric type (U8-U256), cast to u32",
+            "Non-numeric types cause E_GUARD_IDENTIFIER_NOT_NUMBER error",
+            "b_submission must be true (weight is submitted at runtime by the voter)",
+            "Multiple voting_guards can be configured, each corresponding to a different voter group",
+            "When Arbitration bPaused=true, voting is blocked",
+        ],
+        common_patterns: [
+            "Reputation score weight: query(EntityRegistrar.records[reputation]) + GuardIdentifier(u64)",
+            "Fixed weight: identifier(constant_weight) + GuardIdentifier",
+            "Multi-tier voting: different voting_guards correspond to different weight tiers",
+            "Eligibility + weight: logic_and (eligibility check + GuardIdentifier extracts weight)",
+        ],
+        mutable_after_publish: true,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R6", "R7", "R8", "R9"],
+    },
+    {
+        id: "gen_passport_guard",
+        name: "Passport credential generation validation (gen_passport)",
+        host_object: "Standalone",
+        binding_field: "none",
+        validation_scene: "When a user calls gen_passport, the Guard validates user eligibility and generates a Passport with credentials",
+        pass_result: "Passport is generated, containing credentials validated by the Guard",
+        fail_result: "Passport generation fails; the user did not pass validation",
+        submission_source: "Passport applicant (signer + credentials)",
+        special_constraints: [
+            "impack_list is always empty during the verify phase (only filled after result_for_permission)",
+            "Therefore quote_guard (query 1167) always fails in the gen_passport flow (IMPACK_GUARD_NOT_FOUND)",
+            "Only Repository queries with quote_guard==None can pass in gen_passport",
+            "Guard can be created standalone (not bound to a specific Host Object)",
+            "Guard can be depended on by other Guards via rely (requires rep=true)",
+            "The Passport generated by gen_passport can be used as submission data for subsequent operations",
+        ],
+        common_patterns: [
+            "Identity validation: context(Signer) + logic_equal (single address/whitelist)",
+            "Membership eligibility: query(EntityRegistrar) + logic_equal",
+            "Reputation threshold: query(EntityRegistrar.records[reputation]) + logic_as_u256_greater_or_equal",
+            "Multi-condition combination: logic_and (identity + eligibility + reputation)",
+        ],
+        mutable_after_publish: false,
+        r_rounds_focus: ["R1", "R2", "R3", "R5", "R6", "R7"],
+    },
+];
+export function findScene(host_object, binding_field) {
+    return GUARD_SCENES.find((s) => s.host_object === host_object &&
+        s.binding_field === binding_field);
+}
+export function inferSceneFromAction(action) {
+    const map = {
+        buy: "service_buy_guard",
+        forward: "machine_forward_guard",
+        allocate: "service_order_allocators_guard",
+        claim_reward: "reward_guard",
+        vote: "arbitration_voting_guard",
+        dispute: "arbitration_usage_guard",
+        write_repository: "repository_write_guard",
+        submit_progress: "progress_submission_guard",
+        gen_passport: "gen_passport_guard",
+    };
+    const id = map[action];
+    return GUARD_SCENES.find((s) => s.id === id);
+}
+export function getImmutableScenes() {
+    return GUARD_SCENES.filter((s) => !s.mutable_after_publish);
+}
+export function getNumericIdentifierScenes() {
+    return GUARD_SCENES.filter((s) => s.special_constraints.some((c) => c.includes("numeric") || c.includes("GuardIdentifier")));
+}

package/dist/knowledge/guard-lint.d.ts

@@ -0,0 +1,76 @@
+import { type GuardRiskAssessment } from "./guard-risk.js";
+export type DiagnosticSource = "sdk" | "lint" | "risk";
+export type DiagnosticSeverity = "error" | "warning" | "info" | "hint";
+export interface GuardDiagnostic {
+    code: string;
+    message: string;
+    severity: DiagnosticSeverity;
+    source: DiagnosticSource;
+    location: {
+        path: string;
+    };
+    fix?: {
+        description: string;
+        auto_fixable: boolean;
+    };
+}
+export interface GuardJsonInput {
+    description?: string;
+    table: Array<{
+        identifier: number;
+        b_submission?: boolean;
+        value_type?: string;
+        value?: unknown;
+        name?: string;
+        object_type?: string;
+        is_system_address?: boolean;
+    }>;
+    root: any;
+    rely?: {
+        guards: string[];
+        logic_or?: boolean;
+    };
+    binding_hint?: {
+        host_object?: string;
+        binding_field?: string;
+        action?: string;
+    };
+}
+export interface AutoFixAction {
+    diagnostic_code: string;
+    description: string;
+    before?: string;
+    after?: string;
+    path: string;
+}
+export interface GuardLintResult {
+    json_summary: {
+        table_count: number;
+        root_type: string;
+        has_rely: boolean;
+        rely_count: number;
+        has_description: boolean;
+    };
+    diagnostics: GuardDiagnostic[];
+    fixed_json?: GuardJsonInput;
+    fix_actions: AutoFixAction[];
+    risk_assessment?: GuardRiskAssessment;
+    summary: {
+        errors: number;
+        warnings: number;
+        infos: number;
+        auto_fixes_applied: number;
+        ready: boolean;
+        next_step: string;
+    };
+}
+export declare function autoFixGuard(json: GuardJsonInput): {
+    fixed: GuardJsonInput;
+    actions: AutoFixAction[];
+};
+export declare function lintGuard(json: GuardJsonInput, options?: {
+    auto_fix?: boolean;
+}): Promise<GuardLintResult>;
+export declare function isGuardReady(json: GuardJsonInput): Promise<boolean>;
+export declare function getGuardErrors(json: GuardJsonInput): Promise<GuardDiagnostic[]>;
+export declare function formatLintResult(result: GuardLintResult): string;