npm - @opensoha/contracts - Versions diffs - 0.1.4 - Mend

@opensoha/contracts 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (328) hide show

package/go.mod ADDED Viewed

@@ -0,0 +1,18 @@
+module github.com/opensoha/soha-contracts
+go 1.26.5
+require (
+	github.com/oapi-codegen/runtime v1.4.2
+	sigs.k8s.io/yaml v1.5.0
+)
+require (
+	github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/rogpeppe/go-internal v1.13.1 // indirect
+	go.yaml.in/yaml/v2 v2.4.2 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
+)

package/go.sum ADDED Viewed

@@ -0,0 +1,46 @@
+github.com/RaveNoX/go-jsoncommentstrip v1.0.0/go.mod h1:78ihd09MekBnJnxpICcwzCMzGrKSKYe4AqU6PDYYpjk=
+github.com/apapsch/go-jsonmerge/v2 v2.0.0 h1:axGnT1gRIfimI7gJifB699GoE/oq+F2MU7Dml6nw9rQ=
+github.com/apapsch/go-jsonmerge/v2 v2.0.0/go.mod h1:lvDnEdqiQrp0O42VQGgmlKpxL1AP2+08jFMw88y4klk=
+github.com/bmatcuk/doublestar v1.1.1/go.mod h1:UD6OnuiIn0yFxxA2le/rnRU1G4RaI4UvFv1sNto9p6w=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/juju/gnuflag v0.0.0-20171113085948-2ce1bb71843d/go.mod h1:2PavIy+JPciBPrBUjwbNvtwB6RQlve+hkpll6QSNmOE=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/oapi-codegen/nullable v1.1.0 h1:eAh8JVc5430VtYVnq00Hrbpag9PFRGWLjxR1/3KntMs=
+github.com/oapi-codegen/nullable v1.1.0/go.mod h1:KUZ3vUzkmEKY90ksAmit2+5juDIhIZhfDl+0PwOQlFY=
+github.com/oapi-codegen/runtime v1.4.2 h1:GMxFVYLzoYLua+/KvzgSphkyK1lLTReQI9Vf4hvATKE=
+github.com/oapi-codegen/runtime v1.4.2/go.mod h1:GwV7hC2hviaMzj+ITfHVRESK5J2W/GefVwIND/bMGvU=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=
+github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=
+github.com/spkg/bom v0.0.0-20160624110644-59b7046e48ad/go.mod h1:qLr4V1qq6nMqFKkMo8ZTx3f+BZEkzsRUY10Xsm2mwU0=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
+go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
+go.yaml.in/yaml/v3 v3.0.3 h1:bXOww4E/J3f66rav3pX3m8w6jDE4knZjGOw8b5Y6iNE=
+go.yaml.in/yaml/v3 v3.0.3/go.mod h1:tBHosrYAkRZjRAOREWbDnBXUf08JOwYq++0QNwQiWzI=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+sigs.k8s.io/yaml v1.5.0 h1:M10b2U7aEUY6hRtU870n2VTPgR5RZiL/I6Lcc2F4NUQ=
+sigs.k8s.io/yaml v1.5.0/go.mod h1:wZs27Rbxoai4C0f8/9urLZtZtF3avA3gKvGyPdDqTO4=

package/governance/approval-request.schema.json ADDED Viewed

