agent-call/docs/contracts/mq-topology.md

agent-call MQ topology v1.0

This file is an implementation companion to the field authority in SaaS交互_OpenAPI与MQ契约规划_v0.1.md.

Element	Value
Namespace	agent-call
Command exchange	agent-call.commands.v1, durable direct
Tenant command queue	agent-call.executor.{tenant_key}.v1, durable, one exact binding
Command routing key	agent-call.tenant.{tenant_key}.call.execute
Event exchange	agent-call.events.v1, durable topic
SaaS result queue	agent-call.saas.events.v1, durable, binding agent-call.#
Event routing key	agent-call.{event_type}
Body limit	262144 UTF-8 bytes in the Mock profile
Tenant route budget	Broker limit 255 bytes; fixed prefix/suffix consume 31, leaving 224 UTF-8 bytes

Delivery rules

1. SaaS persists the command publication record before publishing. A mandatory publisher confirmation is required; an unroutable/full queue leaves the original record retained for bounded retry.
2. The executor consumes only its trusted tenant queue. RabbitMQ messages are acknowledged after durable SQLite acceptance or durable dead-lettering, not when they are fetched.
3. Executor business events are written to the same database transaction as the state transition. The outbox dispatcher publishes them durably and the SaaS inbox applies each event_id once. saas_applied may remain unknown after broker confirmation; it does not trigger unbounded republishing.
4. tenant_key is copied byte-for-byte into the body, queue name, binding and routing key. It is not normalized, encoded, truncated or cleaned. A route over the byte budget is retained and not sent.
5. Replay publishes the original event body and original event_id from a fixed retention cutoff. It never creates a new business fact and never includes events written after that cutoff.
6. HTTP has no call execution or redial endpoint. Control, query, replay and recording metadata paths require bearer scope and tenant scope.

The in-process broker is only for deterministic tests. Docker Compose uses the same topology through the pika adapter and RabbitMQ durable queues.