Cloud Pub/Sub transports stage wake-ups. Firestore—not the message—is the source of truth for whether work is eligible and what payload should run.
How Harmonia uses it
The web service writes a durable stage outbox alongside workflow state. Dispatch publishes a compact tenant/job/stage envelope to harmonia-stages. A private worker push subscription delivers messages to /pubsub/push with OIDC authentication. The worker claims the stage in Firestore before execution and finalizes the claim afterward.
A dead-letter topic retains exhausted deliveries. Cloud Scheduler-driven recovery republishes due outbox entries and reconciles abandoned claims.
Security and authority
Messages contain identifiers and correlation metadata, not credentials or full source content. The push audience and service account are fixed during deployment. Receipt of a message never authorizes an effect; the worker reconstructs current authority from Firestore.
Failure behavior
Transient failures are nacked for redelivery. Permanent protocol or policy failures are persisted visibly. Duplicate deliveries are safe because stage claims and deterministic operation IDs prevent duplicate work.
Evidence status
The emulator and automated suites cover outbox, claims, retries, and duplicate delivery. Production delivery requires correlated Pub/Sub message, worker trace, and Firestore claim evidence.
Relevant files
src/lib/pubsub.tssrc/lib/stageOutbox.tsagent/harmonia_agent/main.pyagent/harmonia_agent/stages.pyinfra/deploy.sh
Last modified on August 28, 2026
