@wowok/agent-mcp 2.4.3 → 2.5.1

package/dist/knowledge/demand-translation.js

@@ -0,0 +1,354 @@
+import { MAX_REWARD_COUNT, MAX_GUARD_COUNT_DEMAND, MAX_DESCRIPTION_LENGTH, MAX_LONG_NAME_LENGTH, } from "@wowok/wowok";
+const MAX_FEEDBACK_COUNT = 20;
+export const SEMANTIC_TO_DEMAND_SCHEMA_RULES = [
+    {
+        id: "P-DEM-01",
+        pattern_name: "Open Demand (no guards) — free presentation",
+        configuration_classification: "open",
+        semantic_intent: "An open Demand accepts presentations from any sender via the plain `present` function (demand.move:100). " +
+            "No Passport is required. Use this for broad-cast demands where the creator wants to collect as many " +
+            "presentations as possible (e.g. open calls for service providers, public RFPs). The guards vector is empty.",
+        match_keywords: ["open", "no guard", "free presentation", "public", "rfp", "open call"],
+        schema_elements: {
+            required_fields: ["description", "permission"],
+            optional_fields: ["location", "rewards", "um", "namedNew"],
+            presentation_path: "plain_present",
+            um_recommendation: "Optional. Set um to a Contact object if the Demand should be managed by an intermediary. " +
+                "Leave as Option::none for direct creator management.",
+        },
+        constraints: [
+            "guards vector must be empty (initial state — do not call guard_add)",
+            "Callers MUST use plain `present` or `present_service` — present_with_passport will abort with E_GUARD_NOT_FOUND (4)",
+            "description non-empty and within MAX_DESCRIPTION_LENGTH (4000 chars)",
+            "If location is set, within MAX_LONG_NAME_LENGTH (256 chars)",
+        ],
+        example: {
+            description: "Open call for freelance designers — submit portfolio link as recommend",
+            location: "Shanghai",
+            rewards: ["0xabc...reward_addr_1"],
+            permission: "0xperm...permission_addr",
+            um: null,
+            namedNew: { name: "open_design_call_2026" },
+        },
+    },
+    {
+        id: "P-DEM-02",
+        pattern_name: "Guarded Demand (with guards) — passport required for present",
+        configuration_classification: "guarded",
+        semantic_intent: "A guarded Demand requires every presenter to supply a Passport that passes one of the affiliated Guards. " +
+            "Use this when the creator wants to filter presentations by Guard-defined criteria (KYC, membership, " +
+            "stake, etc.). The guards vector is non-empty. Each guard carries an optional service_identifier that, " +
+            "when set, routes present_with_passport to extract the submission address from the Passport (overriding " +
+            "the supplied service parameter).",
+        match_keywords: ["guarded", "passport", "kyc", "membership", "filtered", "gated", "service_identifier"],
+        schema_elements: {
+            required_fields: ["description", "permission", "guards"],
+            optional_fields: ["location", "rewards", "um", "namedNew"],
+            presentation_path: "present_with_passport",
+            um_recommendation: "Optional. Same as P-DEM-01. If the Demand is mediated by an intermediary Contact, set um to that " +
+                "Contact address and the intermediary can manage the Demand via the Contact's permission.",
+        },
+        constraints: [
+            "guards vector non-empty (call guard_add at least once)",
+            "Each guard address must be unique (duplicate guard_add updates service_identifier instead of pushing)",
+            "guard_count ≤ MAX_GUARD_COUNT_DEMAND (20) — E_MAX_GUARD_COUNT_EXCEEDED (2) on overflow",
+            "When service_identifier is provided, it MUST be a valid u8 indexing a Service-typed submission in the Guard",
+            "Presenters MUST use present_with_passport / present_service_with_passport — plain present aborts with E_NEED_PASSPORT (3)",
+            "by_guard (Guard address) passed to present_with_passport MUST already be in the guards vector — E_GUARD_NOT_FOUND (4) otherwise",
+        ],
+        example: {
+            description: "KYC-gated call for certified auditors only",
+            location: "Remote",
+            rewards: ["0xabc...reward_addr_1", "0xdef...reward_addr_2"],
+            guards: [
+                { guard: "0xguard1...", service_identifier: 0 },
+                { guard: "0xguard2...", service_identifier: null },
+            ],
+            permission: "0xperm...permission_addr",
+            um: null,
+            namedNew: { name: "kyc_auditor_call_2026" },
+        },
+    },
+    {
+        id: "P-DEM-03",
+        pattern_name: "Demand with UM (um_set) — Contact object manages demand",
+        configuration_classification: "um_managed",
+        semantic_intent: "A Demand with um set has an affiliated Contact object that manages the Demand on behalf of the creator. " +
+            "The Contact's address is stored in Demand.um (Option<address>). The Contact can perform operations " +
+            "through its own permission scope. Use this when a Demand is operated by an intermediary (agent, " +
+            "marketplace, escrow service) rather than the original creator. um_set_imp (demand.move:139-147) " +
+            "disaffiliates the old um before affiliating the new one (P-DEM-P1-1 fix).",
+        match_keywords: ["um", "contact", "managed", "intermediary", "agent", "marketplace", "escrow"],
+        schema_elements: {
+            required_fields: ["description", "permission", "um"],
+            optional_fields: ["location", "rewards", "guards", "namedNew"],
+            presentation_path: "either",
+            um_recommendation: "Required for this pattern. Set um to a Contact object address via um_set. The Contact's " +
+                "permission scope applies to subsequent operations. To remove the Contact, call um_none — " +
+                "um_none_imp disaffiliates the Contact before clearing self.um.",
+        },
+        constraints: [
+            "um must be a valid Contact object address (set via um_set, permission index 408)",
+            "um_set_imp disaffiliates old um before affiliating new (P-DEM-P1-1 fix — prevents Registrar dependency leak)",
+            "um_none_imp disaffiliates um before clearing (symmetric with um_set_imp)",
+            "If guards is also non-empty, the present_with_passport path applies (P-DEM-02 constraints also hold)",
+            "permission_set (DE-D-2=A) can migrate the Demand to a new Permission — affiliation_change is called on the Registrar",
+        ],
+        example: {
+            description: "Marketplace-managed Demand for freelance design services",
+            location: "Shanghai",
+            rewards: ["0xabc...reward_addr_1"],
+            guards: [{ guard: "0xguard1...", service_identifier: null }],
+            permission: "0xperm...permission_addr",
+            um: "0xcontact...marketplace_contact_addr",
+            namedNew: { name: "marketplace_managed_design_2026" },
+        },
+    },
+];
+export const DEMAND_FIELD_TRANSLATIONS = [
+    {
+        field_name: "description",
+        value_type: "string",
+        semantic: "Human-readable description of this Demand. Required field. The Move contract validates via " +
+            "common::DESCRIPTION (demand.move:157,177), which enforces the 4000-char limit. Should be a one-line " +
+            "summary of what the Demand is asking for (e.g. \"freelance designer for brand identity work\").",
+        format_example: "Freelance designer for brand identity work (logo + style guide)",
+        validation_rules: [
+            "Required field",
+            `Length ≤ MAX_DESCRIPTION_LENGTH (${MAX_DESCRIPTION_LENGTH} chars)`,
+            "Move validates via common::DESCRIPTION — E_DESCRIPTION_LENGTH_EXCEEDED (4) on overflow",
+        ],
+    },
+    {
+        field_name: "location",
+        value_type: "string",
+        semantic: "Geographic location associated with the Demand. Validated via common::LONG_NAME (demand.move:180). " +
+            "Empty string (\"\") is valid — new_imp initializes location to empty. Use location_set to update after " +
+            "creation. This is the ONLY Move Demand struct field that the matching engine reads directly (other " +
+            "matching fields like tags, maxPrice, scenario are caller-enriched — see P-DEM-P1-3 / R-DEM-07).",
+        format_example: "Shanghai or Remote",
+        validation_rules: [
+            "Optional (empty string \"\" is the default initial value)",
+            `Length ≤ MAX_LONG_NAME_LENGTH (${MAX_LONG_NAME_LENGTH} chars)`,
+            "Move validates via common::LONG_NAME — E_LONG_NAME_LENGTH_EXCEEDED (11) on overflow",
+        ],
+    },
+    {
+        field_name: "rewards",
+        value_type: "vector<address> (string[] in SDK)",
+        semantic: "Reward object addresses affiliated with this Demand. Each reward is added via reward_add, which " +
+            "triggers registrar::affiliation. The matching engine reads maxPrice from the Reward objects " +
+            "(caller-enriched — the Demand struct only stores addresses, not Reward metadata).",
+        format_example: "[\"0xabc...reward_addr_1\", \"0xdef...reward_addr_2\"]",
+        validation_rules: [
+            `Count ≤ MAX_REWARD_COUNT (${MAX_REWARD_COUNT}) — E_MAX_REWARD_COUNT_EXCEEDED (1) on overflow`,
+            "Each address must be a valid Reward object address",
+            "Duplicate addresses are silently ignored (reward_add_imp checks contains before push)",
+            "reward_remove / reward_clear disaffiliate via the Registrar before removing",
+        ],
+    },
+    {
+        field_name: "guards",
+        value_type: "vector<ServiceGuard> ({ guard: address, service_identifier: Option<u8> }[] in SDK)",
+        semantic: "Guard addresses with optional service_identifier. When non-empty, presenters MUST use " +
+            "present_with_passport (or present_service_with_passport). The service_identifier, when set, routes " +
+            "present_with_passport to extract the submission address from the Passport (overriding the supplied " +
+            "service parameter). guard_add validates the service_identifier type BEFORE any mutation (P-DEM-P1-2 fix).",
+        format_example: "[{ guard: \"0xguard1...\", service_identifier: 0 }, { guard: \"0xguard2...\", service_identifier: null }]",
+        validation_rules: [
+            `Count ≤ MAX_GUARD_COUNT_DEMAND (${MAX_GUARD_COUNT_DEMAND}) — E_MAX_GUARD_COUNT_EXCEEDED (2) on overflow`,
+            "Each guard address must be a valid Guard object address",
+            "Duplicate addresses update service_identifier in place (no new push)",
+            "When service_identifier is provided, it MUST index a Service-typed submission in the Guard",
+            "guard_remove / guard_clear disaffiliate via the Registrar before removing",
+        ],
+    },
+    {
+        field_name: "um",
+        value_type: "Option<address> (string | null in SDK)",
+        semantic: "Optional Contact object address that manages this Demand. When set, the Contact can perform " +
+            "operations through its own permission scope. um_set_imp (demand.move:139-147) disaffiliates the old " +
+            "um before affiliating the new one (P-DEM-P1-1 fix — prevents Registrar dependency leak). To clear, " +
+            "call um_none — um_none_imp disaffiliates before clearing self.um.",
+        format_example: "0xcontact...marketplace_contact_addr or null",
+        validation_rules: [
+            "Optional (null/undefined → Option::none) — initial state",
+            "When set, must be a valid Contact object address",
+            "um_set_imp disaffiliates old um before setting new (P-DEM-P1-1 fix)",
+            "um_none_imp disaffiliates um before clearing (symmetric)",
+            "Permission index 408 required for um_set / um_none",
+        ],
+    },
+    {
+        field_name: "presenters",
+        value_type: "ParentTable<address, ServiceInfo> (not directly settable — populated by present)",
+        semantic: "Service presentation records, keyed by presenter address. Each entry contains: recommend (String), " +
+            "service (Option<address>), update_time (u64), acceptance_score (Option<u8>), feedback (String), " +
+            "feedback_time (u64). Populated by present_imp — presenters call present / present_with_passport to " +
+            "add or update their entry. feedback_imp updates an existing entry's feedback fields.",
+        format_example: "(not directly settable — populated by present operations)",
+        validation_rules: [
+            "Not directly settable by the creator — populated by presenter operations",
+            "Each presenter address maps to at most one ServiceInfo entry",
+            "present updates update_time and overwrites recommend/service on each call",
+            "feedback updates acceptance_score, feedback, feedback_time (only if presenter exists)",
+        ],
+    },
+    {
+        field_name: "permission",
+        value_type: "address",
+        semantic: "Permission object address bound to this Demand. All mutations require permission::assert_permission_with_sender " +
+            "with the appropriate index (400-408). permission_set (demand.move:286) is exposed via CallPermission.apply " +
+            "(DE-D-2=A) and migrates the affiliation via registrar::affiliation_change.",
+        format_example: "0xperm...permission_addr",
+        validation_rules: [
+            "Required field (set at creation via new_imp)",
+            "permission::assert_with_sender(permission, 400, ctx) required for new (DEMAND_NEW)",
+            "permission::assert_permission_with_sender(permission, <index>, &self.permission, ctx) required for all mutations",
+            "Permission indices: 400=NEW, 401=DESCRIPTION, 402=LOCATION, 404=GUARD, 405=REWARD, 406=FEEDBACK, 407=OWNER_RECEIVE, 408=UM",
+            "permission_set migrates affiliation via registrar::affiliation_change (DE-D-2=A)",
+        ],
+    },
+];
+export const DEMAND_CONSTRAINT_RULES = [
+    {
+        id: "DEMAND_C_01",
+        name: "description non-empty and within size limit",
+        description: `The 'description' field must be non-empty and ≤ MAX_DESCRIPTION_LENGTH (${MAX_DESCRIPTION_LENGTH} chars).`,
+        validation_logic: "description.length > 0 && description.length <= MAX_DESCRIPTION_LENGTH",
+        failure_message: `description must be 1..${MAX_DESCRIPTION_LENGTH} chars — E_DESCRIPTION_LENGTH_EXCEEDED (4) on overflow`,
+        related_field: "description",
+    },
+    {
+        id: "DEMAND_C_02",
+        name: "location within size limit",
+        description: `The 'location' field must be ≤ MAX_LONG_NAME_LENGTH (${MAX_LONG_NAME_LENGTH} chars). Empty string is valid.`,
+        validation_logic: "location.length <= MAX_LONG_NAME_LENGTH",
+        failure_message: `location exceeds MAX_LONG_NAME_LENGTH (${MAX_LONG_NAME_LENGTH} chars) — E_LONG_NAME_LENGTH_EXCEEDED (11)`,
+        related_field: "location",
+    },
+    {
+        id: "DEMAND_C_03",
+        name: "rewards count within limit",
+        description: `The 'rewards' vector count must be ≤ MAX_REWARD_COUNT (${MAX_REWARD_COUNT}).`,
+        validation_logic: `rewards.length <= MAX_REWARD_COUNT`,
+        failure_message: `rewards count exceeds MAX_REWARD_COUNT (${MAX_REWARD_COUNT}) — E_MAX_REWARD_COUNT_EXCEEDED (1)`,
+        related_field: "rewards",
+    },
+    {
+        id: "DEMAND_C_04",
+        name: "guards count within limit",
+        description: `The 'guards' vector count must be ≤ MAX_GUARD_COUNT_DEMAND (${MAX_GUARD_COUNT_DEMAND}).`,
+        validation_logic: `guards.length <= MAX_GUARD_COUNT_DEMAND`,
+        failure_message: `guards count exceeds MAX_GUARD_COUNT_DEMAND (${MAX_GUARD_COUNT_DEMAND}) — E_MAX_GUARD_COUNT_EXCEEDED (2)`,
+        related_field: "guards",
+    },
+    {
+        id: "DEMAND_C_05",
+        name: "service_identifier valid u8 when provided",
+        description: "When service_identifier is provided to guard_add, it must be a valid u8 (0-255) indexing a " +
+            "Service-typed submission in the Guard. guard_add_imp validates via guard::get_submission_object_type " +
+            "and common::assert_service_object_type BEFORE any mutation (P-DEM-P1-2 fix).",
+        validation_logic: "service_identifier == null || (Number.isInteger(service_identifier) && 0 <= service_identifier && service_identifier <= 255)",
+        failure_message: "service_identifier must be a u8 (0-255) indexing a Service-typed submission — E_INVALID_SERVICE_OBJECT_TYPE (13)",
+        related_field: "guards.service_identifier",
+    },
+    {
+        id: "DEMAND_C_06",
+        name: "present requires passport when guards non-empty",
+        description: "When the guards vector is non-empty, callers MUST use present_with_passport / present_service_with_passport. " +
+            "The plain present function asserts `vector::is_empty(&self.guards)` and aborts with E_NEED_PASSPORT (3). " +
+            "The by_guard parameter to present_with_passport MUST already be in the guards vector " +
+            "(otherwise E_GUARD_NOT_FOUND (4)).",
+        validation_logic: "!guards_non_empty || using_present_with_passport; by_guard in guards",
+        failure_message: "present without passport when guards non-empty — E_NEED_PASSPORT (3); by_guard not in guards — E_GUARD_NOT_FOUND (4)",
+        related_field: "guards + presentation_path",
+    },
+];
+export function explainDemand(input) {
+    const warnings = [];
+    const recommendations = [];
+    const hasGuards = !!input.guards && input.guards.length > 0;
+    const hasUm = !!input.um;
+    let classification = "open";
+    let presentationPath = "plain_present";
+    if (hasGuards && hasUm) {
+        classification = "guarded + um_managed (P-DEM-02 + P-DEM-03 combined)";
+        presentationPath = "present_with_passport (um does not change presentation path)";
+    }
+    else if (hasGuards) {
+        classification = "guarded (P-DEM-02) — passport required for present";
+        presentationPath = "present_with_passport / present_service_with_passport";
+    }
+    else if (hasUm) {
+        classification = "um_managed (P-DEM-03) — Contact manages the Demand";
+        presentationPath = "plain present (no guards) OR present_with_passport (if guards added later)";
+    }
+    else {
+        classification = "open (P-DEM-01) — free presentation, no passport required";
+        presentationPath = "present / present_service (plain path)";
+    }
+    const bindingParts = [];
+    if (input.permission) {
+        bindingParts.push(`permission=${input.permission.substring(0, 10)}... (bound at creation)`);
+    }
+    if (hasUm) {
+        bindingParts.push(`um=${input.um.substring(0, 10)}... (Contact manages Demand)`);
+    }
+    if (input.rewards && input.rewards.length > 0) {
+        bindingParts.push(`rewards=${input.rewards.length} affiliated via Registrar`);
+    }
+    if (hasGuards) {
+        bindingParts.push(`guards=${input.guards.length} affiliated via Registrar`);
+    }
+    const bindingStatus = bindingParts.length > 0
+        ? `Bindings: ${bindingParts.join("; ")}`
+        : "No Registrar affiliations (bare Demand)";
+    const sizeStatus = [];
+    if (input.description !== undefined) {
+        sizeStatus.push(`description=${input.description.length} chars (limit ${MAX_DESCRIPTION_LENGTH})`);
+    }
+    if (input.location !== undefined) {
+        sizeStatus.push(`location=${input.location.length} chars (limit ${MAX_LONG_NAME_LENGTH})`);
+    }
+    if (input.rewards) {
+        sizeStatus.push(`rewards=${input.rewards.length}/${MAX_REWARD_COUNT}`);
+    }
+    if (input.guards) {
+        sizeStatus.push(`guards=${input.guards.length}/${MAX_GUARD_COUNT_DEMAND}`);
+    }
+    if (hasGuards) {
+        const invalidSids = input.guards.filter(g => g.service_identifier !== null && g.service_identifier !== undefined
+            && !(typeof g.service_identifier === "number" && Number.isInteger(g.service_identifier)
+                && g.service_identifier >= 0 && g.service_identifier <= 255));
+        if (invalidSids.length > 0) {
+            warnings.push(`${invalidSids.length} guard(s) have invalid service_identifier (must be u8 0-255)`);
+        }
+    }
+    if (!input.description || input.description.length === 0) {
+        warnings.push("description is empty — Demand will be hard to identify in queries");
+    }
+    if (!input.description || input.description.length === 0) {
+        recommendations.push("Provide a non-empty description for discoverability");
+    }
+    if (input.location === undefined || input.location === "") {
+        recommendations.push("Consider setting location if the Demand is geographic (only on-chain field used by matching)");
+    }
+    if (!hasGuards) {
+        recommendations.push("Consider adding guards if presentations should be filtered (KYC, membership, etc.)");
+    }
+    if (!hasUm && classification === "open") {
+        recommendations.push("Consider setting um to a Contact if the Demand should be managed by an intermediary");
+    }
+    const summary = `Demand is ${classification}. ${presentationPath}. ${bindingStatus}. ` +
+        (sizeStatus.length > 0 ? `Sizes: ${sizeStatus.join(", ")}.` : "");
+    return {
+        summary,
+        configuration_classification: classification,
+        presentation_path: presentationPath,
+        binding_status: bindingStatus,
+        size_status: sizeStatus.join(", "),
+        warnings,
+        recommendations,
+    };
+}

