Spec 11: Events & Telemetry

DWS Spec 11: Event & Telemetry Schema

Digital Worker Standard — DWS Specification

Version: 1.0 Tier: 3 — Accumulation Status: Release Candidate Dependencies: All specs (cross-cutting observability layer)

1. Overview

This specification defines the structured event format for everything that happens during worker execution. Events are DWS’s write protocol: the stream of structured records that feeds institutional knowledge (Spec 2), enables observability, and supports compliance auditing (Spec 12).

Every DWS runtime artifact (knowledge entries, verification findings, intent mutations, coordination state) is event-sourced. Events are the single source of truth for what happened during execution. Definition-time artifacts live in git; runtime artifacts live in the event stream. The base_version field on every event connects the two.

DWS events are a superset of OpenTelemetry. They carry DWS-specific semantics (intent references, verification findings, knowledge operations) while maintaining compatibility with OTel export for organisations with existing observability infrastructure.

2. Common Event Fields

All events share these fields:

Field	Type	Required	Description
`event_id`	string (uuid)	MUST	Unique event identifier.
`event_type`	string (dotted)	MUST	Event type from the taxonomy (Section 3).
`timestamp`	string (ISO 8601 UTC)	MUST	When the event occurred.
`session_id`	string (uuid)	MUST	Execution session this event belongs to.
`workflow_id`	string	MUST	Workflow being executed.
`phase_id`	string	SHOULD	Current phase (if applicable).
`worker_id`	string	SHOULD	Worker that produced or is associated with this event.
`correlation_id`	string	MAY	Links causal chains across workers and sessions.
`base_version`	string	MUST	Git commit hash of the definition-time artifacts.
`sequence_number`	integer	MUST	Monotonic within session. Establishes causal ordering.
`context`	object	MAY	Active knowledge entries, intent ref.
`payload`	object	MUST	Event-type-specific data.

3. Event Taxonomy

3.1 Lifecycle Events

Event Type	Description	Required
`lifecycle.worker_started`	Worker instantiated and ready.	Yes
`lifecycle.worker_completed`	Worker finished successfully.	Yes
`lifecycle.worker_failed`	Worker failed and cannot continue.	Yes
`lifecycle.worker_escalated`	Worker escalated to coordinator or human.	Yes
`lifecycle.worker_capacity_changed`	Worker’s effective capacity changed.	No

3.2 Workflow Events

Event Type	Description	Required
`workflow.phase_entered`	Phase began execution.	Yes
`workflow.phase_exited`	Phase completed.	Yes
`workflow.gate_passed`	Verification gate passed.	Yes
`workflow.gate_failed`	Verification gate failed.	Yes
`workflow.completed`	Entire workflow completed.	Yes
`workflow.cancelled`	Workflow cancelled.	Yes
`workflow.resumed`	Workflow resumed from checkpoint.	Yes
`workflow.cost_threshold_reached`	Cost alert threshold crossed.	Yes
`workflow.checkpoint_created`	Execution checkpoint persisted.	Yes

3.3 Skill Events

Event Type	Description	Required
`skill.invoked`	Skill began execution.	No
`skill.completed`	Skill completed.	No
`skill.failed`	Skill failed.	No
`skill.tool_called`	MCP tool invoked.	No
`skill.tool_returned`	MCP tool returned.	No

Skill events are RECOMMENDED for debugging and knowledge accumulation but not REQUIRED.

3.4 Coordination Events

Event Type	Description	Required
`coordination.task_assigned`	Task assigned to worker.	Yes
`coordination.task_completed`	Task completed.	Yes
`coordination.task_failed`	Task failed.	Yes
`coordination.task_progress`	Worker reported progress.	No
`coordination.conflict_detected`	Conflict between workers detected.	Yes
`coordination.conflict_resolved`	Conflict resolved.	Yes
`coordination.dependency_resolved`	Task dependency satisfied.	Yes
`coordination.dependency_discovered`	New dependency discovered at runtime.	Yes
`coordination.escalation_triggered`	Escalation initiated.	Yes
`coordination.escalation_resolved`	Escalation resolved.	Yes
`coordination.contract_validated`	Artifact validated against contract.	Yes
`coordination.contract_breached`	Artifact failed contract validation.	Yes

3.5 Knowledge Events

Event Type	Description	Required
`knowledge.entry_created`	New knowledge entry.	Yes
`knowledge.entry_promoted`	Entry promoted to institutional.	Yes
`knowledge.entry_retired`	Entry retired.	Yes
`knowledge.entry_overridden`	Entry overridden by conflict resolution.	Yes
`knowledge.conflict_detected`	Knowledge conflict found.	No
`knowledge.conflict_resolved`	Knowledge conflict resolved.	No
`knowledge.version_transfer`	Knowledge carried forward to new worker version.	No

3.6 Verification Events

Event Type	Description	Required
`verification.started`	Verification began.	Yes
`verification.finding_issued`	Individual finding produced.	Yes
`verification.verdict_rendered`	Final verdict (pass/conditional_pass/fail).	Yes
`verification.reverification_triggered`	Re-verification loop started.	Yes

3.7 Intent Events

Event Type	Description	Required
`intent.created`	New intent artifact.	Yes
`intent.approved`	Intent approved for execution.	Yes
`intent.activated`	Intent transitioned to active.	Yes
`intent.mutated`	Intent modified during execution.	Yes
`intent.completed`	Intent completed.	Yes

3.8 Guardrail Events

