> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useharmonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Pub/Sub

> How Harmonia uses Pub/Sub for recoverable asynchronous stage delivery.

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.ts`
* `src/lib/stageOutbox.ts`
* `agent/harmonia_agent/main.py`
* `agent/harmonia_agent/stages.py`
* `infra/deploy.sh`