Event Types Reference

Every state change in a Tervos organization emits an event. Events are append-only, ordered per organization, and queryable with tervos audit. This page documents every event type in Layers 1–4 (the MVP scope).

Naming convention: {layer}.{domain}.{action} — all lowercase, dot-separated.

Base Event Shape

All events share this structure:

interface TervosEvent {
  id: string;             // UUIDv7
  type: string;           // e.g., "org.task.assigned"
  orgId: string;          // Organization DID
  emittedBy: string;      // Agent/principal DID
  timestamp: string;      // ISO 8601 UTC
  sequenceNumber: number; // Monotonic per-org
  causationId: string | null;
  correlationId: string;
  payload: Record<string, unknown>;
  prevHash?: string | null; // hex hash of previous event in this org's chain (null = genesis)
  hash?: string;            // hex SHA-256 of this event, computed at append time
}

TypedTervosEvent<T> narrows type and payload to the specific event type. All 20 payload types are defined in EventPayloadMap in @tervos/core.

Hash chaining (v0.2.0+): every appended event is linked to the previous one by hash, making the log tamper-evident. Verify with tervos audit --verify; export portable proof with tervos export-evidence. See the evidence guide for the full workflow.

Identity Events (Layer 1)

Event Type	Emitted By	Description
identity.agent.registered	@tervos/org (bootstrap)	Agent defined and entered PENDING state
identity.agent.activated	@tervos/org (bootstrap)	Agent entered ACTIVE state, can receive tasks
identity.agent.rejected	@tervos/org (lifecycle)	Agent registration denied. Terminal state.
identity.agent.suspended	@tervos/org (lifecycle)	Agent entered SUSPENDED state
identity.agent.resumed	@tervos/org (lifecycle)	Agent returned to ACTIVE from SUSPENDED
identity.agent.terminated	@tervos/org (lifecycle)	Agent permanently deactivated. Terminal state.

Payloads

// identity.agent.registered
{ agentId: string; agentDid: string; agentRole: string }

// identity.agent.activated
{ agentId: string; agentDid: string }

// identity.agent.rejected
{ agentId: string; reason: string }

// identity.agent.suspended
{ agentId: string; reason: string; suspendedBy: string /* DID */ }

// identity.agent.resumed
{ agentId: string; resumedBy: string /* DID */ }

// identity.agent.terminated
{ agentId: string; reason: string; terminatedBy: string /* DID */ }

Policy Events (Layer 2)

Event Type	Emitted By	Description
policy.evaluated	@tervos/policy (engine)	Every policy decision is recorded

// policy.evaluated
{
  principal: string;                            // DID of the requesting agent
  action: string;                               // e.g., "tervos/execute"
  resource: string;                             // Resource identifier
  decision: "allow" | "deny" | "pending_approval";
  matchedPolicies: string[];                    // IDs of matched policy rules
  reason: string;                               // Human-readable explanation
}

Approval Events

Emitted by the ApprovalQueue in @tervos/org. These are top-level approval.* events, not namespaced under policy.*.

Event Type	Emitted By	Description
approval.requested	@tervos/org (ApprovalQueue)	Action needs human approval
approval.granted	@tervos/org (ApprovalQueue)	Human approved the action
approval.denied	@tervos/org (ApprovalQueue)	Human denied the action

// approval.requested
{
  approvalId: string;   // UUID for this approval request
  requestedBy: string;  // Agent DID
  action: string;       // e.g., "tervos/create"
  resource: string;     // Resource type/id
  description: string;  // Human-readable description
}

// approval.granted
{ approvalId: string; grantedBy: string; comment: string }

// approval.denied
{ approvalId: string; deniedBy: string; reason: string }

Organization Events (Layer 4)

Event Type	Emitted By	Description
org.bootstrapped	@tervos/org (bootstrap)	Org is live. All agents registered and activated.
org.task.created	@tervos/org (TaskManager)	New task defined
org.task.assigned	@tervos/org (TaskManager)	Task assigned to an agent
org.task.started	@tervos/org (TaskManager)	Agent began working on task
org.task.submitted	@tervos/org (TaskManager)	Agent submitted output for review
org.task.completed	@tervos/org (TaskManager)	Task approved and finished
org.task.rejected	@tervos/org (TaskManager)	Task output rejected, returned for rework
org.task.blocked	@tervos/org (TaskManager)	Task cannot proceed
org.task.unblocked	@tervos/org (TaskManager)	Blocker resolved
org.task.cancelled	@tervos/org (TaskManager)	Task permanently cancelled

// org.bootstrapped
{
  orgName: string;    // Organization name from TERVOS.yaml
  orgDid: string;     // Organization's did:key
  agentCount: number; // Number of registered agents
  devMode: boolean;   // Whether bootstrap ran in dev mode
}

// org.task.created
{
  taskId: string;
  title: string;
  projectId: string;
  createdBy: string;       // DID
  assignee: string | null; // Agent DID or null if unassigned
}

// org.task.assigned
{ taskId: string; assignedTo: string; assignedBy: string }

// org.task.started
{ taskId: string; startedBy: string }

// org.task.submitted
{
  taskId: string;
  submittedBy: string;
  output: string;
  artifacts: Array<{ name: string; content: string }>;
}

// org.task.completed
{ taskId: string; completedBy: string; result: string }

// org.task.rejected
{ taskId: string; rejectedBy: string; reason: string }

// org.task.blocked
{ taskId: string; blockedBy: string; reason: string }

// org.task.unblocked
{ taskId: string; unblockedBy: string }

// org.task.cancelled
{ taskId: string; cancelledBy: string; reason: string }

Budget Events

Event Type	Emitted By	Description
budget.charged	@tervos/org (TaskExecutor)	Agent budget debited after task execution

// budget.charged
{
  agentId: string;
  amount: number;       // USD debited
  taskId: string;
  balanceAfter: number; // Remaining budget in USD
}

Querying Events

tervos audit                          # full chronological log
tervos audit --type org.task.completed
tervos audit --agent ceo