@opensoha/contracts 0.1.17 → 0.1.18

package/delivery/document_test.go

@@ -0,0 +1,191 @@
+package delivery
+
+import (
+	"context"
+	"encoding/json"
+	"io/fs"
+	"math"
+	"os"
+	"os/exec"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+const recipeYAML = `apiVersion: delivery.soha.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: build-release
+  displayName: 联合构建发布
+spec:
+  definition:
+    mode: delivery_batch
+    schemaVersion: 1
+    stages: [build, plan, deploy, health]
+    executionMode: build_all_then_deploy
+    stopOnFailure: true
+    maxConcurrency: 4
+`
+
+func TestDocumentRoundTrip(t *testing.T) {
+	fixtures := os.DirFS("../fixtures/openapi/DeliveryDocument/valid")
+	files, err := fs.Glob(fixtures, "*.json")
+	if err != nil || len(files) < 4 {
+		t.Fatalf("expected fixtures for all four kinds: %v", err)
+	}
+	for _, file := range files {
+		t.Run(file, func(t *testing.T) {
+			data, err := fs.ReadFile(fixtures, file)
+			if err != nil {
+				t.Fatal(err)
+			}
+			first, invalid := Parse(file, data)
+			if len(invalid) != 0 {
+				t.Fatalf("parse: %+v", invalid)
+			}
+			for _, format := range []string{"yaml", "json"} {
+				encoded, err := first.Encode(format)
+				if err != nil {
+					t.Fatal(err)
+				}
+				second, invalid := Parse("roundtrip."+format, encoded)
+				if len(invalid) != 0 || !reflect.DeepEqual(first, second) {
+					t.Fatalf("lossy %s roundtrip: %+v", format, invalid)
+				}
+			}
+		})
+	}
+}
+
+func TestEquivalentDocumentDigest(t *testing.T) {
+	first, invalid := Parse("recipe.yaml", []byte(recipeYAML))
+	if len(invalid) != 0 {
+		t.Fatalf("parse: %+v", invalid)
+	}
+	data, _ := first.Encode("json")
+	second, invalid := Parse("recipe.json", data)
+	if len(invalid) != 0 {
+		t.Fatal(invalid)
+	}
+	a, err := first.NormalizedSpecDigest()
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, _ := second.NormalizedSpecDigest()
+	if a != b || Digest([]byte(recipeYAML)) == Digest(data) {
+		t.Fatal("semantic and source digest scopes are incorrect")
+	}
+	second.Metadata.Description = "metadata is outside the spec digest"
+	b, _ = second.NormalizedSpecDigest()
+	if a != b {
+		t.Fatal("metadata changed the spec digest")
+	}
+	second.Spec["enabled"] = false
+	b, _ = second.NormalizedSpecDigest()
+	if a == b {
+		t.Fatal("definition change did not change the spec digest")
+	}
+}
+
+func TestDocumentRejectsAmbiguousAndUnsafeInput(t *testing.T) {
+	for _, test := range []struct{ name, content, code string }{
+		{"duplicate", strings.Replace(recipeYAML, "  name: build-release", "  name: first\n  name: second", 1), "duplicate_key"},
+		{"alias", strings.Replace(recipeYAML, "  name: build-release", "  name: &name build-release\n  description: *name", 1), "yaml_feature"},
+		{"merge", strings.Replace(recipeYAML, "  name: build-release", "  <<: {name: build-release}", 1), "non_string_key"},
+		{"tag", strings.Replace(recipeYAML, "name: build-release", "name: !!str build-release", 1), "yaml_feature"},
+		{"key", strings.Replace(recipeYAML, "name: build-release", "7: build-release", 1), "non_string_key"},
+		{"infinity", strings.Replace(recipeYAML, "maxConcurrency: 4", "maxConcurrency: .inf", 1), "invalid_number"},
+		{"unsafe integer", strings.Replace(recipeYAML, "maxConcurrency: 4", "maxConcurrency: 9007199254740993", 1), "number_precision"},
+		{"rounded unsafe boundary", strings.Replace(recipeYAML, "maxConcurrency: 4", "maxConcurrency: 9007199254740991.1", 1), "number_precision"},
+		{"negative rounded unsafe boundary", strings.Replace(recipeYAML, "maxConcurrency: 4", "maxConcurrency: -9007199254740991.1", 1), "number_precision"},
+		{"underflow", strings.Replace(recipeYAML, "maxConcurrency: 4", "maxConcurrency: 1e-9999", 1), "number_precision"},
+		{"hex", strings.Replace(recipeYAML, "maxConcurrency: 4", "maxConcurrency: 0x4", 1), "invalid_number"},
+		{"version", strings.Replace(recipeYAML, APIVersion, "delivery.soha.io/v9", 1), "unsupported_version"},
+		{"kind", strings.Replace(recipeYAML, "kind: WorkflowTemplate", "kind: Deployment", 1), "unsupported_kind"},
+		{"blueprint", strings.Replace(recipeYAML, "kind: WorkflowTemplate", "kind: Blueprint", 1), "unsupported_kind"},
+		{"two documents", recipeYAML + "---\n" + recipeYAML, "multiple_documents"},
+		{"server field", strings.Replace(recipeYAML, "  name: build-release", "  name: build-release\n  publicationState: published", 1), "schema_"},
+		{"unknown field", strings.Replace(recipeYAML, "maxConcurrency: 4", "maxConcurrency: 4\n    typo: true", 1), "schema_"},
+		{"invalid type", strings.Replace(recipeYAML, "maxConcurrency: 4", "maxConcurrency: private-value", 1), "schema_"},
+		{"surrogate", `{"apiVersion":"\ud800"}`, "syntax"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, invalid := Parse("input.yaml", []byte(test.content))
+			if len(invalid) == 0 || !strings.HasPrefix(invalid[0].Code, test.code) {
+				t.Fatalf("expected %s, got %+v", test.code, invalid)
+			}
+			for _, item := range invalid {
+				if strings.Contains(item.Message, "private-value") {
+					t.Fatal("diagnostic disclosed input content")
+				}
+			}
+		})
+	}
+	_, invalid := Parse("input.yaml", []byte(strings.Replace(recipeYAML, "  name: build-release", "  name: first\n  name: second", 1)))
+	if invalid[0].Pointer != "/metadata/name" || invalid[0].Line != 5 || invalid[0].Column != 3 {
+		t.Fatalf("missing duplicate key location: %+v", invalid)
+	}
+	for _, path := range []string{"../input.yaml", "/input.yaml", "a/../input.yaml", "a\\input.yaml", "a//input.yaml", "C:input.yaml"} {
+		if _, invalid := Parse(path, []byte(recipeYAML)); len(invalid) == 0 || invalid[0].Code != "invalid_path" {
+			t.Fatalf("accepted invalid path %q", path)
+		}
+	}
+	for _, input := range [][]byte{[]byte(strings.Repeat(" ", MaxFileBytes+1)), {0xff}, []byte("x: " + strings.Repeat("[", 66) + "0" + strings.Repeat("]", 66))} {
+		if _, invalid := Parse("input.yaml", input); len(invalid) == 0 {
+			t.Fatal("accepted oversized, invalid UTF-8 or deeply nested document")
+		}
+	}
+}
+
+func TestCanonicalJSONVectors(t *testing.T) {
+	for _, test := range []struct{ input, want string }{
+		{`{"z":-0.0,"a":1e-7,"b":0.000001,"c":333333333.33333329}`, `{"a":1e-7,"b":0.000001,"c":333333333.3333333,"z":0}`},
+		{`{"\ufb33":"letter","😀":"emoji","€":"euro","\r":"return","1":"one","ö":"o","\u0080":"control"}`, `{"\r":"return","1":"one","` + "\u0080" + `":"control","ö":"o","€":"euro","😀":"emoji","דּ":"letter"}`},
+		{`{"string":"<>&\u2028\u2029\u000f\b\t\n\f\r\\\"/"}`, "{\"string\":\"<>&\u2028\u2029\\u000f\\b\\t\\n\\f\\r\\\\\\\"/\"}"},
+	} {
+		var value any
+		if err := json.Unmarshal([]byte(test.input), &value); err != nil {
+			t.Fatal(err)
+		}
+		encoded, err := CanonicalJSON(value)
+		if err != nil || string(encoded) != test.want {
+			t.Fatalf("canonical JSON = %q, want %q; %v", encoded, test.want, err)
+		}
+	}
+	for _, value := range []any{math.NaN(), math.Inf(1), string([]byte{0xff})} {
+		if _, err := CanonicalJSON(value); err == nil {
+			t.Fatal("accepted non-I-JSON value")
+		}
+	}
+}
+
+func TestCanonicalJSONMatchesECMAScript(t *testing.T) {
+	if _, err := exec.LookPath("node"); err != nil {
+		t.Skip("Node.js is required for the contracts npm test cross-language gate")
+	}
+	input := `{"numbers":[-0.0,1e-6,1e-7,1e20,1e21,1e23,5e-324,1.7976931348623157e308,333333333.33333329],"keys":{"10":"ten","2":"two","\ufb33":"letter","😀":"emoji","€":"euro","\r":"return","ö":"o","\u0080":"control"},"string":"<>&\u2028\u2029\u000f\b\t\n\f\r\\\"/"}`
+	var value any
+	if err := json.Unmarshal([]byte(input), &value); err != nil {
+		t.Fatal(err)
+	}
+	got, err := CanonicalJSON(value)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	command := exec.CommandContext(ctx, "node", "-e", `
+const canonical = value => Array.isArray(value) ? '[' + value.map(canonical).join(',') + ']'
+  : value !== null && typeof value === 'object' ? '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}'
+  : JSON.stringify(value);
+process.stdout.write(canonical(JSON.parse(require('node:fs').readFileSync(0, 'utf8'))));`)
+	command.Stdin = strings.NewReader(input)
+	want, err := command.Output()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != string(want) {
+		t.Fatalf("Go canonical JSON differs from ECMAScript: got %q, want %q", got, want)
+	}
+}