Event Type	Description	Required
`guardrail.blocked`	Action rejected by a guardrail.	Yes
`guardrail.warned`	Action proceeded with warning.	No
`guardrail.logged`	Guardrail triggered at log level.	No
`guardrail.exhausted`	All guardrail retries exhausted.	Yes

3.9 Interaction Events

Event Type	Description	Required
`interaction.check_in`	Worker check-in report.	No
`interaction.question_asked`	Worker asked human a question.	Yes
`interaction.question_answered`	Human answered worker’s question.	Yes
`interaction.feedback_received`	Human provided feedback.	Yes
`interaction.handoff_initiated`	Handoff started.	Yes
`interaction.handoff_completed`	Handoff completed.	Yes
`interaction.handoff_failed`	Handoff failed.	Yes

3.10 Outcome Events

Event Type	Description	Required
`outcome.produced`	Worker output ready.	Yes
`outcome.verification_passed`	Outcome criteria passed.	Yes
`outcome.verification_failed`	Outcome criteria failed.	Yes
`outcome.delivery_attempted`	Delivery to channel started.	Yes
`outcome.delivery_succeeded`	Delivery confirmed.	Yes
`outcome.delivery_failed`	Delivery failed.	Yes
`outcome.escalated`	Escalation triggered.	Yes
`outcome.completed`	Outcome lifecycle closed.	Yes

3.11 Approval Events

Event Type	Description	Required
`approval.requested`	Approval gate activated.	Yes
`approval.decided`	Approver rendered decision.	Yes
`approval.delegated`	Approval authority delegated.	Yes
`approval.timed_out`	Approval SLA expired.	Yes

4. Event Delivery Guarantees

Mandatory events: Required for audit, state reconstruction, and compliance.
Optional events: Recommended for debugging and knowledge accumulation.
Within session: Causal ordering via sequence_number (monotonic).
Across sessions: No ordering guarantee. timestamp for approximate ordering, correlation_id for causal chains.
Delivery: At-least-once semantics. Consumers must be idempotent.

5. Event Consumption Interface

5.1 Stream Interface

Real-time subscription with filtering:

{
  "subscription": {
    "event_types": ["workflow.*", "verification.*"],
    "worker_ids": ["contract-analyst"],
    "delivery": { "type": "webhook", "url": "https://hooks.example.com/events", "batch_size": 10 }
  }
}

Filters support wildcards on event types. Delivery types: webhook (batched) or stream (WebSocket/SSE).

5.2 Query Interface

Historical event retrieval with cursor-based pagination:

{
  "query": {
    "event_types": ["verification.*"],
    "session_ids": ["sess-001"],
    "time_range": { "from": "2026-04-01T00:00:00Z", "to": "2026-04-10T23:59:59Z" },
    "cursor": null,
    "limit": 100
  }
}

6. OpenTelemetry Mapping

DWS Concept	OTel Concept
Workflow execution	Trace (trace ID = workflow execution ID)
Phase	Span (parent = workflow trace)
Skill execution	Child span
Tool call	Span event
Verification	Span
DWS event (mandatory)	Span event
DWS event (optional)	Log
Knowledge entry	Resource attribute

OTel GenAI semantic convention alignment:

OTel GenAI Convention	DWS Mapping
`gen_ai.agent` span	`lifecycle.worker_started` / `lifecycle.worker_completed`
`gen_ai.tool.call` span	`skill.tool_called` / `skill.tool_returned`
`gen_ai.agent.name`	Worker descriptor `identity.name`
`gen_ai.agent.version`	Worker descriptor `identity.version`

Runtimes SHOULD support OTel export. The mapping above ensures DWS events can flow into existing OTel-compatible monitoring infrastructure (Datadog, Grafana, etc.) without information loss.

7. Event Retention

7.1 Retention Policies

Category	Minimum Retention	Default
Mandatory events	30 days	1 year
Optional events	7 days	90 days
Compliance-relevant events	Per regulatory framework (see Spec 12)	Per framework

7.2 Event Filtering and Subscription

Runtimes SHOULD support:

Event type filtering (including wildcards)
Worker-level filtering
Session-level filtering
Time-range filtering
Custom predicate filtering on payload fields

8. Privacy and Data Classification

Events may contain sensitive data. The data_classification field (from Spec 13) applies:

public — Exportable without restriction.
internal — Organisation-internal only.
confidential — Restricted access, redacted on export.
restricted — Requires explicit authorisation to access.

Runtimes MUST redact sensitive fields in events when exporting based on recipient access level.

9. CloudEvents Compatibility

DWS events SHOULD be expressible as CloudEvents (CNCF v1.0.2). The mapping:

CloudEvents Field	DWS Source
`id`	`event_id`
`type`	`dws.{event_type}` (e.g., `dws.workflow.phase_entered`)
`source`	`dws://{dws-name}/{worker-id}`
`time`	`timestamp`
`subject`	`session_id`
`datacontenttype`	`application/json`
`data`	Full event payload

This enables DWS events to flow through any CloudEvents-compatible event infrastructure (Kafka, AWS EventBridge, Google Cloud Pub/Sub, etc.).

10. References

OpenTelemetry GenAI Semantic Conventions — Agent span conventions and attribute names.
CloudEvents v1.0.2 — Standard event envelope format.
Spec 2: Knowledge Schema — Knowledge events feed the knowledge lifecycle.
Spec 8: Verification Framework — Verification events track quality evaluation.
Spec 12: Compliance & Governance — Determines retention requirements for compliance-relevant events.
Spec 13: Security Model — Defines data classification levels for event privacy.