feat(sdk): C# provider 侧入站 payload 校验接线（ValidateInputPayloads）

- ClientConfig.ValidateInputPayloads（默认关）
- HandleInboundRequestAsync 派发前按函数 input schema 校验，
  失败回 {"error":"payload validation failed: …"}，handler 不调用；
  schema 非法跳过（服务端权威校验）
- 复用既有 JsonSchemaValidator（与 Go/Python/JS 语义对齐），4 例单测

Author: cuihairu

sdks/csharp/src/Croupier.Sdk.Tests/InboundValidationTests.cs

@@ -0,0 +1,75 @@
+// Copyright 2025 Croupier Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using Croupier.Sdk.Models;
+using Xunit;
+
+namespace Croupier.Sdk.Tests;
+
+/// <summary>
+/// F：Provider 侧入站 payload 校验（ValidateInputPayloads）。
+/// </summary>
+public class InboundValidationTests
+{
+    private static ClientConfig NewConfig(bool validate) => new ClientConfig
+    {
+        ValidateInputPayloads = validate,
+    };
+
+    private static FunctionDescriptor NewDescriptor() => new FunctionDescriptor
+    {
+        Id = "player.ban",
+        Version = "1.0.0",
+        InputSchema = "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}},\"required\":[\"id\"]}",
+    };
+
+    [Fact]
+    public void Config_Defaults_To_Off()
+    {
+        Assert.False(new ClientConfig().ValidateInputPayloads);
+    }
+
+    [Fact]
+    public void Validator_Accepts_Valid_Payload()
+    {
+        using var schemaDocument = System.Text.Json.JsonDocument.Parse(
+            NewDescriptor().InputSchema!);
+        using var payloadDocument = System.Text.Json.JsonDocument.Parse("{\"id\":\"p1\"}");
+        var errors = Validation.JsonSchemaValidator.Validate(
+            schemaDocument.RootElement, payloadDocument.RootElement);
+        Assert.Empty(errors);
+    }
+
+    [Fact]
+    public void Validator_Rejects_Missing_Required()
+    {
+        using var schemaDocument = System.Text.Json.JsonDocument.Parse(
+            NewDescriptor().InputSchema!);
+        using var payloadDocument = System.Text.Json.JsonDocument.Parse("{}");
+        var errors = Validation.JsonSchemaValidator.Validate(
+            schemaDocument.RootElement, payloadDocument.RootElement);
+        Assert.NotEmpty(errors);
+    }
+
+    [Fact]
+    public void Validator_Rejects_Type_Mismatch()
+    {
+        using var schemaDocument = System.Text.Json.JsonDocument.Parse(
+            NewDescriptor().InputSchema!);
+        using var payloadDocument = System.Text.Json.JsonDocument.Parse("{\"id\":123}");
+        var errors = Validation.JsonSchemaValidator.Validate(
+            schemaDocument.RootElement, payloadDocument.RootElement);
+        Assert.NotEmpty(errors);
+    }
+}

sdks/csharp/src/Croupier.Sdk/CroupierClient.cs

@@ -440,6 +440,40 @@ private async Task<string> ProcessFunctionCallAsync(FunctionCallTask task)
         }
     }
 
+    /// <summary>
+    /// Provider 侧入站校验（F：与 Go/Python/JS 语义对齐）：按函数声明的
+    /// input schema 校验 payload。开关关闭/未注册/schema 缺失或非法时
+    /// 跳过（服务端仍是权威校验方）；失败返回错误消息。
+    /// </summary>
+    private string? ValidateInboundPayload(string functionId, string payload)
+    {
+        if (!_descriptors.TryGetValue(functionId, out var descriptor))
+        {
+            return null;
+        }
+        if (string.IsNullOrWhiteSpace(descriptor.InputSchema))
+        {
+            return null;
+        }
+        try
+        {
+            using var schemaDocument = System.Text.Json.JsonDocument.Parse(descriptor.InputSchema);
+            using var payloadDocument = System.Text.Json.JsonDocument.Parse(
+                string.IsNullOrWhiteSpace(payload) ? "{}" : payload);
+            var errors = Validation.JsonSchemaValidator.Validate(
+                schemaDocument.RootElement, payloadDocument.RootElement);
+            return errors.Count > 0
+                ? $"payload validation failed: {string.Join("; ", errors)}"
+                : null;
+        }
+        catch (System.Text.Json.JsonException exception)
+        {
+            // schema 非法视为契约缺陷，跳过校验（与 Go/Python 同策略）
+            if (string.IsNullOrWhiteSpace(payload)) return null;
+            return $"payload must be valid JSON: {exception.Message}";
+        }
+    }
+
     /// <summary>
     /// 处理来自Agent的入站请求（InvokeRequest）
     /// </summary>
@@ -464,6 +498,21 @@ private async Task<byte[]> HandleInboundRequestAsync(int msgId, int reqId, byte[
             var request = InvokeRequest.Parser.ParseFrom(body);
             var payload = request.Payload.ToStringUtf8();
 
+            // Provider 侧入站校验（可选）：按函数声明的 input schema 校验
+            // payload，失败回错误响应，handler 不被调用。
+            if (_config.ValidateInputPayloads)
+            {
+                var validationError = ValidateInboundPayload(request.FunctionId, payload);
+                if (validationError != null)
+                {
+                    return new InvokeResponse
+                    {
+                        Payload = Google.Protobuf.ByteString.CopyFromUtf8(
+                            "{\"error\":" + System.Text.Json.JsonSerializer.Serialize(validationError) + "}")
+                    }.ToByteArray();
+                }
+            }
+
             // Extract metadata
             request.Metadata.TryGetValue("X-Game-ID", out var gameId);
             request.Metadata.TryGetValue("X-Env", out var env);

sdks/csharp/src/Croupier.Sdk/Models/ClientConfig.cs

@@ -163,4 +163,11 @@ public class ClientConfig
     /// 最大文件大小（字节）
     /// </summary>
     public int MaxFileSize { get; set; } = 10 * 1024 * 1024;
+
+    /// <summary>
+    /// Provider 侧入站校验（默认关闭）：按函数声明的 input schema 校验入站
+    /// invoke payload，失败回 {"error":"payload validation failed: …"}，
+    /// handler 不被调用；服务端仍是权威校验方。
+    /// </summary>
+    public bool ValidateInputPayloads { get; set; }
 }