package/delivery/parser.go

@@ -0,0 +1,155 @@
+package delivery
+
+import (
+	"bytes"
+	"io"
+	"math"
+	"math/big"
+	"path"
+	"regexp"
+	"strconv"
+	"strings"
+	"unicode/utf8"
+
+	"go.yaml.in/yaml/v3"
+)
+
+var jsonNumber = regexp.MustCompile(`^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$`)
+
+func ValidPath(value string) bool {
+	return value != "" && len(value) <= 512 && utf8.ValidString(value) && value != "." &&
+		path.Clean(value) == value && !path.IsAbs(value) && value != ".." && !strings.HasPrefix(value, "../") &&
+		!strings.ContainsAny(value, "\\\x00\r\n:")
+}
+
+// Parse accepts one bounded JSON-subset YAML document, including JSON syntax.
+// It retains source locations and rejects aliases before decoding any values.
+func Parse(filePath string, content []byte) (Document, []Diagnostic) {
+	if !ValidPath(filePath) {
+		return Document{}, []Diagnostic{diagnostic(filePath, "", "invalid_path", "path must be a normalized relative file path", nil)}
+	}
+	if len(content) == 0 || len(content) > MaxFileBytes || !utf8.Valid(content) {
+		return Document{}, []Diagnostic{diagnostic(filePath, "", "file_limit", "file must be UTF-8 and contain 1 to 1048576 bytes", nil)}
+	}
+	decoder := yaml.NewDecoder(bytes.NewReader(content))
+	var root, trailing yaml.Node
+	if err := decoder.Decode(&root); err != nil || len(root.Content) != 1 {
+		return Document{}, []Diagnostic{diagnostic(filePath, "", "syntax", "invalid YAML or JSON syntax", &root)}
+	}
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		return Document{}, []Diagnostic{diagnostic(filePath, "", "multiple_documents", "each file must contain exactly one document", &trailing)}
+	}
+	parser := documentParser{path: filePath, locations: map[string]*yaml.Node{}}
+	value, invalid := parser.value(root.Content[0], "", 0)
+	if invalid != nil {
+		return Document{}, []Diagnostic{*invalid}
+	}
+	return validateDocument(filePath, value, parser.locations)
+}
+
+type documentParser struct {
+	path      string
+	nodes     int
+	locations map[string]*yaml.Node
+}
+
+func (p *documentParser) value(node *yaml.Node, pointer string, depth int) (any, *Diagnostic) {
+	p.nodes++
+	p.locations[pointer] = node
+	if depth > 64 || p.nodes > 100000 {
+		return nil, p.invalid(node, pointer, "structure_limit", "document exceeds its nesting or node limit")
+	}
+	if node.Kind == yaml.AliasNode || node.Anchor != "" || node.Style&yaml.TaggedStyle != 0 {
+		return nil, p.invalid(node, pointer, "yaml_feature", "aliases, anchors and explicit tags are unsupported")
+	}
+	switch node.Kind {
+	case yaml.MappingNode:
+		return p.mapping(node, pointer, depth)
+	case yaml.SequenceNode:
+		values := make([]any, 0, len(node.Content))
+		for index, child := range node.Content {
+			value, err := p.value(child, pointer+"/"+strconv.Itoa(index), depth+1)
+			if err != nil {
+				return nil, err
+			}
+			values = append(values, value)
+		}
+		return values, nil
+	case yaml.ScalarNode:
+		return p.scalar(node, pointer)
+	default:
+		return nil, p.invalid(node, pointer, "unsupported_value", "only JSON-compatible values are supported")
+	}
+}
+
+func (p *documentParser) mapping(node *yaml.Node, pointer string, depth int) (any, *Diagnostic) {
+	values := make(map[string]any, len(node.Content)/2)
+	for i := 0; i < len(node.Content); i += 2 {
+		key, child := node.Content[i], node.Content[i+1]
+		if key.Kind != yaml.ScalarNode || key.Tag != "!!str" || key.Style&yaml.TaggedStyle != 0 || key.Anchor != "" {
+			return nil, p.invalid(key, pointer, "non_string_key", "object keys must be strings; merge keys are unsupported")
+		}
+		childPointer := pointer + "/" + escapePointer(key.Value)
+		if _, exists := values[key.Value]; exists {
+			return nil, p.invalid(key, childPointer, "duplicate_key", "duplicate object key")
+		}
+		value, err := p.value(child, childPointer, depth+1)
+		if err != nil {
+			return nil, err
+		}
+		values[key.Value] = value
+	}
+	return values, nil
+}
+
+func (p *documentParser) scalar(node *yaml.Node, pointer string) (any, *Diagnostic) {
+	switch node.Tag {
+	case "!!str":
+		return node.Value, nil
+	case "!!null":
+		return nil, nil
+	case "!!bool":
+		return strings.EqualFold(node.Value, "true"), nil
+	case "!!int", "!!float":
+		if !jsonNumber.MatchString(node.Value) {
+			return nil, p.invalid(node, pointer, "invalid_number", "numbers must use finite JSON decimal notation")
+		}
+		value, err := strconv.ParseFloat(node.Value, 64)
+		if err != nil || math.IsInf(value, 0) || math.IsNaN(value) || math.Trunc(value) == value && math.Abs(value) > 9007199254740991 || documentNumberBoundaryLoss(node.Value, value) {
+			return nil, p.invalid(node, pointer, "number_precision", "number exceeds finite IEEE-754 or safe integer limits")
+		}
+		return value, nil
+	default:
+		return nil, p.invalid(node, pointer, "unsupported_scalar", "quote dates and other non-JSON scalar values as strings")
+	}
+}
+
+func documentNumberBoundaryLoss(raw string, value float64) bool {
+	if value != 0 && math.Abs(value) != 9007199254740991 {
+		return false
+	}
+	// Directed rounding detects values just outside the safe range even when
+	// ParseFloat rounds them onto its boundary. It also detects underflow to zero.
+	exact, _, err := big.ParseFloat(raw, 10, 64, big.AwayFromZero)
+	if err != nil {
+		return true
+	}
+	return value == 0 && exact.Sign() != 0 || exact.Abs(exact).Cmp(big.NewFloat(9007199254740991)) > 0
+}
+
+func (p *documentParser) invalid(node *yaml.Node, pointer, code, message string) *Diagnostic {
+	result := diagnostic(p.path, pointer, code, message, node)
+	return &result
+}
+
+func diagnostic(path, pointer, code, message string, node *yaml.Node) Diagnostic {
+	result := Diagnostic{Path: path, Document: 1, Pointer: pointer, Code: code, Message: message}
+	if node != nil {
+		result.Line, result.Column = node.Line, node.Column
+	}
+	return result
+}
+
+func escapePointer(value string) string {
+	return strings.ReplaceAll(strings.ReplaceAll(value, "~", "~0"), "/", "~1")
+}

