Creasura Agentic OS Protocol · v0.1

JSON Schema

Every CAOP v0.1 object as JSON Schema 2020-12: the five abstractions, the lifecycle API payloads, the Capability API, events, errors, and the Business Profile.

On this page

Overview
Shared
PrincipalRef
EntityRef
EvidenceRef
ArtifactRef
Expression
Criterion
Constraint
AuthorizationPolicy
Abstractions
Goal
WorkItem
Fact
Capability
Policy
Capability API
CapabilityDescriptor
CapabilityInvocation
CapabilityResult
Lifecycle API
ExecutionState
ObservationCreate
ObservationAccepted
ContextResolveRequest
ContextBundle
CommitmentCreate
Commitment
CommitmentList
PlanCreate
Plan
ExecutionCreate
ExecutionAccepted
Execution
TransitionRequest
Transition
ResultSubmission
VerificationRequest
Verification
RecordCommit
RecordCommitted
ReviewRequest
Review
ApprovalDecision
Approval
Events and errors
EventEnvelope
Error
Business Profile
MetricNode
ApprovalRoutingRule

Overview

Every CAOP v0.1 object as JSON Schema 2020-12, in one bundle with $defs: 44 definitions. The OpenAPI contract uses the same definitions.

Download caop-v0.1.schema.json

$id https://creasura.com/spec/caop-v0.1.schema.jsonDialect 2020-12

Domain objects (Goal, WorkItem, Fact, Capability, Policy, and the Capability API) use camelCase, as in the specification’s interfaces. Lifecycle API payloads use snake_case, as on the wire.

Shared

PrincipalRef

An authenticated principal: a person, a role, an agent, or a service account.

Field	Type	Notes
`type`required	`user` \| `role` \| `agent` \| `service`
`id`required	string

Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "user",
        "role",
        "agent",
        "service"
      ]
    },
    "id": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "type",
    "id"
  ],
  "description": "An authenticated principal: a person, a role, an agent, or a service account."
}

EntityRef

Identifier of any entity known to the OS, e.g. "property/14-oak-lane".

Type string

Schema

{
  "type": "string",
  "description": "Identifier of any entity known to the OS, e.g. \"property/14-oak-lane\"."
}

EvidenceRef

Identifier of a piece of evidence (an artifact, observation, or record) that supports a fact or outcome.

Type string

Schema

{
  "type": "string",
  "description": "Identifier of a piece of evidence (an artifact, observation, or record) that supports a fact or outcome."
}

ArtifactRef

Identifier of a stored artifact such as a document or report.

Type string

Schema

{
  "type": "string",
  "description": "Identifier of a stored artifact such as a document or report."
}

Expression

A condition evaluated by the policy engine, e.g. "recipient.type == 'client'".

Type string

Schema

{
  "type": "string",
  "description": "A condition evaluated by the policy engine, e.g. \"recipient.type == 'client'\"."
}

Criterion

A success criterion. "type" selects the evaluator; other members are evaluator-specific.

Field	Type	Notes
`type`required	string

Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "type"
  ],
  "description": "A success criterion. \"type\" selects the evaluator; other members are evaluator-specific."
}

Constraint

A constraint on how a goal may be pursued.

Field	Type	Notes
`type`required	string

Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "type"
  ],
  "description": "A constraint on how a goal may be pursued."
}

AuthorizationPolicy

What a caller must hold to invoke a capability.

Field	Type	Notes
`requiredScopes`	array of string
`policyIds`	array of string

Schema

{
  "type": "object",
  "properties": {
    "requiredScopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "policyIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false,
  "description": "What a caller must hold to invoke a capability."
}

Abstractions

Goal

A desired outcome that persists beyond a single conversation.

Field	Type	Notes
`id`required	string
`objective`required	string
`owner`required	PrincipalRef
`successCriteria`required	array of Criterion
`constraints`required	array of Constraint
`status`required	`active` \| `paused` \| `achieved` \| `abandoned`
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "objective": {
      "type": "string"
    },
    "owner": {
      "$ref": "#/$defs/PrincipalRef"
    },
    "successCriteria": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Criterion"
      }
    },
    "constraints": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Constraint"
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "achieved",
        "abandoned"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "objective",
    "owner",
    "successCriteria",
    "constraints",
    "status",
    "createdAt",
    "updatedAt"
  ],
  "description": "A desired outcome that persists beyond a single conversation."
}

WorkItem

A bounded unit of execution that advances a goal.

