Orchestrata Ultimate / Specs / 004-cxp

004-cxp: CXP Protocol (Cross-agent eXchange Protocol)

The Cross-agent eXchange Protocol (CXP) is the structured communication protocol for all agent-to-agent messaging in Orchestrata. It defines an 11-field packet format with deterministic headers, delivery tracking, work status state machines, and Prolog fact integration.

At a glance

Item	Value
Spec directory	`specs/004-cxp/`
Status line in the spec	Complete
Requirement IDs defined	273
With a `@traces` citation in `src/`	203 (74.4%)
With a `@traces` citation in `tests/`	2 (0.7%)
Tracked files	9
RTM page	004-cxp

Reading this spec

The Cross-agent eXchange Protocol (CXP) is the structured protocol for all agent-to-agent messaging in Orchestrata. It defines an 11-field packet format with deterministic headers, delivery tracking, work status state machines and integration with Prolog facts, so that message passing is deterministic and traceable.

The scope is a set of user stories: packet format and structure, header management, payload handling, delivery status tracking, packet serialization and deserialization (all critical), then work status tracking, validation and schema, thread management and correlation, and priority and ordering (high), and further stories after those. Requirement IDs use the REQ-004- prefix.

The key decisions are a standardized packet with required headers; JSON and binary serialization; thread-based correlation of messages; priority-based ordering; and protocol versioning for backward compatibility. Delivery status moves through queued, delivered and acknowledged. Work status moves through pending, in progress, resolved and archived.

In the code, the packet model is in orchestrata_ultimate/core/packet/packet, the largest tracer. The cxp package holds orchestrata_ultimate/cxp/interfaces, orchestrata_ultimate/cxp/headers, orchestrata_ultimate/cxp/validator and orchestrata_ultimate/cxp/json_serializer. The per-requirement view is on the RTM page.

The spec's status line reads Complete. It tracks 9 files and defines 273 requirement IDs. The full text follows below.

Measured coverage is 203 of 273 requirements cited by at least one @traces in src/ (74.4%), spread over 31 modules; the module citing the most of them is orchestrata_ultimate/core/packet/packet (46 requirements). In tests/, 2 requirements are cited by a test-side @traces.

Coverage gaps: 70 requirements have no citing symbol. The largest untraced groups are REQ-004-US-010 (10), REQ-004-US-005 (9), REQ-004-US-001 (7). Untraced means no @traces names the ID; the behaviour may still exist in code that was never annotated. Test-side citations are thinner than code-side ones (2 against 203).

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

