@wowok/agent-mcp 2.6.3 → 2.6.6

package/dist/project/semantic-graph.d.ts

@@ -0,0 +1,95 @@
+import type { ProjectObjectType } from "./namespace.js";
+import type { BusinessIntent } from "./intent-analyzer.js";
+import type { BusinessModule, BusinessModuleId } from "../extensions/business-modules.js";
+export type ConfigValueType = "string" | "number" | "boolean" | "address_ref" | "guard_logic" | "enum";
+export interface ConfigValueBase {
+    type: ConfigValueType;
+    mapsTo: string;
+}
+export interface StringConfigValue extends ConfigValueBase {
+    type: "string";
+    value: string;
+}
+export interface NumberConfigValue extends ConfigValueBase {
+    type: "number";
+    value: number;
+    unit?: string;
+}
+export interface BooleanConfigValue extends ConfigValueBase {
+    type: "boolean";
+    value: boolean;
+}
+export interface AddressRefConfigValue extends ConfigValueBase {
+    type: "address_ref";
+    targetId: string;
+}
+export interface GuardLogicConfigValue extends ConfigValueBase {
+    type: "guard_logic";
+    description: string;
+}
+export interface EnumConfigValue extends ConfigValueBase {
+    type: "enum";
+    value: string;
+    allowed: string[];
+}
+export type ConfigValue = StringConfigValue | NumberConfigValue | BooleanConfigValue | AddressRefConfigValue | GuardLogicConfigValue | EnumConfigValue;
+export interface ExpectedState {
+    published: boolean;
+    paused: boolean;
+    additional?: Record<string, unknown>;
+}
+export interface SemanticNode {
+    id: string;
+    type: ProjectObjectType;
+    purpose: string;
+    derivedFrom: {
+        intentField: string;
+        rationale: string;
+    };
+    config: Record<string, ConfigValue>;
+    expectedState: ExpectedState;
+}
+export interface SemanticEdge {
+    from: string;
+    to: string;
+    relation: string;
+    required: boolean;
+    derivedFrom: {
+        intentField: string;
+        rationale: string;
+    };
+}
+export interface SemanticConstraint {
+    id: string;
+    level: "hard" | "soft" | "info";
+    description: string;
+    source: {
+        layer: "contract" | "harness" | "industry_mode" | "business_rule";
+        reference: string;
+    };
+    fixSuggestion: string;
+}
+export interface EvaluationPreview {
+    estimatedRiskScore: number;
+    estimatedTrustScore: number;
+    estimatedCompletenessScore: number;
+    keyRisks: string[];
+    strengths: string[];
+    moduleBoosts: Record<string, number>;
+}
+export interface SemanticObjectGraph {
+    nodes: SemanticNode[];
+    edges: SemanticEdge[];
+    constraints: SemanticConstraint[];
+    evaluationPreview?: EvaluationPreview;
+    adoptedModules: BusinessModuleId[];
+    businessIntent: BusinessIntent;
+}
+export interface GraphValidationResult {
+    valid: boolean;
+    hardViolations: SemanticConstraint[];
+    softViolations: SemanticConstraint[];
+    infoNotes: SemanticConstraint[];
+}
+export declare function buildSemanticGraph(intent: BusinessIntent, adoptedModules: BusinessModule[]): SemanticObjectGraph;
+export declare function validateGraph(graph: SemanticObjectGraph): GraphValidationResult;

package/dist/project/semantic-graph.js