Field	Type	Notes
`id`required	string
`goalId`required	string
`description`required	string
`dependencies`required	array of string
`status`required	`pending` \| `ready` \| `running` \| `blocked` \| `completed` \| `failed` \| `cancelled`
`assignedCapability`	string
`result`	ArtifactRef
`deadline`	string (date-time)

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "goalId": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "dependencies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "ready",
        "running",
        "blocked",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "assignedCapability": {
      "type": "string"
    },
    "result": {
      "$ref": "#/$defs/ArtifactRef"
    },
    "deadline": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "goalId",
    "description",
    "dependencies",
    "status"
  ],
  "description": "A bounded unit of execution that advances a goal."
}

Fact

A durable, provenance-bearing statement in the OS state. Every material fact has a traceable source.

Field	Type	Notes
`id`required	string
`subject`required	EntityRef
`predicate`required	string
`object`required	any
`source`required	EvidenceRef
`observedAt`required	string (date-time)
`validFrom`	string (date-time)
`validTo`	string (date-time)
`confidence`	number

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "subject": {
      "$ref": "#/$defs/EntityRef"
    },
    "predicate": {
      "type": "string"
    },
    "object": {},
    "source": {
      "$ref": "#/$defs/EvidenceRef"
    },
    "observedAt": {
      "type": "string",
      "format": "date-time"
    },
    "validFrom": {
      "type": "string",
      "format": "date-time"
    },
    "validTo": {
      "type": "string",
      "format": "date-time"
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "subject",
    "predicate",
    "object",
    "source",
    "observedAt"
  ],
  "description": "A durable, provenance-bearing statement in the OS state. Every material fact has a traceable source."
}

Example

{
  "id": "fact_88",
  "subject": "property/14-oak-lane",
  "predicate": "appraised_value",
  "object": 641000,
  "source": "evidence/appraisal-report",
  "observedAt": "2026-11-24T15:10:00Z",
  "confidence": 1.0
}

Capability

Something the OS can invoke to perform work.

Field	Type	Notes
`id`required	string
`operations`required	array of string
`inputSchema`required	object
`outputSchema`required	object
`authorization`required	AuthorizationPolicy
`executionMode`required	`interactive` \| `background` \| `scheduled`
`provider`required	string

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "operations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "inputSchema": {
      "type": "object"
    },
    "outputSchema": {
      "type": "object"
    },
    "authorization": {
      "$ref": "#/$defs/AuthorizationPolicy"
    },
    "executionMode": {
      "type": "string",
      "enum": [
        "interactive",
        "background",
        "scheduled"
      ]
    },
    "provider": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "operations",
    "inputSchema",
    "outputSchema",
    "authorization",
    "executionMode",
    "provider"
  ],
  "description": "Something the OS can invoke to perform work."
}

Policy

A constraint governing execution.

Field	Type	Notes
`id`required	string
`scope`required	string
`condition`required	Expression
`effect`required	`allow` \| `deny` \| `require_approval`
`version`required	string
`enforcement`required	`advisory` \| `enforced`	Advisory policies are instructions to a model. Enforced policies are checked by the runtime before an action executes.

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "scope": {
      "type": "string"
    },
    "condition": {
      "$ref": "#/$defs/Expression"
    },
    "effect": {
      "type": "string",
      "enum": [
        "allow",
        "deny",
        "require_approval"
      ]
    },
    "version": {
      "type": "string"
    },
    "enforcement": {
      "type": "string",
      "enum": [
        "advisory",
        "enforced"
      ],
      "description": "Advisory policies are instructions to a model. Enforced policies are checked by the runtime before an action executes."
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "scope",
    "condition",
    "effect",
    "version",
    "enforcement"
  ],
  "description": "A constraint governing execution."
}

Example

{
  "id": "policy_client_email_approval",
  "scope": "capability:email.send",
  "condition": "recipient.type == 'client'",
  "effect": "require_approval",
  "version": "3",
  "enforcement": "enforced"
}

Capability API

CapabilityDescriptor

What an execution provider can do, independent of any one AI vendor.