ID	Done	Requirement	Traced by
`REQ-004-US-001-001`	yes	Define CXPPacket base class with all required fields	2
`REQ-004-US-001-002`	yes	Implement message_id as UUID string	4
`REQ-004-US-001-003`	yes	Implement from_agent as Volk alias string	3
`REQ-004-US-001-004`	yes	Implement to_agent as Volk alias string	3
`REQ-004-US-001-005`	yes	Implement thread_id as string identifier	3
`REQ-004-US-001-006`	yes	Implement subject as string (max 200 chars)	3
`REQ-004-US-001-007`	yes	Implement payload as generic object (dict or bytes)	3
`REQ-004-US-001-008`	yes	Implement timestamp as ISO8601 string	3
`REQ-004-US-001-009`	yes	Implement priority as integer (0-10 range)	4
`REQ-004-US-001-010`	yes	Implement delivery_status enum (queued, delivered, acknowledged, failed)	3
`REQ-004-US-001-011`	yes	Implement work_status enum (pending, in_progress, resolved, archived)	3
`REQ-004-US-001-012`	yes	Implement protocol_version as semver string	3
`REQ-004-US-001-013`	yes	Validate message_id is valid UUID	1
`REQ-004-US-001-014`	yes	Validate from_agent matches Volk alias pattern (U:[A-Z][a-z])	2
`REQ-004-US-001-015`	yes	Validate to_agent matches Volk alias pattern	2
`REQ-004-US-001-016`	yes	Validate thread_id is non-empty string	none
`REQ-004-US-001-017`	yes	Validate subject is non-empty string	2
`REQ-004-US-001-018`	yes	Validate subject length ≤200 characters	1
`REQ-004-US-001-019`	yes	Validate payload is valid JSON or bytes	1
`REQ-004-US-001-020`	yes	Validate timestamp is valid ISO8601	none
`REQ-004-US-001-021`	yes	Validate priority is integer 0-10	none
`REQ-004-US-001-022`	yes	Validate delivery_status is valid enum value	none
`REQ-004-US-001-023`	yes	Validate work_status is valid enum value	none
`REQ-004-US-001-024`	yes	Validate protocol_version is valid semver	1
`REQ-004-US-001-025`	yes	Add type hints to all packet fields	1
`REQ-004-US-001-026`	yes	Use Pydantic for runtime validation	none
`REQ-004-US-001-027`	yes	Implement init with field validation	1
`REQ-004-US-001-028`	yes	Implement repr for debugging	1
`REQ-004-US-001-029`	yes	Implement eq for comparison	1
`REQ-004-US-001-030`	yes	Implement hash for dict keys	none
`REQ-004-US-002-001`	yes	Implement get_headers() method returning dict	6
`REQ-004-US-002-002`	yes	Extract message_id to header	2
`REQ-004-US-002-003`	yes	Extract from_agent to header	2
`REQ-004-US-002-004`	yes	Extract to_agent to header	2
`REQ-004-US-002-005`	yes	Extract thread_id to header	2
`REQ-004-US-002-006`	yes	Extract subject to header	2
`REQ-004-US-002-007`	yes	Extract timestamp to header	2
`REQ-004-US-002-008`	yes	Extract priority to header	2
`REQ-004-US-002-009`	yes	Extract delivery_status to header	1
`REQ-004-US-002-010`	yes	Extract work_status to header	1
`REQ-004-US-002-011`	yes	Extract protocol_version to header	1
`REQ-004-US-002-012`	yes	Header extraction completes in <1ms	1
`REQ-004-US-002-013`	yes	Validate all required headers present	2
`REQ-004-US-002-014`	yes	Validate header types are correct	1
`REQ-004-US-002-015`	yes	Validate header values are non-empty	2
`REQ-004-US-002-016`	yes	Reject packets with missing headers	1
`REQ-004-US-002-017`	yes	Reject packets with invalid header types	2
`REQ-004-US-002-018`	yes	Provide detailed error messages for invalid headers	1
`REQ-004-US-002-019`	yes	Implement set_delivery_status() method	1
`REQ-004-US-002-020`	yes	Implement set_work_status() method	1
`REQ-004-US-002-021`	yes	Implement set_priority() method	1
`REQ-004-US-002-022`	yes	Validate new status values	2
`REQ-004-US-002-023`	yes	Prevent modification of immutable headers (message_id, from_agent, to_agent)	none
`REQ-004-US-002-024`	yes	Update timestamp on header modification	none
`REQ-004-US-003-001`	yes	Support JSON object payloads	1
`REQ-004-US-003-002`	yes	Support JSON array payloads	1
`REQ-004-US-003-003`	yes	Support nested JSON structures	1
`REQ-004-US-003-004`	yes	Validate JSON schema when provided	1
`REQ-004-US-003-005`	yes	Handle JSON serialization errors gracefully	2
`REQ-004-US-003-006`	yes	Support Unicode in JSON payloads	none
`REQ-004-US-003-007`	yes	Limit JSON payload size to 10MB	2
`REQ-004-US-003-008`	yes	Support binary payloads (bytes)	2
`REQ-004-US-003-009`	yes	Encode binary as base64 for transport	2
`REQ-004-US-003-010`	yes	Decode base64 to binary on receipt	2
`REQ-004-US-003-011`	yes	Validate binary payload size ≤100MB	2
`REQ-004-US-003-012`	yes	Support content-type metadata for binary	2
`REQ-004-US-003-013`	yes	Handle binary encoding errors gracefully	2
`REQ-004-US-003-014`	yes	Validate payload is not None	none
`REQ-004-US-003-015`	yes	Validate payload type (dict or bytes)	1
`REQ-004-US-003-016`	yes	Validate JSON payload structure	1
`REQ-004-US-003-017`	yes	Validate binary payload encoding	1
`REQ-004-US-003-018`	yes	Reject oversized payloads	2
`REQ-004-US-003-019`	yes	Provide detailed error messages	1
`REQ-004-US-003-020`	yes	Implement get_payload() method	2
`REQ-004-US-003-021`	yes	Implement get_payload_json() for JSON extraction	1
`REQ-004-US-003-022`	yes	Implement get_payload_binary() for binary extraction	1
`REQ-004-US-003-023`	yes	Raise error if payload type mismatch	2
`REQ-004-US-003-024`	yes	Support payload type checking (is_json, is_binary)	3
`REQ-004-US-004-001`	yes	Define DeliveryStatus enum	1
`REQ-004-US-004-002`	yes	Implement QUEUED status	1
`REQ-004-US-004-003`	yes	Implement DELIVERED status	1
`REQ-004-US-004-004`	yes	Implement ACKNOWLEDGED status	1
`REQ-004-US-004-005`	yes	Implement FAILED status	1
`REQ-004-US-004-006`	yes	Validate status transitions	3
`REQ-004-US-004-007`	yes	Allow QUEUED → DELIVERED transition	2
`REQ-004-US-004-008`	yes	Allow DELIVERED → ACKNOWLEDGED transition	2
`REQ-004-US-004-009`	yes	Allow QUEUED → FAILED transition	2
`REQ-004-US-004-010`	yes	Allow DELIVERED → FAILED transition	2
`REQ-004-US-004-011`	yes	Prevent invalid transitions (e.g., ACKNOWLEDGED → QUEUED)	3
`REQ-004-US-004-012`	yes	Record timestamp for each transition	1
`REQ-004-US-004-013`	yes	Log status transitions	none
`REQ-004-US-004-014`	yes	Implement is_queued() method	none
`REQ-004-US-004-015`	yes	Implement is_delivered() method	none
`REQ-004-US-004-016`	yes	Implement is_acknowledged() method	none
`REQ-004-US-004-017`	yes	Implement is_failed() method	none
`REQ-004-US-004-018`	yes	Implement get_delivery_history() method	4
`REQ-004-US-004-019`	yes	Support filtering packets by status	none
`REQ-004-US-004-020`	yes	Record failure reason for FAILED status	4
`REQ-004-US-004-021`	yes	Support retry count tracking	4
`REQ-004-US-004-022`	yes	Implement max retry limit	4
`REQ-004-US-004-023`	yes	Log delivery failures	none
`REQ-004-US-004-024`	yes	Notify sender on delivery failure	1
`REQ-004-US-005-001`	yes	Define WorkStatus enum	1
`REQ-004-US-005-002`	yes	Implement PENDING status	1
`REQ-004-US-005-003`	yes	Implement IN_PROGRESS status	1
`REQ-004-US-005-004`	yes	Implement RESOLVED status	1
`REQ-004-US-005-005`	yes	Implement ARCHIVED status	1
`REQ-004-US-005-006`	yes	Validate status transitions	2
`REQ-004-US-005-007`	yes	Allow PENDING → IN_PROGRESS transition	3
`REQ-004-US-005-008`	yes	Allow IN_PROGRESS → RESOLVED transition	3
`REQ-004-US-005-009`	yes	Allow RESOLVED → ARCHIVED transition	3
`REQ-004-US-005-010`	yes	Allow IN_PROGRESS → PENDING transition (re-queue)	3
`REQ-004-US-005-011`	yes	Prevent invalid transitions (e.g., ARCHIVED → PENDING)	3
`REQ-004-US-005-012`	yes	Record timestamp for each transition	2
`REQ-004-US-005-013`	yes	Log status transitions	none
`REQ-004-US-005-014`	yes	Implement is_pending() method	none
`REQ-004-US-005-015`	yes	Implement is_in_progress() method	none
`REQ-004-US-005-016`	yes	Implement is_resolved() method	none
`REQ-004-US-005-017`	yes	Implement is_archived() method	none
`REQ-004-US-005-018`	yes	Implement get_work_history() method	1
`REQ-004-US-005-019`	yes	Support filtering packets by work status	none
`REQ-004-US-005-020`	yes	Track assigned_to Volk for IN_PROGRESS	none
`REQ-004-US-005-021`	yes	Track resolution result for RESOLVED	none
`REQ-004-US-005-022`	yes	Track resolution timestamp	2
`REQ-004-US-005-023`	yes	Track time_in_progress duration	1
`REQ-004-US-005-024`	yes	Support work notes/comments	none
`REQ-004-US-006-001`	yes	Implement to_json() method	5
`REQ-004-US-006-002`	yes	Serialize all packet fields to JSON	4
`REQ-004-US-006-003`	yes	Handle datetime serialization (ISO8601)	5
`REQ-004-US-006-004`	yes	Handle enum serialization (string values)	5
`REQ-004-US-006-005`	yes	Handle UUID serialization (string)	none
`REQ-004-US-006-006`	yes	Handle binary payload (base64)	2
`REQ-004-US-006-007`	yes	Serialize in <10ms for typical packet	none
`REQ-004-US-006-008`	yes	Validate JSON output is valid	none
`REQ-004-US-006-009`	yes	Implement from_json() class method	5
`REQ-004-US-006-010`	yes	Deserialize all packet fields from JSON	4
`REQ-004-US-006-011`	yes	Parse datetime from ISO8601	6
`REQ-004-US-006-012`	yes	Parse enum from string values	2
`REQ-004-US-006-013`	yes	Parse UUID from string	none
`REQ-004-US-006-014`	yes	Decode binary payload from base64	1
`REQ-004-US-006-015`	yes	Deserialize in <10ms for typical packet	1
`REQ-004-US-006-016`	yes	Validate all required fields present	1
`REQ-004-US-006-017`	yes	Implement to_bytes() method using MessagePack	3
`REQ-004-US-006-018`	yes	Serialize all packet fields to binary	2
`REQ-004-US-006-019`	yes	Binary serialization in <5ms	1
`REQ-004-US-006-020`	yes	Support compression for large payloads	none
`REQ-004-US-006-021`	yes	Implement from_bytes() class method	3
`REQ-004-US-006-022`	yes	Deserialize all packet fields from binary	2
`REQ-004-US-006-023`	yes	Binary deserialization in <5ms	1
`REQ-004-US-006-024`	yes	Support decompression for compressed payloads	1
`REQ-004-US-006-025`	yes	Support pretty-print JSON for debugging	3
`REQ-004-US-006-026`	yes	Support compact JSON for production	1
`REQ-004-US-006-027`	yes	Support serialization with/without payload	none
`REQ-004-US-006-028`	yes	Support partial serialization (headers only)	none
`REQ-004-US-007-001`	yes	Validate all required fields present	2
`REQ-004-US-007-002`	yes	Validate field types match specification	3
`REQ-004-US-007-003`	yes	Validate field value constraints	2
`REQ-004-US-007-004`	yes	Validate enum values	1
`REQ-004-US-007-005`	yes	Validate string lengths	3
`REQ-004-US-007-006`	yes	Validate numeric ranges	2
`REQ-004-US-007-007`	yes	Define JSON schema for CXP packets	1
`REQ-004-US-007-008`	yes	Implement validate() method	4
`REQ-004-US-007-009`	yes	Validate packet against JSON schema	4
`REQ-004-US-007-010`	yes	Validate payload against custom schema (if provided)	4
`REQ-004-US-007-011`	yes	Schema validation in <5ms	1
`REQ-004-US-007-012`	yes	Provide detailed validation errors	3
`REQ-004-US-007-013`	yes	Validate delivery_status consistency with timestamps	none
`REQ-004-US-007-014`	yes	Validate work_status consistency with timestamps	none
`REQ-004-US-007-015`	yes	Validate from_agent ≠ to_agent	1
`REQ-004-US-007-016`	yes	Validate thread_id format	none
`REQ-004-US-007-017`	yes	Validate protocol_version compatibility	2
`REQ-004-US-007-018`	yes	Support custom validator functions	3
`REQ-004-US-007-019`	yes	Register validators per field	2
`REQ-004-US-007-020`	yes	Support validator chains	1
`REQ-004-US-007-021`	yes	Provide validator error messages	2
`REQ-004-US-008-001`	yes	Generate thread_id for new conversations	1
`REQ-004-US-008-002`	yes	Use UUID format for thread_id	1
`REQ-004-US-008-003`	yes	Validate thread_id format	none
`REQ-004-US-008-004`	yes	Support thread_id inheritance (replies use same thread_id)	1
`REQ-004-US-008-005`	yes	Implement get_thread_packets(thread_id) method	3
`REQ-004-US-008-006`	yes	Return packets in chronological order	2
`REQ-004-US-008-007`	yes	Support filtering by sender	none
`REQ-004-US-008-008`	yes	Support filtering by recipient	none
`REQ-004-US-008-009`	yes	Support filtering by status	none
`REQ-004-US-008-010`	yes	Thread correlation in <2ms	1
`REQ-004-US-008-011`	yes	Track thread creation timestamp	2
`REQ-004-US-008-012`	yes	Track thread participants (from_agent, to_agent)	3
`REQ-004-US-008-013`	yes	Track thread message count	2
`REQ-004-US-008-014`	yes	Track thread status (active, resolved, archived)	3
`REQ-004-US-008-015`	yes	Support thread subject tracking	2
`REQ-004-US-008-016`	yes	Create new thread on first message	2
`REQ-004-US-008-017`	yes	Add message to existing thread	3
`REQ-004-US-008-018`	yes	Close thread when work_status = ARCHIVED	2
`REQ-004-US-008-019`	yes	Support thread re-opening	2
`REQ-004-US-008-020`	yes	Archive old threads after 30 days	1
`REQ-004-US-009-001`	yes	Define priority range 0-10	1
`REQ-004-US-009-002`	yes	Implement priority constants (LOW=3, NORMAL=5, HIGH=7, URGENT=10)	2
`REQ-004-US-009-003`	yes	Default priority = 5 (NORMAL)	1
`REQ-004-US-009-004`	yes	Validate priority range	3
`REQ-004-US-009-005`	yes	Sort packets by priority (descending)	3
`REQ-004-US-009-006`	yes	Sort packets by timestamp (ascending) within same priority	3
`REQ-004-US-009-007`	yes	Implement compare_priority() method	none
`REQ-004-US-009-008`	yes	Support priority queue operations	2
`REQ-004-US-009-009`	yes	Implement set_priority() method	1
`REQ-004-US-009-010`	yes	Allow priority increase (escalation)	1
`REQ-004-US-009-011`	yes	Allow priority decrease (demotion)	1
`REQ-004-US-009-012`	yes	Log priority changes	none
`REQ-004-US-009-013`	yes	Prevent priority manipulation attacks	2
`REQ-004-US-009-014`	yes	System messages have URGENT priority	1
`REQ-004-US-009-015`	yes	Error messages have HIGH priority	1
`REQ-004-US-009-016`	yes	User requests have NORMAL priority	1
`REQ-004-US-009-017`	yes	Background tasks have LOW priority	1
`REQ-004-US-009-018`	yes	Support custom priority policies per Volk	none
`REQ-004-US-010-001`	yes	Use semantic versioning (major.minor.patch)	4
`REQ-004-US-010-002`	yes	Current version = 1.0.0	1
`REQ-004-US-010-003`	yes	Validate version format	2
`REQ-004-US-010-004`	yes	Store version in protocol_version field	1
`REQ-004-US-010-005`	yes	Implement check_compatibility(version) method	1
`REQ-004-US-010-006`	yes	Support same major version compatibility	2
`REQ-004-US-010-007`	yes	Reject incompatible major versions	2
`REQ-004-US-010-008`	yes	Support backward compatibility (older clients, newer server)	2
`REQ-004-US-010-009`	yes	Warn on minor version mismatch	2
`REQ-004-US-010-010`	yes	Support protocol version negotiation	1
`REQ-004-US-010-011`	yes	Return supported versions in handshake	1
`REQ-004-US-010-012`	yes	Select highest compatible version	1
`REQ-004-US-010-013`	yes	Fallback to older version if needed	1
`REQ-004-US-010-014`	yes	Log version negotiation results	none
`REQ-004-US-010-015`	yes	Support packet migration from v1.0.0 to v2.0.0	none
`REQ-004-US-010-016`	yes	Implement upgrade_packet() method	none
`REQ-004-US-010-017`	yes	Preserve all existing fields	none
`REQ-004-US-010-018`	yes	Add new fields with defaults	none
`REQ-004-US-010-019`	yes	Log packet upgrades	none
`REQ-004-US-010-020`	yes	Document breaking changes in CHANGELOG.md	none
`REQ-004-US-010-021`	yes	Document migration guides	none
`REQ-004-US-010-022`	yes	Document version compatibility matrix	none
`REQ-004-US-010-023`	yes	Document deprecation timeline	none
`REQ-004-PERF-001`	yes	JSON serialization: <10ms for typical packet (1KB payload)	3
`REQ-004-PERF-002`	yes	JSON deserialization: <10ms for typical packet	1
`REQ-004-PERF-003`	yes	Binary serialization: <5ms for typical packet	1
`REQ-004-PERF-004`	yes	Binary deserialization: <5ms for typical packet	1
`REQ-004-PERF-005`	yes	Large payload (10MB JSON): <100ms serialization	none
`REQ-004-PERF-006`	yes	Field validation: <1ms per packet	none
`REQ-004-PERF-007`	yes	Schema validation: <5ms per packet	3
`REQ-004-PERF-008`	yes	Cross-field validation: <2ms per packet	1
`REQ-004-PERF-009`	yes	Thread correlation: <2ms per lookup	1
`REQ-004-PERF-010`	yes	Packet memory footprint: <10KB (excluding payload)	none
`REQ-004-PERF-011`	yes	Thread metadata: <1KB per thread	1
`REQ-004-PERF-012`	yes	Validation cache: <100KB total	none
`REQ-004-PERF-013`	yes	Support 10,000 packets in memory simultaneously	1
`REQ-004-INTG-001`	yes	Store packet facts in Prolog (Article II)	5
`REQ-004-INTG-002`	yes	Query packets by message_id	none
`REQ-004-INTG-003`	yes	Query packets by thread_id	5
`REQ-004-INTG-004`	yes	Query packets by sender/recipient	none
`REQ-004-INTG-005`	yes	Query packets by status	4
`REQ-004-INTG-006`	yes	Isolate packets per session (Article III)	5
`REQ-004-INTG-007`	yes	Load packets on session resume	none
`REQ-004-INTG-008`	yes	Archive packets on session end	none
`REQ-004-INTG-009`	yes	Support cross-session thread continuation	none
`REQ-004-INTG-010`	yes	Postman accepts CXP packets for delivery	5
`REQ-004-INTG-011`	yes	Postman updates delivery_status	3
`REQ-004-INTG-012`	yes	Postman manages packet queues	6
`REQ-004-INTG-013`	yes	Postman handles delivery failures	3
`REQ-004-INTG-014`	yes	All Volks send CXP packets	none
`REQ-004-INTG-015`	yes	All Volks receive CXP packets	none
`REQ-004-INTG-016`	yes	Volks validate received packets	1
`REQ-004-INTG-017`	yes	Volks acknowledge received packets	2
`REQ-004-SUCC-001`	yes	All 250+ checkboxes in this file are marked	none
`REQ-004-SUCC-002`	yes	All 10 user stories (US-001 to US-010) implemented	none
`REQ-004-SUCC-003`	yes	All performance requirements met	none
`REQ-004-SUCC-004`	yes	All integration requirements satisfied	none
`REQ-004-SUCC-005`	yes	Unit tests passing for all user stories	1
`REQ-004-SUCC-006`	yes	Integration tests passing with Postman and Volks	1
`REQ-004-SUCC-007`	yes	Documentation complete	none

