@opensoha/contracts 0.1.4

package/knowledge/knowledge-source.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/knowledge-source.schema.json",
+  "title": "Knowledge Source",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "knowledgeBaseId", "name", "kind", "syncPolicy", "status", "createdAt", "updatedAt"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "knowledgeBaseId": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "minLength": 1, "maxLength": 160 },
+    "kind": { "enum": ["inline", "http", "git", "object"] },
+    "configRef": { "type": "string" },
+    "config": { "type": "object" },
+    "syncPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": { "mode": { "enum": ["manual", "scheduled"] }, "schedule": { "type": "string" } }
+    },
+    "cursor": { "type": "string" },
+    "status": { "enum": ["pending", "ready", "syncing", "failed"] },
+    "lastError": { "type": "string" },
+    "lastSyncedAt": { "type": "string", "format": "date-time" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/knowledge/retrieval-trace.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/knowledge/retrieval-trace.schema.json",
+  "title": "Production Retrieval Trace",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "traceId", "queryHash", "indexRevision", "routeRef", "candidateCount", "hitCount", "noAnswer", "timingMs"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/knowledge-retrieval-trace/v1" },
+    "traceId": { "type": "string", "minLength": 1 },
+    "queryHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "indexRevision": { "type": "string", "minLength": 1 },
+    "routeRef": { "type": "string", "minLength": 1 },
+    "providerRef": { "type": "string" },
+    "candidateCount": { "type": "integer", "minimum": 0 },
+    "hitCount": { "type": "integer", "minimum": 0 },
+    "noAnswer": { "type": "boolean" },
+    "degraded": { "type": "boolean" },
+    "timingMs": { "type": "integer", "minimum": 0 }
+  }
+}

package/mcp/gateway-capability-baseline.schema.json

