@kindgi/specs 0.0.0-bootstrap.0 → 0.1.0

package/schemas/compliance-evidence.schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/compliance-evidence.schema.json",
+  "$comment": "schema-version: 1.1.0",
+  "title": "Compliance evidence bundle",
+  "description": "One evidence record emitted by the Kindgi runtime for compliance / audit consumption. Derived from provenance DAG + policy decisions + audit log. Consumed by a ComplianceProvider, whose adapters forward evidence to a compliance platform or a SIEM. The optional Ed25519 `signature` provides tamper detection.",
+  "type": "object",
+  "required": ["id", "tenantId", "kind", "timestamp", "payload"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique evidence record ID."
+    },
+    "tenantId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "projectId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Content-scope anchor: the project the underlying audit event belongs to. Absent for tenant-level events (e.g. authz decisions, tenant-level admin actions)."
+    },
+    "kind": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The compliance-relevant event class. Open set: evidence is a classifier lens over the audit stream, and a deployment can mark any audit-event kind exportable. `examples` lists the built-in kinds; consumers must tolerate kinds they do not know.",
+      "examples": [
+        "access-event",
+        "policy-decision",
+        "config-change",
+        "secret-rotation",
+        "incident-event",
+        "guardrail-violation",
+        "eval-run",
+        "approval-completed",
+        "data-retention-action",
+        "authn-event",
+        "authz-decision",
+        "model-invocation",
+        "pack-install",
+        "pack-upgrade",
+        "pack-uninstall",
+        "run-outcome",
+        "env-resolved",
+        "env-set",
+        "env-deleted",
+        "secret-resolved",
+        "secret-set",
+        "secret-rotated",
+        "secret-rotation-started",
+        "secret-rotation-failed",
+        "secret-revoked",
+        "secret-hard-revoked",
+        "hitl-decision"
+      ]
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Who performed the action.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["user", "agent", "system", "admin", "external"]
+        },
+        "id": {
+          "type": "string"
+        },
+        "ipAddress": {
+          "type": "string"
+        },
+        "userAgent": {
+          "type": "string"
+        }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What the action was performed on.",
+      "properties": {
+        "kind": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        }
+      }
+    },
+    "outcome": {
+      "type": "string",
+      "enum": ["allowed", "denied", "succeeded", "failed", "escalated"],
+      "description": "Result of the action, for kinds where this is meaningful."
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Kind-specific evidence detail. For policy-decision: the rule that matched, the request context. For config-change: before/after diff. For secret-rotation: which secret, when. Etc."
+    },
+    "provenanceRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional back-reference to the provenance DAG that produced this evidence.",
+      "properties": {
+        "runId": {
+          "type": "string"
+        },
+        "nodeId": {
+          "type": "string"
+        }
+      }
+    },
+    "signature": {
+      "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/discoverable.schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/discoverable.schema.json",
+  "$comment": "schema-version: 1.1.0",
+  "title": "Discoverable entity",
+  "description": "Marks an entity (chat, conversation, document, artifact, memo, playbook, tool) as searchable via the cross-history retrieval API. The framework handles embedding via a configured provider; retrieval is always policy-scoped (owner / team / project / org / tenant). Deletion cascades to embeddings + retrieval caches.",
+  "type": "object",
+  "required": ["entityId", "entityKind", "scope"],
+  "additionalProperties": false,
+  "properties": {
+    "entityId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ID of the entity being made discoverable."
+    },
+    "entityKind": {
+      "type": "string",
+      "enum": [
+        "chat",
+        "conversation",
+        "document",
+        "artifact",
+        "memo",
+        "playbook",
+        "tool",
+        "agent",
+        "flow",
+        "note"
+      ]
+    },
+    "scope": {
+      "$ref": "#/$defs/DiscoverabilityScope"
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Tags to filter retrieval by (e.g. 'customer:acme', 'topic:billing')."
+    },
+    "title": {
+      "type": "string",
+      "description": "Human-readable title used in search UIs."
+    },
+    "summary": {
+      "type": "string",
+      "description": "Optional pre-computed summary used as a second-tier retrieval index (embed summaries + link to full content)."
+    },
+    "content": {
+      "description": "Content to index. May be inline string or a blob reference. If absent, the retrieval layer derives content from the entity by kind."
+    },
+    "contentRef": {
+      "type": "string",
+      "description": "Optional blob reference for large content. Format: 'blob://<provider>/<bucket>/<key>'."
+    },
+    "embeddingConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "type": "string",
+          "description": "Embedding model id, as a registered embedding provider reports it (`describe().model`). Router picks based on tenant policy if absent."
+        },
+        "chunker": {
+          "type": "string",
+          "enum": ["turn-aware", "sliding-window", "recursive", "semantic"],
+          "description": "Chunking strategy. 'turn-aware' is the correct default for chats and conversations (context-preserving); documents use 'recursive' or 'sliding-window'."
+        },
+        "chunkSize": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "chunkOverlap": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "keepUntil": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "keepDays": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "legalHold": {
+          "type": "boolean"
+        }
+      }
+    },
+    "declaredAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "$defs": {
+    "DiscoverabilityScope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tenantId", "visibility"],
+      "properties": {
+        "tenantId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "visibility": {
+          "type": "string",
+          "enum": ["owner-only", "team", "project", "org", "public"],
+          "description": "Who can retrieve this entity via search. 'owner-only' = declaring user only. 'team' = members of a specified team (added in schema-version 1.1.0). 'project' = anyone with policy access to the project. 'org' = anyone in the org with the appropriate role. 'public' = anyone in the tenant. Policy engine enforces at retrieval time regardless of this hint."
+        },
+        "userId": {
+          "type": "string",
+          "description": "Required if visibility = 'owner-only'."
+        },
+        "teamId": {
+          "type": "string",
+          "description": "Required if visibility = 'team'. Added in schema-version 1.1.0."
+        },
+        "projectId": {
+          "type": "string",
+          "description": "Required if visibility = 'project'."
+        },
+        "orgId": {
+          "type": "string",
+          "description": "Required if visibility = 'org'."
+        },
+        "allowedRoles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Additional role gate applied on top of visibility (e.g. 'admin-only', 'compliance-only')."
+        }
+      }
+    }
+  }
+}