Field	Type	Notes
`id`required	string
`provider`required	string
`operations`required	array of string
`inputSchema`required	object
`outputSchema`required	object
`supportsAsync`required	boolean
`supportsResume`required	boolean
`supportsCancellation`required	boolean
`authorizationRequired`required	boolean
`sideEffectLevel`required	`none` \| `reversible` \| `irreversible`

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "provider": {
      "type": "string"
    },
    "operations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "inputSchema": {
      "type": "object"
    },
    "outputSchema": {
      "type": "object"
    },
    "supportsAsync": {
      "type": "boolean"
    },
    "supportsResume": {
      "type": "boolean"
    },
    "supportsCancellation": {
      "type": "boolean"
    },
    "authorizationRequired": {
      "type": "boolean"
    },
    "sideEffectLevel": {
      "type": "string",
      "enum": [
        "none",
        "reversible",
        "irreversible"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "provider",
    "operations",
    "inputSchema",
    "outputSchema",
    "supportsAsync",
    "supportsResume",
    "supportsCancellation",
    "authorizationRequired",
    "sideEffectLevel"
  ],
  "description": "What an execution provider can do, independent of any one AI vendor."
}

Example

{
  "id": "esign.send",
  "provider": "docusign",
  "operations": [
    "send_envelope"
  ],
  "inputSchema": {},
  "outputSchema": {},
  "supportsAsync": true,
  "supportsResume": false,
  "supportsCancellation": true,
  "authorizationRequired": true,
  "sideEffectLevel": "irreversible"
}

CapabilityInvocation

A request to a capability.

Field	Type	Notes
`invocationId`required	string
`capabilityId`required	string
`input`required	any
`contextRefs`required	array of string
`authorizationRef`	string
`idempotencyKey`required	string

Schema

{
  "type": "object",
  "properties": {
    "invocationId": {
      "type": "string"
    },
    "capabilityId": {
      "type": "string"
    },
    "input": {},
    "contextRefs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "authorizationRef": {
      "type": "string"
    },
    "idempotencyKey": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "invocationId",
    "capabilityId",
    "input",
    "contextRefs",
    "idempotencyKey"
  ],
  "description": "A request to a capability."
}

CapabilityResult

The outcome of a capability invocation.

Field	Type	Notes
`invocationId`required	string
`status`required	`completed` \| `failed` \| `pending` \| `requires_approval`
`output`	any
`evidenceRefs`required	array of string
`error`	object

Schema

{
  "type": "object",
  "properties": {
    "invocationId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "completed",
        "failed",
        "pending",
        "requires_approval"
      ]
    },
    "output": {},
    "evidenceRefs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "additionalProperties": false,
      "required": [
        "code",
        "message",
        "retryable"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "invocationId",
    "status",
    "evidenceRefs"
  ],
  "description": "The outcome of a capability invocation."
}

Lifecycle API

ExecutionState

Execution states. COMPLETED, CANCELLED, and EXPIRED are terminal. Invalid transitions are rejected.

Schema

{
  "type": "string",
  "enum": [
    "CREATED",
    "READY",
    "RUNNING",
    "WAITING_APPROVAL",
    "BLOCKED",
    "VERIFYING",
    "FAILED",
    "COMPLETED",
    "CANCELLED",
    "EXPIRED"
  ],
  "description": "Execution states. COMPLETED, CANCELLED, and EXPIRED are terminal. Invalid transitions are rejected."
}

ObservationCreate

Something the OS learned from an external source. Replaying the same source event must not create a duplicate.

Field	Type	Notes
`source`required	object
`type`required	string
`occurred_at`required	string (date-time)
`payload_ref`	ArtifactRef
`idempotency_key`required	string

Schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "object",
      "properties": {
        "provider": {
          "type": "string"
        },
        "resource_id": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "provider",
        "resource_id"
      ]
    },
    "type": {
      "type": "string"
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time"
    },
    "payload_ref": {
      "$ref": "#/$defs/ArtifactRef"
    },
    "idempotency_key": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "source",
    "type",
    "occurred_at",
    "idempotency_key"
  ],
  "description": "Something the OS learned from an external source. Replaying the same source event must not create a duplicate."
}

Example

{
  "source": {
    "provider": "gmail",
    "resource_id": "message_123"
  },
  "type": "message.received",
  "occurred_at": "2026-11-01T14:00:00Z",
  "payload_ref": "artifact_456",
  "idempotency_key": "gmail-message-123"
}

ObservationAccepted

Field	Type	Notes
`observation_id`required	string
`status`required	`accepted`
`duplicate`required	boolean

Schema

{
  "type": "object",
  "properties": {
    "observation_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "accepted"
      ]
    },
    "duplicate": {
      "type": "boolean"
    }
  },
  "additionalProperties": false,
  "required": [
    "observation_id",
    "status",
    "duplicate"
  ]
}

Example

{
  "observation_id": "obs_123",
  "status": "accepted",
  "duplicate": false
}

ContextResolveRequest