package/evaluation/evaluation-run.schema.json

@@ -4,16 +4,70 @@
   "title": "Evaluation Run",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "id", "datasetId", "datasetVersion", "candidateRefs", "status", "startedAt"],
+  "required": [
+    "schemaVersion",
+    "id",
+    "datasetId",
+    "datasetVersion",
+    "candidateRefs",
+    "status",
+    "startedAt"
+  ],
   "properties": {
-    "schemaVersion": { "const": "opensoha.dev/evaluation-run/v1" },
-    "id": { "type": "string", "minLength": 1, "maxLength": 128 },
-    "datasetId": { "type": "string", "minLength": 1, "maxLength": 128 },
-    "datasetVersion": { "type": "string", "minLength": 1, "maxLength": 64 },
-    "candidateRefs": { "type": "object", "minProperties": 1, "maxProperties": 32, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 512 } },
-    "status": { "enum": ["queued", "running", "completed", "failed", "cancelled"] },
-    "startedAt": { "type": "string", "format": "date-time" },
-    "completedAt": { "type": "string", "format": "date-time" },
-    "aggregateScores": { "type": "object", "maxProperties": 128, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } }
+    "schemaVersion": {
+      "const": "opensoha.dev/evaluation-run/v1"
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "datasetId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "datasetVersion": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "candidateRefs": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 32,
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 512
+      },
+      "description": "Versioned candidate metadata. Gateway execution applies publicModel, routeId, endpoint, and optional systemPrompt and retrievalContext strings (at most 512 characters each); promptVersion and retrievalVersion identify the supplied variants."
+    },
+    "status": {
+      "enum": [
+        "queued",
+        "running",
+        "completed",
+        "failed",
+        "cancelled"
+      ]
+    },
+    "startedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "completedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "aggregateScores": {
+      "type": "object",
+      "maxProperties": 128,
+      "additionalProperties": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      }
+    }
   }
 }