@@ -0,0 +1,187 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/governance/approval-request.schema.json",
+  "title": "OpenSoha Approval Request",
+  "description": "Public approval request, trace, decision, stage, and timeline event contract for high-risk Gateway and platform operations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "status",
+    "strategy",
+    "actorType",
+    "actorId",
+    "toolName",
+    "riskLevel",
+    "requiresApproval",
+    "summary",
+    "createdAt",
+    "updatedAt"
+  ],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "status": { "type": "string", "minLength": 1 },
+    "strategy": { "type": "string", "minLength": 1 },
+    "policyId": { "type": "string" },
+    "approvalPolicyRef": { "type": "string" },
+    "actorType": { "type": "string", "minLength": 1 },
+    "actorId": { "type": "string", "minLength": 1 },
+    "actorName": { "type": "string" },
+    "actorRoles": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "actorTeams": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "aiClientId": { "type": "string" },
+    "aiClientName": { "type": "string" },
+    "skillId": { "type": "string" },
+    "toolName": { "type": "string", "minLength": 1 },
+    "riskLevel": { "$ref": "#/$defs/RiskLevel" },
+    "requiresApproval": { "type": "boolean" },
+    "resourceScope": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "toolInput": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "relatedIds": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "approvalTrace": { "$ref": "#/$defs/ApprovalTrace" },
+    "timelineEvents": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ApprovalTimelineEvent" }
+    },
+    "output": {},
+    "summary": { "type": "string", "minLength": 1 },
+    "requestId": { "type": "string" },
+    "sourceIp": { "type": "string" },
+    "decidedBy": { "type": "string" },
+    "decidedByName": { "type": "string" },
+    "decidedAt": { "type": "string", "format": "date-time" },
+    "decisionComment": { "type": "string" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "RiskLevel": {
+      "type": "string",
+      "enum": ["read", "analyze", "mutate", "execute", "high"]
+    },
+    "ApprovalTrace": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "approvalMode": { "type": "string" },
+        "currentStageIndex": { "type": "integer" },
+        "currentStageName": { "type": "string" },
+        "stageCount": { "type": "integer" },
+        "approvedCount": { "type": "integer" },
+        "requiredApprovals": { "type": "integer" },
+        "pendingRequirements": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "satisfiedRequirements": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "roleApprovedCounts": {
+          "type": "object",
+          "additionalProperties": { "type": "integer" }
+        },
+        "teamApprovedCounts": {
+          "type": "object",
+          "additionalProperties": { "type": "integer" }
+        },
+        "candidateUserIds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "candidateRoles": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "candidateTeams": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "onCallCandidateUserIds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "workflowRunId": { "type": "string" },
+        "executionTaskId": { "type": "string" },
+        "releaseBundleId": { "type": "string" },
+        "decisions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ApprovalDecisionTrace" }
+        },
+        "stageHistory": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ApprovalStageTrace" }
+        }
+      }
+    },
+    "ApprovalDecisionTrace": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "userId": { "type": "string" },
+        "userName": { "type": "string" },
+        "roles": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "teams": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "result": { "type": "string" },
+        "comment": { "type": "string" },
+        "stageIndex": { "type": "integer" },
+        "stageName": { "type": "string" },
+        "decidedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ApprovalStageTrace": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "stageIndex": { "type": "integer" },
+        "stageName": { "type": "string" },
+        "result": { "type": "string" },
+        "completedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ApprovalTimelineEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "action", "result", "createdAt"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "type": "string", "minLength": 1 },
+        "action": { "type": "string", "minLength": 1 },
+        "result": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string" },
+        "actorType": { "type": "string" },
+        "actorId": { "type": "string" },
+        "actorName": { "type": "string" },
+        "stageIndex": { "type": "integer" },
+        "stageName": { "type": "string" },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "createdAt": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/governance/audit-log.schema.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/governance/audit-log.schema.json",
+  "title": "OpenSoha Audit Log",
+  "description": "Public audit log contract for Gateway, platform, connector, plugin, skill, and Cloud extension point actions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "actorType", "actorId", "action", "result", "summary", "createdAt"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "actorType": { "type": "string", "minLength": 1 },
+    "actorId": { "type": "string", "minLength": 1 },
+    "actorName": { "type": "string" },
+    "aiClientId": { "type": "string" },
+    "aiClientName": { "type": "string" },
+    "skillId": { "type": "string" },
+    "toolName": { "type": "string" },
+    "riskLevel": {
+      "type": "string",
+      "enum": ["read", "analyze", "mutate", "execute", "high"]
+    },
+    "resourceScope": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "action": { "type": "string", "minLength": 1 },
+    "result": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "minLength": 1 },
+    "requestId": { "type": "string" },
+    "sourceIp": { "type": "string" },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "createdAt": { "type": "string", "format": "date-time" }
+  }
+}

