orchestrata_ultimate.postman

Reference › orchestrata_ultimate › postman

Postman (U:PS) - Message routing and delivery engine

The postman package is the message broker (U:PS, SPEC-002) between Orchestrata's agents: it takes a CXPPacket from a sender and gets it to the right recipient handler, queue or topic subscribers, with a record of what happened. Redis holds its queues and thread trail when available, with in-memory fallbacks. The hand-written story is the curated postman page. Its main user is the kernel: cli_main starts a Postman, and the pipeline registers each volk's handler with it.

How messages move:

• Synchronous path: the pipeline calls route_sync (sync_router) for every hop. It stamps a deterministic id, drops duplicates, persists the packet to the thread's Redis list, queues it, runs the recipient's registered handler and returns the stamped reply. A human intent travels this way from HUMAN to the concierge volk, and the reply travels back.
• Async path: postman offers route, aroute and aroute_outcome (delivery_outcome) and publish_topic for pub/sub fan-out.
• Envelope path, the component-based design: envelope and payload build and validate messages, router resolves recipients, and delivery places the message on recipient queues.

Parts, by role:

• Contracts and types: interfaces, types, constants, exceptions.
• Routing: router, routing_rules, filter, topic_registry, subscription_manager.
• Queues and guarantees: queue, queue_manager, priority, guarantees.
• Storage: message_store, receipt_store, replay_engine.
• Resilience, policy and operations: error_handler, governance, metrics, health, admin, config, event_emitting_postman.

The entry points are the Postman class, re-exported by init, and the standalone cli. Start reading at postman, then sync_router.

Curated narrative

The hand-written story of this package: orchestrata_ultimate.postman.

31 modules, 11,199 lines of code.

Modules

Dependency diagram