app.communicationos-worker

CommunicationOS worker

Provider effects remain behind canonical Runtime Node approval and its execution fence. The worker claims and settles durable outbox records; it does not manufacture approval.

The journal resolver requires current sender membership and applicable agent grants. Deleted messages and revoked memberships cannot resolve provider context. Dispatch snapshots context before adapter/health calls and resolves again immediately before sending; changed recipients, content, credentials or routing metadata are rejected without provider.send.

Ownership: the subscription lifecycle coordinator and connection sync coordinator belong to @lssm-tech/lib.communication-runtime (./ecosystem-subscription-coordinator, ./ecosystem-connection-sync). This host binds them to the Runtime Node subscription authority, the secret-backed adapter resolver and CommunicationDeliveryError, and schedules them through the sync and subscription workers.

Capability readiness

Read (synchronization), draft and send readiness are reported separately in /health (capabilities). Started without DATABASE_URL, the worker stays up, opens no connection, starts no loop and answers /health with 503 configuration_required / database_not_configured, listing DATABASE_URL under missing for every capability. Sync-only installations (COMMUNICATION_OS_WORKER_ENABLE_SYNC=true, delivery disabled) ingest with state partial while sends report their blocker. Sync and delivery run on independent loops.

Sends require COMMUNICATION_OS_WORKER_ENABLE_DELIVERY=true, a credential-reference policy and an actual Runtime Node delivery port: COMMUNICATION_OS_RUNTIME_NODE_DELIVERY_URL (HTTPS, or loopback HTTP) plus COMMUNICATION_OS_RUNTIME_NODE_WORKLOAD_TOKEN (COMMUNICATION_OS_RUNTIME_NODE_TIMEOUT_MS, default 15000). Without them every claimed record is rejected with runtime_node_authority_not_configured. The port posts { schema: "communication.runtime-node.delivery-effect.v1", outboxRecord } with an Idempotency-Key; a timeout, lost response, malformed success or 5xx is held in reconciliation custody and never resent.

Gmail connections synchronize through durable, account-bound history sync: a bounded backfill (COMMUNICATION_OS_GMAIL_BACKFILL_QUERY, e.g. after:2019/01/01), history catch-up from the pre-scan baseline, and incremental history afterwards. The cursor is journaled only after a page's records commit. Credentials may record grantedScopes; a credential without a send scope refuses sends while read-only sync continues. Every Gmail read is bound to the connection's authorized address: a credential that authenticates another mailbox is connection_scope_mismatch and the connection becomes revoked; a transient provider failure is offline and is retried on the next poll. A message that fails on its own (non-retryable typed error or normalization failure) is recorded as a message_held sync invalidation and keeps coverage partial. Founder connections are created by the CommunicationOS Gmail OAuth flow; see docs/operations/founder-ops-v2/gmail-connect.md.

Schema and outbox recovery

The worker never migrates in production. Run bun run migrate (explicit step, same DATABASE_URL) before rolling out workers; at start the worker only verifies the migration ledger and reports schema_version_mismatch on every capability when its migrations are missing or differ. COMMUNICATION_OS_WORKER_MIGRATE_ON_START=true is a development/test convenience and is ignored when NODE_ENV=production. A re-claimed expired outbox lease is held in reconciliation custody (lease_expired_outcome_unknown) instead of being redispatched, once the store marks it (reclaimedExpiredLease). A database that cannot be reached or refuses the login is reported as database_unreachable (reason connection, authentication, tls_handshake, tls_not_offered — sslmode=require against a server that offers no TLS, diagnosed with one SSLRequest — or query_failed, never the URL or message), distinct from schema_version_mismatch, whose body lists migrations.expected, found and missing ids. /health is always Cache-Control: no-store. The schema is checked once at start: restart the worker after the database becomes reachable or is migrated; a persistent 503 on /health lets the orchestrator's health check restart it.

Evidence ingestion

With COMMUNICATION_OS_EVIDENCE_ENABLED=true and a complete binding (COMMUNICATION_OS_EVIDENCE_TENANT_ID, _ORIGINALS_BUCKET, _COLLECTION, _QDRANT_URL, optional _QDRANT_API_KEY and _NAMESPACE, _EMBEDDING_API_KEY, _EMBEDDING_MODEL, _REDACTION_DECISION_REF, plus a durable evidence ledger supplied by the host), Gmail sync hands every attachment original to knowledge custody (one original per digest, one provenance per account) and ingests each thread with account-bound ids; provider deletions withdraw the thread. Anything missing reports evidence_ingestion as evidence_binding_not_configured with the missing names, and sync continues without evidence. This host does not compose a durable ledger yet, so the row stays blocked on durable_evidence_ledger.

Run bun run typecheck, bun run build, and the delivery-dispatcher/journal-delivery-context/Slack/Teams pipeline tests. These synthetic tests do not qualify deployed providers, OPA follow-up source authority or production rollout.