@kindgi/specs 0.0.0-bootstrap.0 → 0.1.1

package/schemas/pack.schema.json

@@ -0,0 +1,320 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/pack.schema.json",
+  "$comment": "schema-version: 1.1.0",
+  "title": "Pack manifest",
+  "description": "An installable vertical application. Bundles agents, tools, guardrails, memory schemas, capability declarations, and UI metadata — all as data. Installation is 'load this manifest into tenant config'. Pack tools reach the runtime over MCP (`mcpEndpoint`), as a handler artifact (`codeArtifactRef`), or as a declarative `spec`; pack code runs outside the runtime server process, in a separate process or container.",
+  "type": "object",
+  "required": ["id", "version", "name", "manifestVersion"],
+  "additionalProperties": false,
+  "properties": {
+    "manifestVersion": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Version of the pack manifest schema itself. Bumped on breaking manifest changes."
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*(?:\\.[a-z][a-z0-9-]*)*$",
+      "minLength": 1,
+      "description": "Globally unique pack id (dotted lowercase, e.g. 'com.acme.support')."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string"
+    },
+    "author": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "email": {
+          "type": "string",
+          "format": "email"
+        }
+      }
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri"
+    },
+    "license": {
+      "type": "string"
+    },
+    "requiresOsVersion": {
+      "type": "string",
+      "description": "Semver range of Kindgi runtime versions this pack is compatible with (e.g. '>=1.0.0 <2.0.0')."
+    },
+    "agents": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/AgentDecl"
+      },
+      "description": "Agents this pack contributes. Each is a full agent definition (declarative)."
+    },
+    "flows": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/FlowDecl"
+      },
+      "description": "Task flows this pack contributes (references to flow documents)."
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ToolDecl"
+      },
+      "description": "Tools this pack contributes. Tools that run pack code point at it through an `mcpEndpoint` (the pack's MCP server) or a `codeArtifactRef` (a handler artifact); declarative tools carry a `spec`."
+    },
+    "guardrails": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/GuardrailDecl"
+      }
+    },
+    "memorySchemas": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/MemorySchemaDecl"
+      },
+      "description": "Fact type schemas this pack defines. Registered so the memory layer knows how to validate writes."
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/CapabilityDecl"
+      },
+      "description": "Capability declarations named by this pack (referenced by pack agents)."
+    },
+    "ui": {
+      "$ref": "#/$defs/UiMetadata",
+      "description": "Optional metadata for how Kindgi UIs display this pack (icon, category, tags, external app URL)."
+    },
+    "requiredNeeds": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Context slots this pack requires the tenant to have configured (e.g. 'model:vision-capable', 'blob', 'compliance-provider'). Install fails if any is unmet."
+    },
+    "permissions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Permissions this pack asks the admin to grant on install (e.g. 'memory:write:facts', 'blob:write', 'events:emit'). Enforced by the tenant policy engine."
+    },
+    "signature": {
+      "$ref": "#/$defs/PackSignature"
+    }
+  },
+  "$defs": {
+    "AgentDecl": {
+      "type": "object",
+      "required": ["id", "instructions", "capabilities"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "instructions": {
+          "type": "string",
+          "description": "System prompt / instructions for the agent."
+        },
+        "capabilities": {
+          "description": "Reference to a capability declaration by id, or an inline capability declaration.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "$ref": "https://kindgi.com/schemas/v1/capability.schema.json"
+            }
+          ]
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "$ref": "https://kindgi.com/schemas/v1/agent.schema.json#/$defs/ToolRef"
+          },
+          "description": "Tools this agent is allowed to call, as `{ id, version }` references — the same `ToolRef` shape as `agent.schema.json`. Schema-version 1.1.0 replaced the bare-string tool ids of 1.0.0."
+        },
+        "memory": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Memory binding configuration (which fact types the agent reads/writes, retrieval hints)."
+        },
+        "guardrails": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Guardrail ids that apply to this agent."
+        },
+        "exitConditions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "maxTurns": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "maxToolCalls": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "maxDurationMs": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "FlowDecl": {
+      "type": "object",
+      "required": ["path"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Relative path (within the pack bundle) to a JSON file conforming to flow.schema.json."
+        }
+      }
+    },
+    "ToolDecl": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["path"],
+          "additionalProperties": false,
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "Relative path to a JSON file conforming to tool.schema.json."
+            }
+          }
+        },
+        {
+          "$ref": "https://kindgi.com/schemas/v1/tool.schema.json"
+        }
+      ]
+    },
+    "GuardrailDecl": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["path"],
+          "additionalProperties": false,
+          "properties": {
+            "path": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "$ref": "https://kindgi.com/schemas/v1/guardrail.schema.json"
+        }
+      ]
+    },
+    "MemorySchemaDecl": {
+      "type": "object",
+      "required": ["factType", "schema"],
+      "additionalProperties": false,
+      "properties": {
+        "factType": {
+          "type": "string",
+          "description": "Fact type identifier this schema governs."
+        },
+        "schema": {
+          "type": "object",
+          "description": "JSON Schema (Draft 2020-12) for the fact content."
+        },
+        "retrieve": {
+          "type": "string",
+          "enum": ["semantic", "recency", "exact", "flow", "none"],
+          "description": "Default retrieval hint for facts of this type."
+        }
+      }
+    },
+    "CapabilityDecl": {
+      "type": "object",
+      "required": ["id", "declaration"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "declaration": {
+          "$ref": "https://kindgi.com/schemas/v1/capability.schema.json"
+        }
+      }
+    },
+    "UiMetadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "icon": {
+          "type": "string"
+        },
+        "category": {
+          "type": "string"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "externalAppUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL of the pack's own user-facing UI (separate app consuming the Kindgi client SDK). A pack's own drafting UI, for example, lives here — not embedded in Kindgi's own UI."
+        }
+      }
+    },
+    "PackSignature": {
+      "type": "object",
+      "required": ["algorithm", "keyId", "value", "signedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "algorithm": {
+          "type": "string",
+          "enum": ["ed25519"]
+        },
+        "keyId": {
+          "type": "string"
+        },
+        "value": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9+/]+={0,2}$"
+        },
+        "signedAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

