Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate / Specs / 002-postman

002-postman: Postman Message Broker (U:PS)

The Postman (U:PS) is the message routing engine for Orchestrata. It handles message delivery, topic-based subscriptions, queue management, priority processing, message filtering, persistence, and delivery guarantees.

At a glance

Item Value
Spec directory specs/002-postman/
Status line in the spec Complete
Requirement IDs defined 457
With a @traces citation in src/ 227 (49.7%)
With a @traces citation in tests/ 13 (2.8%)
Tracked files 8
RTM page 002-postman

Reading this spec

The Postman (U:PS) is the message routing engine of Orchestrata. Agents do not talk to each other directly; the Postman handles message delivery, topic-based subscriptions, queue management, priority processing, message filtering, persistence and delivery guarantees, so that communication is reliable and decoupled.

The scope is ten user stories: agent message delivery, topic subscription, queue management, priority handling, filtering and routing, persistence and replay, delivery guarantees and acknowledgments, monitoring and metrics, configuration management, and performance and scalability. Delivery, topic subscription, delivery guarantees and performance are marked critical. Requirement IDs take the forms REQ-002-US-nnn and REQ-002-FRnn; the functional group REQ-002-FR11 is the largest.

The key decisions in the overview are Redis-backed queues and topics, several delivery protocols (CXP, gRPC, WebSocket and HTTP), priority-based processing, and acknowledgment-based delivery. The spec names three delivery guarantees: at-most-once, at-least-once and exactly-once. Persistence supports recovery and replay. The stated performance target is more than 5000 messages per second.

In the code, the package is orchestrata_ultimate/postman. Most citations land in orchestrata_ultimate/postman/interfaces and orchestrata_ultimate/postman/types, with orchestrata_ultimate/postman/priority, orchestrata_ultimate/postman/router and orchestrata_ultimate/postman/queue behind them. The per-requirement view is on the RTM page.

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

Measured coverage is 227 of 457 requirements cited by at least one @traces in src/ (49.7%), spread over 36 modules; the module citing the most of them is orchestrata_ultimate/postman/interfaces (81 requirements). In tests/, 13 requirements are cited by a test-side @traces.

