@kindgi/specs 0.0.0-bootstrap.0 → 0.1.1

package/schemas/guardrail.schema.json

@@ -0,0 +1,261 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/guardrail.schema.json",
+  "$comment": "schema-version: 1.1.0",
+  "title": "Guardrail",
+  "description": "An assertion about agent behavior. Enforced at runtime (halt / retry / escalate / log-only / compensate per guardrail) AND in CI (blocks builds). Same definition, two enforcement paths — no drift between what tests check and what prod enforces. Zero-LLM checks are default (fast, deterministic); LLM-judge scorers are an opt-in class with explicit cost declaration. Schema-version 1.1.0 matches the `Guardrail` type: `check` is required, a `retry` action needs `maxAttempts`, `kind` and `on-violation` accept any non-empty string (the built-ins are listed as `examples`), and `sandbox` / `limits` / `network` / `needsSpec` are allowed.",
+  "type": "object",
+  "required": ["id", "kind", "check", "action"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique guardrail identifier."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name."
+    },
+    "description": {
+      "type": "string",
+      "description": "What this guardrail guarantees, and what happens if violated."
+    },
+    "kind": {
+      "type": "string",
+      "minLength": 1,
+      "examples": ["zero-llm", "llm-judge", "external"],
+      "description": "How the guardrail is checked. Open string: the engine dispatches it to the execution strategy registered for that kind, and `defineGuardrail` requires a registered check of the same kind. Built-in kinds: 'zero-llm' = pure function over run trace (default, fast, deterministic). 'llm-judge' = uses a model to score (opt-in, costs money). 'external' = evaluated outside the engine by a caller-registered strategy (the built-in 'external' strategy returns an error). Adapters can register strategies for their own kinds."
+    },
+    "check": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Id of the check in the CheckRegistry. For zero-llm: a built-in check ('must-cite', 'never-call-tool', 'max-tool-calls', 'output-matches', 'tool-order', 'required-substring', 'forbidden-substring') or a custom check id. For llm-judge: the id of a registered check of kind 'llm-judge' (the judge is configured by config and judgeCapabilities). For external and adapter kinds: an id the kind's strategy understands. Required since schema-version 1.1.0 (`defineGuardrail` already failed without a registered check)."
+    },
+    "config": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Check-specific configuration. Interpreted by the check implementation."
+    },
+    "action": {
+      "$ref": "#/$defs/Action"
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "warn", "error", "critical"],
+      "default": "error"
+    },
+    "scope": {
+      "$ref": "#/$defs/Scope",
+      "description": "When this guardrail applies: 'always' (every run), 'ci-only' (blocks CI, not runtime), 'runtime-only' (runtime enforcement, not CI), or a per-agent/per-flow selector."
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "For llm-judge guardrails: cost budget per invocation. Declarative — not enforced by the runtime.",
+      "properties": {
+        "maxCostUsd": {
+          "type": "number",
+          "minimum": 0
+        },
+        "maxLatencyMs": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "sandbox": {
+      "type": "string",
+      "enum": ["none", "context-isolated", "strict"],
+      "description": "Isolation posture the runtime enforces around the check's handler. Same values as a tool's `sandbox`. Added in schema-version 1.1.0."
+    },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Sandbox-enforced resource caps while the check runs. Same shape as a tool's `limits`. Added in schema-version 1.1.0.",
+      "properties": {
+        "memMB": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "cpuMs": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "required": ["memMB", "cpuMs"]
+    },
+    "network": {
+      "type": "object",
+      "description": "Network egress policy the sandbox honors while the check runs. Discriminated on `kind`; same shape as a tool's `network`. Added in schema-version 1.1.0.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["none", "unrestricted"]
+            }
+          },
+          "required": ["kind"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "allowlist"
+            },
+            "hosts": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "required": ["kind", "hosts"]
+        }
+      ]
+    },
+    "needsSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Typed discriminated needs of the check (env / secrets / config / capabilities / bindings). Same shape as a tool's `needsSpec`. Added in schema-version 1.1.0.",
+      "properties": {
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          }
+        },
+        "secrets": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          }
+        },
+        "config": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object"
+          }
+        },
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "bindings": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "codeArtifactRef": {
+      "description": "Handler-artifact pointer for the guardrail's check implementation. Discriminated on `kind`: `oci` is the deploy-pipeline shape (image + module path + artifactVersion); `filesystem` is the local-development shape — absolute host path at the check module. Production servers SHOULD reject `filesystem`.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "oci" },
+            "imageRef": { "type": "string", "minLength": 1 },
+            "modulePath": { "type": "string", "minLength": 1 },
+            "artifactVersion": { "type": "string", "minLength": 1 }
+          },
+          "required": ["kind", "imageRef", "modulePath", "artifactVersion"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "filesystem" },
+            "modulePath": { "type": "string", "minLength": 1 }
+          },
+          "required": ["kind", "modulePath"]
+        }
+      ]
+    },
+    "judgeCapabilities": {
+      "type": "object",
+      "description": "For llm-judge guardrails: capability declaration for the judge model. Routed through `@kindgi/capabilities` over the providers bound for evaluation; when the caller passes a tenant policy (an agent turn passes its own), the judge is routed under it. BYO judges supported.",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "Action": {
+      "type": "object",
+      "required": ["on-violation"],
+      "additionalProperties": false,
+      "properties": {
+        "on-violation": {
+          "type": "string",
+          "minLength": 1,
+          "examples": ["halt", "retry", "escalate", "log-only", "compensate"],
+          "description": "What happens when the guardrail fires. Open string: any non-empty name is accepted here, and an action handler registered under that name applies it; when the caller evaluates with an action-handler registry, a name with no handler fails with `unknown-action`. Built-in actions: 'halt' = fail the run. 'retry' = re-execute the step (needs `retry.maxAttempts`). 'escalate' = route to HITL review. 'log-only' = record but don't block. 'compensate' = invoke a compensation action."
+        },
+        "retry": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "For on-violation = 'retry'.",
+          "required": ["maxAttempts"],
+          "properties": {
+            "maxAttempts": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10
+            }
+          }
+        },
+        "escalateTo": {
+          "type": "string",
+          "description": "For on-violation = 'escalate': reviewer role or queue id."
+        },
+        "compensateWith": {
+          "type": "string",
+          "description": "For on-violation = 'compensate': tool id to invoke as compensation."
+        }
+      }
+    },
+    "Scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "when": {
+          "type": "string",
+          "enum": ["always", "ci-only", "runtime-only"],
+          "default": "always"
+        },
+        "agents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Agent ids this guardrail applies to. Empty = all agents."
+        },
+        "flows": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Flow ids this guardrail applies to. Empty = all flows."
+        },
+        "tenants": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Tenant ids this guardrail applies to. Empty = all tenants."
+        }
+      }
+    }
+  }
+}