@@ -0,0 +1,290 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/mcp/gateway-capability-baseline.schema.json",
+  "title": "Soha AI Gateway Capability Baseline",
+  "description": "Release-governed AI Gateway capability baseline used by skills, CLI/MCP validation, and product release review. Unlike the runtime manifest, this catalog may include approved or reserved capabilities before they are visible to a caller.",
+  "type": "object",
+  "required": ["schemaVersion", "version", "source", "tools"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "minLength": 1
+    },
+    "schemaVersion": {
+      "const": "opensoha.dev/gateway-capability-catalog/v1"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([-+][A-Za-z0-9.-]+)?$"
+    },
+    "source": {
+      "type": "object",
+      "required": ["repository", "path", "syncStrategy"],
+      "properties": {
+        "repository": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "syncStrategy": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "plannedSkills": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "tools": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/ToolRecord"
+      },
+      "uniqueItems": true
+    },
+    "resources": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ResourceRecord"
+      },
+      "uniqueItems": true
+    },
+    "prompts": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/PromptRecord"
+      },
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "RiskLevel": {
+      "type": "string",
+      "enum": ["read", "analyze", "mutate", "execute", "high"]
+    },
+    "BaselineStatus": {
+      "type": "string",
+      "enum": ["stable-runtime", "baseline-approved", "baseline-proposed", "reserved", "deprecated"]
+    },
+    "StringArray": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "StringArrayAllowEmpty": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "AuditRecord": {
+      "type": "object",
+      "required": ["resourceKind", "relatedIds"],
+      "properties": {
+        "resourceKind": {
+          "type": "string",
+          "minLength": 1
+        },
+        "relatedIds": {
+          "$ref": "#/$defs/StringArray"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ToolRecord": {
+      "type": "object",
+      "required": [
+        "name",
+        "title",
+        "domain",
+        "owningWorkbench",
+        "owningService",
+        "action",
+        "riskLevel",
+        "permissionKeys",
+        "requiredScopes",
+        "mcpAdapterId",
+        "mcpToolName",
+        "requiresApproval",
+        "status",
+        "skillRefs",
+        "audit",
+        "redaction",
+        "moduleId",
+        "routeEvidence"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "domain": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owningWorkbench": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owningService": {
+          "type": "string",
+          "minLength": 1
+        },
+        "action": {
+          "type": "string",
+          "minLength": 1
+        },
+        "riskLevel": {
+          "$ref": "#/$defs/RiskLevel"
+        },
+        "permissionKeys": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "requiredScopes": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "mcpAdapterId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mcpToolName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "requiresApproval": {
+          "type": "boolean"
+        },
+        "status": {
+          "$ref": "#/$defs/BaselineStatus"
+        },
+        "skillRefs": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "resourceRefs": {
+          "$ref": "#/$defs/StringArrayAllowEmpty"
+        },
+        "promptRefs": {
+          "$ref": "#/$defs/StringArrayAllowEmpty"
+        },
+        "audit": {
+          "$ref": "#/$defs/AuditRecord"
+        },
+        "redaction": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "moduleId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "routeEvidence": {
+          "$ref": "#/$defs/StringArray"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ResourceRecord": {
+      "type": "object",
+      "required": [
+        "name",
+        "description",
+        "permissionKeys",
+        "requiredScopes",
+        "status",
+        "skillRefs",
+        "toolRefs",
+        "promptRefs"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "permissionKeys": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "requiredScopes": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "status": {
+          "$ref": "#/$defs/BaselineStatus"
+        },
+        "skillRefs": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "toolRefs": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "promptRefs": {
+          "$ref": "#/$defs/StringArrayAllowEmpty"
+        }
+      },
+      "additionalProperties": false
+    },
+    "PromptRecord": {
+      "type": "object",
+      "required": [
+        "name",
+        "description",
+        "permissionKeys",
+        "requiredScopes",
+        "status",
+        "skillRefs",
+        "toolRefs",
+        "resourceRefs"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "permissionKeys": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "requiredScopes": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "status": {
+          "$ref": "#/$defs/BaselineStatus"
+        },
+        "skillRefs": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "toolRefs": {
+          "$ref": "#/$defs/StringArray"
+        },
+        "resourceRefs": {
+          "$ref": "#/$defs/StringArrayAllowEmpty"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/mcp/gateway-manifest.schema.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.opensoha.dev/mcp/gateway-manifest.schema.json",
+  "title": "Soha AI Gateway Manifest",
+  "description": "Permission-filtered capability manifest consumed by Soha CLI, MCP clients, AI agents, and web console surfaces.",
+  "type": "object",
+  "required": [
+    "name",
+    "version",
+    "generatedAt",
+    "principal",
+    "caller",
+    "permissionKeys",
+    "tools",
+    "summary"
+  ],
+  "properties": {
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "principal": { "$ref": "#/$defs/Principal" },
+    "caller": { "$ref": "#/$defs/CallerContext" },
+    "permissionKeys": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "tools": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ToolCapability" }
+    },
+    "resources": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ResourceCapability" }
+    },
+    "prompts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/PromptCapability" }
+    },
+    "skills": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/SkillCapability" }
+    },
+    "summary": { "$ref": "#/$defs/ManifestSummary" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "JSONSchema": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "Principal": {
+      "type": "object",
+      "required": ["userId", "userName", "email", "roles", "teams", "projects", "tags"],
+      "properties": {
+        "userId": { "type": "string" },
+        "userName": { "type": "string" },
+        "email": { "type": "string" },
+        "roles": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "teams": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "projects": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "permissionKeys": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "CallerContext": {
+      "type": "object",
+      "required": ["identityMode"],
+      "properties": {
+        "identityMode": { "type": "string" },
+        "aiClientId": { "type": "string" },
+        "aiClientName": { "type": "string" },
+        "skillId": { "type": "string" },
+        "tokenId": { "type": "string" },
+        "sessionId": { "type": "string" },
+        "subjectType": { "type": "string" },
+        "subjectId": { "type": "string" },
+        "source": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "RiskLevel": {
+      "type": "string",
+      "enum": ["read", "analyze", "mutate", "execute", "high"]
+    },
+    "ToolCapability": {
+      "type": "object",
+      "required": [
+        "name",
+        "title",
+        "description",
+        "domain",
+        "action",
+        "riskLevel",
+        "permissionKeys",
+        "requiresApproval"
+      ],
+      "properties": {
+        "name": { "type": "string" },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "domain": { "type": "string" },
+        "action": { "type": "string" },
+        "riskLevel": { "$ref": "#/$defs/RiskLevel" },
+        "permissionKeys": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "requiredScopes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "mcpAdapterId": { "type": "string" },
+        "mcpToolName": { "type": "string" },
+        "requiresApproval": { "type": "boolean" },
+        "inputSchema": { "$ref": "#/$defs/JSONSchema" },
+        "outputSchema": { "$ref": "#/$defs/JSONSchema" }
+      },
+      "additionalProperties": false
+    },
+    "ResourceCapability": {
+      "type": "object",
+      "required": ["name", "description", "permissionKeys"],
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "permissionKeys": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "requiredScopes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "contextSchema": { "$ref": "#/$defs/JSONSchema" }
+      },
+      "additionalProperties": false
+    },
+    "PromptCapability": {
+      "type": "object",
+      "required": ["name", "description", "permissionKeys"],
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "permissionKeys": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "requiredScopes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "argumentSchema": { "$ref": "#/$defs/JSONSchema" },
+        "contextSchema": { "$ref": "#/$defs/JSONSchema" }
+      },
+      "additionalProperties": false
+    },
+    "SkillCapability": {
+      "type": "object",
+      "required": ["id", "name", "category", "description"],
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "category": { "type": "string" },
+        "description": { "type": "string" },
+        "capabilityRefs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "permissionKeys": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "requiredScopes": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "ManifestSummary": {
+      "type": "object",
+      "required": ["toolCount", "resourceCount", "promptCount", "skillCount", "deniedCount"],
+      "properties": {
+        "toolCount": { "type": "integer", "minimum": 0 },
+        "resourceCount": { "type": "integer", "minimum": 0 },
+        "promptCount": { "type": "integer", "minimum": 0 },
+        "skillCount": { "type": "integer", "minimum": 0 },
+        "deniedCount": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    }
+  }
+}
+

package/memory/memory-policy.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/memory/memory-policy.schema.json",
+  "title": "Long-Term Memory Policy",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "version", "ownerTypes", "defaultTtlSeconds", "maximumTtlSeconds", "minimumConfidence", "explicitWriteOnly", "enabled"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/memory-policy/v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "minLength": 1 },
+    "ownerTypes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["user", "session", "agent"] } },
+    "defaultTtlSeconds": { "type": "integer", "minimum": 1, "maximum": 31536000 },
+    "maximumTtlSeconds": { "type": "integer", "minimum": 1, "maximum": 31536000 },
+    "minimumConfidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "explicitWriteOnly": { "type": "boolean" },
+    "enabled": { "type": "boolean" }
+  }
+}

package/memory/memory-record.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/memory/memory-record.schema.json",
+  "title": "Explicit Long-Term Memory Record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "ownerType", "ownerId", "scopeHash", "fact", "sourceType", "confidence", "validFrom", "policyVersion", "status", "createdAt"],
+  "properties": {
+    "schemaVersion": { "const": "opensoha.dev/memory-record/v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "ownerType": { "enum": ["user", "session", "agent"] },
+    "ownerId": { "type": "string", "minLength": 1 },
+    "scopeHash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "fact": { "type": "string", "minLength": 1, "maxLength": 8000 },
+    "sourceType": { "enum": ["explicit_user", "curated_extractor"] },
+    "sourceRefs": { "type": "array", "maxItems": 32, "items": { "type": "string" } },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "validFrom": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "policyVersion": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["active", "expired", "deleted"] },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "deletedAt": { "type": "string", "format": "date-time" }
+  }
+}