Field	Type	Notes
`observation_ids`	array of string
`goal_id`	string
`scope`required	object
`include`required	array of `related_goals` \| `open_commitments` \| `relevant_policies` \| `prior_decisions`

Schema

{
  "type": "object",
  "properties": {
    "observation_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "goal_id": {
      "type": "string"
    },
    "scope": {
      "type": "object",
      "properties": {
        "workspace_id": {
          "type": "string"
        },
        "project_ids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "workspace_id"
      ]
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "related_goals",
          "open_commitments",
          "relevant_policies",
          "prior_decisions"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "scope",
    "include"
  ]
}

Example

{
  "observation_ids": [
    "obs_123"
  ],
  "scope": {
    "workspace_id": "personal",
    "project_ids": [
      "mortgage-refinance"
    ]
  },
  "include": [
    "related_goals",
    "open_commitments",
    "relevant_policies",
    "prior_decisions"
  ]
}

ContextBundle

Resolved context. Retrieved facts and inferred interpretations are kept separate.

Field	Type	Notes
`context_id`required	string
`state_version`required	integer
`related_goals`required	array of string
`open_commitments`required	array of string
`applicable_policies`required	array of string
`unresolved_questions`required	array of string
`retrieved_facts`	array of Fact
`inferences`	array of object

Schema

{
  "type": "object",
  "properties": {
    "context_id": {
      "type": "string"
    },
    "state_version": {
      "type": "integer",
      "minimum": 0
    },
    "related_goals": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "open_commitments": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "applicable_policies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "unresolved_questions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "retrieved_facts": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Fact"
      }
    },
    "inferences": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "statement": {
            "type": "string"
          },
          "based_on": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "statement",
          "based_on"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "context_id",
    "state_version",
    "related_goals",
    "open_commitments",
    "applicable_policies",
    "unresolved_questions"
  ],
  "description": "Resolved context. Retrieved facts and inferred interpretations are kept separate."
}

Example

{
  "context_id": "ctx_123",
  "state_version": 42,
  "related_goals": [
    "goal_refinance"
  ],
  "open_commitments": [
    "commitment_12"
  ],
  "applicable_policies": [
    "policy_financial_approval"
  ],
  "unresolved_questions": []
}

CommitmentCreate

Field	Type	Notes
`goal_id`required	string
`objective`required	string
`success_criteria`required	array of Criterion
`deadline`	string (date-time)

Schema

{
  "type": "object",
  "properties": {
    "goal_id": {
      "type": "string"
    },
    "objective": {
      "type": "string"
    },
    "success_criteria": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Criterion"
      }
    },
    "deadline": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "required": [
    "goal_id",
    "objective",
    "success_criteria"
  ]
}

Example

{
  "goal_id": "goal_refinance",
  "objective": "Evaluate updated refinancing offer",
  "success_criteria": [
    {
      "type": "artifact_exists",
      "artifact_type": "refinancing_comparison"
    }
  ],
  "deadline": "2026-11-05T23:59:00Z"
}

Commitment

A durable obligation. It cannot be marked completed solely because an agent claims it is complete.

Field	Type	Notes
`commitment_id`required	string
`goal_id`	string
`objective`	string
`success_criteria`	array of Criterion
`deadline`	string (date-time)
`status`required	`open` \| `completed` \| `failed` \| `cancelled` \| `expired`
`version`required	integer

Schema

{
  "type": "object",
  "properties": {
    "commitment_id": {
      "type": "string"
    },
    "goal_id": {
      "type": "string"
    },
    "objective": {
      "type": "string"
    },
    "success_criteria": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Criterion"
      }
    },
    "deadline": {
      "type": "string",
      "format": "date-time"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "completed",
        "failed",
        "cancelled",
        "expired"
      ]
    },
    "version": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false,
  "required": [
    "commitment_id",
    "status",
    "version"
  ],
  "description": "A durable obligation. It cannot be marked completed solely because an agent claims it is complete."
}

Example

{
  "commitment_id": "com_123",
  "status": "open",
  "version": 1
}

CommitmentList

Field	Type	Notes
`data`required	array of Commitment
`next_cursor`	string \| null

Schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Commitment"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "data"
  ]
}

PlanCreate

Field	Type	Notes
`commitment_id`required	string
`constraints`	object
`preferred_capabilities`	array of string

Schema

{
  "type": "object",
  "properties": {
    "commitment_id": {
      "type": "string"
    },
    "constraints": {
      "type": "object",
      "properties": {
        "require_approval_for_external_actions": {
          "type": "boolean"
        }
      },
      "additionalProperties": true
    },
    "preferred_capabilities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "commitment_id"
  ]
}