package/fixtures/json-schema/gateway-manifest/invalid/bad-execution-mode.json

@@ -0,0 +1,73 @@
+{
+  "name": "soha-ai-gateway",
+  "version": "0.1.0",
+  "generatedAt": "2026-06-09T12:00:00Z",
+  "principal": {
+    "userId": "u-1",
+    "userName": "admin",
+    "email": "admin@example.com",
+    "roles": [
+      "platform-admin"
+    ],
+    "teams": [],
+    "projects": [],
+    "tags": [],
+    "permissionKeys": [
+      "ai.gateway.view"
+    ]
+  },
+  "caller": {
+    "identityMode": "user",
+    "source": "cli"
+  },
+  "permissionKeys": [
+    "ai.gateway.view"
+  ],
+  "tools": [
+    {
+      "name": "docker.projects.deploy.trigger",
+      "title": "Deploy Docker project",
+      "description": "Start a durable Compose deployment.",
+      "domain": "docker",
+      "action": "execute",
+      "riskLevel": "execute",
+      "permissionKeys": [
+        "platform.pods.view"
+      ],
+      "requiresApproval": true,
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "projectId",
+          "idempotencyKey"
+        ],
+        "properties": {
+          "projectId": {
+            "type": "string"
+          },
+          "idempotencyKey": {
+            "type": "string"
+          }
+        }
+      },
+      "version": "1",
+      "execution": {
+        "mode": "magic",
+        "idempotent": true,
+        "idempotencyKeyField": "idempotencyKey",
+        "taskKind": "docker.operation",
+        "statusTool": "docker.operations.get"
+      }
+    }
+  ],
+  "resources": [],
+  "prompts": [],
+  "skills": [],
+  "summary": {
+    "toolCount": 1,
+    "resourceCount": 0,
+    "promptCount": 0,
+    "skillCount": 0,
+    "deniedCount": 0
+  }
+}