package/schemas/eval-suite.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/eval-suite.schema.json",
+  "$comment": "schema-version: 1.0.0",
+  "title": "Evaluation suite",
+  "description": "Tenant-scoped evaluation suite definition — the *registry* shape (`/v1/eval-suites`). Suites define WHAT to evaluate; run execution + per-kind grader dispatch are separate concerns. `kind` selects the shape of `spec`; the registry treats `spec` as opaque JSON so new kinds can extend the catalog without breaking existing readers. Each kind's runtime consumer (eval-judge adapter for `accuracy` / `pairwise` / `regression`, HITL bridge for `human-review`, sandbox handler for `custom`) deserializes `spec` against its own contract. Case data lives in `spec`.",
+  "type": "object",
+  "required": ["id", "tenantId", "version", "kind", "spec"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable suite id chosen by the caller (e.g. `acme.drafting-accuracy`)."
+    },
+    "tenantId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Tenant owning the suite. When published via HTTP, must match the caller tenant (server-derived from the token). Cross-tenant publish is rejected."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver — publishing a modified suite produces a new version. Eval runs are traceable back to the version in force at the time."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["accuracy", "pairwise", "regression", "human-review", "benchmark", "custom"],
+      "description": "Closed enum, extended additively — new kinds require a spec + validator update in tandem so the registry never accepts a kind no runtime consumer honors. `accuracy` — metric-based grading against ground truth (input → expectedOutput pairs; grader is an eval-judge adapter). `pairwise` — A/B comparisons between two agent/flow versions. `regression` — compare against a stored baseline run. `human-review` — delegates rubric grading to HITL. `benchmark` — reference to a standardized suite (name + version). `custom` — caller-supplied evaluator handler (sandboxed handler-as-code)."
+    },
+    "description": {
+      "type": "string"
+    },
+    "spec": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Kind-specific suite body. Registry validates only that this is an object; deeper validation is the runtime consumer's responsibility per kind. For `accuracy`, typically `{ cases: [{ input, expectedOutput }], grader?: { adapterId, config? } }`. For `pairwise`, typically `{ prompts: [...], variantA: { agentId, version }, variantB: { agentId, version } }`. For `regression`, typically `{ baseline: { runId } | { suiteId, version }, cases: [...] }`. For `human-review`, typically `{ rubric: [...], reviewerRole }`. For `benchmark`, typically `{ benchmark: { name, version } }`. For `custom`, typically `{ handler: { modulePath, entrypointPath }, cases: [...] }`."
+    }
+  }
+}

package/schemas/event.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/event.schema.json",
+  "$comment": "schema-version: 1.0.0",
+  "title": "Event",
+  "description": "The causal glue between runs. Emitted by kernel, memory, tools, agents, supervisor, HITL. Consumed by subscriptions to trigger new runs or resume in-flight waits. Every event has an ID for idempotent delivery; every subscription is policy-scoped. Delivery is at-least-once with idempotent handlers.",
+  "type": "object",
+  "required": ["id", "type", "tenantId", "timestamp"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique event ID. Enables dedup on the consumer side (at-least-once delivery)."
+    },
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Dotted event type (e.g. 'run.started', 'run.completed', 'guardrail.violated', 'fact.written', 'entity.deleted', 'tool.invoked', 'fix.proposed', 'approval.requested'). Convention: '<subject>.<past-tense-verb>'."
+    },
+    "tenantId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Tenant that owns this event. Cross-tenant delivery is denied by policy."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "actor": {
+      "type": "string",
+      "description": "Who emitted this event (agent id, tool id, subsystem name, user id)."
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The primary object the event is about.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "description": "Object kind (e.g. 'run', 'agent', 'fact', 'entity', 'tool', 'guardrail')."
+        },
+        "id": {
+          "type": "string"
+        }
+      }
+    },
+    "causedBy": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Zero or more IDs (event IDs or provenance node IDs) that caused this event. Extends the causal DAG across the reactive boundary — an agent that runs because of an event has provenance edges back through the event to its emitter."
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional additional scoping (project, thread, session). Interpreted by subscriptions."
+    },
+    "payload": {
+      "description": "Event-type-specific payload. Consumers must tolerate unknown fields for forward compatibility."
+    },
+    "attributes": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Non-structural annotations useful for filter predicates (e.g. severity, kind hints, feature flags)."
+    }
+  }
+}