Example

{
  "commitment_id": "com_123",
  "constraints": {
    "require_approval_for_external_actions": true
  },
  "preferred_capabilities": [
    "document_analysis",
    "calculator",
    "research"
  ]
}

Plan

A validated proposal. The runtime checks it against schemas, dependencies, and policy before execution.

Field	Type	Notes
`plan_id`required	string
`commitment_id`	string
`steps`required	array of object

Schema

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "string"
    },
    "commitment_id": {
      "type": "string"
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "capability": {
            "type": "string"
          },
          "depends_on": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "capability",
          "depends_on"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "plan_id",
    "steps"
  ],
  "description": "A validated proposal. The runtime checks it against schemas, dependencies, and policy before execution."
}

Example

{
  "plan_id": "plan_123",
  "steps": [
    {
      "id": "step_1",
      "capability": "document_analysis",
      "depends_on": []
    },
    {
      "id": "step_2",
      "capability": "calculator",
      "depends_on": [
        "step_1"
      ]
    },
    {
      "id": "step_3",
      "capability": "report_generation",
      "depends_on": [
        "step_2"
      ]
    }
  ]
}

ExecutionCreate

Field	Type	Notes
`plan_id`required	string
`idempotency_key`required	string
`authorization_context`required	object

Schema

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "string"
    },
    "idempotency_key": {
      "type": "string"
    },
    "authorization_context": {
      "type": "object",
      "properties": {
        "principal_id": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "principal_id"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "plan_id",
    "idempotency_key",
    "authorization_context"
  ]
}

Example

{
  "plan_id": "plan_123",
  "idempotency_key": "execute-plan-123-v1",
  "authorization_context": {
    "principal_id": "user_123"
  }
}

ExecutionAccepted

Execution is asynchronous. Acceptance does not mean the work is complete.

Field	Type	Notes
`execution_id`required	string
`status`required	`queued`
`next_action`	string

Schema

{
  "type": "object",
  "properties": {
    "execution_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued"
      ]
    },
    "next_action": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "execution_id",
    "status"
  ],
  "description": "Execution is asynchronous. Acceptance does not mean the work is complete."
}

Example

{
  "execution_id": "exec_123",
  "status": "queued",
  "next_action": "await_execution"
}

Execution

Field	Type	Notes
`execution_id`required	string
`plan_id`	string
`state`required	ExecutionState
`state_version`required	integer
`correlation_id`	string
`updated_at`	string (date-time)

Schema