package/dist/knowledge/deployment-scanner.d.ts

@@ -0,0 +1,63 @@
+import { type DeploymentDocInput } from "../project/deployment-doc.js";
+export interface DeploymentScanInput {
+    project_name: string;
+    document_path?: string;
+    deployment_doc?: DeploymentDocInput;
+    project_graph?: unknown;
+    user_confirmed_high_risks?: string[];
+}
+export interface Finding {
+    check_id: string;
+    severity: "critical" | "warning" | "info";
+    message: string;
+    location?: string;
+    suggestion?: string;
+}
+export interface DeploymentScanResult {
+    project_name: string;
+    document_path?: string;
+    overall_readiness: "ready" | "blocked" | "warnings";
+    findings: Finding[];
+    coverage: {
+        objects_defined: number;
+        objects_with_scenario: number;
+        testnet_steps: number;
+        mainnet_steps: number;
+        verification_items: number;
+    };
+    checks: {
+        D01_object_defined: "pass" | "fail";
+        D02_dependency_complete: "pass" | "fail";
+        D03_scenario_covered: "pass" | "fail";
+        D04_testnet_topo_order: "pass" | "fail";
+        D05_testnet_network: "pass" | "fail";
+        D06_testnet_replace: "pass" | "fail";
+        D07_permission_index: "pass" | "fail";
+        D08_guard_gen_passport: "pass" | "fail";
+        D09_machine_node_count: "pass" | "fail";
+        D10_substep_coherence: "pass" | "fail";
+        D11_mainnet_testnet_match: "pass" | "fail";
+        D12_mainnet_network: "pass" | "fail";
+        D13_mainnet_replace: "pass" | "fail";
+        D14_testnet_verification: "pass" | "fail";
+        D15_mainnet_verification: "pass" | "fail";
+        D16_no_critical_risk: "pass" | "fail";
+        D17_no_high_risk: "pass" | "fail";
+        D18_completeness_checklist: "pass" | "fail";
+    };
+    scanned_at: number;
+    scanner_version: string;
+}
+export declare function analyzeObjectDependencyCompleteness(input: DeploymentScanInput): Finding[];
+export declare function analyzeSubstepCoherence(input: DeploymentScanInput): Finding[];
+export declare function analyzeNetworkConsistency(input: DeploymentScanInput): Finding[];
+export declare function analyzeNamingConvention(input: DeploymentScanInput): Finding[];
+export declare function analyzePermissionIndexRange(input: DeploymentScanInput): Finding[];
+export declare function analyzeScenarioCoverage(input: DeploymentScanInput): Finding[];
+export declare function analyzeVerificationChecklist(input: DeploymentScanInput): Finding[];
+export declare function analyzeDeployableReadiness(input: DeploymentScanInput): Finding[];
+export declare function scanDeployment(input: DeploymentScanInput): DeploymentScanResult;
+export declare function isReady(scan: DeploymentScanResult): boolean;
+export declare function isBlocked(scan: DeploymentScanResult): boolean;
+export declare function summarizeScan(scan: DeploymentScanResult): string;
+export declare const DEPLOYMENT_SCANNER_VERSION = "2.0.0";