package/helmrelease/release.go ADDED Viewed

@@ -0,0 +1,108 @@
+package helmrelease
+import (
+	"bytes"
+	"compress/gzip"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"io"
+	"strings"
+	"time"
+	"sigs.k8s.io/yaml"
+)
+var gzipMagicHeader = []byte{0x1f, 0x8b, 0x08}
+type Release struct {
+	Name      string                 `json:"name,omitempty"`
+	Info      *Info                  `json:"info,omitempty"`
+	Chart     *Chart                 `json:"chart,omitempty"`
+	Config    map[string]any         `json:"config,omitempty"`
+	Manifest  string                 `json:"manifest,omitempty"`
+	Version   int                    `json:"version,omitempty"`
+	Namespace string                 `json:"namespace,omitempty"`
+	Labels    map[string]string      `json:"-"`
+	Raw       map[string]any         `json:"-"`
+	Hooks     []map[string]any       `json:"hooks,omitempty"`
+	Meta      map[string]interface{} `json:"-"`
+}
+type Info struct {
+	FirstDeployed time.Time `json:"first_deployed,omitempty"`
+	LastDeployed  time.Time `json:"last_deployed,omitempty"`
+	Deleted       time.Time `json:"deleted,omitempty"`
+	Description   string    `json:"description,omitempty"`
+	Status        string    `json:"status,omitempty"`
+	Notes         string    `json:"notes,omitempty"`
+}
+type Chart struct {
+	Metadata *ChartMetadata `json:"metadata,omitempty"`
+}
+type ChartMetadata struct {
+	Name        string            `json:"name,omitempty"`
+	Version     string            `json:"version,omitempty"`
+	AppVersion  string            `json:"appVersion,omitempty"`
+	Description string            `json:"description,omitempty"`
+	Annotations map[string]string `json:"annotations,omitempty"`
+}
+func Decode(encoded string, labels map[string]string) (*Release, error) {
+	decodedBytes, err := base64.StdEncoding.DecodeString(encoded)
+	if err != nil {
+		return nil, err
+	}
+	if len(decodedBytes) > 3 && bytes.Equal(decodedBytes[:3], gzipMagicHeader) {
+		reader, err := gzip.NewReader(bytes.NewReader(decodedBytes))
+		if err != nil {
+			return nil, err
+		}
+		defer func() { _ = reader.Close() }()
+		uncompressed, err := io.ReadAll(reader)
+		if err != nil {
+			return nil, err
+		}
+		decodedBytes = uncompressed
+	}
+	var release Release
+	if err := json.Unmarshal(decodedBytes, &release); err != nil {
+		return nil, err
+	}
+	release.Labels = cloneStringMap(labels)
+	return &release, nil
+}
+func ValuesYAML(release *Release) (string, error) {
+	if release == nil || len(release.Config) == 0 {
+		return "{}\n", nil
+	}
+	content, err := yaml.Marshal(release.Config)
+	if err != nil {
+		return "", err
+	}
+	return string(content), nil
+}
+func Digest(content string) string {
+	if strings.TrimSpace(content) == "" {
+		return ""
+	}
+	sum := sha256.Sum256([]byte(content))
+	return hex.EncodeToString(sum[:])
+}
+func cloneStringMap(values map[string]string) map[string]string {
+	if len(values) == 0 {
+		return nil
+	}
+	cloned := make(map[string]string, len(values))
+	for key, value := range values {
+		cloned[key] = value
+	}
+	return cloned
+}

package/helmrelease/release_test.go ADDED Viewed

@@ -0,0 +1,9 @@
+package helmrelease
+import "testing"
+func TestDigestEmptyString(t *testing.T) {
+	if got := Digest("   "); got != "" {
+		t.Fatalf("Digest(empty) = %q, want empty", got)
+	}
+}