{
  "type": "object",
  "properties": {
    "execution_id": {
      "type": "string"
    },
    "plan_id": {
      "type": "string"
    },
    "state": {
      "$ref": "#/$defs/ExecutionState"
    },
    "state_version": {
      "type": "integer",
      "minimum": 0
    },
    "correlation_id": {
      "type": "string"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "required": [
    "execution_id",
    "state",
    "state_version"
  ]
}

Example

{
  "execution_id": "exec_123",
  "plan_id": "plan_123",
  "state": "RUNNING",
  "state_version": 3,
  "correlation_id": "goal_refinance",
  "updated_at": "2026-11-01T14:05:00Z"
}

TransitionRequest

Field	Type	Notes
`expected_state`required	ExecutionState
`target_state`required	ExecutionState
`verification_id`	string
`reason`	string

Schema

{
  "type": "object",
  "properties": {
    "expected_state": {
      "$ref": "#/$defs/ExecutionState"
    },
    "target_state": {
      "$ref": "#/$defs/ExecutionState"
    },
    "verification_id": {
      "type": "string"
    },
    "reason": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "expected_state",
    "target_state"
  ]
}

Example

{
  "expected_state": "VERIFYING",
  "target_state": "COMPLETED",
  "verification_id": "verify_123"
}

Transition

Every accepted transition is persisted with an actor, timestamp, reason, and correlation ID.

Field	Type	Notes
`transition_id`required	string
`execution_id`required	string
`from_state`required	ExecutionState
`to_state`required	ExecutionState
`state_version`required	integer
`actor`required	PrincipalRef
`reason`	string
`correlation_id`required	string
`occurred_at`required	string (date-time)

Schema

{
  "type": "object",
  "properties": {
    "transition_id": {
      "type": "string"
    },
    "execution_id": {
      "type": "string"
    },
    "from_state": {
      "$ref": "#/$defs/ExecutionState"
    },
    "to_state": {
      "$ref": "#/$defs/ExecutionState"
    },
    "state_version": {
      "type": "integer",
      "minimum": 0
    },
    "actor": {
      "$ref": "#/$defs/PrincipalRef"
    },
    "reason": {
      "type": "string"
    },
    "correlation_id": {
      "type": "string"
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "required": [
    "transition_id",
    "execution_id",
    "from_state",
    "to_state",
    "state_version",
    "actor",
    "correlation_id",
    "occurred_at"
  ],
  "description": "Every accepted transition is persisted with an actor, timestamp, reason, and correlation ID."
}

Example

{
  "transition_id": "tr_9",
  "execution_id": "exec_123",
  "from_state": "VERIFYING",
  "to_state": "COMPLETED",
  "state_version": 5,
  "actor": {
    "type": "service",
    "id": "caop-runtime"
  },
  "reason": "verification passed",
  "correlation_id": "goal_refinance",
  "occurred_at": "2026-11-01T15:00:00Z"
}

ResultSubmission

Field	Type	Notes
`output`	any
`evidence_refs`required	array of string
`idempotency_key`required	string

Schema

{
  "type": "object",
  "properties": {
    "output": {},
    "evidence_refs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "idempotency_key": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "evidence_refs",
    "idempotency_key"
  ]
}

Example

{
  "output": {
    "report": "artifact_789"
  },
  "evidence_refs": [
    "artifact_789"
  ],
  "idempotency_key": "submit-exec-123-v1"
}

VerificationRequest

Field	Type	Notes
`execution_id`required	string
`criteria`required	array of string

Schema

{
  "type": "object",
  "properties": {
    "execution_id": {
      "type": "string"
    },
    "criteria": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "execution_id",
    "criteria"
  ]
}

Example

{
  "execution_id": "exec_123",
  "criteria": [
    "all_required_steps_completed",
    "result_has_supporting_evidence",
    "no_policy_violations"
  ]
}

Verification

A verdict must identify which checks were performed.

Field	Type	Notes
`verification_id`required	string
`verdict`required	`passed` \| `failed`
`evidence_refs`required	array of string
`checks`required	array of object

Schema

{
  "type": "object",
  "properties": {
    "verification_id": {
      "type": "string"
    },
    "verdict": {
      "type": "string",
      "enum": [
        "passed",
        "failed"
      ]
    },
    "evidence_refs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "deterministic",
              "model_rubric",
              "human"
            ]
          },
          "result": {
            "type": "string",
            "enum": [
              "pass",
              "fail"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "name",
          "kind",
          "result"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "verification_id",
    "verdict",
    "evidence_refs",
    "checks"
  ],
  "description": "A verdict must identify which checks were performed."
}

Example

{
  "verification_id": "verify_123",
  "verdict": "passed",
  "evidence_refs": [
    "artifact_789"
  ],
  "checks": [
    {
      "name": "all_required_steps_completed",
      "kind": "deterministic",
      "result": "pass"
    },
    {
      "name": "result_has_supporting_evidence",
      "kind": "model_rubric",
      "result": "pass"
    },
    {
      "name": "no_policy_violations",
      "kind": "deterministic",
      "result": "pass"
    }
  ]
}

RecordCommit

A state mutation. A conflicting state version rejects the transaction or invokes a declared conflict policy.

Field	Type	Notes
`execution_id`	string
`verification_id`	string
`expected_state_version`required	integer
`changes`required	array of object

Schema

{
  "type": "object",
  "properties": {
    "execution_id": {
      "type": "string"
    },
    "verification_id": {
      "type": "string"
    },
    "expected_state_version": {
      "type": "integer",
      "minimum": 0
    },
    "changes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entity_id": {
            "type": "string"
          },
          "operation": {
            "type": "string"
          },
          "value": {}
        },
        "additionalProperties": false,
        "required": [
          "entity_id",
          "operation"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "expected_state_version",
    "changes"
  ],
  "description": "A state mutation. A conflicting state version rejects the transaction or invokes a declared conflict policy."
}

Example

{
  "execution_id": "exec_123",
  "verification_id": "verify_123",
  "expected_state_version": 42,
  "changes": [
    {
      "entity_id": "com_123",
      "operation": "set_status",
      "value": "completed"
    }
  ]
}

RecordCommitted

Field	Type	Notes
`transaction_id`required	string
`state_version`required	integer
`status`required	`committed`

Schema

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string"
    },
    "state_version": {
      "type": "integer",
      "minimum": 0
    },
    "status": {
      "type": "string",
      "enum": [
        "committed"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "transaction_id",
    "state_version",
    "status"
  ]
}

Example

{
  "transaction_id": "txn_123",
  "state_version": 43,
  "status": "committed"
}

ReviewRequest

Field	Type	Notes
`goal_id`required	string
`review_type`required	`progress` \| `outcome` \| `risk`
`include`	array of `outcomes` \| `unresolved_commitments` \| `failures` \| `next_actions`

Schema

{
  "type": "object",
  "properties": {
    "goal_id": {
      "type": "string"
    },
    "review_type": {
      "type": "string",
      "enum": [
        "progress",
        "outcome",
        "risk"
      ]
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "outcomes",
          "unresolved_commitments",
          "failures",
          "next_actions"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "goal_id",
    "review_type"
  ]
}

Example

{
  "goal_id": "goal_refinance",
  "review_type": "progress",
  "include": [
    "outcomes",
    "unresolved_commitments",
    "failures",
    "next_actions"
  ]
}

Review

Recommendations are proposals, not authorized actions.

Field	Type	Notes
`review_id`required	string
`goal_status`required	`active` \| `paused` \| `achieved` \| `abandoned`
`recommended_actions`required	array of object

Schema

{
  "type": "object",
  "properties": {
    "review_id": {
      "type": "string"
    },
    "goal_status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "achieved",
        "abandoned"
      ]
    },
    "recommended_actions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string"
          },
          "requires_approval": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "required": [
          "action",
          "requires_approval"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "review_id",
    "goal_status",
    "recommended_actions"
  ],
  "description": "Recommendations are proposals, not authorized actions."
}

Example

{
  "review_id": "review_123",
  "goal_status": "active",
  "recommended_actions": [
    {
      "action": "request_final_offer",
      "requires_approval": true
    }
  ]
}

ApprovalDecision

Field	Type	Notes
`decision`required	`approve` \| `deny`
`scope`	object	What exactly is authorized, e.g. a document, amount, or recipient.
`expires_at`required	string (date-time)

Schema

{
  "type": "object",
  "properties": {
    "decision": {
      "type": "string",
      "enum": [
        "approve",
        "deny"
      ]
    },
    "scope": {
      "type": "object",
      "description": "What exactly is authorized, e.g. a document, amount, or recipient."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "required": [
    "decision",
    "expires_at"
  ]
}

Example

{
  "decision": "approve",
  "scope": {
    "document": "offer-v2",
    "max_price": 632000
  },
  "expires_at": "2026-11-02T22:00:00Z"
}

Approval

A scoped, expiring authorization for a consequential action.

Field	Type	Notes
`approval_id`required	string
`approval_request_id`required	string
`decision`required	`approve` \| `deny`
`scope`	object
`approved_by`required	PrincipalRef
`expires_at`required	string (date-time)

Schema

{
  "type": "object",
  "properties": {
    "approval_id": {
      "type": "string"
    },
    "approval_request_id": {
      "type": "string"
    },
    "decision": {
      "type": "string",
      "enum": [
        "approve",
        "deny"
      ]
    },
    "scope": {
      "type": "object"
    },
    "approved_by": {
      "$ref": "#/$defs/PrincipalRef"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "required": [
    "approval_id",
    "approval_request_id",
    "decision",
    "approved_by",
    "expires_at"
  ],
  "description": "A scoped, expiring authorization for a consequential action."
}

Example

{
  "approval_id": "appr_301",
  "approval_request_id": "approval_123",
  "decision": "approve",
  "scope": {
    "document": "offer-v2"
  },
  "approved_by": {
    "type": "user",
    "id": "user_123"
  },
  "expires_at": "2026-11-02T22:00:00Z"
}

Events and errors

EventEnvelope

Field	Type	Notes
`event_id`required	string
`event_type`required	string	e.g. observation.received, commitment.created, plan.approved, execution.started, execution.blocked, approval.requested, approval.granted, execution.completed, verification.failed, record.committed, goal.achieved
`schema_version`required	string
`occurred_at`required	string (date-time)
`workspace_id`required	string
`subject_id`required	string
`correlation_id`required	string
`causation_id`	string
`payload`required	object

Schema

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string"
    },
    "event_type": {
      "type": "string",
      "description": "e.g. observation.received, commitment.created, plan.approved, execution.started, execution.blocked, approval.requested, approval.granted, execution.completed, verification.failed, record.committed, goal.achieved"
    },
    "schema_version": {
      "type": "string"
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time"
    },
    "workspace_id": {
      "type": "string"
    },
    "subject_id": {
      "type": "string"
    },
    "correlation_id": {
      "type": "string"
    },
    "causation_id": {
      "type": "string"
    },
    "payload": {
      "type": "object"
    }
  },
  "additionalProperties": false,
  "required": [
    "event_id",
    "event_type",
    "schema_version",
    "occurred_at",
    "workspace_id",
    "subject_id",
    "correlation_id",
    "payload"
  ]
}

Example

{
  "event_id": "evt_123",
  "event_type": "commitment.deadline_approaching",
  "schema_version": "1.0",
  "occurred_at": "2026-11-01T14:00:00Z",
  "workspace_id": "personal",
  "subject_id": "com_123",
  "correlation_id": "goal_refinance",
  "causation_id": "evt_100",
  "payload": {
    "hours_remaining": 24
  }
}

Error

Field	Type	Notes
`error`required	object
`trace_id`required	string

Schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "INVALID_REQUEST",
            "UNAUTHENTICATED",
            "FORBIDDEN",
            "NOT_FOUND",
            "POLICY_APPROVAL_REQUIRED",
            "POLICY_DENIED",
            "INVALID_TRANSITION",
            "STATE_VERSION_CONFLICT",
            "VERIFICATION_FAILED",
            "RATE_LIMITED",
            "INTERNAL"
          ]
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "details": {
          "type": "object"
        }
      },
      "additionalProperties": false,
      "required": [
        "code",
        "message",
        "retryable"
      ]
    },
    "trace_id": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "error",
    "trace_id"
  ]
}