Coverage gaps: 230 requirements have no citing symbol. The largest untraced groups are REQ-002-FR11 (37), REQ-002-US-010 (24), REQ-002-US-008 (21). 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 (13 against 227).

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-002-US-001-001 yes Agent can send messages through Postman service 4
REQ-002-US-001-002 yes Messages are routed to correct recipient agents 5
REQ-002-US-001-003 yes Message delivery is acknowledged with receipts 2
REQ-002-US-001-004 yes Failed deliveries trigger retry mechanisms 4
REQ-002-US-001-005 yes Delivery status is tracked and logged 10
REQ-002-US-001-006 yes Support for INFORM message type 1
REQ-002-US-001-007 yes Support for REQUEST message type 1
REQ-002-US-001-008 yes Support for QUERY message type 1
REQ-002-US-001-009 yes Support for RESPONSE message type 1
REQ-002-US-001-010 yes Support for ERROR message type 1
REQ-002-US-001-011 yes Support for NOTIFY message type 1
REQ-002-US-001-012 yes Support for SUBSCRIBE message type 1
REQ-002-US-001-013 yes Support for UNSUBSCRIBE message type 1
REQ-002-US-001-014 yes Direct agent-to-agent delivery none
REQ-002-US-001-015 yes Broadcast delivery to multiple agents none
REQ-002-US-001-016 yes Topic-based delivery 2
REQ-002-US-001-017 yes Queue-based delivery none
REQ-002-US-001-018 yes Priority-based delivery none
REQ-002-US-001-019 yes Handle recipient not found errors none
REQ-002-US-001-020 yes Handle network timeout errors none
REQ-002-US-001-021 yes Handle malformed message errors none
REQ-002-US-001-022 yes Handle authentication errors none
REQ-002-US-001-023 yes Handle authorization errors none
REQ-002-US-001-024 yes Retry failed deliveries (up to 3 attempts) 5
REQ-002-US-001-025 yes Log all delivery failures none
REQ-002-US-001-026 yes Notify sender of permanent failures 1
REQ-002-US-001-027 yes Deliver messages within 100ms (p95) none
REQ-002-US-001-028 yes Support 5000+ messages/second throughput none
REQ-002-US-001-029 yes Handle concurrent deliveries efficiently none
REQ-002-US-001-030 yes Maintain message ordering per sender-recipient pair none
REQ-002-US-002-001 yes Agent can subscribe to topics 4
REQ-002-US-002-002 yes Agent can unsubscribe from topics 3
REQ-002-US-002-003 yes Agent can list subscribed topics 1
REQ-002-US-002-004 yes Support wildcard topic patterns (e.g., "agent.*") none
REQ-002-US-002-005 yes Support hierarchical topic structures none
REQ-002-US-002-006 yes Validate topic names on subscription 1
REQ-002-US-002-007 yes Deliver messages to all topic subscribers 2
REQ-002-US-002-008 yes Filter messages by topic match none
REQ-002-US-002-009 yes Support multiple simultaneous subscriptions 1
REQ-002-US-002-010 yes Handle subscription conflicts gracefully none
REQ-002-US-002-011 yes Maintain delivery order per topic none
REQ-002-US-002-012 yes Persist subscriptions across restarts none
REQ-002-US-002-013 yes Auto-unsubscribe on agent termination none
REQ-002-US-002-014 yes Track subscription creation timestamp 1
REQ-002-US-002-015 yes Track last message received timestamp 1
REQ-002-US-002-016 yes Support subscription TTL (time-to-live) 3
REQ-002-US-002-017 yes Subscribe/unsubscribe within 50ms none
REQ-002-US-002-018 yes Deliver to 100+ subscribers per topic none
REQ-002-US-002-019 yes Handle 1000+ active subscriptions none
REQ-002-US-002-020 yes Efficient topic matching algorithm none
REQ-002-US-003-001 yes Create named message queues 3
REQ-002-US-003-002 yes Delete message queues 3
REQ-002-US-003-003 yes List available queues 3
REQ-002-US-003-004 yes Query queue metadata (size, age, etc.) 6
REQ-002-US-003-005 yes Purge queue contents 3
REQ-002-US-003-006 yes FIFO (First-In-First-Out) ordering 1
REQ-002-US-003-007 yes Priority queue support none
REQ-002-US-003-008 yes Message deduplication 2
REQ-002-US-003-009 yes Dead-letter queue for failed messages 3
REQ-002-US-003-010 yes Message TTL (time-to-live) 2
REQ-002-US-003-011 yes Single consumer mode none
REQ-002-US-003-012 yes Multiple consumer mode (load balancing) none
REQ-002-US-003-013 yes Peek messages without consuming 1
REQ-002-US-003-014 yes Batch message retrieval none
REQ-002-US-003-015 yes Acknowledge message consumption 2
REQ-002-US-003-016 yes Maximum queue size (10000 messages) 2
REQ-002-US-003-017 yes Maximum message age (24 hours) none
REQ-002-US-003-018 yes Queue overflow handling none
REQ-002-US-003-019 yes Memory limit per queue none
REQ-002-US-003-020 yes Persist queue state to disk none
REQ-002-US-003-021 yes Restore queues on restart none
REQ-002-US-003-022 yes Handle corruption gracefully none
REQ-002-US-003-023 yes Periodic checkpoint creation none
REQ-002-US-004-001 yes CRITICAL priority level (0) 1
REQ-002-US-004-002 yes HIGH priority level (1) 1
REQ-002-US-004-003 yes NORMAL priority level (2) 1
REQ-002-US-004-004 yes LOW priority level (3) 1
REQ-002-US-004-005 yes BACKGROUND priority level (4) 1
REQ-002-US-004-006 yes Process messages in priority order 2
REQ-002-US-004-007 yes Preempt lower priority messages none
REQ-002-US-004-008 yes Prevent starvation of low-priority messages 2
REQ-002-US-004-009 yes Age-based priority boost 2
REQ-002-US-004-010 yes Priority inversion detection 1
REQ-002-US-004-011 yes Set default priority per agent none
REQ-002-US-004-012 yes Override priority per message 3
REQ-002-US-004-013 yes Configure priority thresholds none
REQ-002-US-004-014 yes Configure aging parameters 1
REQ-002-US-004-015 yes Track processing time per priority none
REQ-002-US-004-016 yes Monitor priority distribution 1
REQ-002-US-004-017 yes Alert on priority queue buildup none
REQ-002-US-004-018 yes Report priority inversion incidents none
REQ-002-US-005-001 yes Content-based filtering 6
REQ-002-US-005-002 yes Header-based filtering 3
REQ-002-US-005-003 yes Sender-based filtering 3
REQ-002-US-005-004 yes Topic-based filtering 3
REQ-002-US-005-005 yes Pattern-based filtering (regex) none
REQ-002-US-005-006 yes Composite filters (AND/OR logic) 8
REQ-002-US-005-007 yes Static routing by recipient 1
REQ-002-US-005-008 yes Dynamic routing by content none
REQ-002-US-005-009 yes Conditional routing (if-then rules) none
REQ-002-US-005-010 yes Load-balanced routing none
REQ-002-US-005-011 yes Failover routing none
REQ-002-US-005-012 yes Create routing rules 4
REQ-002-US-005-013 yes Update routing rules 3
REQ-002-US-005-014 yes Delete routing rules 4
REQ-002-US-005-015 yes List active rules 3
REQ-002-US-005-016 yes Enable/disable rules 1
REQ-002-US-005-017 yes Validate rule syntax 2
REQ-002-US-005-018 yes Evaluate rules in priority order 3
REQ-002-US-005-019 yes Stop on first match (if configured) 2
REQ-002-US-005-020 yes Evaluate all matching rules 1
REQ-002-US-005-021 yes Handle rule conflicts none
REQ-002-US-005-022 yes Log rule evaluations none
REQ-002-US-005-023 yes Rule evaluation < 10ms per message none
REQ-002-US-005-024 yes Support 1000+ active rules none
REQ-002-US-005-025 yes Efficient pattern matching 2
REQ-002-US-005-026 yes Cache compiled rule expressions none
REQ-002-US-006-001 yes Persist all messages to disk 4
REQ-002-US-006-002 yes Store message metadata (timestamp, sender, etc.) 2
REQ-002-US-006-003 yes Store message payload 2
REQ-002-US-006-004 yes Store delivery receipts none
REQ-002-US-006-005 yes Compress stored messages none
REQ-002-US-006-006 yes Configure retention period (default 7 days) none
REQ-002-US-006-007 yes Configure storage limits (default 10GB) none
REQ-002-US-006-008 yes Automatic cleanup of old messages 2
REQ-002-US-006-009 yes Manual purge operations 2
REQ-002-US-006-010 yes Export messages to archive none
REQ-002-US-006-011 yes Replay messages by time range 2
REQ-002-US-006-012 yes Replay messages by sender 2
REQ-002-US-006-013 yes Replay messages by topic 1
REQ-002-US-006-014 yes Replay messages by message ID 4
REQ-002-US-006-015 yes Replay messages by filter criteria 3
REQ-002-US-006-016 yes Replay at original speed none
REQ-002-US-006-017 yes Replay at accelerated speed 1
REQ-002-US-006-018 yes Replay with delay between messages 3
REQ-002-US-006-019 yes Replay to different recipients 1
REQ-002-US-006-020 yes Dry-run replay (no delivery) 1
REQ-002-US-006-021 yes Recover from storage corruption none
REQ-002-US-006-022 yes Rebuild indexes from logs none
REQ-002-US-006-023 yes Verify message integrity none
REQ-002-US-006-024 yes Handle missing messages gracefully none
REQ-002-US-007-001 yes At-most-once delivery (fire and forget) 3
REQ-002-US-007-002 yes At-least-once delivery (with retries) 2
REQ-002-US-007-003 yes Exactly-once delivery (with deduplication) 3
REQ-002-US-007-004 yes Configure delivery mode per message 2
REQ-002-US-007-005 yes Configure delivery mode per queue none
REQ-002-US-007-006 yes Synchronous ACK (immediate response) none
REQ-002-US-007-007 yes Asynchronous ACK (deferred response) none
REQ-002-US-007-008 yes Negative ACK (NACK) for failures 2
REQ-002-US-007-009 yes Batch acknowledgments none
REQ-002-US-007-010 yes Selective acknowledgments none
REQ-002-US-007-011 yes Configure ACK timeout per message none
REQ-002-US-007-012 yes Configure ACK timeout per agent none
REQ-002-US-007-013 yes Retry on timeout (up to max retries) none
REQ-002-US-007-014 yes Exponential backoff for retries 1
REQ-002-US-007-015 yes Alert on persistent timeouts none
REQ-002-US-007-016 yes Generate unique receipt ID 1
REQ-002-US-007-017 yes Track receipt status (pending/acked/nacked) none
REQ-002-US-007-018 yes Query receipt status by message ID 1
REQ-002-US-007-019 yes Store receipts for audit trail 2
REQ-002-US-007-020 yes Expire old receipts 1
REQ-002-US-007-021 yes Dead-letter queue for undeliverable messages none
REQ-002-US-007-022 yes Alert on delivery failures none
REQ-002-US-007-023 yes Log detailed failure reasons none
REQ-002-US-007-024 yes Retry with different routes none
REQ-002-US-007-025 yes Manual intervention support none
REQ-002-US-008-001 yes Messages sent per second 5
REQ-002-US-008-002 yes Messages received per second 5
REQ-002-US-008-003 yes Messages queued (current) 1
REQ-002-US-008-004 yes Messages in-flight (current) none
REQ-002-US-008-005 yes Messages failed (total) 5
REQ-002-US-008-006 yes Average message latency (p50, p95, p99) 4
REQ-002-US-008-007 yes Message throughput (bytes/sec) none
REQ-002-US-008-008 yes Active agents count 1
REQ-002-US-008-009 yes Messages per agent none
REQ-002-US-008-010 yes Agent message latency none
REQ-002-US-008-011 yes Agent error rate none
REQ-002-US-008-012 yes Agent connection status none
REQ-002-US-008-013 yes Queue depth per queue 6
REQ-002-US-008-014 yes Queue age (oldest message) 2
REQ-002-US-008-015 yes Messages enqueued per queue none
REQ-002-US-008-016 yes Messages dequeued per queue none
REQ-002-US-008-017 yes Queue overflow events none
REQ-002-US-008-018 yes Subscribers per topic none
REQ-002-US-008-019 yes Messages per topic none
REQ-002-US-008-020 yes Topic message rate none
REQ-002-US-008-021 yes Topic latency none
REQ-002-US-008-022 yes CPU usage none
REQ-002-US-008-023 yes Memory usage none
REQ-002-US-008-024 yes Disk I/O none
REQ-002-US-008-025 yes Network I/O none
REQ-002-US-008-026 yes Thread pool utilization none
REQ-002-US-008-027 yes Prometheus format export 3
REQ-002-US-008-028 yes JSON format export 4
REQ-002-US-008-029 yes CSV format export none
REQ-002-US-008-030 yes Real-time streaming metrics none
REQ-002-US-008-031 yes Historical metrics query none
REQ-002-US-009-001 yes Load from YAML file 2
REQ-002-US-009-002 yes Load from environment variables none
REQ-002-US-009-003 yes Load from command-line arguments none
REQ-002-US-009-004 yes Configuration priority order none
REQ-002-US-009-005 yes Validate configuration on load 1
REQ-002-US-009-006 yes Postman service port 1
REQ-002-US-009-007 yes Maximum message size 1
REQ-002-US-009-008 yes Maximum queue size 2
REQ-002-US-009-009 yes Default message TTL 1
REQ-002-US-009-010 yes Retry policy configuration 1
REQ-002-US-009-011 yes Thread pool size 1
REQ-002-US-009-012 yes Storage path configuration 2
REQ-002-US-009-013 yes Default topic patterns none
REQ-002-US-009-014 yes Topic retention policy 1
REQ-002-US-009-015 yes Topic access control none
REQ-002-US-009-016 yes Topic rate limits none
REQ-002-US-009-017 yes Default queue behavior (FIFO/priority) none
REQ-002-US-009-018 yes Queue persistence settings 1
REQ-002-US-009-019 yes Queue size limits 2
REQ-002-US-009-020 yes Dead-letter queue settings 1
REQ-002-US-009-021 yes Enable/disable authentication none
REQ-002-US-009-022 yes Enable/disable encryption none
REQ-002-US-009-023 yes Certificate paths none
REQ-002-US-009-024 yes Access control policies none
REQ-002-US-009-025 yes Reload configuration without restart 3
REQ-002-US-009-026 yes Validate configuration changes none
REQ-002-US-009-027 yes Rollback failed changes none
REQ-002-US-009-028 yes Notify on configuration changes 5
REQ-002-US-010-001 yes Handle 5000+ messages/second none
REQ-002-US-010-002 yes Handle 10000+ concurrent connections none
REQ-002-US-010-003 yes Handle 1000+ active queues none
REQ-002-US-010-004 yes Handle 100+ topics with subscribers none
REQ-002-US-010-005 yes Message delivery < 100ms (p95) none
REQ-002-US-010-006 yes Queue operations < 50ms (p95) none
REQ-002-US-010-007 yes Topic subscription < 50ms (p95) none
REQ-002-US-010-008 yes ACK processing < 10ms (p95) none
REQ-002-US-010-009 yes Maximum 1GB memory usage none
REQ-002-US-010-010 yes Maximum 10GB disk usage none
REQ-002-US-010-011 yes Maximum 100 threads none
REQ-002-US-010-012 yes Efficient CPU utilization (<50% at peak) none
REQ-002-US-010-013 yes Load test with 1000 messages/sec none
REQ-002-US-010-014 yes Load test with 5000 messages/sec none
REQ-002-US-010-015 yes Load test with 10000 messages/sec none
REQ-002-US-010-016 yes Stress test with 100 concurrent agents none
REQ-002-US-010-017 yes Stress test with 1000 concurrent agents none
REQ-002-US-010-018 yes Spike test (sudden load increase) none
REQ-002-US-010-019 yes Soak test (24-hour sustained load) none
REQ-002-US-010-020 yes Message batching none
REQ-002-US-010-021 yes Connection pooling none
REQ-002-US-010-022 yes Zero-copy message transfer none
REQ-002-US-010-023 yes Lock-free data structures none
REQ-002-US-010-024 yes Asynchronous I/O none
REQ-002-FR1-001 yes message_id field (UUID) 1
REQ-002-FR1-002 yes sender field (agent ID) 1
REQ-002-FR1-003 yes recipient field (agent ID or topic) 1
REQ-002-FR1-004 yes timestamp field (ISO 8601) 2
REQ-002-FR1-005 yes priority field (0-4) 1
REQ-002-FR1-006 yes ttl field (seconds) 1
REQ-002-FR1-007 yes correlation_id field (for request-response) 3
REQ-002-FR1-008 yes reply_to field (for responses) 1
REQ-002-FR1-009 yes content_type field (MIME type) 1
REQ-002-FR1-010 yes Validate all required fields present 4
REQ-002-FR1-011 yes Validate field types 2
REQ-002-FR1-012 yes Validate field constraints (e.g., priority range) 3
REQ-002-FR1-013 yes Validate message_id uniqueness 1
REQ-002-FR1-014 yes Reject invalid envelopes 5
REQ-002-FR1-015 yes Parse envelope from JSON 4
REQ-002-FR1-016 yes Serialize envelope to JSON 4
REQ-002-FR1-017 yes Extract routing information 2
REQ-002-FR1-018 yes Extract priority information 1
REQ-002-FR1-019 yes Generate envelope from message 3
REQ-002-FR2-001 yes Plain text payloads 4
REQ-002-FR2-002 yes JSON payloads 5
REQ-002-FR2-003 yes Binary payloads 4
REQ-002-FR2-004 yes Compressed payloads 7
REQ-002-FR2-005 yes Encrypted payloads none
REQ-002-FR2-006 yes Validate payload size (max 1MB) 3
REQ-002-FR2-007 yes Validate content_type matches payload 2
REQ-002-FR2-008 yes Validate JSON structure 1
REQ-002-FR2-009 yes Validate character encoding 1
REQ-002-FR2-010 yes Reject oversized payloads 1
REQ-002-FR2-011 yes Parse JSON payloads 2
REQ-002-FR2-012 yes Decompress compressed payloads 4
REQ-002-FR2-013 yes Decrypt encrypted payloads none
REQ-002-FR2-014 yes Handle binary data 2
REQ-002-FR2-015 yes Preserve payload integrity none
REQ-002-FR3-001 yes Direct routing (agent-to-agent) 2
REQ-002-FR3-002 yes Topic-based routing 2
REQ-002-FR3-003 yes Queue-based routing none
REQ-002-FR3-004 yes Broadcast routing 2
REQ-002-FR3-005 yes Multicast routing 2
REQ-002-FR3-006 yes Resolve recipient by agent ID 3
REQ-002-FR3-007 yes Resolve recipients by topic 2
REQ-002-FR3-008 yes Resolve recipients by queue none
REQ-002-FR3-009 yes Resolve recipients by filter 3
REQ-002-FR3-010 yes Handle unresolved routes 3
REQ-002-FR3-011 yes Cache resolved routes 3
REQ-002-FR3-012 yes Invalidate cache on changes 2
REQ-002-FR3-013 yes Configure cache size none
REQ-002-FR3-014 yes Configure cache TTL 1
REQ-002-FR3-015 yes Cache hit/miss metrics none
REQ-002-FR4-001 yes In-memory queue implementation 2
REQ-002-FR4-002 yes Disk-backed queue implementation 4
REQ-002-FR4-003 yes Priority queue implementation 3
REQ-002-FR4-004 yes Bounded queue with overflow handling 5
REQ-002-FR4-005 yes Concurrent queue access 2
REQ-002-FR4-006 yes Enqueue message 12
REQ-002-FR4-007 yes Dequeue message 10
REQ-002-FR4-008 yes Peek message 6
REQ-002-FR4-009 yes Get queue size 7
REQ-002-FR4-010 yes Clear queue 6
REQ-002-FR4-011 yes Iterate queue (for admin) 2
REQ-002-FR4-012 yes Write-ahead log for durability none
REQ-002-FR4-013 yes Periodic checkpoints 11
REQ-002-FR4-014 yes Recovery on startup 6
REQ-002-FR4-015 yes Corruption detection 2
REQ-002-FR4-016 yes Repair corrupted queues none
REQ-002-FR5-001 yes Store topic definitions 4
REQ-002-FR5-002 yes Store topic subscriptions 1
REQ-002-FR5-003 yes Store topic metadata 2
REQ-002-FR5-004 yes Persist registry to disk none
REQ-002-FR5-005 yes Load registry on startup none
REQ-002-FR5-006 yes Create topic 3
REQ-002-FR5-007 yes Delete topic 3
REQ-002-FR5-008 yes List topics 2
REQ-002-FR5-009 yes Query topic info 3
REQ-002-FR5-010 yes Subscribe to topic none
REQ-002-FR5-011 yes Unsubscribe from topic 1
REQ-002-FR5-012 yes Exact match none
REQ-002-FR5-013 yes Wildcard match (*) 3
REQ-002-FR5-014 yes Pattern match (regex) 1
REQ-002-FR5-015 yes Hierarchical match (topic.subtopic) none
REQ-002-FR5-016 yes Efficient matching algorithm none
REQ-002-FR6-001 yes Store subscriptions in memory 2
REQ-002-FR6-002 yes Persist subscriptions to disk none
REQ-002-FR6-003 yes Index subscriptions by topic none
REQ-002-FR6-004 yes Index subscriptions by agent 1
REQ-002-FR6-005 yes Handle large subscription counts none
REQ-002-FR6-006 yes Add subscription 2
REQ-002-FR6-007 yes Remove subscription 5
REQ-002-FR6-008 yes List subscriptions by agent 2
REQ-002-FR6-009 yes List subscriptions by topic 1
REQ-002-FR6-010 yes Update subscription metadata none
REQ-002-FR6-011 yes Match message to subscriptions 3
REQ-002-FR6-012 yes Return all matching subscribers 3
REQ-002-FR6-013 yes Filter by agent status (active) none
REQ-002-FR6-014 yes Cache frequent matches none
REQ-002-FR6-015 yes Optimize for common patterns none
REQ-002-FR7-001 yes Generate receipt on message receipt 1
REQ-002-FR7-002 yes Generate receipt on message delivery 2
REQ-002-FR7-003 yes Generate receipt on message failure 2
REQ-002-FR7-004 yes Include delivery timestamp 1
REQ-002-FR7-005 yes Include failure reason (if applicable) 1
REQ-002-FR7-006 yes Store receipts in memory 4
REQ-002-FR7-007 yes Persist receipts to disk 5
REQ-002-FR7-008 yes Index by message ID 3
REQ-002-FR7-009 yes Index by recipient none
REQ-002-FR7-010 yes Expire old receipts 3
REQ-002-FR7-011 yes Query receipt by message ID 3
REQ-002-FR7-012 yes Query receipts by time range 2
REQ-002-FR7-013 yes Query receipts by sender 1
REQ-002-FR7-014 yes Query receipts by recipient 1
REQ-002-FR7-015 yes Export receipts for audit none
REQ-002-FR8-001 yes Connection errors none
REQ-002-FR8-002 yes Timeout errors none
REQ-002-FR8-003 yes Validation errors none
REQ-002-FR8-004 yes Authorization errors none
REQ-002-FR8-005 yes System errors (OOM, disk full) none
REQ-002-FR8-006 yes Generate error message 3
REQ-002-FR8-007 yes Include error code 2
REQ-002-FR8-008 yes Include error description 3
REQ-002-FR8-009 yes Include stack trace (if debug) 3
REQ-002-FR8-010 yes Send error to sender none
REQ-002-FR8-011 yes Log all errors 1
REQ-002-FR8-012 yes Include context information 3
REQ-002-FR8-013 yes Include timestamp none
REQ-002-FR8-014 yes Rotate log files none
REQ-002-FR8-015 yes Export logs for analysis none
REQ-002-FR8-016 yes Retry transient errors 3
REQ-002-FR8-017 yes Fallback for permanent errors 3
REQ-002-FR8-018 yes Alert on critical errors none
REQ-002-FR8-019 yes Graceful degradation 2
REQ-002-FR8-020 yes Circuit breaker pattern 16
REQ-002-FR9-001 yes Collect core metrics (see US-008) 3
REQ-002-FR9-002 yes Aggregate metrics by time window none
REQ-002-FR9-003 yes Calculate percentiles (p50, p95, p99) none
REQ-002-FR9-004 yes Track metric trends none
REQ-002-FR9-005 yes Alert on anomalies none
REQ-002-FR9-006 yes /metrics endpoint (Prometheus format) none
REQ-002-FR9-007 yes /health endpoint (health check) 10
REQ-002-FR9-008 yes /stats endpoint (JSON stats) none
REQ-002-FR9-009 yes Real-time metrics WebSocket none
REQ-002-FR9-010 yes Historical metrics API none
REQ-002-FR9-011 yes Structured logging (JSON) none
REQ-002-FR9-012 yes Log levels (DEBUG, INFO, WARN, ERROR) none
REQ-002-FR9-013 yes Log filtering none
REQ-002-FR9-014 yes Log aggregation none
REQ-002-FR9-015 yes Log search none
REQ-002-FR10-001 yes List all agents 6
REQ-002-FR10-002 yes List all queues none
REQ-002-FR10-003 yes List all topics none
REQ-002-FR10-004 yes View agent details none
REQ-002-FR10-005 yes View queue details none
REQ-002-FR10-006 yes View topic details none
REQ-002-FR10-007 yes Purge queue none
REQ-002-FR10-008 yes Delete topic none
REQ-002-FR10-009 yes Disconnect agent 4
REQ-002-FR10-010 yes Replay messages 1
REQ-002-FR10-011 yes Export configuration 4
REQ-002-FR10-012 yes Import configuration 4
REQ-002-FR10-013 yes REST API for admin operations none
REQ-002-FR10-014 yes Authentication required none
REQ-002-FR10-015 yes Authorization by role 1
REQ-002-FR10-016 yes Audit log all admin actions none
REQ-002-FR10-017 yes Rate limit admin requests none
REQ-002-FR11-001 yes Load from postman.yaml 2
REQ-002-FR11-002 yes Load from environment variables 4
REQ-002-FR11-003 yes Load from CLI arguments none
REQ-002-FR11-004 yes Merge configurations 2
REQ-002-FR11-005 yes Validate loaded configuration 4
REQ-002-FR11-006 yes Define YAML schema none
REQ-002-FR11-007 yes Validate against schema none
REQ-002-FR11-008 yes Provide schema documentation none
REQ-002-FR11-009 yes Default values for all settings 2
REQ-002-FR11-010 yes Required vs optional settings none
REQ-002-FR11-011 yes Watch configuration file 3
REQ-002-FR11-012 yes Detect changes 2
REQ-002-FR11-013 yes Validate new configuration none
REQ-002-FR11-014 yes Apply changes atomically none
REQ-002-FR11-015 yes Rollback on failure none
REQ-002-FR11-016 yes Postman facts stored in Prolog KB none
REQ-002-FR11-017 yes Query message routing via Prolog none
REQ-002-FR11-018 yes Query subscription rules via Prolog none
REQ-002-FR11-019 yes Update Postman state in Prolog none
REQ-002-FR11-020 yes Prolog-based message filtering none
REQ-002-FR11-021 yes Agent registration with Postman 2
REQ-002-FR11-022 yes Agent deregistration none
REQ-002-FR11-023 yes Agent message send/receive none
REQ-002-FR11-024 yes Agent status tracking none
REQ-002-FR11-025 yes Agent capability discovery none
REQ-002-FR11-026 yes Session-based message isolation none
REQ-002-FR11-027 yes Per-session queues none
REQ-002-FR11-028 yes Per-session topics none
REQ-002-FR11-029 yes Session cleanup on end none
REQ-002-FR11-030 yes Session message history none
REQ-002-FR11-031 yes Installation guide none
REQ-002-FR11-032 yes Configuration guide none
REQ-002-FR11-033 yes User manual none
REQ-002-FR11-034 yes API reference none
REQ-002-FR11-035 yes Examples and tutorials none
REQ-002-FR11-036 yes Architecture overview none
REQ-002-FR11-037 yes Component design docs none
REQ-002-FR11-038 yes API documentation none
REQ-002-FR11-039 yes Testing guide none
REQ-002-FR11-040 yes Contribution guide none
REQ-002-FR11-041 yes Deployment guide none
REQ-002-FR11-042 yes Monitoring guide none
REQ-002-FR11-043 yes Troubleshooting guide none
REQ-002-FR11-044 yes Performance tuning guide none
REQ-002-FR11-045 yes Backup/restore procedures none