package/knowledge/connector-checkpoint.schema.json ADDED Viewed

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/connector-checkpoint.schema.json",
+  "title": "Knowledge Connector Checkpoint",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "sourceId", "connectorVersion", "cursor", "configHash", "committedAt"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/knowledge-connector-checkpoint/v1" },
+    "sourceId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "connectorVersion": { "type": "string", "minLength": 1, "maxLength": 64 },
+    "cursor": { "type": "object", "maxProperties": 32, "additionalProperties": true },
+    "configHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "committedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/knowledge/connector-definition.schema.json ADDED Viewed

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/connector-definition.schema.json",
+  "title": "Knowledge Connector Definition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "kind", "version", "configRef", "enabled"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/knowledge-connector-definition/v1" },
+    "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "kind": { "enum": ["http", "git", "object-store"] },
+    "version": { "type": "string", "minLength": 1, "maxLength": 64 },
+    "configRef": { "type": "string", "pattern": "^secret:[^\\s]{1,240}$" },
+    "allowedHosts": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 253 } },
+    "pathPrefixes": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "maxLength": 1024 } },
+    "enabled": { "type": "boolean" }
+  }
+}

package/knowledge/context-envelope.schema.json ADDED Viewed

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/context-envelope.schema.json",
+  "title": "Context Envelope",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "id", "requestId", "principal", "task", "budgets", "budgetUsage", "policySnapshot", "contentHash", "createdAt"],
+  "properties": {
+    "version": { "const": "v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "requestId": { "type": "string", "minLength": 1 },
+    "sessionId": { "type": "string" },
+    "agentRunId": { "type": "string" },
+    "principal": { "type": "object", "additionalProperties": false, "required": ["userId"], "properties": { "userId": { "type": "string", "minLength": 1 } } },
+    "task": { "type": "object", "additionalProperties": false, "required": ["goal"], "properties": { "mode": { "type": "string" }, "goal": { "type": "string", "minLength": 1 } } },
+    "prompt": { "$ref": "#/$defs/versionRef" },
+    "skills": { "type": "array", "items": { "$ref": "#/$defs/versionRef" } },
+    "session": { "type": "object" },
+    "evidence": { "type": "array", "items": { "type": "object", "required": ["citationId", "content", "tokenCount"], "properties": { "citationId": { "type": "string" }, "content": { "type": "string" }, "tokenCount": { "type": "integer", "minimum": 0 } } } },
+    "citations": { "type": "array", "items": { "type": "object" } },
+    "tools": { "type": "array", "items": { "type": "object" } },
+    "environment": { "type": "object" },
+    "budgets": { "type": "object" },
+    "budgetUsage": { "type": "object" },
+    "policySnapshot": { "$ref": "#/$defs/versionRef" },
+    "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "createdAt": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "versionRef": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }
+  }
+}