Code that traces this spec

Module	Symbols	Requirements
`orchestrata_ultimate/core/packet/compat`	4	13
`orchestrata_ultimate/core/packet/enums`	3	15
`orchestrata_ultimate/core/packet/exceptions`	2	3
`orchestrata_ultimate/core/packet/packet`	27	46
`orchestrata_ultimate/core/packet/results`	4	2
`orchestrata_ultimate/core/protocols/components`	1	2
`orchestrata_ultimate/cxp/binary_serializer`	5	9
`orchestrata_ultimate/cxp/delivery_status`	7	11
`orchestrata_ultimate/cxp/deterministic_ids`	1	1
`orchestrata_ultimate/cxp/dispatcher`	2	2
`orchestrata_ultimate/cxp/exceptions`	6	8
`orchestrata_ultimate/cxp/headers`	11	31
`orchestrata_ultimate/cxp/interfaces`	34	33
`orchestrata_ultimate/cxp/json_serializer`	10	17
`orchestrata_ultimate/cxp/payload`	13	16
`orchestrata_ultimate/cxp/postman_adapter`	9	8
`orchestrata_ultimate/cxp/priority`	6	9
`orchestrata_ultimate/cxp/prolog_bridge`	8	3
`orchestrata_ultimate/cxp/proto_codec`	1	1
`orchestrata_ultimate/cxp/schema`	10	10
`orchestrata_ultimate/cxp/serializer`	3	3
`orchestrata_ultimate/cxp/session_adapter`	5	1
`orchestrata_ultimate/cxp/threads`	7	16
`orchestrata_ultimate/cxp/types`	4	6
`orchestrata_ultimate/cxp/validator`	12	22
`orchestrata_ultimate/cxp/version`	7	7
`orchestrata_ultimate/cxp/version_compat`	4	10
`orchestrata_ultimate/cxp/work_status`	9	10
`orchestrata_ultimate/gateway/cli`	2	2
`orchestrata_ultimate/postman/postman`	1	4
`orchestrata_ultimate/postman/sync_router`	2	3

Checklists

`checklists/README.md`

CXP Protocol Checklists

Project: Orchestrator-AI CXP Protocol (Spec 004)
Component: Cross-agent eXchange Protocol
Version: 1.0.0
Status: Planning

Overview

The CXP Protocol (Cross-agent eXchange Protocol) is the communication standard for Orchestrata that enables structured, deterministic agent-to-agent messaging with complete delivery and work status tracking.

Core Responsibilities

The CXP Protocol provides:

Structured Packet Format - Standardized message structure with headers and payload
Deterministic Headers - Required fields: TO, FROM, THREAD_ID, SUBJECT
Delivery Status Tracking - queued, delivered, acknowledged, failed
Work Status Tracking - pending, in_progress, resolved, archived
Packet Serialization - JSON and binary serialization with <10ms performance
Packet Validation - Schema validation with <5ms performance
Thread Management - Message correlation and conversation tracking
Priority Ordering - Message prioritization and delivery ordering
Protocol Versioning - Backward compatibility and version negotiation

Checklist Summary

Checklist	Purpose	Checkboxes	Status
requirements.md	Functional requirements (US-001 to US-010)	~250	Not Started
constitutional.md	Constitutional compliance (11 Articles)	~250	Not Started
testing.md	Comprehensive testing plan	~200	Not Started
TOTAL	Complete CXP Protocol implementation	~700	Not Started

CXP Packet Structure

Core Packet Fields

Field	Type	Required	Description
`message_id`	string	Yes	Unique identifier (UUID)
`from_agent`	string	Yes	Sender Volk alias (e.g., "U:Ox")
`to_agent`	string	Yes	Recipient Volk alias (e.g., "U:Vz")
`thread_id`	string	Yes	Conversation thread identifier
`subject`	string	Yes	Message subject line
`payload`	object	Yes	Message content (JSON or binary)
`timestamp`	ISO8601	Yes	Message creation time
`priority`	int	No	Priority level (0-10, default 5)
`delivery_status`	enum	Yes	queued, delivered, acknowledged, failed
`work_status`	enum	Yes	pending, in_progress, resolved, archived
`protocol_version`	string	Yes	CXP protocol version (e.g., "1.0.0")

Example CXP Packet

{
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "from_agent": "U:Ox",
  "to_agent": "U:Vz",
  "thread_id": "thread-001",
  "subject": "Generate UserService Implementation",
  "payload": {
    "task": "generate_code",
    "spec": "UserService with CRUD operations",
    "language": "Python"
  },
  "timestamp": "2026-01-15T10:30:00Z",
  "priority": 8,
  "delivery_status": "delivered",
  "work_status": "in_progress",
  "protocol_version": "1.0.0"
}

Performance Requirements

Operation	Target	Measurement
Packet Serialization	<10ms	JSON encoding of full packet
Packet Deserialization	<10ms	JSON decoding to object
Packet Validation	<5ms	Schema validation
Header Extraction	<1ms	Parse headers from packet
Thread Correlation	<2ms	Match thread_id in history

Usage Guidelines

For Developers

Start with Requirements - Read requirements.md to understand all user stories (US-001 to US-010)
Review Constitutional Compliance - Check constitutional.md for governance rules
Plan Testing - Review testing.md for comprehensive test coverage
Track Progress - Mark checkboxes as you complete each item
Verify Performance - Ensure all performance targets are met

For Reviewers

Completeness Check - Verify all checkboxes are marked
Constitutional Compliance - Ensure all 11 Articles are satisfied
Test Coverage - Confirm 310+ tests are implemented
Performance Validation - Verify all performance targets achieved
Integration Verification - Test with Postman and Volks

Dependencies

Core Dependencies

Python 3.11+ - Modern Python with type hints
Pydantic - Data validation and serialization
Prolog Interface - Packet fact storage (via Article II)
Session Management - Per-session packet isolation (via Article III)

Integration Points

Postman (Spec 002) - Packet delivery and queue management
Volks - All agents send/receive CXP packets
Governance (Spec 003) - Packet authorization and ownership
Session System - Packet persistence and retrieval

Checkpoint Strategy

Git Checkpoints

Create checkpoints after completing:

Requirements Phase - All 10 user stories implemented
Constitutional Phase - All 11 Articles satisfied
Testing Phase - 100+ unit tests passing
Integration Phase - 70+ integration tests passing
Contract Phase - 60 contract tests passing
Performance Phase - All performance targets met
Interoperability Phase - 30+ version compatibility tests passing

Verification Commands

# Run all CXP tests
uv run pytest tests/test_cxp*.py -v

# Test packet serialization performance
uv run pytest tests/test_cxp_performance.py -v

# Test protocol compliance
uv run pytest tests/test_cxp_contract.py -v