Code that traces this spec

Module Symbols Requirements
orchestrata_ultimate/agents/kernel_handler 1 1
orchestrata_ultimate/agents/tool_registry 3 4
orchestrata_ultimate/agents/volks/base 1 1
orchestrata_ultimate/core/patterns/error_handling 6 5
orchestrata_ultimate/core/protocols/components 6 6
orchestrata_ultimate/cxp/postman_adapter 2 2
orchestrata_ultimate/knowledge_graph/query_engine 1 3
orchestrata_ultimate/knowledge_graph/synchronizer 1 1
orchestrata_ultimate/postman/admin 13 5
orchestrata_ultimate/postman/cli 1 1
orchestrata_ultimate/postman/config 13 10
orchestrata_ultimate/postman/delivery 12 10
orchestrata_ultimate/postman/envelope 9 10
orchestrata_ultimate/postman/error_handler 13 7
orchestrata_ultimate/postman/event_emitting_postman 3 3
orchestrata_ultimate/postman/exceptions 13 14
orchestrata_ultimate/postman/filter 4 7
orchestrata_ultimate/postman/governance 2 2
orchestrata_ultimate/postman/guarantees 4 5
orchestrata_ultimate/postman/health 9 2
orchestrata_ultimate/postman/interfaces 85 81
orchestrata_ultimate/postman/message_store 6 8
orchestrata_ultimate/postman/metrics 8 7
orchestrata_ultimate/postman/payload 8 12
orchestrata_ultimate/postman/postman 11 11
orchestrata_ultimate/postman/priority 19 17
orchestrata_ultimate/postman/queue 37 15
orchestrata_ultimate/postman/queue_manager 8 8
orchestrata_ultimate/postman/receipt_store 7 10
orchestrata_ultimate/postman/replay_engine 5 7
orchestrata_ultimate/postman/router 13 15
orchestrata_ultimate/postman/routing_rules 7 9
orchestrata_ultimate/postman/subscription_manager 9 10
orchestrata_ultimate/postman/sync_router 4 5
orchestrata_ultimate/postman/topic_registry 7 8
orchestrata_ultimate/postman/types 30 78