package/knowledge/graph-revision.schema.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/graph-revision.schema.json",
+  "title": "Knowledge Graph Revision",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "knowledgeBaseId", "sourceIndexRef", "extractorVersion", "status", "entityCount", "relationCount", "createdAt"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/knowledge-graph-revision/v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "knowledgeBaseId": { "type": "string", "minLength": 1 },
+    "sourceIndexRef": { "type": "string", "minLength": 1 },
+    "extractorVersion": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["building", "verified", "active", "failed", "superseded"] },
+    "entityCount": { "type": "integer", "minimum": 0 },
+    "relationCount": { "type": "integer", "minimum": 0 },
+    "provenanceRoot": { "type": "string" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "publishedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/knowledge/index-publish.schema.json ADDED Viewed

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/index-publish.schema.json",
+  "title": "Knowledge Index Publish Decision",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "knowledgeBaseId", "revisionId", "expectedActiveRevision", "decision", "decidedAt"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/knowledge-index-publish/v1" },
+    "knowledgeBaseId": { "type": "string", "minLength": 1 },
+    "revisionId": { "type": "string", "minLength": 1 },
+    "expectedActiveRevision": { "type": "string" },
+    "decision": { "enum": ["publish", "reject", "rollback"] },
+    "verificationRefs": { "type": "array", "maxItems": 64, "items": { "type": "string" } },
+    "decidedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/knowledge/ingestion-job.schema.json ADDED Viewed

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/ingestion-job.schema.json",
+  "title": "Knowledge Ingestion Job",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "sourceId", "targetRevision", "stage", "status", "attempt", "createdAt"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/knowledge-ingestion-job/v1" },
+    "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "sourceId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "targetRevision": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "stage": { "enum": ["discovering", "fetching", "scanning", "parsing", "chunking", "embedding", "indexing", "verifying", "publishing"] },
+    "status": { "enum": ["queued", "running", "retry_wait", "cancelling", "cancelled", "failed", "succeeded"] },
+    "attempt": { "type": "integer", "minimum": 0, "maximum": 20 },
+    "leaseOwner": { "type": "string", "maxLength": 160 },
+    "leaseExpiresAt": { "type": "string", "format": "date-time" },
+    "errorCode": { "type": "string", "maxLength": 128 },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/knowledge/ingestion-stage.schema.json ADDED Viewed

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/ingestion-stage.schema.json",
+  "title": "Knowledge Ingestion Stage Completion",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "jobId", "stage", "attempt", "status", "completedAt"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/knowledge-ingestion-stage/v1" },
+    "jobId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "stage": { "type": "string", "minLength": 1, "maxLength": 64 },
+    "attempt": { "type": "integer", "minimum": 1, "maximum": 20 },
+    "status": { "enum": ["succeeded", "retryable", "failed", "cancelled"] },
+    "artifactRefs": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 512 } },
+    "checkpointRef": { "type": "string", "maxLength": 512 },
+    "errorCode": { "type": "string", "maxLength": 128 },
+    "completedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/knowledge/knowledge-base.schema.json ADDED Viewed

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/knowledge-base.schema.json",
+  "title": "Knowledge Base",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "name", "status", "ownerId", "scope", "retrievalPolicy", "createdAt", "updatedAt"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "tenantId": { "type": "string" },
+    "workspaceId": { "type": "string" },
+    "name": { "type": "string", "minLength": 1, "maxLength": 160 },
+    "description": { "type": "string", "maxLength": 4000 },
+    "status": { "enum": ["active", "disabled"] },
+    "ownerId": { "type": "string", "minLength": 1 },
+    "scope": { "$ref": "#/$defs/accessScope" },
+    "retrievalPolicy": { "$ref": "#/$defs/retrievalPolicy" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "stringSet": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "accessScope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["visibility"],
+      "properties": {
+        "visibility": { "enum": ["private", "restricted", "public"] },
+        "users": { "$ref": "#/$defs/stringSet" },
+        "roles": { "$ref": "#/$defs/stringSet" },
+        "teams": { "$ref": "#/$defs/stringSet" },
+        "projects": { "$ref": "#/$defs/stringSet" }
+      }
+    },
+    "retrievalPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["defaultTopK", "maxTopK", "lexicalWeight", "vectorWeight", "minScore"],
+      "properties": {
+        "defaultTopK": { "type": "integer", "minimum": 1, "maximum": 50 },
+        "maxTopK": { "type": "integer", "minimum": 1, "maximum": 50 },
+        "lexicalWeight": { "type": "number", "minimum": 0, "maximum": 1 },
+        "vectorWeight": { "type": "number", "minimum": 0, "maximum": 1 },
+        "minScore": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    }
+  }
+}

package/knowledge/knowledge-search.schema.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/knowledge-search.schema.json",
+  "title": "Knowledge Search Request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["knowledgeBaseIds", "query"],
+  "properties": {
+    "knowledgeBaseIds": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "query": { "type": "string", "minLength": 1, "maxLength": 16000 },
+    "topK": { "type": "integer", "minimum": 1, "maximum": 50 },
+    "filters": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sourceIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "documentIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }
+      }
+    }
+  }
+}