package/schemas/policy.schema.json

@@ -0,0 +1,180 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/policy.schema.json",
+  "$comment": "schema-version: 1.0.0",
+  "title": "Tenant policy",
+  "description": "Kernel-level access control for a tenant. Enforced at every boundary — agent construction, tool invocation, memory read/write, blob access, model routing, event subscription. Applications cannot bypass; they inherit. The decision engine is pluggable (e.g. OpenFGA, Zanzibar-style) — this schema is transport-neutral.",
+  "type": "object",
+  "required": ["id", "tenantId", "version", "rules"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "tenantId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver — policy edits produce a new version. Decisions are traceable back to the version in force at the time."
+    },
+    "description": {
+      "type": "string"
+    },
+    "rules": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Rule"
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Fail-closed defaults. If no rule matches a decision request, these apply.",
+      "properties": {
+        "onNoMatch": {
+          "type": "string",
+          "enum": ["deny", "allow"],
+          "default": "deny"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "Rule": {
+      "type": "object",
+      "required": ["id", "effect", "principal", "resource", "action"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "effect": {
+          "type": "string",
+          "enum": ["allow", "deny"]
+        },
+        "principal": {
+          "$ref": "#/$defs/PrincipalSelector"
+        },
+        "resource": {
+          "$ref": "#/$defs/ResourceSelector"
+        },
+        "action": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "description": "Action verb (e.g. 'read', 'write', 'invoke', 'subscribe', 'delete', 'approve', 'route', 'sign')."
+          }
+        },
+        "condition": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Optional structured condition (e.g. time window, IP allowlist, attribute match). Engine-specific evaluation."
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "PrincipalSelector": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Who this rule applies to. At least one selector field required.",
+      "minProperties": 1,
+      "properties": {
+        "userIds": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "roles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "agentIds": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "toolIds": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "packIds": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "any": {
+          "type": "boolean",
+          "description": "If true, applies to any principal (used for public/anonymous rules — rare)."
+        }
+      }
+    },
+    "ResourceSelector": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What this rule governs.",
+      "minProperties": 1,
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "memory-fact",
+            "memory-log",
+            "blob",
+            "run",
+            "flow",
+            "agent",
+            "tool",
+            "model",
+            "event-subscription",
+            "provenance",
+            "approval-queue",
+            "pack-config",
+            "tenant-config",
+            "secret",
+            "audit-log"
+          ]
+        },
+        "ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Specific resource ids. If absent, applies to all resources of the kind."
+        },
+        "scope": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Scope match (project, thread, session, org). Fields interpreted per resource kind."
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Match resources bearing all these tags."
+        }
+      }
+    }
+  }
+}