Checklists

checklists/README.md

Postman Integration Checklists

Project: Orchestrator-AI Postman Integration (Spec 002) Version: 1.0.0 Last Updated: 2026-01-13

Overview

This directory contains comprehensive checklists for implementing and verifying the Postman Integration component of the Orchestrator-AI system. The checklists cover requirements, constitutional compliance, and testing.

Checklist Files
1. requirements.md

Purpose: Track implementation of all functional requirements and user stories Total Checkboxes: 457 Coverage:

Key Sections:

2. constitutional.md

Purpose: Ensure compliance with all 11 articles of the Orchestrator-AI Constitution Total Checkboxes: 355 Coverage:

Key Sections:

3. testing.md

Purpose: Comprehensive testing plan including unit, integration, contract, and performance tests Total Checkboxes: 490 Coverage:

Key Sections:

Total Checklist Summary
File Checkboxes Lines Size
requirements.md 457 788 20K
constitutional.md 355 590 18K
testing.md 490 645 22K
TOTAL 1,302 2,023 60K
Usage Guidelines
For Implementation
  1. Start with requirements.md to understand what needs to be built
  2. Check constitutional.md to ensure compliance with architectural principles
  3. Use testing.md to guide test development and verification
For Reviews
  1. Verify all checkboxes in relevant sections are addressed
  2. Ensure compliance items in constitutional.md are satisfied
  3. Confirm test coverage meets requirements in testing.md