@@ -0,0 +1,245 @@
+export function buildSemanticGraph(intent, adoptedModules) {
+    const nodes = [];
+    const edges = [];
+    const constraints = [];
+    nodes.push({
+        id: "main_permission",
+        type: "permission",
+        purpose: "Role-based access control for merchant, customer, and optional arbitrator",
+        derivedFrom: { intentField: "roles", rationale: "All WOW services require a Permission object for role management" },
+        config: {
+            name: { type: "string", value: `${intent.description.slice(0, 20)}_permission`, mapsTo: "object.name" },
+        },
+        expectedState: { published: true, paused: false },
+    });
+    if (intent.intent.startsWith("sell_") || intent.intent === "rent_asset") {
+        nodes.push({
+            id: "main_service",
+            type: "service",
+            purpose: `Main service offering: ${intent.description}`,
+            derivedFrom: { intentField: "description", rationale: "Service is the primary object representing the merchant offering" },
+            config: {
+                name: { type: "string", value: `${intent.description.slice(0, 20)}_service`, mapsTo: "object.name" },
+                type_parameter: { type: "string", value: intent.payment.currency, mapsTo: "object.type_parameter" },
+                permission: { type: "address_ref", targetId: "main_permission", mapsTo: "object.permission" },
+            },
+            expectedState: { published: true, paused: false },
+        });
+        edges.push({
+            from: "main_service",
+            to: "main_permission",
+            relation: "has_permission",
+            required: true,
+            derivedFrom: { intentField: "roles", rationale: "Service must reference its Permission object" },
+        });
+    }
+    if (intent.payment.model === "milestone" || intent.deliverables.length > 1) {
+        nodes.push({
+            id: "main_machine",
+            type: "machine",
+            purpose: "Workflow controlling deliverable milestones and acceptance",
+            derivedFrom: { intentField: "deliverables", rationale: "Multiple deliverables or milestone payment requires Machine workflow" },
+            config: {
+                name: { type: "string", value: `${intent.description.slice(0, 20)}_machine`, mapsTo: "object.name" },
+                permission: { type: "address_ref", targetId: "main_permission", mapsTo: "object.permission" },
+            },
+            expectedState: { published: true, paused: false },
+        });
+        if (nodes.find((n) => n.id === "main_service")) {
+            edges.push({
+                from: "main_service",
+                to: "main_machine",
+                relation: "uses_machine",
+                required: true,
+                derivedFrom: { intentField: "deliverables", rationale: "Service binds to Machine for workflow execution" },
+            });
+        }
+    }
+    if (intent.payment.model === "milestone" || intent.payment.model === "escrow" || intent.trust.escrow) {
+        nodes.push({
+            id: "main_allocation",
+            type: "allocation",
+            purpose: "Fund distribution among merchant and optional suppliers",
+            derivedFrom: { intentField: "payment.allocation", rationale: "Escrow/milestone requires Allocation for fund routing" },
+            config: {
+                name: { type: "string", value: `${intent.description.slice(0, 20)}_allocation`, mapsTo: "object.name" },
+                type_parameter: { type: "string", value: intent.payment.currency, mapsTo: "object.type_parameter" },
+                permission: { type: "address_ref", targetId: "main_permission", mapsTo: "object.permission" },
+            },
+            expectedState: { published: true, paused: false },
+        });
+        if (nodes.find((n) => n.id === "main_service")) {
+            edges.push({
+                from: "main_service",
+                to: "main_allocation",
+                relation: "has_order_allocators",
+                required: true,
+                derivedFrom: { intentField: "payment", rationale: "Service must bind Allocation for order fund routing" },
+            });
+        }
+    }
+    if (intent.trust.arbitration !== "none") {
+        nodes.push({
+            id: "main_arbitration",
+            type: "arb",
+            purpose: "Independent dispute resolution",
+            derivedFrom: { intentField: "trust.arbitration", rationale: "Arbitration object provides binding dispute resolution" },
+            config: {
+                name: { type: "string", value: `${intent.description.slice(0, 20)}_arbitration`, mapsTo: "object.name" },
+                type_parameter: { type: "string", value: intent.payment.currency, mapsTo: "object.type_parameter" },
+            },
+            expectedState: { published: true, paused: false },
+        });
+        nodes.push({
+            id: "arb_permission",
+            type: "permission",
+            purpose: "Independent permission for arbitration (MUST differ from Service.permission)",
+            derivedFrom: { intentField: "trust.arbitration", rationale: "Contract-enforced: arbitration.permission != service.permission (E_ARBITRATION_PERMISSION_CONFLICT=33)" },
+            config: {
+                name: { type: "string", value: `${intent.description.slice(0, 20)}_arb_permission`, mapsTo: "object.name" },
+            },
+            expectedState: { published: true, paused: false },
+        });
+        edges.push({
+            from: "main_arbitration",
+            to: "arb_permission",
+            relation: "has_permission",
+            required: true,
+            derivedFrom: { intentField: "trust.arbitration", rationale: "Arbitration requires its own Permission" },
+        });
+        if (nodes.find((n) => n.id === "main_service")) {
+            edges.push({
+                from: "main_service",
+                to: "main_arbitration",
+                relation: "has_arbitration",
+                required: false,
+                derivedFrom: { intentField: "trust.arbitration", rationale: "Service references Arbitration in arbitrations list" },
+            });
+        }
+    }
+    const needsRepository = adoptedModules.some((m) => m.id === "wip_provenance" || m.id === "subscription_with_proof" || m.id === "damage_attestation");
+    if (needsRepository) {
+        nodes.push({
+            id: "main_repository",
+            type: "repository",
+            purpose: "Store WIP hashes and delivery evidence",
+            derivedFrom: { intentField: "deliverables", rationale: "WIP provenance requires Repository for hash commitments" },
+            config: {
+                name: { type: "string", value: `${intent.description.slice(0, 20)}_repository`, mapsTo: "object.name" },
+                permission: { type: "address_ref", targetId: "main_permission", mapsTo: "object.permission" },
+            },
+            expectedState: { published: true, paused: false },
+        });
+    }
+    for (const mod of adoptedModules) {
+        for (const ref of mod.templateRefs) {
+            if (ref.object_type === "guard") {
+                nodes.push({
+                    id: `guard_${mod.id}`,
+                    type: "guard",
+                    purpose: ref.purpose,
+                    derivedFrom: { intentField: "trust", rationale: `Guard for ${mod.name} module` },
+                    config: {
+                        name: { type: "string", value: `${intent.description.slice(0, 20)}_${mod.id}_guard`, mapsTo: "object.name" },
+                    },
+                    expectedState: { published: true, paused: false },
+                });
+            }
+        }
+    }
+    constraints.push({
+        id: "service_permission_bound",
+        level: "hard",
+        description: "Service must be bound to a Permission object",
+        source: { layer: "contract", reference: "service.move: permission field is required" },
+        fixSuggestion: "Create Permission object first, then reference it in Service.object.permission",
+    });
+    if (intent.trust.arbitration !== "none") {
+        constraints.push({
+            id: "arbitration_permission_independent",
+            level: "hard",
+            description: "Arbitration.permission MUST be different from Service.permission",
+            source: { layer: "contract", reference: "service.move:433-436 E_ARBITRATION_PERMISSION_CONFLICT=33" },
+            fixSuggestion: "Create a dedicated Permission object for Arbitration, do NOT reuse Service.permission",
+        });
+    }
+    if (intent.payment.model === "milestone") {
+        constraints.push({
+            id: "machine_bound_before_publish",
+            level: "hard",
+            description: "Machine must be published and bound to Service before Service.publish",
+            source: { layer: "contract", reference: "service.move: machine is IMMUTABLE after publish" },
+            fixSuggestion: "Create and publish Machine before calling Service.publish. Machine cannot be changed after Service is published.",
+        });
+    }
+    const moduleBoosts = calculateModuleScoreBoost(adoptedModules);
+    const estimatedRiskScore = Math.min(100, 40 + Object.values(moduleBoosts).reduce((a, b) => a + b, 0) / 2);
+    const estimatedTrustScore = Math.min(100, 50 + (moduleBoosts["trust"] ?? 0) + (moduleBoosts["fund_safety"] ?? 0));
+    const estimatedCompletenessScore = Math.min(100, 30 + adoptedModules.length * 8);
+    const evaluationPreview = {
+        estimatedRiskScore,
+        estimatedTrustScore,
+        estimatedCompletenessScore,
+        keyRisks: [
+            ...(intent.trust.arbitration === "none" ? ["No arbitration configured — disputes have no resolution path"] : []),
+            ...(intent.payment.model === "upfront" && intent.trust.refundPolicy === "no_refund" ? ["Full upfront + no refund = high user risk"] : []),
+        ],
+        strengths: adoptedModules.map((m) => `${m.name}: ${m.description.slice(0, 60)}...`),
+        moduleBoosts,
+    };
+    return {
+        nodes,
+        edges,
+        constraints,
+        evaluationPreview,
+        adoptedModules: adoptedModules.map((m) => m.id),
+        businessIntent: intent,
+    };
+}
+function calculateModuleScoreBoost(modules) {
+    const boosts = {};
+    for (const m of modules) {
+        for (const impact of m.evaluationImpact) {
+            const increment = impact.effect === "required" ? 15 : impact.effect === "boost" ? 8 : 3;
+            boosts[impact.dimension] = (boosts[impact.dimension] ?? 0) + increment;
+        }
+    }
+    return boosts;
+}
+export function validateGraph(graph) {
+    const hardViolations = [];
+    const softViolations = [];
+    const infoNotes = [];
+    for (const constraint of graph.constraints) {
+        if (constraint.id === "service_permission_bound") {
+            const hasService = graph.nodes.some((n) => n.type === "service");
+            const hasPermissionEdge = graph.edges.some((e) => e.relation === "has_permission" && e.from.startsWith("main_service"));
+            if (hasService && !hasPermissionEdge) {
+                hardViolations.push(constraint);
+            }
+        }
+        if (constraint.id === "arbitration_permission_independent") {
+            const serviceNode = graph.nodes.find((n) => n.id === "main_service");
+            const arbNode = graph.nodes.find((n) => n.id === "main_arbitration");
+            if (serviceNode && arbNode) {
+                const servicePerm = graph.edges.find((e) => e.from === "main_service" && e.relation === "has_permission")?.to;
+                const arbPerm = graph.edges.find((e) => e.from === "main_arbitration" && e.relation === "has_permission")?.to;
+                if (servicePerm && arbPerm && servicePerm === arbPerm) {
+                    hardViolations.push(constraint);
+                }
+            }
+        }
+        if (constraint.level === "soft") {
+            softViolations.push(constraint);
+        }
+        else if (constraint.level === "info") {
+            infoNotes.push(constraint);
+        }
+    }
+    return {
+        valid: hardViolations.length === 0,
+        hardViolations,
+        softViolations,
+        infoNotes,
+    };
+}

