diff --git a/docs/control-plane/README.md b/docs/control-plane/README.md new file mode 100644 index 0000000..6e3d163 --- /dev/null +++ b/docs/control-plane/README.md @@ -0,0 +1,25 @@ +# Control-Plane Contracts (MeshSkill / Validation Lifecycle) + +This directory is the intended canonical home for the typed control-plane contract surface that was previously published in the umbrella public-surface repo. + +## What lives here + +- architecture and doctrine for agent validation control planes +- MeshSkill descriptor specification +- skill execution lifecycle specification +- machine-readable control-plane schemas +- starter policy pack and examples + +## Why this is here + +`sourceos-spec` is the canonical typed-contract and vocabulary lane for the SourceOS / AgentOS topology. The control-plane package belongs here as contract material, even if public-facing documentation or downstream examples continue to exist elsewhere. + +## Current caveat + +This first import preserves the existing schema IDs and content shape from the previously published package so we do not silently change identifiers during the re-home. A follow-on revision should decide whether those `$id` values should remain stable for compatibility or be normalized into the SourceOS / SourceOS-Linux namespace. + +## Adjacent repos + +- `SociOS-Linux/agentos-spine` should treat these files as the canonical contract surface for Linux-side integration. +- `SocioProphet/sociosphere` may reference or consume these contracts at the platform workspace-controller layer. +- `SocioProphet/socioprophet` and `SociOS-Linux/socioslinux-web` may explain these contracts downstream, but should not be treated as the canonical source of truth. diff --git a/docs/control-plane/agent-validation-control-plane.md b/docs/control-plane/agent-validation-control-plane.md new file mode 100644 index 0000000..ab730e2 --- /dev/null +++ b/docs/control-plane/agent-validation-control-plane.md @@ -0,0 +1,179 @@ +# Agent Validation Control Plane + +Status: draft v0.1 + +## Purpose + +This document defines the control-plane architecture for deterministic agent validation in the SocioProphet mesh. The problem is not that agents can generate patches, plans, prompts, or commands. The problem is that most systems still treat validation as an afterthought, leaving agents with broad proposal power but weak, inconsistent, or non-repeatable pathways to trustworthy evidence. + +Our position is simple: + +- agents are strongest as planners, scouts, and proposers; +- skills are the deterministic hands that execute bounded work; +- the control plane is the constitution that governs admission, execution, evidence, and promotion. + +The system therefore separates soft-lane activity from hard-lane activity. Soft-lane activity may search, infer, rank, summarize, draft, and propose. Hard-lane activity may only execute through typed, policy-governed, replayable, evidence-producing skills. + +## Why a validation control plane exists + +Most agent stacks collapse four distinct concerns into one mushy runtime surface: + +1. tool invocation; +2. validation; +3. approval; +4. commitment. + +We reject that collapse. + +Tool use is not validation. Validation is not approval. Approval is not commitment. Commitment is not truth. Those boundaries must remain explicit if the mesh is to remain auditable, secure, and useful under real operational pressure. + +The validation control plane exists to preserve those boundaries while still enabling high-throughput agentic work. + +## Core model + +The control plane operates around six first-class objects: + +1. **MeshSkill**: a versioned, typed, policy-bound capability descriptor. +2. **Action**: an atomic executable primitive with declared side effects and evidence outputs. +3. **Plan**: an ordered or conditional composition of actions. +4. **Coordinates**: typed execution selectors such as environment, topology scope, trust class, tenant scope, frontier limits, and data sensitivity. +5. **Evidence Bundle**: the attributed result set emitted by a run. +6. **Cairn**: a deterministic checkpoint carrying cryptographic commitments before and after execution. + +This replaces generic "tools" and vague "tags" with a model that is schedulable, governable, queryable, and replayable. + +## Design principles + +### 1. Evidence first + +No run is considered useful merely because it returned `success=true`. A run is useful only when it emits evidence that can support a claim, reject a claim, or justify the next decision. + +### 2. Typed coordinates, not free-form labels + +Execution context must be explicit and machine-checkable. A skill admitted for `env=preview` and `frontier_hops=2` is not implicitly admitted for production or for wider topological reach. + +### 3. Replayability is mandatory + +Every materially important hard-lane execution must be bound to before/after cairns, trace identifiers, and an event trail sufficient for replay and forensic review. + +### 4. Human authority remains explicit + +High-consequence operations, irreversible side effects, and policy exceptions require human approval. The control plane does not erase accountability; it makes accountability enforceable. + +### 5. Bounded side effects + +A skill descriptor must state what side effects are possible. If the side-effect class is undeclared, the skill is not admitted to the hard lane. + +### 6. Mesh portability + +Execution should not depend on a single host or product-local runtime. Skills are transported and invoked through typed envelopes over TriTRPC so they can operate across local nodes, clusters, and federated mesh participants. + +## Major components + +### Skill Registry + +The registry stores versioned MeshSkill descriptors, action definitions, plan references, policy bindings, evidence requirements, and publication trust state. Registry entries should be Merkle-addressable and signable so that a resolver can prove exactly what was admitted. + +### Skill Planner and Resolver + +The planner maps a proposed change or question into one or more required validation skills. The resolver narrows admissible execution based on policy, available coordinates, user or tenant scope, environment, and trust boundaries. + +### Shadow Cell Orchestrator + +A shadow cell is a topologically faithful validation cell. It may mirror a single service, a workflow slice, a cluster subsystem, or a bounded data path. The orchestrator materializes the cell, binds the plan, injects test or replay inputs, enforces frontier caps, and records the initial cairn. + +### Skill Runtime Broker + +The broker executes actions and plans through typed TriTRPC envelopes. It provides admission control, scheduling, idempotence, retries within policy, tracing, and artifact collection. + +### Evidence Bridge + +The evidence bridge normalizes outputs into structured evidence bundles, emits events to the event fabric, and maps results into the claim store and truth-maintenance lane. + +### Approval Gate + +The approval gate evaluates policy decisions, risk classes, environment sensitivity, and human-approval requirements before promotion or commitment occurs. + +### Skill Explorer + +The explorer exposes run history, evidence bundles, policy decisions, topology diffs, replayable cairns, and promotion outcomes. It is not just an activity feed. It is the operator-facing explanation layer for the hard lane. + +## Trust boundaries + +The architecture enforces at least five trust boundaries: + +1. **proposal boundary** between soft-lane suggestion and hard-lane admission; +2. **execution boundary** between allowed coordinates and prohibited reach; +3. **data boundary** between redacted/test data and sensitive/live data; +4. **approval boundary** between policy pass and side-effect authorization; +5. **truth boundary** between observed run output and promoted claim state. + +Each boundary should emit explicit events and denial reasons. + +## Shadow cells + +A shadow cell is not merely a temporary sandbox. It is a bounded validation environment with enough fidelity to produce operationally relevant evidence. A shadow cell may support: + +- dependency pinning; +- synthetic or redacted data feeds; +- differential traffic replay; +- contract checking; +- SLO or regression comparison; +- fault injection; +- constrained write prohibitions; +- environment-specific policy overlays. + +Shadow cells are a control-plane primitive because they turn validation into a governed workload rather than an improvised script. + +## Evidence bundles + +An evidence bundle is the minimum durable product of a skill run. Typical contents include: + +- logs; +- traces; +- metrics; +- config diffs; +- dependency diffs; +- topology diffs; +- policy decisions; +- before and after cairns; +- verdicts and derived risk signals. + +Evidence bundles are stored as artifacts and referenced from events and claims. They are not transient console output. + +## Hard-lane lifecycle summary + +1. An agent or human proposes work. +2. The planner determines required skills. +3. The resolver binds admissible coordinates. +4. Policy admission decides whether the run may start. +5. The orchestrator materializes the shadow cell. +6. The runtime executes the plan through TriTRPC actions. +7. Evidence is collected and normalized. +8. Policy evaluates promotion and approval requirements. +9. Claims are promoted, rejected, or left candidate. +10. Commit-class skills may proceed only after required approval. + +The formal lifecycle is specified in `docs/control-plane/skill-execution-lifecycle-v0.1.md`. + +## Relationship to existing concepts + +### Hard lane / soft lane + +Mesh skills are a hard-lane execution substrate. They exist precisely so that soft-lane output does not become de facto authority. + +### Capability descriptors + +A MeshSkill can be implemented as a specialized capability descriptor or a capability-descriptor profile for deterministic validation and bounded commitment. + +### Cairns + +Cairns are mandatory at state transition boundaries. They provide replayable checkpoints and cryptographic commitments for forensic review and divergence analysis. + +### TriTRPC + +TriTRPC is the transport fabric for skill invocation, evidence handoff, and planner-runtime coordination. The transport does not by itself make a skill safe; the control-plane contract does. + +### Truth maintenance + +Validation outputs become decision-grade only when linked into the claim store with provenance, status transitions, and dependency-aware justification. diff --git a/docs/control-plane/mesh-skill-descriptor-v0.1.md b/docs/control-plane/mesh-skill-descriptor-v0.1.md new file mode 100644 index 0000000..89b8ec3 --- /dev/null +++ b/docs/control-plane/mesh-skill-descriptor-v0.1.md @@ -0,0 +1,144 @@ +# MeshSkill Descriptor Specification v0.1 + +Status: draft + +## 1. Scope + +This specification defines the `MeshSkill` descriptor used by the validation and control plane. A MeshSkill is a typed, versioned, policy-bound capability object for hard-lane execution. It exists to make validation, simulation, replay, verification, and bounded commitment explicit, schedulable, and replayable. + +This document is normative unless marked otherwise. + +## 2. Goals + +The descriptor MUST: + +- make execution intent explicit; +- bind execution to typed coordinates; +- declare action composition or plan references; +- declare inputs, outputs, and side-effect class; +- define evidence obligations; +- support policy admission and approval gating; +- support deterministic replay and auditing. + +The descriptor SHOULD: + +- be signable and Merkle-addressable; +- be compatible with capability-descriptor registries; +- support cross-node and cross-cluster execution via TriTRPC; +- remain transport-neutral above the action envelope layer. + +The descriptor MUST NOT: + +- grant implicit authority outside declared coordinates; +- hide side effects behind untyped plugins; +- permit promotion without evidence; +- treat success/failure flags as sufficient evidence. + +## 3. Object shape + +A MeshSkill is a resource with `metadata` and `spec` sections. + +### 3.1 Metadata + +`metadata.id` is the canonical skill identifier. It SHOULD follow the braided naming model used across registries. + +`metadata.merkle_root` is the content commitment for the descriptor and referenced in-registry normalization rules. + +`metadata.signer` identifies the entity that signed or published the descriptor. + +Additional metadata MAY include ownership, publication scope, lifecycle state, and lineage. + +### 3.2 Spec + +The `spec` section defines execution semantics. + +Required fields: + +- `lane` +- `class` +- `coordinates` +- `actions` or `plan` +- `inputs` +- `outputs` +- `evidence` + +Optional but strongly recommended fields: + +- `policy` +- `side_effects` +- `risk` +- `attestation` +- `timeouts` +- `budgets` + +## 4. Lane + +`spec.lane` identifies the execution lane. + +Allowed values in v0.1: + +- `hard` + +Future values may exist for descriptive compatibility, but a MeshSkill governed by this specification is intended for hard-lane execution. Soft-lane operations are not represented as MeshSkill execution rights. + +## 5. Skill classes + +`spec.class` MUST be one of: + +- `read` +- `replay` +- `simulate` +- `verify` +- `commit` + +## 6. Coordinates + +`spec.coordinates` binds where and under what trust conditions a skill may execute. Coordinates MUST be machine-checkable. + +Recommended fields in v0.1: + +- `env` +- `topology_scope` +- `trust_class` +- `tenant_scope` +- `frontier_hops` +- `data_sensitivity` + +## 7. Actions and plans + +A MeshSkill MUST define either ordered `actions` or a `plan` reference / embedded plan object. + +## 8. Inputs and outputs + +`spec.inputs` defines required external materials or references. + +`spec.outputs` defines the durable outputs expected from successful execution. + +## 9. Evidence obligations + +`spec.evidence.require` lists evidence artifacts that MUST exist for the run to satisfy the descriptor. + +## 10. Policy section + +`spec.policy` declares local constraints and default execution rules. Platform policy overlays MAY narrow execution further but MUST NOT broaden execution beyond what the descriptor declares. + +## 11. Side effects + +A descriptor SHOULD declare intended side-effect class explicitly. + +## 12. Risk and approval + +Commit-class skills SHOULD include stricter approval and evidence requirements. + +## 13. Invariants + +1. A MeshSkill MUST have an identifier. +2. A MeshSkill MUST declare a class. +3. A MeshSkill MUST bind coordinates. +4. A MeshSkill MUST define actions or plan. +5. A MeshSkill MUST define inputs and outputs. +6. A MeshSkill MUST define required evidence. +7. A MeshSkill MUST be rejected if requested execution exceeds declared coordinates. +8. A MeshSkill MUST NOT promote claims without required evidence. +9. A commit-class MeshSkill MUST NOT execute without satisfying approval policy. +10. Every admitted run MUST be traceable through events and cairn references. diff --git a/docs/control-plane/skill-execution-lifecycle-v0.1.md b/docs/control-plane/skill-execution-lifecycle-v0.1.md new file mode 100644 index 0000000..78ab3fd --- /dev/null +++ b/docs/control-plane/skill-execution-lifecycle-v0.1.md @@ -0,0 +1,99 @@ +# Skill Execution Lifecycle v0.1 + +Status: draft + +## 1. Scope + +This specification defines the end-to-end lifecycle for hard-lane MeshSkill execution in the control plane. It covers admission, orchestration, execution, evidence production, policy evaluation, truth-state impact, and commit gating. + +The lifecycle exists so that agent-driven work remains bounded, attributable, and replayable. + +## 2. Terms + +- **proposal**: a candidate action, patch, investigation, or change request produced by a human or agent. +- **admission**: policy-governed authorization to start a skill run. +- **shadow cell**: a bounded validation environment with topological fidelity. +- **evidence bundle**: the durable artifact set emitted by a run. +- **promotion**: a status transition in the claim store based on policy and evidence. +- **commit**: an allowed side effect that changes external or durable state. +- **cairn**: a cryptographically committed checkpoint before or after a materially relevant transition. + +## 3. Lifecycle states + +A run SHOULD move through: `proposed`, `planned`, `resolved`, `admitted`, `materialized`, `running`, `evidence_collected`, `evaluated`, `approved|denied`, `promoted|rejected|committed`, `archived`. + +## 4. End-to-end flow + +1. Proposal +2. Planning +3. Resolution +4. Admission +5. Materialization +6. Execution +7. Evidence collection +8. Evaluation +9. Approval +10. Promotion and commit +11. Archival + +## 5. Idempotence and retries + +Retries MUST remain within declared policy and idempotency constraints. Commit-class retries MUST be conservative and SHOULD require explicit idempotency proof or human review. + +## 6. Failure handling + +Failure is evidence. The lifecycle MUST preserve failures as first-class outputs rather than merely log noise. + +## 7. Truth-maintenance integration + +A run result is not truth merely because it exists. Promotion requires provenance, evidence completeness, and satisfied policy. + +## 8. Minimum artifacts per run + +Every archived run MUST retain or reference: + +- run identifier +- actor identity +- descriptor identifier and version +- resolved coordinates +- event trail +- evidence bundle +- policy decision +- approval record if applicable +- `cairn_before` and `cairn_after` when stateful execution occurred + +## 9. Event set + +The recommended event set for v0.1 includes: + +- `skill.requested` +- `skill.planned` +- `skill.resolved` +- `skill.admitted` +- `skill.materialized` +- `skill.started` +- `action.started` +- `action.completed` +- `action.failed` +- `evidence.attached` +- `skill.evaluated` +- `policy.denied` +- `approval.requested` +- `approval.granted` +- `approval.denied` +- `claim.promoted` +- `claim.rejected` +- `claim.retracted` +- `commit.approved` +- `commit.executed` +- `commit.denied` +- `skill.archived` + +## 10. Security invariants + +1. No run may start without resolved coordinates. +2. No run may exceed descriptor-declared coordinate bounds. +3. No validated promotion may occur without required evidence. +4. No commit may occur without satisfying required approval policy. +5. Every state transition of consequence must be attributable. +6. Every materially stateful run must be replayable through cairn references and event lineage. diff --git a/examples/control-plane/mesh-skill.checkout-validate.yaml b/examples/control-plane/mesh-skill.checkout-validate.yaml new file mode 100644 index 0000000..54e769b --- /dev/null +++ b/examples/control-plane/mesh-skill.checkout-validate.yaml @@ -0,0 +1,60 @@ +apiVersion: control.socioprophet.org/v1alpha1 +kind: MeshSkill +metadata: + id: sp.control.checkout-validate@e23.proc7-3.draft+l0 + merkle_root: sha256:REPLACE_ME + signer: mesh-registry + owner: team-checkout + publication_scope: internal +spec: + lane: hard + class: verify + coordinates: + env: preview + topology_scope: service.checkout + trust_class: internal + tenant_scope: default + frontier_hops: 2 + data_sensitivity: redacted + actions: + - build_artifact + - deploy_shadow_cell + - replay_traffic_window + - run_contract_checks + - compare_slo_regressions + - emit_evidence_bundle + plan: + ref: cairn://plans/checkout-validate/v3 + deterministic: true + timeout_s: 900 + max_cost_units: 250 + idempotency_key_strategy: sha256(patch_ref,dependency_lock,traffic_window) + inputs: + - patch_ref + - dependency_lock + - traffic_window + outputs: + - verdict + - evidence_bundle_ref + - promoted_claim_refs + policy: + allow_autoapprove_below_risk: 30 + deny: + - live_prod_write + - pii_export + - frontier_hops_gt_2 + require_human_approval_for: + - prod + - commit + evidence: + require: + - logs + - traces + - metrics + - config_diff + - dependency_diff + - policy_decision + - cairn_before + - cairn_after + side_effects: ephemeral_internal + risk: 18 diff --git a/examples/control-plane/skill.evidence.attached.sample.json b/examples/control-plane/skill.evidence.attached.sample.json new file mode 100644 index 0000000..535c09a --- /dev/null +++ b/examples/control-plane/skill.evidence.attached.sample.json @@ -0,0 +1,35 @@ +{ + "event_id": "evt_01JQ2Y7M8AQ4J6K8F7M8Q1P4ZX", + "event_name": "evidence.attached", + "occurred_at": "2026-03-25T20:40:00Z", + "actor": { + "kind": "service", + "id": "skill-runtime-broker" + }, + "run": { + "run_id": "run_01JQ2Y7H7F4Y2A8C9R1S3T6U9V", + "skill_id": "sp.control.checkout-validate@e23.proc7-3.draft+l0", + "trace_id": "trace_2db0e8e8a58e4e5bb5f6b6d6d8ef1d90", + "span_id": "span_3f89d7018d9d4c76", + "attempt": 1 + }, + "coordinates": { + "env": "preview", + "topology_scope": "service.checkout", + "trust_class": "internal", + "tenant_scope": "default", + "frontier_hops": 2, + "data_sensitivity": "redacted" + }, + "status": "running", + "refs": { + "proposal_ref": "claim://candidate/checkout-patch-001", + "evidence_bundle_ref": "artifact://evidence/run_01JQ2Y7H7F4Y2A8C9R1S3T6U9V", + "cairn_before_ref": "cairn://checkout/preview/before/01JQ2Y6ZK7D", + "parent_run_id": "run_01JQ2Y6Q5B1X9N3L2W4E6R8T0Y" + }, + "payload": { + "artifacts": ["logs", "traces", "metrics", "config_diff", "dependency_diff", "policy_decision", "cairn_before"], + "verdict_pending": true + } +} diff --git a/policies/skills/default-policy-pack.rego b/policies/skills/default-policy-pack.rego new file mode 100644 index 0000000..5364177 --- /dev/null +++ b/policies/skills/default-policy-pack.rego @@ -0,0 +1,60 @@ +package skills.default + +default allow = false + +risk_threshold := 30 + +allow { + count(deny) == 0 +} + +autoapprove { + count(deny) == 0 + input.skill.spec.class != "commit" + input.risk.score <= risk_threshold +} + +deny[msg] { + input.skill.spec.class == "commit" + not input.approval.human_approved + msg := "human approval required for commit class" +} + +deny[msg] { + input.request.coordinates.frontier_hops > input.skill.spec.coordinates.frontier_hops + msg := sprintf("requested frontier_hops %v exceeds declared limit %v", [input.request.coordinates.frontier_hops, input.skill.spec.coordinates.frontier_hops]) +} + +deny[msg] { + contains_value(input.skill.spec.policy.deny, "live_prod_write") + input.request.intent.write_live_prod == true + msg := "live prod write forbidden by descriptor" +} + +deny[msg] { + contains_value(input.skill.spec.policy.deny, "pii_export") + input.request.intent.export_pii == true + msg := "pii export forbidden by descriptor" +} + +deny[msg] { + required := input.skill.spec.evidence.require[_] + not present_evidence[required] + msg := sprintf("missing required evidence: %s", [required]) +} + +deny[msg] { + input.request.coordinates.env == "prod" + input.skill.spec.class != "read" + not input.approval.human_approved + msg := "non-read production execution requires human approval" +} + +present_evidence[e] { + input.run.evidence_present[_] == e +} + +contains_value(xs, v) { + some i + xs[i] == v +} diff --git a/schemas/control-plane/mesh-skill.schema.json b/schemas/control-plane/mesh-skill.schema.json new file mode 100644 index 0000000..1870c73 --- /dev/null +++ b/schemas/control-plane/mesh-skill.schema.json @@ -0,0 +1,109 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://socioprophet.org/schemas/control-plane/mesh-skill.schema.json", + "title": "MeshSkill", + "type": "object", + "additionalProperties": false, + "required": ["apiVersion", "kind", "metadata", "spec"], + "properties": { + "apiVersion": { "const": "control.socioprophet.org/v1alpha1" }, + "kind": { "const": "MeshSkill" }, + "metadata": { + "type": "object", + "additionalProperties": true, + "required": ["id", "merkle_root", "signer"], + "properties": { + "id": { "type": "string", "minLength": 1 }, + "merkle_root": { "type": "string", "pattern": "^sha256:[A-Za-z0-9]+$" }, + "signer": { "type": "string", "minLength": 1 } + } + }, + "spec": { + "type": "object", + "additionalProperties": false, + "required": ["lane", "class", "coordinates", "inputs", "outputs", "evidence"], + "properties": { + "lane": { "const": "hard" }, + "class": { "type": "string", "enum": ["read", "replay", "simulate", "verify", "commit"] }, + "coordinates": { + "type": "object", + "additionalProperties": true, + "required": ["env", "topology_scope", "trust_class", "tenant_scope", "frontier_hops", "data_sensitivity"], + "properties": { + "env": { "type": "string", "minLength": 1 }, + "topology_scope": { "type": "string", "minLength": 1 }, + "trust_class": { "type": "string", "minLength": 1 }, + "tenant_scope": { "type": "string", "minLength": 1 }, + "frontier_hops": { "type": "integer", "minimum": 0 }, + "data_sensitivity": { "type": "string", "minLength": 1 } + } + }, + "actions": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "minItems": 1, + "uniqueItems": true + }, + "plan": { + "type": "object", + "additionalProperties": true, + "properties": { + "ref": { "type": "string", "minLength": 1 }, + "deterministic": { "type": "boolean" }, + "timeout_s": { "type": "integer", "minimum": 1 }, + "max_cost_units": { "type": "integer", "minimum": 0 }, + "idempotency_key_strategy": { "type": "string" } + } + }, + "inputs": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "minItems": 1, + "uniqueItems": true + }, + "outputs": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "minItems": 1, + "uniqueItems": true + }, + "policy": { + "type": "object", + "additionalProperties": true, + "properties": { + "allow_autoapprove_below_risk": { "type": "integer", "minimum": 0, "maximum": 100 }, + "deny": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "uniqueItems": true + }, + "require_human_approval_for": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "uniqueItems": true + } + } + }, + "evidence": { + "type": "object", + "additionalProperties": true, + "required": ["require"], + "properties": { + "require": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "minItems": 1, + "uniqueItems": true + } + } + }, + "side_effects": { + "type": "string", + "enum": ["none", "ephemeral_internal", "artifact_write", "topology_mutation", "external_commit"] + }, + "risk": { "type": "integer", "minimum": 0, "maximum": 100 } + }, + "anyOf": [{ "required": ["actions"] }, { "required": ["plan"] }] + } + } +} diff --git a/schemas/control-plane/skill-execution-events.schema.json b/schemas/control-plane/skill-execution-events.schema.json new file mode 100644 index 0000000..f0fbaaf --- /dev/null +++ b/schemas/control-plane/skill-execution-events.schema.json @@ -0,0 +1,51 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://socioprophet.org/schemas/events/skill-execution-events.schema.json", + "title": "SkillExecutionEvent", + "type": "object", + "additionalProperties": false, + "required": ["event_id", "event_name", "occurred_at", "actor", "run", "status"], + "properties": { + "event_id": { "type": "string", "minLength": 1 }, + "event_name": { + "type": "string", + "enum": [ + "skill.requested", "skill.planned", "skill.resolved", "skill.admitted", + "skill.materialized", "skill.started", "action.started", "action.completed", + "action.failed", "evidence.attached", "skill.evaluated", "policy.denied", + "approval.requested", "approval.granted", "approval.denied", "claim.promoted", + "claim.rejected", "claim.retracted", "commit.approved", "commit.executed", + "commit.denied", "skill.archived" + ] + }, + "occurred_at": { "type": "string", "format": "date-time" }, + "actor": { + "type": "object", + "additionalProperties": true, + "required": ["kind", "id"], + "properties": { + "kind": { "type": "string", "enum": ["human", "agent", "service", "scheduler"] }, + "id": { "type": "string", "minLength": 1 } + } + }, + "run": { + "type": "object", + "additionalProperties": true, + "required": ["run_id", "skill_id"], + "properties": { + "run_id": { "type": "string", "minLength": 1 }, + "skill_id": { "type": "string", "minLength": 1 }, + "trace_id": { "type": "string" }, + "span_id": { "type": "string" }, + "attempt": { "type": "integer", "minimum": 1 } + } + }, + "coordinates": { "type": "object", "additionalProperties": true }, + "status": { + "type": "string", + "enum": ["requested", "planned", "resolved", "admitted", "materialized", "running", "succeeded", "failed", "denied", "approved", "promoted", "rejected", "committed", "archived"] + }, + "refs": { "type": "object", "additionalProperties": true }, + "payload": { "type": "object", "additionalProperties": true } + } +}