package/schemas/provenance.schema.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/provenance.schema.json",
+  "$comment": "schema-version: 1.0.0",
+  "title": "Provenance DAG",
+  "description": "Causal DAG for a run. Every output node has edges back to every input that influenced it — prompts, retrieved chunks, tool results, prior turns, model version, tenant policy in effect. This is the PRIMARY audit artifact, not a derivative of OTel spans. Signed with Ed25519 for verification outside the runtime.",
+  "type": "object",
+  "required": ["id", "runId", "tenantId", "version", "nodes", "edges", "createdAt"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique provenance record identifier."
+    },
+    "runId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The kernel run this DAG describes."
+    },
+    "tenantId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Tenant that owns this provenance record. Cross-tenant reads are denied by policy."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Schema version for this DAG document (semver)."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this DAG was emitted (ISO-8601 UTC)."
+    },
+    "flowRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The flow and version this run executed.",
+      "required": ["id", "version"],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Node"
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Edge"
+      }
+    },
+    "signature": {
+      "$ref": "#/$defs/Signature"
+    }
+  },
+  "$defs": {
+    "Node": {
+      "type": "object",
+      "required": ["id", "kind", "timestamp"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "input",
+            "prompt",
+            "retrieval",
+            "tool-call",
+            "tool-result",
+            "model-call",
+            "model-output",
+            "artifact",
+            "guardrail-check",
+            "event",
+            "policy-decision",
+            "memory-read",
+            "memory-write",
+            "wait",
+            "resume"
+          ],
+          "description": "What this node represents in the causal chain."
+        },
+        "actor": {
+          "type": "string",
+          "description": "Which agent/tool/subsystem produced this node (id or name)."
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "contentHash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "Content-addressed hash of the node's payload. Enables dedup + tamper detection without storing the payload inline."
+        },
+        "contentRef": {
+          "type": "string",
+          "description": "Optional blob reference for large payloads (e.g. full model outputs). Format: 'blob://<provider>/<bucket>/<key>'."
+        },
+        "modelVersion": {
+          "type": "string",
+          "description": "Model + version, for model-call and model-output nodes (e.g. 'anthropic/claude-opus-4-7@2026-06-01')."
+        },
+        "policyDecisionId": {
+          "type": "string",
+          "description": "For policy-decision nodes: the ID that resolves to the full decision record."
+        },
+        "attributes": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Kind-specific attributes. Interpreted per node kind; consumers should tolerate unknown attributes for forward compatibility."
+        }
+      }
+    },
+    "Edge": {
+      "type": "object",
+      "required": ["from", "to", "kind"],
+      "additionalProperties": false,
+      "properties": {
+        "from": {
+          "type": "string",
+          "minLength": 1
+        },
+        "to": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "caused-by",
+            "influenced-by",
+            "retrieved-from",
+            "invoked",
+            "produced",
+            "checked-against",
+            "waited-on",
+            "resumed-from"
+          ]
+        }
+      }
+    },
+    "Signature": {
+      "type": "object",
+      "required": ["algorithm", "keyId", "value", "signedAt"],
+      "additionalProperties": false,
+      "description": "Cryptographic signature over the canonical serialization of (nodes, edges, id, runId, tenantId, createdAt, flowRef).",
+      "properties": {
+        "algorithm": {
+          "type": "string",
+          "enum": ["ed25519"]
+        },
+        "keyId": {
+          "type": "string",
+          "description": "Identifier of the signing key (per-tenant or per-deployment)."
+        },
+        "value": {
+          "type": "string",
+          "description": "Base64-encoded signature bytes.",
+          "pattern": "^[A-Za-z0-9+/]+={0,2}$"
+        },
+        "signedAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}