For Project Tracking
  1. Update checkboxes as work progresses
  2. Track completion percentage in each file
  3. Generate progress reports from checkbox counts
  4. Identify blockers and dependencies
Checkbox Status
Key Metrics and Targets
Performance Targets
Quality Targets
Functional Completeness
Dependencies
Core Dependencies
Testing Dependencies
Documentation Dependencies
Review Process
Checklist Review
  1. Initial Review: Architecture team reviews all checklists
  2. Implementation Review: Developers review during implementation
  3. Testing Review: QA team reviews test checklists
  4. Final Review: All stakeholders review before release
Sign-off Requirements
Maintenance
Updates
Version Control
References
Quick Stats
Total Checkboxes: 1,302
Total Lines: 2,023
Total Size: 60K
Estimated Work: 3-6 months (with team)
Critical Path: Performance + Prolog Integration
Contact

For questions or updates to these checklists:

checklists/SUMMARY.txt

================================================================================
POSTMAN INTEGRATION CHECKLISTS - CREATION SUMMARY
================================================================================

Project: Orchestrator-AI Postman Integration (Spec 002)
Created: 2026-01-13
Location: /home/mohamed/workspace/research/orchestrator-ai/specs/002-postman/checklists/

================================================================================
FILES CREATED
================================================================================