# Test version compatibility
uv run pytest tests/test_cxp_interop.py -v

Success Criteria

The CXP Protocol is complete when:

[ ] All ~700 checkboxes across checklists are marked
[ ] All 10 user stories (US-001 to US-010) implemented
[ ] All 11 Constitutional Articles satisfied
[ ] 310+ tests passing (100 unit, 70 integration, 60 contract, 50 performance, 30 interop)
[ ] Serialization <10ms, validation <5ms
[ ] Integrated with Postman for delivery
[ ] Integrated with Prolog for fact storage
[ ] Integrated with Session system for persistence
[ ] Version 1.0.0 protocol specification documented

CXP Protocol Specification - Full protocol specification
Postman Spec (002) - Message delivery system
Governance Spec (003) - Authorization and ownership
Implementation Architecture - Core implementation

Last Updated: 2026-01-15
Next Review: After Requirements Phase

`checklists/SUMMARY.md`

CXP Protocol Checklists Summary

Created: 2026-01-15
Status: Complete - All 4 checklist files created

File Statistics

File	Size	Checkboxes	Purpose
README.md	6.4 KB	9	Overview and usage guidelines
requirements.md	15 KB	273	Functional requirements (US-001 to US-010)
constitutional.md	12 KB	205	Constitutional compliance (11 Articles)
testing.md	19 KB	340	Comprehensive testing plan (310+ tests)
TOTAL	52.4 KB	827	Complete CXP Protocol implementation

Checkbox Breakdown by File

requirements.md (273 checkboxes)

US-001: Packet Format and Structure (26 checks)
US-002: Header Management (21 checks)
US-003: Payload Handling (25 checks)
US-004: Delivery Status Tracking (29 checks)
US-005: Work Status Tracking (29 checks)
US-006: Packet Serialization/Deserialization (38 checks)
US-007: Packet Validation and Schema (30 checks)
US-008: Thread Management and Correlation (23 checks)
US-009: Priority and Ordering (24 checks)
US-010: CXP Protocol Versioning (28 checks)

constitutional.md (205 checkboxes)

Article I: Sessions Are Unit Of Work (16 checks)
Article II: Prolog Is Source Of Truth (20 checks)
Article III: Sessions Isolate State (16 checks)
Article IV: Adapters Abstract LLMs (16 checks)
Article V: Volks Embody Personas (16 checks)
Article VI: CXP Governs Exchange (16 checks)
Article VII: No Mocking In Tests (23 checks)
Article VIII: Dependency Injection (12 checks)
Article IX: Logging Is Mandatory (20 checks)
Article X: Governance Via PAM++ (16 checks)
Article XI: Container Native (16 checks)

testing.md (340 checkboxes)

Unit Tests (140 tests across 6 test files)
- test_cxp_packet.py (30 tests)
- test_cxp_serialization.py (25 tests)
- test_cxp_validation.py (25 tests)
- test_cxp_headers.py (20 tests)
- test_cxp_status.py (20 tests)
- test_cxp_threads.py (20 tests)
Integration Tests (70 tests)
- test_cxp_integration.py (70 tests)
Contract Tests (60 tests)
- test_cxp_contract.py (60 tests)
Performance Tests (50 tests)
- test_cxp_performance.py (50 tests)
Interoperability Tests (30 tests)
- test_cxp_interop.py (30 tests)

Implementation Phases

Phase 1: Requirements (requirements.md)

Goal: Implement all 10 user stories
Checkboxes: 273
Estimated: 2-3 weeks

Key deliverables:

CXPPacket base class with all fields
Header management (extraction, validation, modification)
Payload handling (JSON, binary)
Status tracking (delivery, work)
Serialization/deserialization (JSON, binary)
Validation and schema
Thread management
Priority ordering
Protocol versioning

Phase 2: Constitutional Compliance (constitutional.md)

Goal: Satisfy all 11 Articles
Checkboxes: 205
Estimated: 1-2 weeks

Key deliverables:

Session isolation for packets
Prolog fact storage
LLM adapter integration
Volk identification and authorization
Protocol enforcement (CXP-only communication)
No mocking in tests
Dependency injection
Comprehensive logging
PAM++ governance integration
Container-native deployment

Phase 3: Testing (testing.md)

Goal: Implement 310+ tests
Checkboxes: 340
Estimated: 2-3 weeks

Key deliverables:

140 unit tests (packet, serialization, validation, headers, status, threads)
70 integration tests (Postman, Volks, Prolog, Session, Adapter)
60 contract tests (schema, protocol version, interoperability)
50 performance tests (serialization, validation, throughput, latency)
30 interoperability tests (cross-language, version compatibility)

Success Metrics

The CXP Protocol is complete when:

[x] All 4 checklist files created (DONE)
[ ] All 827 checkboxes marked complete
[ ] All 10 user stories implemented
[ ] All 11 Constitutional Articles satisfied
[ ] All 310+ tests passing
[ ] Performance targets met:
- Serialization <10ms (JSON), <5ms (binary)
- Validation <5ms
- Thread correlation <2ms
- Header extraction <1ms
[ ] Integration complete:
- Postman delivery working
- Prolog fact storage working
- Session isolation working
- Volk communication working
[ ] Documentation complete:
- Protocol specification
- API documentation
- Usage examples
- Migration guide

Quick Reference

Key Performance Targets

Operation	Target	Test File
JSON Serialization	<10ms	test_cxp_performance.py
Binary Serialization	<5ms	test_cxp_performance.py
Validation	<5ms	test_cxp_performance.py
Thread Correlation	<2ms	test_cxp_performance.py
Header Extraction	<1ms	test_cxp_headers.py

Core Packet Fields

Field	Type	Required	Description
message_id	UUID	Yes	Unique identifier
from_agent	string	Yes	Sender Volk alias
to_agent	string	Yes	Recipient Volk alias
thread_id	string	Yes	Conversation thread
subject	string	Yes	Message subject
payload	object	Yes	Message content
timestamp	ISO8601	Yes	Creation time
priority	int	No	Priority level (0-10)
delivery_status	enum	Yes	Delivery state
work_status	enum	Yes	Work state
protocol_version	semver	Yes	Protocol version

Test Execution Commands

# All tests
uv run pytest tests/test_cxp*.py -v

# Unit tests only
uv run pytest tests/test_cxp_packet.py tests/test_cxp_serialization.py tests/test_cxp_validation.py -v

# Integration tests
uv run pytest tests/test_cxp_integration.py -v

# Performance tests
uv run pytest tests/test_cxp_performance.py -v

# With coverage
uv run pytest tests/test_cxp*.py --cov=src/cxp --cov-report=html -v

Spec 002: Postman - Message delivery system
Spec 003: Governance - Authorization and ownership
Spec 005: Session - Session management (planned)
Spec 006: Prolog - Prolog interface (planned)

Last Updated: 2026-01-15
Next Review: After Phase 1 completion

`checklists/constitutional.md`

CXP Protocol Constitutional Compliance Checklist

Project: Orchestrator-AI CXP Protocol (Spec 004)
Component: Cross-agent eXchange Protocol
Version: 1.0.0

Overview

This checklist ensures the CXP Protocol implementation complies with all 11 Articles of the Orchestrata Constitution. Each Article includes specific compliance checks for packet structure, serialization, validation, and integration.

Total Articles: 11
Total Checkboxes: ~250

Article I: Sessions Are Unit Of Work

Principle: All packet operations are scoped to sessions.

Session Isolation

[ ] Packets are isolated per session
[ ] Session ID is recorded with each packet
[ ] Cross-session packet queries require explicit session ID
[ ] Session boundaries prevent packet leakage

Session Lifecycle

[ ] Packets created during session are stored in session context
[ ] Session start loads previous packets (carryover)
[ ] Session end archives packets to portfolio
[ ] Session resume restores packet state

Session Context

[ ] CXP packets stored in session.facts
[ ] Session context includes active threads
[ ] Session handover includes packet history
[ ] Session archive preserves all packets

Session Testing

[ ] Test packet isolation between sessions
[ ] Test packet carryover to next session
[ ] Test packet archival on session end
[ ] Test packet restoration on session resume

Article II: Prolog Is Source Of Truth

Principle: All CXP packet facts are stored in Prolog.

Packet Facts

[ ] Define cxp_packet/12 Prolog predicate
[ ] Store message_id, from_agent, to_agent, thread_id in Prolog
[ ] Store subject, timestamp, priority in Prolog
[ ] Store delivery_status, work_status in Prolog
[ ] Store protocol_version in Prolog
[ ] Store payload reference (not full payload)

Fact Assertions

[ ] Assert packet fact on packet creation
[ ] Assert packet fact on packet receipt
[ ] Retract old fact on status update
[ ] Assert new fact with updated status

Fact Queries

[ ] Query packets by message_id
[ ] Query packets by thread_id
[ ] Query packets by sender (from_agent)
[ ] Query packets by recipient (to_agent)
[ ] Query packets by delivery_status
[ ] Query packets by work_status
[ ] Query packets by priority
[ ] Query packets by timestamp range

Fact Persistence

[ ] Prolog facts persisted across sessions (via portfolio)
[ ] Prolog facts loaded on session resume
[ ] Prolog facts archived on session end
[ ] Prolog facts restored from archive

Prolog Testing

[ ] Test packet fact assertion
[ ] Test packet fact retraction
[ ] Test packet fact queries (all query types)
[ ] Test packet fact persistence

Article III: Sessions Isolate State

Principle: Packet state is isolated per session.

State Boundaries

[ ] Packet state stored in session namespace
[ ] Cross-session queries require explicit session ID
[ ] No implicit state sharing between sessions
[ ] Session boundaries enforced at runtime

State Transitions

[ ] Packet status changes confined to session
[ ] Thread state isolated per session
[ ] Delivery tracking isolated per session
[ ] Work tracking isolated per session

State Carryover

[ ] Active threads carried over to next session
[ ] Unresolved packets carried over to next session
[ ] Resolved packets archived (not carried over)
[ ] Failed packets logged and carried over for retry

State Testing

[ ] Test packet state isolation
[ ] Test cross-session query enforcement
[ ] Test state carryover logic
[ ] Test state archival on session end

Article IV: Adapters Abstract LLMs

Principle: CXP Protocol is LLM-agnostic.

LLM Independence