package/schemas/memory.schema.json

@@ -0,0 +1,283 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/memory.schema.json",
+  "$comment": "schema-version: 1.3.0",
+  "title": "Memory — Log + Facts",
+  "description": "Two memory primitives: LogEntry (append-only event stream — turns, tool calls, tool results, agent internal messages) and Fact (typed, versioned records with declared retrieval hints). Views like message history, working memory, and semantic recall are queries over these two. Everything is tenant-scoped; scope is explicit and pluggable (tenant / user / org / project / thread / session). Log entries form a tamper-evident hash chain per (tenantId, runId) so any modification cascades — see LogEntry.prevHash / entryHash.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/LogEntry"
+    },
+    {
+      "$ref": "#/$defs/Fact"
+    }
+  ],
+  "$defs": {
+    "Scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tenantId"],
+      "description": "Every memory item is scoped. Reads and writes must present a scope; the policy engine denies out-of-scope operations at the boundary.",
+      "properties": {
+        "tenantId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "userId": {
+          "type": "string"
+        },
+        "orgId": {
+          "type": "string"
+        },
+        "projectId": {
+          "type": "string",
+          "description": "Project scope — whatever unit of work a pack organizes its memory around; the memory layer stays neutral about what it represents."
+        },
+        "threadId": {
+          "type": "string"
+        },
+        "sessionId": {
+          "type": "string"
+        }
+      }
+    },
+    "LogEntry": {
+      "type": "object",
+      "title": "LogEntry",
+      "description": "One event in the append-only log for a run/thread/session. Immutable once written. Ordered by (sequence, timestamp). Every entry commits to a hash of the previous entry in the same (tenantId, runId) — tamper with any past entry and every subsequent entry's prevHash breaks.",
+      "required": [
+        "id",
+        "kind",
+        "scope",
+        "timestamp",
+        "sequence",
+        "runId",
+        "prevHash",
+        "entryHash"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "user-message",
+            "agent-message",
+            "system-message",
+            "tool-call",
+            "tool-result",
+            "internal-thought",
+            "retrieval",
+            "artifact-produced",
+            "event-emitted",
+            "event-received",
+            "guardrail-triggered",
+            "wait-suspended",
+            "wait-resumed"
+          ]
+        },
+        "scope": {
+          "$ref": "#/$defs/Scope"
+        },
+        "runId": {
+          "type": "string",
+          "description": "Kernel run that produced this entry."
+        },
+        "actor": {
+          "type": "string",
+          "description": "Who produced this entry (user id, agent id, tool id, or 'system')."
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "sequence": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Monotonic sequence within (tenantId, runId). Enables deterministic replay ordering. Together with prevHash defines the tamper-evident chain within a run."
+        },
+        "payload": {
+          "description": "Kind-specific payload. Consumers must tolerate unknown fields."
+        },
+        "contentHash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "Optional SHA-256 of the payload alone (independent of the chain), useful for content-addressed dedup."
+        },
+        "prevHash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "SHA-256 of the previous LogEntry in the same (tenantId, runId) chain. The first entry (sequence=0) uses the zero-hash 'sha256:0000000000000000000000000000000000000000000000000000000000000000'. Added in schema-version 1.2.0."
+        },
+        "entryHash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "SHA-256 of this entry's canonical serialization (id + kind + scope + runId + actor + timestamp + sequence + payload + prevHash). Used as the prevHash of the next entry in the chain. Added in schema-version 1.2.0."
+        },
+        "causedByLogId": {
+          "type": "string",
+          "description": "Optional link to the log entry that caused this one. Feeds the provenance DAG directly."
+        }
+      }
+    },
+    "Fact": {
+      "type": "object",
+      "title": "Fact",
+      "description": "A typed, versioned record. Facts are the durable, retrievable memory. Two flavors are expressible via the same primitive: (A) immutable outputs the runtime wrote from an agent run — versioned by supersession, no freshness semantics; (B) cached views of external state — carry an optional `source` block describing where the ground truth lives and how to refresh. Views (working memory, semantic recall, cross-history search) are queries over facts. Retrieval strategy (which indexes populate for a given `type`) is declared by pack authors via a policy registry, not per-instance — see `RetrievalPolicyRegistry` in @kindgi/memory. Schema-version 1.3.0 removed the per-instance `retrieve` hint that used to live on this record.",
+      "required": ["id", "type", "scope", "version", "createdAt"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Fact type identifier. Vertical packs define their own; a few general-purpose names are conventional ('working-memory', 'user-profile', 'summary', 'entity-index')."
+        },
+        "scope": {
+          "$ref": "#/$defs/Scope"
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Monotonic version within (scope, id). New writes increment; old versions are retained until retention policy expires them."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "content": {
+          "description": "The fact payload — inline JSON. Optional since schema-version 1.1.0: if `contentRef` is set, the payload lives in blob storage and `content` may hold a summary or fingerprint for cheap retrieval-scoring. Rule of thumb: keep `content` ≤ ~64 KB inline; larger goes to blob."
+        },
+        "contentRef": {
+          "type": "string",
+          "description": "Optional (schema-version 1.1.0+): reference to a blob holding the actual bytes when they're too large to store inline. Format: 'blob://<provider>/<bucket>/<key>'. Consumers fetch it through the blob storage binding (`BlobStorageBinding.get()` in `@kindgi/blob-binding`)."
+        },
+        "contentHash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Optional (schema-version 1.1.0+): payload size in bytes. Populated by the writer; enables cheap size-based retrieval decisions without fetching the payload."
+        },
+        "embeddingModel": {
+          "type": "string",
+          "description": "For facts whose type-policy includes semantic indexing: the model used to embed. Enables re-indexing when the model changes."
+        },
+        "retention": {
+          "$ref": "#/$defs/Retention"
+        },
+        "source": {
+          "$ref": "#/$defs/Source",
+          "description": "Optional (schema-version 1.1.0+): present iff this fact is a cached view of external state (Kind B) rather than immutable runtime output (Kind A). Carries freshness metadata and a refresh strategy so readers can distinguish live-cached facts from historical facts."
+        },
+        "causedByLogId": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1,
+          "description": "Log entries that caused this fact write, in temporal order. Every fact traces back to at least one causal event. Multi-source facts (consolidation, extraction over many messages, cross-fact synthesis) list all source log ids; single-source facts list one. Widened from string → string[] in schema-version 1.2.0."
+        },
+        "supersedes": {
+          "type": "string",
+          "description": "The previous fact id/version this one supersedes."
+        }
+      }
+    },
+    "Source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "freshness", "refresh"],
+      "description": "External source of a Kind-B (cached-view) fact. Added in schema-version 1.1.0. Absent for Kind-A (immutable historical) facts.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["http-api", "blob", "mcp-tool", "external-db", "user-input"],
+          "description": "Where the source of truth lives. Opaque to the memory layer; the `refresh.handler` knows how to fetch from it."
+        },
+        "uri": {
+          "type": "string",
+          "description": "Optional locator interpreted per `kind` (URL, blob ref, MCP tool id + args, JDBC URI, etc.). May be absent when the handler resolves the source internally."
+        },
+        "freshness": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "How to tell if the cached fact is still current.",
+          "properties": {
+            "ttlSeconds": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Fact is considered stale after this many seconds past `lastVerifiedAt`."
+            },
+            "lastVerifiedAt": {
+              "type": "string",
+              "format": "date-time",
+              "description": "When the source was last confirmed to still match the cached value. Updated by refresh handlers."
+            },
+            "etag": {
+              "type": "string",
+              "description": "HTTP-style validator, if the source supports one. Refresh handlers use conditional GET semantics."
+            },
+            "sourceVersion": {
+              "type": "string",
+              "description": "Explicit source-side version identifier (e.g., document revision id, DB row transaction id). Present when the source is versioned."
+            }
+          }
+        },
+        "refresh": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["strategy"],
+          "description": "How the cached fact gets refreshed.",
+          "properties": {
+            "strategy": {
+              "type": "string",
+              "enum": ["on-read", "background", "manual"],
+              "description": "'on-read' = reader triggers a refresh check before returning stale results. 'background' = a scheduled kernel run walks stale facts and refreshes. 'manual' = only refresh when explicitly invoked."
+            },
+            "handler": {
+              "type": "string",
+              "description": "Tool id, agent id, or flow id that performs the refresh. Invoked by the kernel per the chosen strategy."
+            },
+            "priority": {
+              "type": "integer",
+              "description": "Higher = refresh first when a background sweep dispatches many at once."
+            }
+          }
+        }
+      }
+    },
+    "Retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Fact-level retention override. Tenant policy sets defaults.",
+      "properties": {
+        "keepUntil": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "keepDays": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "legalHold": {
+          "type": "boolean",
+          "description": "If true, retention rules cannot delete this fact. Requires explicit release via admin action."
+        }
+      }
+    }
+  }
+}