1. requirements.md
   - Purpose: Track all functional requirements and user stories
   - Size: 20K
   - Lines: 788
   - Checkboxes: 457
   - Sections:
     * 10 User Stories (US-001 to US-010)
     * 11 Functional Requirements (FR-001 to FR-011)
     * Integration requirements
     * Documentation requirements

2. constitutional.md
   - Purpose: Ensure compliance with Orchestrator-AI Constitution
   - Size: 18K
   - Lines: 590
   - Checkboxes: 355
   - Sections:
     * Article I: Agent Autonomy
     * Article II: Prolog as Single Source of Truth
     * Article III: Session Isolation
     * Article IV: Hooks for Extensibility
     * Article V: Minimal Core, Maximal Extension
     * Article VI: Python 3.11+ Implementation
     * Article VII: Testing Without Mocks
     * Article VIII: Metrics and Observability
     * Article IX: Graceful Degradation
     * Article X: Version Compatibility
     * Article XI: Documentation First

3. testing.md
   - Purpose: Comprehensive testing plan and verification
   - Size: 22K
   - Lines: 645
   - Checkboxes: 490
   - Sections:
     * Unit Tests (160+ tests)
     * Integration Tests (120+ tests)
     * Contract Tests (55 tests)
     * Performance Tests (90+ tests)
     * Compliance Tests (11 tests)
     * Failure Scenario Tests (54+ tests)

4. README.md
   - Purpose: Overview and usage guide for all checklists
   - Size: 6.2K
   - Lines: 196
   - Checkboxes: 4 (sign-off requirements)
   - Sections:
     * File descriptions
     * Usage guidelines
     * Key metrics and targets
     * Review process
     * Maintenance procedures

================================================================================
STATISTICS
================================================================================

Total Files: 4
Total Size: 68K
Total Lines: 2,219
Total Checkboxes: 1,306 (including README)

Breakdown by Category:
- Requirements Tracking: 457 checkboxes (35%)
- Constitutional Compliance: 355 checkboxes (27%)
- Testing & Verification: 490 checkboxes (38%)