[ ] CXP packet structure independent of LLM provider
[ ] Packet serialization works with any LLM
[ ] Packet validation independent of LLM
[ ] Packet delivery independent of LLM

Adapter Integration

[ ] Adapters can send CXP packets to any LLM
[ ] Adapters can receive CXP packets from any LLM
[ ] Adapters translate LLM responses to CXP packets
[ ] Adapters handle LLM-specific errors

Multi-LLM Support

[ ] Support Claude adapter sending CXP packets
[ ] Support OpenAI adapter sending CXP packets
[ ] Support Gemini adapter sending CXP packets
[ ] Support local LLM adapter sending CXP packets

Adapter Testing

[ ] Test CXP with Claude adapter
[ ] Test CXP with OpenAI adapter
[ ] Test CXP with Gemini adapter
[ ] Test CXP with local LLM adapter

Article V: Volks Embody Personas

Principle: CXP packets enforce Volk identities.

Volk Identification

[ ] from_agent field contains Volk alias (e.g., "U:Ox")
[ ] to_agent field contains Volk alias
[ ] Validate from_agent matches sender Volk
[ ] Validate to_agent matches recipient Volk

Volk Authorization

[ ] Check sender Volk is authorized to send packets
[ ] Check recipient Volk is authorized to receive packets
[ ] Check subject matches Volk responsibilities
[ ] Check payload type matches Volk capabilities

Volk Routing

[ ] Route packets based on to_agent field
[ ] Validate routing rules per PAM++
[ ] Handle routing errors (invalid to_agent)
[ ] Log routing decisions

Volk Testing

[ ] Test packet from each Volk type (Ox, PS, Vz, Ux, PM, Ar, Qa, Cx)
[ ] Test packet routing to each Volk type
[ ] Test authorization checks
[ ] Test routing error handling

Article VI: CXP Governs Exchange

Principle: CXP is the sole communication protocol.

Protocol Enforcement

[ ] All agent-to-agent communication uses CXP packets
[ ] No direct function calls between agents
[ ] No shared memory between agents
[ ] All messages go through Postman

Protocol Compliance

[ ] Reject non-CXP messages
[ ] Validate CXP packet format
[ ] Enforce required headers
[ ] Enforce protocol version

Protocol Monitoring

[ ] Log all packet sends
[ ] Log all packet receives
[ ] Log protocol violations
[ ] Alert on repeated violations

Protocol Testing

[ ] Test CXP-only communication
[ ] Test rejection of non-CXP messages
[ ] Test protocol validation
[ ] Test protocol violation logging

Article VII: No Mocking In Tests

Principle: Test with real CXP serialization and delivery.

Real Serialization

[ ] No mocking of to_json() method
[ ] No mocking of from_json() method
[ ] No mocking of to_bytes() method
[ ] No mocking of from_bytes() method
[ ] Test actual JSON serialization
[ ] Test actual binary serialization

Real Validation

[ ] No mocking of validate() method
[ ] No mocking of schema validation
[ ] Test actual validation logic
[ ] Test actual validation errors

Real Delivery

[ ] No mocking of Postman delivery
[ ] Test actual packet queuing
[ ] Test actual packet delivery
[ ] Test actual delivery status updates

Real Integration

[ ] No mocking of Prolog interface
[ ] Test actual fact assertion
[ ] Test actual fact queries
[ ] Test actual session integration

Testing Standards

[ ] All tests use real CXP packets
[ ] All tests use real serialization
[ ] All tests use real validation
[ ] All tests use real delivery (or test doubles, not mocks)

Article VIII: Dependency Injection

Principle: CXP components are injectable.

Injectable Components

[ ] CXPPacket class is injectable
[ ] CXPSerializer is injectable
[ ] CXPValidator is injectable
[ ] CXPThreadManager is injectable

DI Container

[ ] Register CXP components in DI container
[ ] Resolve CXP components via DI
[ ] Support multiple CXP implementations
[ ] Support test doubles via DI

DI Testing

[ ] Test component registration
[ ] Test component resolution
[ ] Test dependency injection
[ ] Test component lifecycle

Article IX: Logging Is Mandatory

Principle: All CXP operations are logged.

Packet Logging

[ ] Log packet creation with all fields
[ ] Log packet send (from_agent, to_agent, message_id)
[ ] Log packet receipt (to_agent, from_agent, message_id)
[ ] Log packet validation (success/failure)

Status Logging

[ ] Log delivery status changes
[ ] Log work status changes
[ ] Log priority changes
[ ] Log thread creation/closure

Error Logging

[ ] Log serialization errors
[ ] Log deserialization errors
[ ] Log validation errors
[ ] Log delivery errors

Performance Logging

[ ] Log serialization time
[ ] Log validation time
[ ] Log delivery time
[ ] Log thread correlation time

Logging Compliance

[ ] All logs include timestamp
[ ] All logs include session_id
[ ] All logs include message_id
[ ] All logs are structured (JSON)

Article X: Governance Via PAM++

Principle: CXP respects PAM++ ownership rules.

Ownership Validation

[ ] Check sender owns subject component (per PAM++)
[ ] Check recipient owns target component (per PAM++)
[ ] Check sender is authorized to send to recipient
[ ] Check recipient is authorized to receive from sender

Escalation Handling

[ ] Support escalation via priority increase
[ ] Route escalated packets to authorized recipients
[ ] Log escalation decisions
[ ] Validate escalation authority

Component Boundaries

[ ] Enforce component ownership in packet routing
[ ] Reject packets violating ownership rules
[ ] Log ownership violations
[ ] Alert on repeated ownership violations

Governance Testing

[ ] Test ownership validation
[ ] Test escalation routing
[ ] Test component boundary enforcement
[ ] Test ownership violation logging

Article XI: Container Native

Principle: CXP Protocol works in containerized environments.

Container Deployment

[ ] CXP serialization works in Docker
[ ] CXP serialization works in Kubernetes
[ ] CXP delivery works across container boundaries
[ ] CXP thread state persists across container restarts

Network Communication

[ ] Support packet transmission over gRPC
[ ] Support packet transmission over WebSocket
[ ] Support packet transmission over HTTP/2
[ ] Handle network timeouts and retries

State Persistence

[ ] Persist packet state to external storage (Redis/PostgreSQL)
[ ] Load packet state on container restart
[ ] Support distributed packet queues
[ ] Support distributed thread management

Container Testing

[ ] Test CXP in Docker container
[ ] Test CXP in Kubernetes pod
[ ] Test CXP across container network
[ ] Test CXP state persistence

Constitutional Success Criteria

All Articles are satisfied when:

[ ] All 250+ checkboxes in this file are marked
[ ] All Article I (Sessions) checks pass
[ ] All Article II (Prolog) checks pass
[ ] All Article III (Isolation) checks pass
[ ] All Article IV (Adapters) checks pass
[ ] All Article V (Volks) checks pass
[ ] All Article VI (CXP) checks pass
[ ] All Article VII (No Mocking) checks pass
[ ] All Article VIII (DI) checks pass
[ ] All Article IX (Logging) checks pass
[ ] All Article X (PAM++) checks pass
[ ] All Article XI (Container) checks pass
[ ] Constitutional compliance tests passing (60+ tests)

Last Updated: 2026-01-15
Next Review: After Testing Phase

`checklists/requirements.md`

The requirement list above comes from this file; 273 of 273 checkbox items are ticked.

`checklists/testing.md`

CXP Protocol Testing Checklist

Project: Orchestrator-AI CXP Protocol (Spec 004)
Component: Cross-agent eXchange Protocol
Version: 1.0.0

Overview

This checklist tracks all testing requirements for the CXP Protocol. Tests are organized by category: Unit, Integration, Contract, Performance, and Interoperability.

Total Test Categories: 5
Total Tests: 310+
Total Checkboxes: ~200

Test File Structure

tests/
├── test_cxp_packet.py           # Unit tests for CXPPacket class (30 tests)
├── test_cxp_serialization.py    # Unit tests for serialization (25 tests)
├── test_cxp_validation.py       # Unit tests for validation (25 tests)
├── test_cxp_headers.py          # Unit tests for header management (20 tests)
├── test_cxp_status.py           # Unit tests for status tracking (20 tests)
├── test_cxp_threads.py          # Unit tests for thread management (20 tests)
├── test_cxp_integration.py      # Integration tests with Postman/Volks (70 tests)
├── test_cxp_contract.py         # Contract tests for protocol compliance (60 tests)
├── test_cxp_performance.py      # Performance tests (50 tests)
└── test_cxp_interop.py          # Interoperability tests (30 tests)

Unit Tests (140 tests)

test_cxp_packet.py (30 tests)

Packet Creation

[ ] Test create packet with all required fields
[ ] Test create packet with optional fields
[ ] Test create packet with default values
[ ] Test packet ID generation (UUID)
[ ] Test packet timestamp generation (ISO8601)

Packet Validation

[ ] Test validate required fields present
[ ] Test reject missing message_id
[ ] Test reject missing from_agent
[ ] Test reject missing to_agent
[ ] Test reject missing thread_id
[ ] Test reject missing subject
[ ] Test reject missing payload
[ ] Test reject invalid Volk alias format
[ ] Test reject invalid UUID format
[ ] Test reject invalid timestamp format

Packet Comparison

[ ] Test packet equality by message_id
[ ] Test packet inequality
[ ] Test packet hash for dict keys
[ ] Test packet ordering by priority
[ ] Test packet ordering by timestamp

Packet Representation

[ ] Test packet repr includes all fields
[ ] Test packet str is readable
[ ] Test packet to_dict() method
[ ] Test packet from_dict() method

Edge Cases

[ ] Test packet with empty subject (rejected)
[ ] Test packet with very long subject (>200 chars, rejected)
[ ] Test packet with same from_agent and to_agent (rejected)
[ ] Test packet with None payload (rejected)
[ ] Test packet with invalid priority (rejected)
[ ] Test packet with invalid status enum (rejected)

test_cxp_serialization.py (25 tests)

JSON Serialization

[ ] Test serialize packet to JSON
[ ] Test serialize packet with JSON payload
[ ] Test serialize packet with binary payload (base64)
[ ] Test serialize datetime to ISO8601
[ ] Test serialize UUID to string
[ ] Test serialize enums to string
[ ] Test JSON serialization <10ms
[ ] Test pretty-print JSON
[ ] Test compact JSON