Example

{
  "error": {
    "code": "POLICY_APPROVAL_REQUIRED",
    "message": "External action requires approval",
    "retryable": false,
    "details": {
      "approval_request_id": "approval_123"
    }
  },
  "trace_id": "trace_456"
}

Business Profile

MetricNode

A node in a hierarchical KPI tree. Variance beyond thresholds triggers Understand or a Commitment.

Field	Type	Notes
`id`required	string
`name`required	string
`formula`	string
`parentMetricId`	string
`childMetricIds`required	array of string
`owner`required	PrincipalRef
`baselineCadence`required	`hourly` \| `daily` \| `weekly` \| `monthly`
`varianceThresholds`required	object

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "formula": {
      "type": "string"
    },
    "parentMetricId": {
      "type": "string"
    },
    "childMetricIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "owner": {
      "$ref": "#/$defs/PrincipalRef"
    },
    "baselineCadence": {
      "type": "string",
      "enum": [
        "hourly",
        "daily",
        "weekly",
        "monthly"
      ]
    },
    "varianceThresholds": {
      "type": "object",
      "properties": {
        "warningDeltaPct": {
          "type": "number"
        },
        "criticalDeltaPct": {
          "type": "number"
        }
      },
      "additionalProperties": false,
      "required": [
        "warningDeltaPct",
        "criticalDeltaPct"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "id",
    "name",
    "childMetricIds",
    "owner",
    "baselineCadence",
    "varianceThresholds"
  ],
  "description": "A node in a hierarchical KPI tree. Variance beyond thresholds triggers Understand or a Commitment."
}