================================================================================
KEY COVERAGE AREAS
================================================================================

USER STORIES (10 total):
✓ US-001: Agent Message Delivery via Postman
✓ US-002: Topic-Based Message Subscription
✓ US-003: Message Queue Management
✓ US-004: Message Priority Handling
✓ US-005: Message Filtering and Routing
✓ US-006: Message Persistence and Replay
✓ US-007: Delivery Guarantees and Acknowledgments
✓ US-008: Monitoring and Metrics
✓ US-009: Configuration Management
✓ US-010: Performance and Scalability

FUNCTIONAL REQUIREMENTS (11 total):
✓ FR-001: Message Envelope Structure
✓ FR-002: Message Payload Handling
✓ FR-003: Routing Engine
✓ FR-004: Queue Implementation
✓ FR-005: Topic Management
✓ FR-006: Subscription Manager
✓ FR-007: Delivery Receipts
✓ FR-008: Error Handling
✓ FR-009: Monitoring Interface
✓ FR-010: Administrative Interface
✓ FR-011: Configuration System

CONSTITUTIONAL ARTICLES (11 total):
✓ Article I: Agent Autonomy
✓ Article II: Prolog as Single Source of Truth
✓ Article III: Session Isolation
✓ Article IV: Hooks for Extensibility
✓ Article V: Minimal Core, Maximal Extension
✓ Article VI: Python 3.11+ Implementation
✓ Article VII: Testing Without Mocks
✓ Article VIII: Metrics and Observability
✓ Article IX: Graceful Degradation
✓ Article X: Version Compatibility
✓ Article XI: Documentation First

TESTING CATEGORIES:
✓ Unit Tests (message, queue, topic, routing, etc.)
✓ Integration Tests (Prolog, agents, sessions, hooks)
✓ Contract Tests (API, schema, backward compatibility)
✓ Performance Tests (throughput, latency, scalability)
✓ Compliance Tests (constitutional, security, integrity)
✓ Failure Scenario Tests (network, system, component failures)

================================================================================
PERFORMANCE TARGETS
================================================================================

Throughput: 5,000+ messages/second sustained
Latency (p95): <100ms
Latency (p99): <200ms
Scalability: 1,000 concurrent agents, 1,000 queues, 1,000 topics
Memory Usage: <1GB at target throughput
CPU Usage: <50% utilization at peak load
Test Coverage: >90% code coverage
Constitutional Compliance: 100%

================================================================================
ESTIMATED EFFORT
================================================================================

Based on 1,302 checkboxes with varying complexity:

- Requirements Implementation: 8-12 weeks
- Constitutional Compliance: 4-6 weeks
- Testing & Verification: 6-8 weeks
- Documentation: 2-4 weeks

Total Estimated Duration: 3-6 months (with team of 3-5 developers)

Critical Path:
1. Core message delivery (US-001, FR-001, FR-002, FR-003)
2. Queue and topic infrastructure (US-002, US-003, FR-004, FR-005)
3. Prolog integration (Article II)
4. Performance optimization (US-010)
5. Comprehensive testing (all test categories)

================================================================================
NEXT STEPS
================================================================================

1. Review checklists with architecture team
2. Prioritize requirements based on dependencies
3. Create detailed implementation plan
4. Assign work to development team
5. Begin implementation with daily checklist updates
6. Conduct regular reviews against checklists
7. Track completion metrics
8. Verify all compliance requirements

================================================================================
USAGE INSTRUCTIONS
================================================================================

For Developers:
- Check off items as you complete them
- Update progress regularly
- Reference requirements during implementation
- Verify constitutional compliance for each component
- Write tests according to testing checklist

For Reviewers:
- Verify all relevant checkboxes are addressed
- Ensure code matches requirements
- Confirm constitutional compliance
- Validate test coverage

For Project Managers:
- Track completion percentage
- Identify blockers
- Monitor progress against timeline
- Generate status reports

================================================================================
END OF SUMMARY
================================================================================

checklists/constitutional.md

Constitutional Compliance Checklist - Postman Integration

Project: Orchestrator-AI Postman Integration Version: 1.0.0 Last Updated: 2026-01-13 Reference: orchestrator-constitution.md

Overview

This checklist ensures the Postman Integration complies with all 11 articles of the Orchestrator-AI Constitution. Every component, interface, and implementation must adhere to these constitutional principles.

Total Items: 180+ checkboxes

Article I: Agent Autonomy

Principle: Agents are autonomous entities with explicit capabilities, constraints, and lifecycle management.

Agent Registration (Postman Context)
Agent Capabilities Declaration
Agent Lifecycle Management
Agent State Transitions
Agent Constraints
Article II: Prolog as Single Source of Truth

Principle: All authoritative knowledge resides in the Prolog knowledge base.

Postman State in Prolog
Prolog Fact Schemas
Prolog Query Integration
Prolog Update Protocol
Prolog Synchronization
Article III: Session Isolation

Principle: Sessions are isolated execution contexts with clear boundaries.

Session-Based Messaging
Session Queue Management
Session Topic Management
Session Message Routing
Session Cleanup
Session Statistics
Article IV: Hooks for Extensibility

Principle: Behavior is customizable through well-defined hook points.

Message Lifecycle Hooks
Subscription Lifecycle Hooks
Queue Lifecycle Hooks
Routing Hooks
Hook Implementation
Hook Configuration
Article V: Minimal Core, Maximal Extension

Principle: Core is minimal and stable; extensions add functionality.

Core Postman Functionality
Extension Modules
Extension Interface
Core Stability
Extension Guidelines
Article VI: Python 3.11+ Implementation

Principle: Implementation uses modern Python features and best practices.

Python Version Compliance
Type Annotations
Modern Python Features
Code Quality Standards
Package Management
Article VII: Testing Without Mocks

Principle: Tests use real implementations, not mocks.

Real Component Testing
Integration Tests
Test Data
Test Environment
No Mocking Policy
Article VIII: Metrics and Observability

Principle: All components expose metrics for monitoring and debugging.

Core Metrics
Latency Metrics
Throughput Metrics
Error Metrics
Resource Metrics
Metric Export
Structured Logging
Distributed Tracing
Article IX: Graceful Degradation

Principle: System degrades gracefully under failure conditions.

Failure Scenarios
Degraded Mode Operations
Circuit Breaker Pattern
Backpressure Handling
Fallback Behaviors
Recovery Procedures
Article X: Version Compatibility