JSON Deserialization

[ ] Test deserialize packet from JSON
[ ] Test deserialize JSON payload
[ ] Test deserialize binary payload (base64)
[ ] Test deserialize datetime from ISO8601
[ ] Test deserialize UUID from string
[ ] Test deserialize enums from string
[ ] Test JSON deserialization <10ms
[ ] Test reject invalid JSON

Binary Serialization

[ ] Test serialize packet to binary (MessagePack)
[ ] Test binary serialization <5ms
[ ] Test compress large payloads
[ ] Test deserialize packet from binary
[ ] Test binary deserialization <5ms
[ ] Test decompress large payloads

Serialization Options

[ ] Test serialize headers only
[ ] Test serialize without payload
[ ] Test partial serialization

test_cxp_validation.py (25 tests)

Field Validation

[ ] Test validate message_id (UUID format)
[ ] Test validate from_agent (Volk alias pattern)
[ ] Test validate to_agent (Volk alias pattern)
[ ] Test validate thread_id (non-empty)
[ ] Test validate subject (non-empty, max 200 chars)
[ ] Test validate payload (JSON or bytes)
[ ] Test validate timestamp (ISO8601)
[ ] Test validate priority (0-10 range)
[ ] Test validate delivery_status (enum)
[ ] Test validate work_status (enum)
[ ] Test validate protocol_version (semver)

Schema Validation

[ ] Test validate against JSON schema
[ ] Test validate custom payload schema
[ ] Test schema validation <5ms
[ ] Test reject invalid schema

Cross-Field Validation

[ ] Test validate from_agent ≠ to_agent
[ ] Test validate delivery_status consistency with timestamp
[ ] Test validate work_status consistency with timestamp
[ ] Test validate thread_id format

Custom Validators

[ ] Test register custom validator
[ ] Test validator chain execution
[ ] Test validator error messages

Edge Cases

[ ] Test validate packet with extra fields (allowed)
[ ] Test validate packet with missing optional fields (allowed)
[ ] Test validate malformed packet (rejected)

test_cxp_headers.py (20 tests)

Header Extraction

[ ] Test get_headers() returns all headers
[ ] Test header extraction <1ms
[ ] Test extract message_id
[ ] Test extract from_agent
[ ] Test extract to_agent
[ ] Test extract thread_id
[ ] Test extract subject
[ ] Test extract timestamp
[ ] Test extract priority
[ ] Test extract delivery_status
[ ] Test extract work_status
[ ] Test extract protocol_version

Header Modification

[ ] Test set_delivery_status()
[ ] Test set_work_status()
[ ] Test set_priority()
[ ] Test prevent modification of immutable headers
[ ] Test update timestamp on modification

Header Validation

[ ] Test validate all required headers present
[ ] Test validate header types
[ ] Test reject missing headers

test_cxp_status.py (20 tests)

Delivery Status

[ ] Test set delivery_status to QUEUED
[ ] Test set delivery_status to DELIVERED
[ ] Test set delivery_status to ACKNOWLEDGED
[ ] Test set delivery_status to FAILED
[ ] Test valid status transitions (QUEUED → DELIVERED)
[ ] Test invalid status transitions (ACKNOWLEDGED → QUEUED)
[ ] Test is_queued() method
[ ] Test is_delivered() method
[ ] Test is_acknowledged() method
[ ] Test is_failed() method

Work Status

[ ] Test set work_status to PENDING
[ ] Test set work_status to IN_PROGRESS
[ ] Test set work_status to RESOLVED
[ ] Test set work_status to ARCHIVED
[ ] Test valid status transitions (PENDING → IN_PROGRESS)
[ ] Test invalid status transitions (ARCHIVED → PENDING)
[ ] Test is_pending() method
[ ] Test is_in_progress() method
[ ] Test is_resolved() method
[ ] Test is_archived() method

test_cxp_threads.py (20 tests)

Thread Management

[ ] Test generate new thread_id (UUID)
[ ] Test get_thread_packets() by thread_id
[ ] Test thread packets in chronological order
[ ] Test filter thread packets by sender
[ ] Test filter thread packets by recipient
[ ] Test filter thread packets by status
[ ] Test thread correlation <2ms

Thread Metadata

[ ] Test track thread creation timestamp
[ ] Test track thread participants
[ ] Test track thread message count
[ ] Test track thread status (active, resolved, archived)

Thread Lifecycle

[ ] Test create new thread on first message
[ ] Test add message to existing thread
[ ] Test close thread when work_status = ARCHIVED
[ ] Test re-open closed thread
[ ] Test archive old threads after 30 days

Edge Cases

[ ] Test thread with single message
[ ] Test thread with 100+ messages
[ ] Test thread with multiple participants

Integration Tests (70 tests)

test_cxp_integration.py (70 tests)

Postman Integration

[ ] Test send packet via Postman
[ ] Test Postman queues packet
[ ] Test Postman delivers packet
[ ] Test Postman updates delivery_status
[ ] Test Postman handles delivery failure
[ ] Test Postman retries failed delivery
[ ] Test Postman respects priority ordering
[ ] Test Postman logs all operations

Volk Integration

[ ] Test Orchestrator (U:Ox) sends packet
[ ] Test Postman (U:PS) sends packet
[ ] Test VizInt (U:Vz) sends packet
[ ] Test UX (U:Ux) sends packet
[ ] Test PM (U:PM) sends packet
[ ] Test Architect (U:Ar) sends packet
[ ] Test QA (U:Qa) sends packet
[ ] Test Concierge (U:Cx) sends packet
[ ] Test each Volk receives packet
[ ] Test each Volk validates received packet
[ ] Test each Volk acknowledges received packet

Prolog Integration

[ ] Test assert packet fact on creation
[ ] Test query packet by message_id
[ ] Test query packets by thread_id
[ ] Test query packets by sender
[ ] Test query packets by recipient
[ ] Test query packets by delivery_status
[ ] Test query packets by work_status
[ ] Test retract packet fact on status update
[ ] Test packet fact persistence

Session Integration

[ ] Test packet isolation per session
[ ] Test packet carryover to next session
[ ] Test packet archival on session end
[ ] Test packet restoration on session resume
[ ] Test cross-session thread continuation
[ ] Test session boundary enforcement

Adapter Integration

[ ] Test send packet via Claude adapter
[ ] Test send packet via OpenAI adapter
[ ] Test receive packet from Claude adapter
[ ] Test receive packet from OpenAI adapter
[ ] Test adapter translates LLM response to packet

Thread Integration

[ ] Test create new thread
[ ] Test add message to thread
[ ] Test query thread history
[ ] Test thread participants
[ ] Test close thread
[ ] Test re-open thread

Priority Integration

[ ] Test high-priority packet delivered first
[ ] Test urgent system messages
[ ] Test priority escalation
[ ] Test priority demotion

Error Integration

[ ] Test handle invalid packet (reject)
[ ] Test handle delivery failure (retry)
[ ] Test handle serialization error (log)
[ ] Test handle validation error (reject)

Performance Integration

[ ] Test handle 100 packets/second
[ ] Test handle 1000 packets/second
[ ] Test handle 10,000 packets in memory
[ ] Test thread correlation with 100+ threads

End-to-End Scenarios

[ ] Test full conversation (Cx → Ox → Vz → Cx)
[ ] Test escalation scenario (Vz → Ox → Ar)
[ ] Test parallel tasks (Ox → Vz, Ox → Ux, Ox → PM)
[ ] Test error recovery (failed delivery, retry, success)

Contract Tests (60 tests)

test_cxp_contract.py (60 tests)

Schema Compliance

[ ] Test packet conforms to JSON schema
[ ] Test all required fields present
[ ] Test field types match schema
[ ] Test enum values match schema
[ ] Test reject extra required fields

Protocol Version Compliance

[ ] Test v1.0.0 packet format
[ ] Test v1.0.0 serialization
[ ] Test v1.0.0 deserialization
[ ] Test v1.0.0 validation

Header Contract

[ ] Test message_id is UUID
[ ] Test from_agent matches Volk alias pattern
[ ] Test to_agent matches Volk alias pattern
[ ] Test thread_id is non-empty
[ ] Test subject is non-empty
[ ] Test timestamp is ISO8601
[ ] Test priority is 0-10
[ ] Test delivery_status is enum
[ ] Test work_status is enum
[ ] Test protocol_version is semver

Payload Contract

[ ] Test JSON payload is valid JSON
[ ] Test binary payload is bytes
[ ] Test payload size ≤10MB (JSON)
[ ] Test payload size ≤100MB (binary)

Status Contract

[ ] Test delivery_status values (queued, delivered, acknowledged, failed)
[ ] Test work_status values (pending, in_progress, resolved, archived)
[ ] Test valid status transitions
[ ] Test invalid status transitions rejected

Serialization Contract

[ ] Test to_json() returns valid JSON string
[ ] Test from_json() accepts valid JSON string
[ ] Test to_bytes() returns bytes
[ ] Test from_bytes() accepts bytes
[ ] Test round-trip serialization (packet → JSON → packet)
[ ] Test round-trip binary serialization (packet → bytes → packet)

Validation Contract

[ ] Test validate() returns True for valid packet
[ ] Test validate() returns False for invalid packet
[ ] Test validate() provides error messages
[ ] Test schema validation enforces required fields
[ ] Test schema validation enforces field types

Threading Contract

[ ] Test thread_id is consistent across messages
[ ] Test thread_id is UUID format
[ ] Test get_thread_packets() returns chronological order
[ ] Test thread participants tracked

Priority Contract

[ ] Test priority is integer 0-10
[ ] Test priority defaults to 5
[ ] Test priority ordering (high priority first)

Interoperability Contract

[ ] Test packet sent by Python received by Go
[ ] Test packet sent by Go received by Python
[ ] Test packet sent by Rust received by Python
[ ] Test protocol version negotiation

Backward Compatibility Contract

[ ] Test v1.0.0 packet readable by v1.1.0
[ ] Test v1.1.0 packet readable by v1.0.0 (with warnings)
[ ] Test v2.0.0 packet rejected by v1.0.0

Performance Tests (50 tests)

test_cxp_performance.py (50 tests)

Serialization Performance