package/dist/schema/call/allocation.d.ts

@@ -325,7 +325,6 @@ export declare const CallAllocation_OperateSchema: z.ZodObject<{
     alloc_by_guard: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strict", z.ZodTypeAny, {
     object: string;
-    alloc_by_guard?: string | undefined;
     received_coins?: {
         received: {
             id: string;
@@ -335,9 +334,9 @@ export declare const CallAllocation_OperateSchema: z.ZodObject<{
         balance: string | number;
         token_type: string;
     } | "recently" | undefined;
+    alloc_by_guard?: string | undefined;
 }, {
     object: string;
-    alloc_by_guard?: string | undefined;
     received_coins?: {
         received: {
             id: string;
@@ -347,6 +346,7 @@ export declare const CallAllocation_OperateSchema: z.ZodObject<{
         balance: string | number;
         token_type: string;
     } | "recently" | undefined;
+    alloc_by_guard?: string | undefined;
 }>;
 export declare const CallAllocation_DataSchema: z.ZodUnion<[z.ZodObject<{
     object: z.ZodObject<{
@@ -673,7 +673,6 @@ export declare const CallAllocation_DataSchema: z.ZodUnion<[z.ZodObject<{
     alloc_by_guard: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strict", z.ZodTypeAny, {
     object: string;
-    alloc_by_guard?: string | undefined;
     received_coins?: {
         received: {
             id: string;
@@ -683,9 +682,9 @@ export declare const CallAllocation_DataSchema: z.ZodUnion<[z.ZodObject<{
         balance: string | number;
         token_type: string;
     } | "recently" | undefined;
+    alloc_by_guard?: string | undefined;
 }, {
     object: string;
-    alloc_by_guard?: string | undefined;
     received_coins?: {
         received: {
             id: string;
@@ -695,6 +694,7 @@ export declare const CallAllocation_DataSchema: z.ZodUnion<[z.ZodObject<{
         balance: string | number;
         token_type: string;
     } | "recently" | undefined;
+    alloc_by_guard?: string | undefined;
 }>]>;
 export declare const CallAllocation_InputSchema: z.ZodObject<{
     data: z.ZodUnion<[z.ZodObject<{
@@ -1022,7 +1022,6 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         alloc_by_guard: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     }, "strict", z.ZodTypeAny, {
         object: string;
-        alloc_by_guard?: string | undefined;
         received_coins?: {
             received: {
                 id: string;
@@ -1032,9 +1031,9 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
             balance: string | number;
             token_type: string;
         } | "recently" | undefined;
+        alloc_by_guard?: string | undefined;
     }, {
         object: string;
-        alloc_by_guard?: string | undefined;
         received_coins?: {
             received: {
                 id: string;
@@ -1044,6 +1043,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
             balance: string | number;
             token_type: string;
         } | "recently" | undefined;
+        alloc_by_guard?: string | undefined;
     }>]>;
     env: z.ZodOptional<z.ZodObject<{
         account: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
@@ -1055,10 +1055,11 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         user_intent_phrases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         project: z.ZodOptional<z.ZodString>;
         client_schema_version: z.ZodOptional<z.ZodString>;
-        schema_strict_mode: z.ZodOptional<z.ZodBoolean>;
+        schema_strict_mode: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
         dry_run: z.ZodOptional<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         account: string;
+        schema_strict_mode: boolean;
         no_cache?: boolean | undefined;
         network?: import("@wowok/wowok").ENTRYPOINT | undefined;
         permission_guard?: string[] | undefined;
@@ -1067,7 +1068,6 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         user_intent_phrases?: string[] | undefined;
         project?: string | undefined;
         client_schema_version?: string | undefined;
-        schema_strict_mode?: boolean | undefined;
         dry_run?: boolean | undefined;
     }, {
         no_cache?: boolean | undefined;
@@ -1307,7 +1307,6 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         };
     } | {
         object: string;
-        alloc_by_guard?: string | undefined;
         received_coins?: {
             received: {
                 id: string;
@@ -1317,6 +1316,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
             balance: string | number;
             token_type: string;
         } | "recently" | undefined;
+        alloc_by_guard?: string | undefined;
     };
     submission?: {
         type: "submission";
@@ -1347,6 +1347,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
     } | undefined;
     env?: {
         account: string;
+        schema_strict_mode: boolean;
         no_cache?: boolean | undefined;
         network?: import("@wowok/wowok").ENTRYPOINT | undefined;
         permission_guard?: string[] | undefined;
@@ -1355,7 +1356,6 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         user_intent_phrases?: string[] | undefined;
         project?: string | undefined;
         client_schema_version?: string | undefined;
-        schema_strict_mode?: boolean | undefined;
         dry_run?: boolean | undefined;
     } | undefined;
 }, {
@@ -1403,7 +1403,6 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
         };
     } | {
         object: string;
-        alloc_by_guard?: string | undefined;
         received_coins?: {
             received: {
                 id: string;
@@ -1413,6 +1412,7 @@ export declare const CallAllocation_InputSchema: z.ZodObject<{
             balance: string | number;
             token_type: string;
         } | "recently" | undefined;
+        alloc_by_guard?: string | undefined;
     };
     submission?: {
         type: "submission";

package/dist/schema/call/allocation.js

@@ -11,7 +11,17 @@ export const CallAllocation_CreateSchema = z.object({
 export const CallAllocation_OperateSchema = z.object({
     object: NameOrAddressSchema.describe("REQUIRED for operating existing object. Provide the Allocation object ID or existing name to reference the target object."),
     received_coins: ReceivedBalanceOrRecentlySchema.optional().describe("Unwrap the CoinWrapper objects received by the Allocation object and deposit them into the pending allocation balance." + RECEIVE_FORMAT_BLOCK_BALANCE),
-    alloc_by_guard: NameOrAddressSchema.optional().describe("Verify the specified Guard and execute the corresponding fund allocation")
+    alloc_by_guard: NameOrAddressSchema.optional().describe("Verify the specified Guard and execute the corresponding fund allocation. " +
+        "POST-ALLOCATION CLAIM (required step): each recipient receives a CoinWrapper object (NOT spendable coins). " +
+        "Recipient address resolution (allocation.move): Entity recipients receive it at the Entity's address; " +
+        "Signer recipients receive it at the transaction sender's address; " +
+        "GuardIdentifier n recipients receive it at the ADDRESS SUBMITTED for identifier n in this call's submission " +
+        "(resolved via passport::submission_get) — conventionally the Order OBJECT address (escrow pattern), " +
+        "in which case the order owner claims it via operation_type='order' {object:'<order_id>', receive:'recently'}. " +
+        "Claim paths by holder: EOA wallet → operation_type='payment' RECEIVE mode {object:'<coinwrapper_id>', receive:true, type_parameter:'0x2::wow::WOW'}; " +
+        "Order object → order receive; Treasury object → treasury receive. " +
+        "Find pending CoinWrappers via query_toolkit query_type='onchain_received'. " +
+        "Verify the distribution via the immutable Payment object created by this call (allocation.payment array).")
 }).strict().describe("Operate on an existing Allocation object. Set 'object' field with the object ID or existing name to specify the target.");
 export const CallAllocation_DataSchema = z.union([
     CallAllocation_CreateSchema,