Principle: Interfaces are versioned and backward compatible.

API Versioning
Message Format Versioning
Protocol Versioning
Backward Compatibility
Deprecation Policy
Article XI: Documentation First

Principle: Documentation is written before implementation.

Design Documentation
API Documentation
User Documentation
Developer Documentation
Operational Documentation
Documentation Standards
Compliance Verification
Automated Checks
Manual Reviews
Continuous Compliance
Completion Summary

Total Checkboxes: 180+ Completed: 0 In Progress: 0 Not Started: 180+

Progress: 0%

Notes

checklists/requirements.md

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

checklists/testing.md

Testing Checklist - Postman Integration

Project: Orchestrator-AI Postman Integration Version: 1.0.0 Last Updated: 2026-01-13

Overview

This checklist covers all testing requirements for the Postman Integration, including unit tests, integration tests, contract tests, performance tests, and compliance tests. Target throughput: 5000+ messages/second.

Total Items: 300+ checkboxes

Unit Tests
Message Envelope Tests (20 tests)
Queue Implementation Tests (30 tests)
Topic Management Tests (25 tests)
Subscription Manager Tests (20 tests)
Routing Engine Tests (30 tests)
Delivery Receipt Tests (15 tests)
Error Handling Tests (20 tests)
Integration Tests
Prolog Integration Tests (25 tests)
Agent Integration Tests (25 tests)
Session Integration Tests (20 tests)
Hook System Integration Tests (20 tests)
Multi-Component Workflow Tests (30 tests)
Contract Tests
Message Envelope Contract (10 tests)
Queue API Contract (10 tests)
Topic API Contract (10 tests)
Receipt API Contract (5 tests)
Metrics API Contract (10 tests)
Prolog Fact Contract (10 tests)
Performance Tests
Throughput Tests (Target: 5000 msg/sec)
Latency Tests (Target: <100ms p95)
Scalability Tests
Resource Usage Tests
Stress Tests
Endurance Tests
Spike Tests
Compliance Tests
Constitutional Compliance (11 tests)
Security Compliance
Data Integrity
Failure Scenario Tests
Network Failures
System Failures
Component Failures
Recovery Tests
Completion Summary

Total Checkboxes: 500+ Completed: 0 In Progress: 0 Not Started: 500+

Progress: 0%

Test Execution Guidelines
Test Environment
Performance Test Requirements
Test Reporting
Continuous Testing
Notes

Other tracked files

Full spec text

Verbatim from specs/002-postman/spec.md; headings are pushed down two levels.

SPEC-002: Postman Message Broker (U:PS)

Metadata

Overview

What

The Postman (U:PS) is the message routing engine for Orchestrata. It handles message delivery, topic-based subscriptions, queue management, priority processing, message filtering, persistence, and delivery guarantees.

Why
How

User Scenarios & Stories

US-001: Agent Message Delivery (Critical)

As an agent I want to send messages through the Postman service So that they are reliably delivered to recipients

Acceptance Criteria:

US-002: Topic-Based Message Subscription (Critical)

As an agent I want to subscribe to topics So that I receive relevant messages without direct addressing

Acceptance Criteria:

US-003: Message Queue Management (High)

As an agent I want to use message queues So that I can buffer and process messages asynchronously

Acceptance Criteria:

US-004: Message Priority Handling (High)

As a sender I want to assign priorities to messages So that urgent messages are processed first

Acceptance Criteria:

US-005: Message Filtering and Routing (High)

As a system administrator I want to filter and route messages So that messages reach the right destinations

Acceptance Criteria:

US-006: Message Persistence and Replay (High)

As a developer I want to persist and replay messages So that I can recover from failures and debug issues

Acceptance Criteria:

US-007: Delivery Guarantees and Acknowledgments (Critical)

As a sender I want to configure delivery guarantees So that messages are delivered reliably

Acceptance Criteria:

US-008: Monitoring and Metrics (High)

As a system operator I want to monitor the Postman service So that I can ensure system health

Acceptance Criteria:

US-009: Configuration Management (Medium)

As a system administrator I want to configure the Postman service So that I can tune for my environment

Acceptance Criteria:

US-010: Performance and Scalability (Critical)

As a system architect I want high performance and scalability So that the system handles load

Acceptance Criteria:

Functional Requirements

See checklists/requirements.md for 200+ detailed requirements.

Key Performance Targets
Operation Target
Message Delivery < 100ms (p95)
Queue Operations < 50ms (p95)
Topic Subscription < 50ms (p95)
ACK Processing < 10ms (p95)
Throughput 5000+ msg/sec

Technical Design

Architecture
┌─────────────────────────────────────────────────────────┐
│                  U:PS - Postman                          │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Message   │  │    Topic    │  │    Queue    │     │
│  │   Router    │  │   Manager   │  │   Manager   │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │             │
│  ┌──────┴──────┐  ┌──────┴──────┐  ┌──────┴──────┐     │
│  │   Delivery  │  │  Subscription│  │ Persistence │     │
│  │   Engine    │  │   Manager   │  │   Manager   │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
├─────────────────────────────────────────────────────────┤
│  Redis (Queues/Topics)  │  Disk (Persistence)          │
└─────────────────────────────────────────────────────────┘
Message Envelope
class MessageEnvelope:
    message_id: UUID
    sender: str                    # Agent ID
    recipient: str                 # Agent ID or topic
    timestamp: datetime            # ISO 8601
    priority: int                  # 0-4
    ttl: int                       # seconds
    correlation_id: Optional[str]  # For request-response
    reply_to: Optional[str]        # For responses
    content_type: str              # MIME type
    payload: Union[dict, bytes]
Delivery Semantics
class DeliveryMode(Enum):
    AT_MOST_ONCE = "fire_and_forget"
    AT_LEAST_ONCE = "with_retries"
    EXACTLY_ONCE = "with_dedup"

Integration Points

Component Integration
orchestrata-kernel Message routing decisions
orchestrata-cxp CXP packet handling
orchestrata-governance Delivery authorization
orchestrata-session Session-based isolation

Success Criteria

  1. Performance: 5000+ msg/sec, <100ms delivery latency
  2. Reliability: 99.99% message delivery rate
  3. Scale: 10,000+ concurrent connections
  4. Durability: Zero message loss with persistence enabled
  5. Flexibility: Support all three delivery guarantees

Dependencies

Revision History

Date Version Author Changes
2026-03-07 1.0 Mohamed Initial specification