[ ] Test JSON serialization <10ms (1KB payload)
[ ] Test JSON serialization <50ms (10KB payload)
[ ] Test JSON serialization <100ms (100KB payload)
[ ] Test JSON serialization <1000ms (10MB payload)
[ ] Test binary serialization <5ms (1KB payload)
[ ] Test binary serialization <25ms (10KB payload)
[ ] Test binary serialization <50ms (100KB payload)

Deserialization Performance

[ ] Test JSON deserialization <10ms (1KB payload)
[ ] Test JSON deserialization <50ms (10KB payload)
[ ] Test JSON deserialization <100ms (100KB payload)
[ ] Test binary deserialization <5ms (1KB payload)
[ ] Test binary deserialization <25ms (10KB payload)

Validation Performance

[ ] Test field validation <1ms
[ ] Test schema validation <5ms (simple schema)
[ ] Test schema validation <10ms (complex schema)
[ ] Test cross-field validation <2ms

Thread Performance

[ ] Test thread correlation <2ms (10 messages)
[ ] Test thread correlation <5ms (100 messages)
[ ] Test thread correlation <20ms (1000 messages)
[ ] Test get_thread_packets() <10ms (100 messages)

Query Performance

[ ] Test query by message_id <1ms
[ ] Test query by thread_id <5ms (10 messages)
[ ] Test query by sender <10ms (100 messages)
[ ] Test query by recipient <10ms (100 messages)
[ ] Test query by status <10ms (100 messages)

Throughput Performance

[ ] Test serialize 100 packets/second
[ ] Test serialize 1000 packets/second
[ ] Test deserialize 100 packets/second
[ ] Test deserialize 1000 packets/second
[ ] Test validate 100 packets/second
[ ] Test validate 1000 packets/second

Memory Performance

[ ] Test packet memory footprint <10KB (excluding payload)
[ ] Test 1000 packets in memory <10MB (excluding payloads)
[ ] Test 10,000 packets in memory <100MB (excluding payloads)
[ ] Test thread metadata <1KB per thread
[ ] Test 1000 threads in memory <1MB

Latency Performance

[ ] Test end-to-end latency <50ms (create, serialize, deserialize, validate)
[ ] Test delivery latency <100ms (send via Postman)
[ ] Test acknowledgment latency <150ms (send, deliver, acknowledge)

Stress Tests

[ ] Test handle 10,000 packets without crash
[ ] Test handle 100 concurrent threads
[ ] Test handle 1000 packets/thread
[ ] Test handle 1MB payload serialization
[ ] Test handle 10MB payload serialization
[ ] Test handle 100MB payload serialization

Interoperability Tests (30 tests)

test_cxp_interop.py (30 tests)

Cross-Language Interop

[ ] Test Python → Go packet transmission
[ ] Test Go → Python packet transmission
[ ] Test Python → Rust packet transmission
[ ] Test Rust → Python packet transmission
[ ] Test Python → TypeScript packet transmission
[ ] Test TypeScript → Python packet transmission

Version Compatibility

[ ] Test v1.0.0 → v1.0.1 compatibility
[ ] Test v1.0.1 → v1.0.0 compatibility
[ ] Test v1.0.0 → v1.1.0 compatibility (backward)
[ ] Test v1.1.0 → v1.0.0 compatibility (forward, with warnings)
[ ] Test v1.0.0 → v2.0.0 incompatibility (rejected)
[ ] Test v2.0.0 → v1.0.0 incompatibility (rejected)

Protocol Negotiation

[ ] Test negotiate v1.0.0 when both support v1.0.0
[ ] Test negotiate v1.1.0 when both support v1.1.0
[ ] Test negotiate v1.0.0 when one supports v1.0.0, other v1.1.0
[ ] Test negotiate highest common version
[ ] Test reject connection when no common version

Encoding Compatibility

[ ] Test UTF-8 encoding in JSON payloads
[ ] Test UTF-16 encoding in JSON payloads
[ ] Test binary encoding compatibility
[ ] Test base64 encoding consistency

Timestamp Compatibility

[ ] Test ISO8601 timestamp parsing (Python)
[ ] Test ISO8601 timestamp parsing (Go)
[ ] Test timestamp timezone handling (UTC)
[ ] Test timestamp timezone conversion

Enum Compatibility

[ ] Test delivery_status enum serialization (Python → Go)
[ ] Test work_status enum serialization (Python → Go)
[ ] Test enum deserialization (Go → Python)

Edge Cases

[ ] Test very long subject (199 chars, at limit)
[ ] Test very large payload (9.9MB JSON, at limit)
[ ] Test minimal packet (required fields only)
[ ] Test maximal packet (all optional fields)

Test Execution

Run All Tests

uv run pytest tests/test_cxp*.py -v

Run Unit Tests

uv run pytest tests/test_cxp_packet.py tests/test_cxp_serialization.py tests/test_cxp_validation.py tests/test_cxp_headers.py tests/test_cxp_status.py tests/test_cxp_threads.py -v

Run Integration Tests

uv run pytest tests/test_cxp_integration.py -v

Run Contract Tests

uv run pytest tests/test_cxp_contract.py -v

Run Performance Tests

uv run pytest tests/test_cxp_performance.py -v

Run Interoperability Tests

uv run pytest tests/test_cxp_interop.py -v

Run with Coverage

uv run pytest tests/test_cxp*.py --cov=src/cxp --cov-report=html -v

Testing Success Criteria

All testing is complete when:

[ ] All 200+ checkboxes in this file are marked
[ ] All 140 unit tests passing
[ ] All 70 integration tests passing
[ ] All 60 contract tests passing
[ ] All 50 performance tests passing
[ ] All 30 interoperability tests passing
[ ] Total 350+ tests passing
[ ] Test coverage ≥95% for CXP modules
[ ] All performance targets met
[ ] All constitutional compliance tests passing (from constitutional.md)

Last Updated: 2026-01-15
Next Review: After Test Implementation

Other tracked files

specs/004-cxp/compliance-audit.md
specs/004-cxp/prompt.md
specs/004-cxp/review-2026-03-25.md

Full spec text

Verbatim from specs/004-cxp/spec.md; headings are pushed down two levels.

SPEC-004: CXP Protocol (Cross-agent eXchange Protocol)

Metadata

Spec ID: 004-cxp
Title: Cross-agent eXchange Protocol
Author: Mohamed
Status: Complete
Created: 2026-01-15
Last Updated: 2026-03-07
Priority: P0
Components: CXP Packet, Message Envelope, Protocol Handler

Overview

What

Why

Deterministic, traceable message passing
Consistent structure across all agent communication
Delivery status tracking (queued → delivered → acknowledged)
Work status tracking (pending → in_progress → resolved → archived)
Integration with Prolog knowledge base

How

Standardized packet format with required headers
JSON and binary serialization support
Thread-based message correlation
Priority-based message ordering
Protocol versioning for backward compatibility

User Scenarios & Stories

US-001: Packet Format and Structure (Critical)

As a developer I want to a standardized packet format So that all agents communicate consistently

Acceptance Criteria:

CXPPacket base class with all required fields
message_id: UUID string
from_agent: Volk alias string (U:[A-Z][a-z] pattern)
to_agent: Volk alias string
thread_id: string identifier
subject: string (max 200 chars)
payload: generic object (dict or bytes)
timestamp: ISO8601 string
priority: integer (0-10 range)
delivery_status: enum (queued, delivered, acknowledged, failed)
work_status: enum (pending, in_progress, resolved, archived)
protocol_version: semver string
Type hints and Pydantic validation

US-002: Header Management (Critical)

As a Postman agent I want to efficient header extraction So that I can route messages quickly

Acceptance Criteria:

get_headers() method returning dict
Extract all 11 fields to headers
Header extraction < 1ms
Validate all required headers present
Reject packets with missing/invalid headers
set_delivery_status() and set_work_status() methods
Prevent modification of immutable headers (message_id, from_agent, to_agent)

US-003: Payload Handling (Critical)

As a Volk agent I want to flexible payload formats So that I can send various data types

Acceptance Criteria:

Support JSON object/array/nested structures
JSON payload size limit: 10MB
Support binary payloads (bytes)
Base64 encoding for binary transport
Binary payload size limit: 100MB
Content-type metadata for binary
get_payload(), get_payload_json(), get_payload_binary() methods

US-004: Delivery Status Tracking (Critical)

As a Postman agent I want to delivery status tracking So that I can monitor message delivery

Acceptance Criteria:

DeliveryStatus enum: QUEUED, DELIVERED, ACKNOWLEDGED, FAILED
Valid transitions: QUEUED→DELIVERED→ACKNOWLEDGED, QUEUED→FAILED, DELIVERED→FAILED
Invalid transitions prevented
Timestamp recorded for each transition
is_queued(), is_delivered(), is_acknowledged(), is_failed() methods
get_delivery_history() method
Failure reason recorded for FAILED status
Retry count tracking with max retry limit

US-005: Work Status Tracking (High)

As a recipient Volk I want to work status tracking So that I can manage task progress

Acceptance Criteria:

WorkStatus enum: PENDING, IN_PROGRESS, RESOLVED, ARCHIVED
Valid transitions: PENDING→IN_PROGRESS→RESOLVED→ARCHIVED, IN_PROGRESS→PENDING
Invalid transitions prevented
Timestamp recorded for each transition
is_pending(), is_in_progress(), is_resolved(), is_archived() methods
get_work_history() method
Track assigned_to Volk for IN_PROGRESS
Track resolution result and timestamp for RESOLVED

US-006: Packet Serialization/Deserialization (Critical)

As a developer I want to efficient serialization So that packets transmit quickly

Acceptance Criteria:

to_json() and from_json() methods
Handle datetime (ISO8601), enum (string), UUID (string), binary (base64)
JSON serialization < 10ms for typical 1KB packet
to_bytes() and from_bytes() using MessagePack
Binary serialization < 5ms
Support compression for large payloads
Pretty-print JSON for debugging
Partial serialization (headers only) support

US-007: Packet Validation and Schema (High)

As a developer I want to comprehensive validation So that invalid packets are rejected

Acceptance Criteria:

Validate all required fields present
Validate field types match specification
Validate enum values
Validate string lengths and numeric ranges
JSON schema for CXP packets
Schema validation < 5ms
Cross-field validation (delivery_status consistency, from_agent ≠ to_agent)
Custom validator support