package/fixtures/json-schema/gateway-manifest/invalid/unversioned-check.json

@@ -0,0 +1,85 @@
+{
+  "name": "soha-ai-gateway",
+  "version": "0.1.0",
+  "generatedAt": "2026-06-09T12:00:00Z",
+  "principal": {
+    "userId": "u-1",
+    "userName": "admin",
+    "email": "admin@example.com",
+    "roles": [
+      "platform-admin"
+    ],
+    "teams": [],
+    "projects": [],
+    "tags": [],
+    "permissionKeys": [
+      "ai.gateway.view"
+    ]
+  },
+  "caller": {
+    "identityMode": "user",
+    "source": "cli"
+  },
+  "permissionKeys": [
+    "ai.gateway.view"
+  ],
+  "tools": [
+    {
+      "name": "docker.projects.deploy.trigger",
+      "title": "Deploy Docker project",
+      "description": "Start a durable Compose deployment.",
+      "domain": "docker",
+      "action": "execute",
+      "riskLevel": "execute",
+      "permissionKeys": [
+        "platform.pods.view"
+      ],
+      "requiresApproval": true,
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "projectId",
+          "idempotencyKey"
+        ],
+        "properties": {
+          "projectId": {
+            "type": "string"
+          },
+          "idempotencyKey": {
+            "type": "string"
+          }
+        }
+      },
+      "version": "1",
+      "execution": {
+        "mode": "async",
+        "idempotent": true,
+        "idempotencyKeyField": "idempotencyKey",
+        "taskKind": "docker.operation",
+        "statusTool": "docker.operations.get",
+        "checks": [
+          {
+            "purpose": "precondition",
+            "toolName": "docker.projects.deploy.plan"
+          },
+          {
+            "purpose": "verification",
+            "toolName": "docker.projects.runtime.assess",
+            "capabilityVersion": "1"
+          }
+        ],
+        "recoveryMode": "original_call"
+      }
+    }
+  ],
+  "resources": [],
+  "prompts": [],
+  "skills": [],
+  "summary": {
+    "toolCount": 1,
+    "resourceCount": 0,
+    "promptCount": 0,
+    "skillCount": 0,
+    "deniedCount": 0
+  }
+}

