@opensoha/contracts 0.1.17 → 0.1.18

package/compat/openapi-loose-boundaries-0.1.0.json

@@ -1,102 +1,98 @@
 {
-  "version": "0.1.17",
+  "version": "0.1.18",
   "generatedFrom": "openapi/soha-api.yaml",
   "entries": [
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRun/additionalProperties"
-    },
-    {
-      "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRun/properties/analysisArtifacts/items/additionalProperties"
+      "path": "components/schemas/AIEnvironmentTemplate/properties/networkPolicy/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRun/properties/input/additionalProperties"
+      "path": "components/schemas/AIEnvironmentTemplate/properties/resourcePolicy/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRun/properties/output/additionalProperties"
+      "path": "components/schemas/AIEnvironmentTemplateInput/properties/networkPolicy/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRun/properties/scope/additionalProperties"
+      "path": "components/schemas/AIEnvironmentTemplateInput/properties/resourcePolicy/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRun/properties/skillBindings/items/additionalProperties"
+      "path": "components/schemas/AISkillSettings/properties/inputSchema/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRun/properties/toolBindings/items/additionalProperties"
+      "path": "components/schemas/AISkillSettings/properties/outputSchema/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRun/properties/toolset/additionalProperties"
+      "path": "components/schemas/AgentProviderConformanceRun/properties/results/items/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRunCallbackRequest/properties/analysisArtifacts/items/additionalProperties"
+      "path": "components/schemas/AgentRun/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRunCallbackRequest/properties/payload/additionalProperties"
+      "path": "components/schemas/AgentRun/properties/analysisArtifacts/items/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRunCallbackRequest/properties/toolExecutions/items/additionalProperties"
+      "path": "components/schemas/AgentRun/properties/input/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRunCallbackWorkbenchMessageDoneEvent/allOf/1/properties/metadata/additionalProperties"
+      "path": "components/schemas/AgentRun/properties/output/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentRunToolCallRequest/properties/input/additionalProperties"
+      "path": "components/schemas/AgentRun/properties/scope/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentToolCallResult/additionalProperties"
+      "path": "components/schemas/AgentRun/properties/skillBindings/items/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentToolCallResult/properties/output/additionalProperties"
+      "path": "components/schemas/AgentRun/properties/toolBindings/items/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentToolCallResult/properties/toolExecution/additionalProperties"
+      "path": "components/schemas/AgentRun/properties/toolset/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AgentProviderConformanceRun/properties/results/items/additionalProperties"
+      "path": "components/schemas/AgentRunCallbackRequest/properties/analysisArtifacts/items/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AIEnvironmentTemplate/properties/networkPolicy/additionalProperties"
+      "path": "components/schemas/AgentRunCallbackRequest/properties/payload/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AIEnvironmentTemplate/properties/resourcePolicy/additionalProperties"
+      "path": "components/schemas/AgentRunCallbackRequest/properties/toolExecutions/items/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AIEnvironmentTemplateInput/properties/networkPolicy/additionalProperties"
+      "path": "components/schemas/AgentRunCallbackWorkbenchMessageDoneEvent/allOf/1/properties/metadata/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AIEnvironmentTemplateInput/properties/resourcePolicy/additionalProperties"
+      "path": "components/schemas/AgentRunToolCallRequest/properties/input/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/KnowledgeConnectorInput/properties/config/additionalProperties"
+      "path": "components/schemas/AgentToolCallResult/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AISkillSettings/properties/inputSchema/additionalProperties"
+      "path": "components/schemas/AgentToolCallResult/properties/output/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/AISkillSettings/properties/outputSchema/additionalProperties"
+      "path": "components/schemas/AgentToolCallResult/properties/toolExecution/additionalProperties"
     },
     {
       "kind": "additionalPropertiesTrue",
@@ -210,14 +206,6 @@
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/AuthBootstrapEnvelope/properties/data/properties/permissionSnapshot/additionalProperties"
     },
-    {
-      "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/IdentityApplication/properties/metadata/additionalProperties"
-    },
-    {
-      "kind": "additionalPropertiesTrue",
-      "path": "components/schemas/IdentityApplicationInput/properties/metadata/additionalProperties"
-    },
     {
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/BuildPolicy/properties/buildArgs/additionalProperties"
@@ -246,6 +234,10 @@
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/BuildTemplateInput/properties/variableSchema/additionalProperties"
     },
+    {
+      "kind": "additionalPropertiesTrue",
+      "path": "components/schemas/CapabilityCall/properties/input/additionalProperties"
+    },
     {
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/CohereRerankRequest/additionalProperties"
@@ -254,6 +246,14 @@
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/CohereRerankRequest/properties/documents/items/oneOf/1/additionalProperties"
     },
+    {
+      "kind": "additionalPropertiesTrue",
+      "path": "components/schemas/DeliveryGitLabPushEvent/additionalProperties"
+    },
+    {
+      "kind": "additionalPropertiesTrue",
+      "path": "components/schemas/DeliveryGitLabPushEvent/properties/project/additionalProperties"
+    },
     {
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/DeliveryPlan/properties/buildArgs/additionalProperties"
@@ -354,6 +354,14 @@
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/GovernanceStatus/properties/metadata/additionalProperties"
     },
+    {
+      "kind": "additionalPropertiesTrue",
+      "path": "components/schemas/IdentityApplication/properties/metadata/additionalProperties"
+    },
+    {
+      "kind": "additionalPropertiesTrue",
+      "path": "components/schemas/IdentityApplicationInput/properties/metadata/additionalProperties"
+    },
     {
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/IdentityProvider/properties/config/additionalProperties"
@@ -374,6 +382,10 @@
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/JSONSchema/additionalProperties"
     },
+    {
+      "kind": "additionalPropertiesTrue",
+      "path": "components/schemas/KnowledgeConnectorInput/properties/config/additionalProperties"
+    },
     {
       "kind": "additionalPropertiesTrue",
       "path": "components/schemas/LLMCallLog/properties/metadata/additionalProperties"
@@ -668,16 +680,6 @@
       "path": "components/schemas/AgentRunCallbackWorkbenchCardCommandEvent/allOf/1/properties/command",
       "target": "#/components/schemas/AnyValue"
     },
-    {
-      "kind": "schemaRef",
-      "path": "components/schemas/AnthropicMessagesRequest/properties/system",
-      "target": "#/components/schemas/AnyValue"
-    },
-    {
-      "kind": "schemaRef",
-      "path": "components/schemas/ApprovalRequest/properties/output",
-      "target": "#/components/schemas/AnyValue"
-    },
     {
       "kind": "schemaRef",
       "path": "components/schemas/AlertRule/properties/datasourceSelector",
@@ -723,6 +725,26 @@
       "path": "components/schemas/AlertRuleTestResult/properties/samples/items",
       "target": "#/components/schemas/GenericObject"
     },
+    {
+      "kind": "schemaRef",
+      "path": "components/schemas/AnthropicMessagesRequest/properties/system",
+      "target": "#/components/schemas/AnyValue"
+    },
+    {
+      "kind": "schemaRef",
+      "path": "components/schemas/ApprovalRequest/properties/output",
+      "target": "#/components/schemas/AnyValue"
+    },
+    {
+      "kind": "schemaRef",
+      "path": "components/schemas/DeliveryBlueprint/properties/executionHints",
+      "target": "#/components/schemas/GenericObject"
+    },
+    {
+      "kind": "schemaRef",
+      "path": "components/schemas/DeliveryBlueprintInput/properties/executionHints",
+      "target": "#/components/schemas/GenericObject"
+    },
     {
       "kind": "schemaRef",
       "path": "components/schemas/DeliveryDraft/properties/executionHints",
@@ -753,6 +775,16 @@
       "path": "components/schemas/GenericItemsEnvelope/properties/items/items",
       "target": "#/components/schemas/AnyValue"
     },
+    {
+      "kind": "schemaRef",
+      "path": "components/schemas/IdentityOutpost/properties/metadata",
+      "target": "#/components/schemas/GenericObject"
+    },
+    {
+      "kind": "schemaRef",
+      "path": "components/schemas/IdentityOutpostInput/properties/metadata",
+      "target": "#/components/schemas/GenericObject"
+    },
     {
       "kind": "schemaRef",
       "path": "components/schemas/OpenAIEmbeddingRequest/properties/input",

package/delivery/canonical.go

@@ -0,0 +1,136 @@
+package delivery
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"math"
+	"slices"
+	"strconv"
+	"strings"
+	"unicode/utf16"
+	"unicode/utf8"
+)
+
+func Digest(data []byte) string {
+	digest := sha256.Sum256(data)
+	return "sha256:" + hex.EncodeToString(digest[:])
+}
+
+// CanonicalJSON implements RFC 8785 for parsed JSON values. Integers outside the
+// interoperable range are rejected by the document parser before reaching here.
+func CanonicalJSON(value any) ([]byte, error) {
+	var output bytes.Buffer
+	if err := appendCanonical(&output, value, 0); err != nil {
+		return nil, err
+	}
+	return output.Bytes(), nil
+}
+
+func appendCanonical(output *bytes.Buffer, value any, depth int) error {
+	if depth > 64 {
+		return fmt.Errorf("canonical value exceeds nesting limit")
+	}
+	switch value := value.(type) {
+	case nil:
+		output.WriteString("null")
+	case bool:
+		output.WriteString(strconv.FormatBool(value))
+	case string:
+		return appendJSONString(output, value)
+	case float64:
+		return appendJSONNumber(output, value)
+	case []any:
+		output.WriteByte('[')
+		for index, child := range value {
+			if index > 0 {
+				output.WriteByte(',')
+			}
+			if err := appendCanonical(output, child, depth+1); err != nil {
+				return err
+			}
+		}
+		output.WriteByte(']')
+	case map[string]any:
+		return appendJSONObject(output, value, depth)
+	default:
+		return fmt.Errorf("canonical value must be a parsed JSON value")
+	}
+	return nil
+}
+
+func appendJSONObject(output *bytes.Buffer, value map[string]any, depth int) error {
+	keys := make([]string, 0, len(value))
+	for key := range value {
+		keys = append(keys, key)
+	}
+	slices.SortFunc(keys, func(a, b string) int {
+		return slices.Compare(utf16.Encode([]rune(a)), utf16.Encode([]rune(b)))
+	})
+	output.WriteByte('{')
+	for index, key := range keys {
+		if index > 0 {
+			output.WriteByte(',')
+		}
+		if err := appendJSONString(output, key); err != nil {
+			return err
+		}
+		output.WriteByte(':')
+		if err := appendCanonical(output, value[key], depth+1); err != nil {
+			return err
+		}
+	}
+	output.WriteByte('}')
+	return nil
+}
+
+func appendJSONString(output *bytes.Buffer, value string) error {
+	if !utf8.ValidString(value) {
+		return fmt.Errorf("canonical strings must be valid Unicode")
+	}
+	output.WriteByte('"')
+	for _, r := range value {
+		switch r {
+		case '"', '\\':
+			output.WriteByte('\\')
+			output.WriteRune(r)
+		case '\b':
+			output.WriteString(`\b`)
+		case '\t':
+			output.WriteString(`\t`)
+		case '\n':
+			output.WriteString(`\n`)
+		case '\f':
+			output.WriteString(`\f`)
+		case '\r':
+			output.WriteString(`\r`)
+		default:
+			if r < 0x20 {
+				fmt.Fprintf(output, `\u%04x`, r)
+			} else {
+				output.WriteRune(r)
+			}
+		}
+	}
+	output.WriteByte('"')
+	return nil
+}
+
+func appendJSONNumber(output *bytes.Buffer, value float64) error {
+	if math.IsInf(value, 0) || math.IsNaN(value) {
+		return fmt.Errorf("canonical numbers must be finite")
+	}
+	if value == 0 {
+		output.WriteByte('0')
+		return nil
+	}
+	format := byte('f')
+	if math.Abs(value) < 1e-6 || math.Abs(value) >= 1e21 {
+		format = 'e'
+	}
+	text := strconv.FormatFloat(value, format, -1, 64)
+	text = strings.ReplaceAll(strings.ReplaceAll(text, "e-0", "e-"), "e+0", "e+")
+	output.WriteString(text)
+	return nil
+}

package/delivery/document.go

@@ -0,0 +1,203 @@
+// Package delivery implements the versioned delivery document boundary shared
+// by the server and CLI. It does not resolve references or authorize imports.
+package delivery
+
+import (
+	"bytes"
+	_ "embed"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/santhosh-tekuri/jsonschema/v6"
+	"go.yaml.in/yaml/v3"
+)
+
+const APIVersion = "delivery.soha.io/v1alpha1"
+const MaxFileBytes = 1 << 20
+const MaxTotalBytes = 2 << 20
+const MaxFiles = 100
+
+//go:embed document.schema.json
+var documentSchema []byte
+
+func Schema() []byte { return bytes.Clone(documentSchema) }
+
+type Metadata struct {
+	Name        string `json:"name"`
+	DisplayName string `json:"displayName,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
+type Document struct {
+	APIVersion string         `json:"apiVersion"`
+	Kind       string         `json:"kind"`
+	Metadata   Metadata       `json:"metadata"`
+	Spec       map[string]any `json:"spec"`
+}
+
+type Diagnostic struct {
+	Path     string `json:"path"`
+	Document int    `json:"document"`
+	Pointer  string `json:"pointer"`
+	Line     int    `json:"line,omitempty"`
+	Column   int    `json:"column,omitempty"`
+	Code     string `json:"code"`
+	Message  string `json:"message"`
+}
+
+func (d Diagnostic) Error() string { return fmt.Sprintf("%s%s: %s", d.Path, d.Pointer, d.Message) }
+
+var compiledSchemas = sync.OnceValues(func() (map[string]*jsonschema.Schema, error) {
+	resource, err := jsonschema.UnmarshalJSON(bytes.NewReader(documentSchema))
+	if err != nil {
+		return nil, err
+	}
+	const location = "https://contracts.opensoha.dev/delivery/document.schema.json"
+	compiler := jsonschema.NewCompiler()
+	compiler.AssertFormat()
+	if err := compiler.AddResource(location, resource); err != nil {
+		return nil, err
+	}
+	schemas := map[string]*jsonschema.Schema{}
+	for kind, name := range map[string]string{
+		"BuildTemplate": "DeliveryBuildTemplateDocument", "DeploymentTemplate": "DeliveryDeploymentTemplateDocument",
+		"WorkflowTemplate": "DeliveryWorkflowTemplateDocument", "Workflow": "DeliveryWorkflowDocument",
+	} {
+		schemas[kind], err = compiler.Compile(location + "#/$defs/" + name)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return schemas, nil
+})
+
+func validateDocument(path string, value any, locations map[string]*yaml.Node) (Document, []Diagnostic) {
+	root, ok := value.(map[string]any)
+	if !ok {
+		return Document{}, []Diagnostic{diagnostic(path, "", "document_object", "document must be an object", locations[""])}
+	}
+	if root["apiVersion"] != APIVersion {
+		return Document{}, []Diagnostic{diagnostic(path, "/apiVersion", "unsupported_version", "unsupported or missing apiVersion", locations["/apiVersion"])}
+	}
+	schemas, err := compiledSchemas()
+	if err != nil {
+		return Document{}, []Diagnostic{diagnostic(path, "", "schema_unavailable", "document schema could not be loaded", nil)}
+	}
+	kind, _ := root["kind"].(string)
+	schema, supported := schemas[kind]
+	if !supported {
+		return Document{}, []Diagnostic{diagnostic(path, "/kind", "unsupported_kind", "unsupported document kind", locations["/kind"])}
+	}
+	if err := schema.Validate(root); err != nil {
+		return Document{}, schemaDiagnostics(path, err, locations)
+	}
+	data, err := json.Marshal(root)
+	if err != nil {
+		return Document{}, []Diagnostic{diagnostic(path, "", "invalid_json", "document must contain JSON values", nil)}
+	}
+	var document Document
+	if err := json.Unmarshal(data, &document); err != nil {
+		return Document{}, []Diagnostic{diagnostic(path, "", "invalid_document", "document fields are invalid", nil)}
+	}
+	normalizeDocument(&document)
+	return document, nil
+}
+
+func schemaDiagnostics(path string, err error, locations map[string]*yaml.Node) []Diagnostic {
+	var invalid *jsonschema.ValidationError
+	if !errors.As(err, &invalid) {
+		return []Diagnostic{diagnostic(path, "", "schema_invalid", "document does not satisfy its schema", nil)}
+	}
+	var results []Diagnostic
+	var visit func(*jsonschema.ValidationError)
+	visit = func(item *jsonschema.ValidationError) {
+		if len(results) >= 20 {
+			return
+		}
+		if len(item.Causes) > 0 {
+			for _, cause := range item.Causes {
+				visit(cause)
+			}
+			return
+		}
+		pointer := ""
+		for _, part := range item.InstanceLocation {
+			pointer += "/" + escapePointer(part)
+		}
+		keyword := strings.Join(item.ErrorKind.KeywordPath(), ".")
+		// The library's formatted errors can contain raw values. Keep diagnostics
+		// at the field/constraint boundary, including for legacy executor config.
+		results = append(results, diagnostic(path, pointer, "schema_"+keyword, "field does not satisfy "+keyword, locations[pointer]))
+	}
+	visit(invalid)
+	return results
+}
+
+func normalizeDocument(document *Document) {
+	spec := document.Spec
+	if document.Kind != "Workflow" {
+		setDefault(spec, "enabled", true)
+		if document.Metadata.DisplayName == "" {
+			document.Metadata.DisplayName = document.Metadata.Name
+		}
+	}
+	switch document.Kind {
+	case "BuildTemplate":
+		setDefault(spec, "builderKind", "custom")
+		setDefault(spec, "variableSchema", map[string]any{})
+		setDefault(spec, "defaultVariables", map[string]any{})
+	case "WorkflowTemplate":
+		setDefault(spec, "category", "release")
+		definition, _ := spec["definition"].(map[string]any) // Schema-validated before normalization.
+		if definition["mode"] != "delivery_batch" {
+			setDefault(definition, "mode", "release_dag")
+		}
+	case "Workflow":
+		definition, _ := spec["definition"].(map[string]any) // Schema-validated before normalization.
+		// Template defaults are resolved by the server against the pinned version.
+		if definition["workflowTemplateId"] == nil {
+			setDefault(definition, "mode", "service_serial")
+			setDefault(definition, "stopOnFailure", true)
+			setDefault(definition, "maxConcurrency", float64(4))
+		}
+	}
+}
+
+func setDefault(object map[string]any, key string, value any) {
+	if _, exists := object[key]; !exists {
+		object[key] = value
+	}
+}
+
+func (d Document) Value() map[string]any {
+	metadata := map[string]any{"name": d.Metadata.Name}
+	if d.Metadata.DisplayName != "" {
+		metadata["displayName"] = d.Metadata.DisplayName
+	}
+	if d.Metadata.Description != "" {
+		metadata["description"] = d.Metadata.Description
+	}
+	return map[string]any{"apiVersion": d.APIVersion, "kind": d.Kind, "metadata": metadata, "spec": d.Spec}
+}
+
+func (d Document) NormalizedSpecDigest() (string, error) {
+	data, err := CanonicalJSON(map[string]any{"apiVersion": d.APIVersion, "kind": d.Kind, "spec": d.Spec})
+	if err != nil {
+		return "", err
+	}
+	return Digest(data), nil
+}
+
+func (d Document) Encode(format string) ([]byte, error) {
+	switch format {
+	case "json":
+		return json.MarshalIndent(d, "", "  ")
+	case "yaml":
+		return yaml.Marshal(d.Value())
+	default:
+		return nil, fmt.Errorf("unsupported document format")
+	}
+}