US-008: Thread Management and Correlation (High)

As a developer I want to thread correlation So that related messages are grouped

Acceptance Criteria:

Generate thread_id (UUID format) for new conversations
thread_id inheritance for replies
get_thread_packets(thread_id) method
Return packets in chronological order
Thread correlation < 2ms
Track thread creation timestamp, participants, message count
Track thread status (active, resolved, archived)
Close thread when work_status = ARCHIVED
Archive old threads after 30 days

US-009: Priority and Ordering (High)

As a Postman agent I want to priority-based ordering So that urgent messages processed first

Acceptance Criteria:

Priority range 0-10
Priority constants: LOW=3, NORMAL=5, HIGH=7, URGENT=10
Default priority = 5 (NORMAL)
Sort by priority (descending), then timestamp (ascending)
set_priority() method with escalation/demotion support
Log priority changes
Priority policies: System=URGENT, Error=HIGH, User=NORMAL, Background=LOW

US-010: CXP Protocol Versioning (High)

As a developer I want to protocol versioning So that backward compatibility maintained

Acceptance Criteria:

Semantic versioning (major.minor.patch)
Current version = 1.0.0
check_compatibility(version) method
Same major version compatibility
Reject incompatible major versions
Version negotiation support
upgrade_packet() method for migration
Document breaking changes in CHANGELOG.md

US-011: fix_issues Subject for Code Review (Critical)

As a U:Qa (QA) agent I want to send code review findings to U:Vz (VizInt) So that issues can be fixed iteratively

Acceptance Criteria:

New CXP subject: fix_issues
From: U:Qa, To: U:Vz
Payload contains review_id, issues array, and summary
Issues include type, rule, line, message, and severity
Supports recursive routing for review cycles
Compatible with MAX_REVIEW_CYCLES configuration
Escalation support when cycles exhausted

US-011: fix_issues Subject for Code Review (Critical)

As a U:Qa (QA) agent I want to send code review findings to U:Vz (VizInt) So that issues can be fixed iteratively

Acceptance Criteria:

New CXP subject: fix_issues
From: U:Qa, To: U:Vz
Payload contains review_id, issues array, and summary
Issues include type, rule, line, message, and severity
Supports recursive routing for review cycles
Compatible with MAX_REVIEW_CYCLES configuration
Escalation support when cycles exhausted

Functional Requirements

Performance Requirements

Operation	Target
JSON serialization	<10ms (1KB payload)
JSON deserialization	<10ms
Binary serialization	<5ms
Binary deserialization	<5ms
Field validation	<1ms
Schema validation	<5ms
Thread correlation	<2ms

Memory Requirements

Packet memory footprint: <10KB (excluding payload)
Thread metadata: <1KB per thread
Support 10,000 packets in memory simultaneously

Subject Requirements

Support fix_issues subject for code review loop
Subject validation includes new fix_issues value
Subject length limit: 200 characters (includes fix_issues)
Backward compatibility with existing subjects

Subject Requirements

Support fix_issues subject for code review loop
Subject validation includes new fix_issues value
Subject length limit: 200 characters (includes fix_issues)
Backward compatibility with existing subjects

Technical Design

CXP Packet Structure

class CXPPacket(BaseModel):
    # Identity
    message_id: UUID
    from_agent: str              # Volk alias (U:[A-Z][a-z])
    to_agent: str                # Volk alias
    thread_id: str               # Conversation ID
    
    # Content
    subject: str                 # Max 200 chars
    payload: Union[Dict, bytes]  # Message body
    
    # Metadata
    timestamp: datetime          # ISO8601
    priority: int                # 0-10
    protocol_version: str        # Semver
    
    # Status
    delivery_status: DeliveryStatus  # queued, delivered, acknowledged, failed
    work_status: WorkStatus          # pending, in_progress, resolved, archived

Status Enums

class DeliveryStatus(Enum):
    QUEUED = "queued"
    DELIVERED = "delivered"
    ACKNOWLEDGED = "acknowledged"
    FAILED = "failed"

class WorkStatus(Enum):
    PENDING = "pending"
    IN_PROGRESS = "in_progress"
    RESOLVED = "resolved"
    ARCHIVED = "archived"

Integration Points

Component	Integration
orchestrata-kernel	Packet routing, recursive routing for fix_issues
orchestrata-postman	Packet delivery
orchestrata-governance	Prolog fact storage
orchestrata-session	Session-scoped packets
orchestrata-qa	fix_issues subject consumption, MAX_REVIEW_CYCLES config
orchestrata-vizint	fix_issues subject handling
orchestrata-qa	fix_issues subject consumption, MAX_REVIEW_CYCLES config
orchestrata-vizint	fix_issues subject handling

Revision History

Date	Version	Author	Changes
2026-03-07	1.0	Mohamed	Initial specification
2026-03-07	1.1	Mohamed	Added fix_issues CXP subject for U:Qa code review loop and MAX_REVIEW_CYCLES configuration
2026-03-07	1.1	Mohamed	Added fix_issues CXP subject for U:Qa code review loop and MAX_REVIEW_CYCLES configuration

Prolog Integration

% CXP facts stored in Prolog (Article II)
cxp_packet(MessageID, From, To, ThreadID, Subject, Timestamp).
cxp_delivery_status(MessageID, Status, Timestamp).
cxp_work_status(MessageID, Status, Timestamp).

fix_issues Subject Specification

The fix_issues subject enables the U:Qa code review loop functionality by allowing QA agents to send code review findings back to VizInt agents for remediation.

Subject Values

Subject	From	To	Purpose
`review_code`	U:Cx, U:Ox, U:Vz	U:Qa	Request code review
`fix_issues`	U:Qa	U:Vz	Send review findings for remediation
`review_complete`	U:Qa	U:Ox	Notify orchestrator of review completion

fix_issues Packet Format

CXP Packet(
    subject="fix_issues",
    from_agent="U:Qa",
    to_agent="U:Vz",
    payload={
        "review_id": "rev_123",
        "file_path": "packages/.../kernel.py",
        "issues": [
            {
                "type": "style",
                "rule": "E501",
                "line": 42,
                "message": "Line too long (92 > 88 chars)",
                "severity": "warning"
            },
            {
                "type": "complexity",
                "rule": "C101",
                "line": 156,
                "function": "handle_packet",
                "message": "Function too long (67 > 40 lines)",
                "severity": "warning"
            }
        ],
        "summary": {
            "total_issues": 5,
            "errors": 0,
            "warnings": 4,
            "infos": 1
        },
        "auto_fixable": True
    }
)

Review-Fix Loop Flow

1. U:Cx receives user requirement
2. U:Cx → U:Vz: "build feature X"
3. U:Vz generates code
4. U:Vz → U:Qa: "review_code" with file_path
5. U:Qa analyzes code → finds issues
6. U:Qa → U:Vz: "fix_issues" with issue list
7. U:Vz applies fixes → sends back to U:Qa
8. Loop back to step 5 until MAX_REVIEW_CYCLES (default: 3)
9. If issues remain after MAX cycles → escalate to U:Ox
10. U:Qa → U:Ox: "review_complete" with final status

MAX_REVIEW_CYCLES Configuration

# In orchestrata-qa configuration
MAX_REVIEW_CYCLES: int = 3  # Maximum review-fix iterations
REVIEW_TIMEOUT_SECONDS: int = 300  # 5 minutes per cycle
ESCALATE_ON_MAX_CYCLES: bool = True

Recursive Routing in Kernel

The Kernel must support recursive routing for review cycles:

Detect fix_issues subject
Route back to U:Qa for re-review
Track cycle count in packet metadata
Escalate to U:Ox when MAX_REVIEW_CYCLES exceeded

Success Criteria

All 11 fields present and validated
Serialization: JSON <10ms, Binary <5ms
Validation: <5ms per packet
Compatibility: Backward compatible versioning
Reliability: Zero packet corruption in transit

Dependencies

orchestrata-core (enums, interfaces)
orchestrata-qa (MAX_REVIEW_CYCLES configuration)
orchestrata-vizint (fix_issues handler)
Pydantic (validation)
MessagePack (binary serialization)

004-cxp: CXP Protocol (Cross-agent eXchange Protocol)

At a glance

Reading this spec

Requirements

Code that traces this spec

Checklists

checklists/README.md

CXP Protocol Checklists

Overview

Core Responsibilities

Checklist Summary

CXP Packet Structure

Core Packet Fields

Example CXP Packet

Performance Requirements

Usage Guidelines

For Developers

For Reviewers

Dependencies

Core Dependencies

Integration Points

Checkpoint Strategy

Git Checkpoints

Verification Commands

Success Criteria

Related Documentation

checklists/SUMMARY.md

CXP Protocol Checklists Summary

File Statistics

Checkbox Breakdown by File

requirements.md (273 checkboxes)

constitutional.md (205 checkboxes)

testing.md (340 checkboxes)

Implementation Phases

Phase 1: Requirements (requirements.md)

Phase 2: Constitutional Compliance (constitutional.md)

Phase 3: Testing (testing.md)

Success Metrics

Quick Reference

Key Performance Targets

Core Packet Fields

Test Execution Commands

Related Specs

checklists/constitutional.md

CXP Protocol Constitutional Compliance Checklist

Overview

Article I: Sessions Are Unit Of Work

Session Isolation

Session Lifecycle

Session Context

Session Testing

Article II: Prolog Is Source Of Truth

Packet Facts

Fact Assertions

Fact Queries

Fact Persistence

Prolog Testing

Article III: Sessions Isolate State

State Boundaries

State Transitions

State Carryover

State Testing

Article IV: Adapters Abstract LLMs

LLM Independence

Adapter Integration

Multi-LLM Support

Adapter Testing

Article V: Volks Embody Personas

Volk Identification

Volk Authorization

Volk Routing

Volk Testing

Article VI: CXP Governs Exchange

Protocol Enforcement

Protocol Compliance

Protocol Monitoring

Protocol Testing

Article VII: No Mocking In Tests

Real Serialization

Real Validation

`checklists/README.md`

`checklists/SUMMARY.md`

`checklists/constitutional.md`

`checklists/requirements.md`

`checklists/testing.md`