package/fixtures/json-schema/gateway-manifest/valid/checks.json

@@ -0,0 +1,86 @@
+{
+  "name": "soha-ai-gateway",
+  "version": "0.1.0",
+  "generatedAt": "2026-06-09T12:00:00Z",
+  "principal": {
+    "userId": "u-1",
+    "userName": "admin",
+    "email": "admin@example.com",
+    "roles": [
+      "platform-admin"
+    ],
+    "teams": [],
+    "projects": [],
+    "tags": [],
+    "permissionKeys": [
+      "ai.gateway.view"
+    ]
+  },
+  "caller": {
+    "identityMode": "user",
+    "source": "cli"
+  },
+  "permissionKeys": [
+    "ai.gateway.view"
+  ],
+  "tools": [
+    {
+      "name": "docker.projects.deploy.trigger",
+      "title": "Deploy Docker project",
+      "description": "Start a durable Compose deployment.",
+      "domain": "docker",
+      "action": "execute",
+      "riskLevel": "execute",
+      "permissionKeys": [
+        "platform.pods.view"
+      ],
+      "requiresApproval": true,
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "projectId",
+          "idempotencyKey"
+        ],
+        "properties": {
+          "projectId": {
+            "type": "string"
+          },
+          "idempotencyKey": {
+            "type": "string"
+          }
+        }
+      },
+      "version": "1",
+      "execution": {
+        "mode": "async",
+        "idempotent": true,
+        "idempotencyKeyField": "idempotencyKey",
+        "taskKind": "docker.operation",
+        "statusTool": "docker.operations.get",
+        "checks": [
+          {
+            "purpose": "precondition",
+            "toolName": "docker.projects.deploy.plan",
+            "capabilityVersion": "1"
+          },
+          {
+            "purpose": "verification",
+            "toolName": "docker.projects.runtime.assess",
+            "capabilityVersion": "1"
+          }
+        ],
+        "recoveryMode": "original_call"
+      }
+    }
+  ],
+  "resources": [],
+  "prompts": [],
+  "skills": [],
+  "summary": {
+    "toolCount": 1,
+    "resourceCount": 0,
+    "promptCount": 0,
+    "skillCount": 0,
+    "deniedCount": 0
+  }
+}