Example

{
  "id": "metric.net_contribution_margin",
  "name": "Net contribution margin",
  "formula": "revenue - cogs - ad_spend",
  "childMetricIds": [
    "metric.revenue",
    "metric.cogs",
    "metric.ad_spend"
  ],
  "owner": {
    "type": "role",
    "id": "cfo"
  },
  "baselineCadence": "weekly",
  "varianceThresholds": {
    "warningDeltaPct": -3.0,
    "criticalDeltaPct": -7.5
  }
}

ApprovalRoutingRule

Delegation of Authority routing for a policy.

Field	Type	Notes
`policyId`required	string
`requiredRoles`required	array of string
`minQuorum`required	integer
`expirationSeconds`required	integer
`escalateToRoleOnTimeout`	string

Schema

{
  "type": "object",
  "properties": {
    "policyId": {
      "type": "string"
    },
    "requiredRoles": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "minQuorum": {
      "type": "integer",
      "minimum": 1
    },
    "expirationSeconds": {
      "type": "integer",
      "minimum": 1
    },
    "escalateToRoleOnTimeout": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "policyId",
    "requiredRoles",
    "minQuorum",
    "expirationSeconds"
  ],
  "description": "Delegation of Authority routing for a policy."
}

Example

{
  "policyId": "doa_marketing_spend",
  "requiredRoles": [
    "finance_lead",
    "operations_lead"
  ],
  "minQuorum": 2,
  "expirationSeconds": 86400,
  "escalateToRoleOnTimeout": "ceo"
}