# @lssm-tech/app.communicationos-worker

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `0.7.4`
- Package path: `packages/apps/communicationos-worker`
- Manifest path: `packages/apps/communicationos-worker/package.json`
- Manifest Git blob: `715ae4a31132c447a4d9a50637ef5dd6a667e7cd`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.communicationos-worker](https://lssm.co/docs/packages/app.communicationos-worker/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.communicationos-worker.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "communication-and-notifications",
  "classification": {
    "privateDeclared": true,
    "catalogFamily": null,
    "catalogKind": null,
    "catalogStatus": null,
    "adoptionMode": null,
    "stability": null
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: true — workspace only.

Primary area: [Communication and notifications](https://lssm.co/docs/areas/communication-and-notifications/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/communicationos-worker/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker/README.md",
  "blobSha": "30ba745f1aef3cbb7e15f3004ecd81c492a9a190",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# 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.


## Declared capabilities

This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source.

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

- `@lssm-tech/app.communicationos-worker` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker/src/index.ts); verified source file.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": null,
  "files": null,
  "publishExports": null
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/integration.communication-channel-core](https://lssm.co/docs/packages/integration.communication-channel-core/): `workspace:*`
- [@lssm-tech/integration.communication-channel-email](https://lssm.co/docs/packages/integration.communication-channel-email/): `workspace:*`
- [@lssm-tech/integration.communication-channel-slack](https://lssm.co/docs/packages/integration.communication-channel-slack/): `workspace:*`
- [@lssm-tech/integration.communication-channel-sms](https://lssm.co/docs/packages/integration.communication-channel-sms/): `workspace:*`
- [@lssm-tech/integration.communication-channel-telegram](https://lssm.co/docs/packages/integration.communication-channel-telegram/): `workspace:*`
- [@lssm-tech/integration.communication-os-persistence](https://lssm.co/docs/packages/integration.communication-os-persistence/): `workspace:*`
- [@lssm-tech/integration.company-intelligence-postgres](https://lssm.co/docs/packages/integration.company-intelligence-postgres/): `workspace:*`
- [@lssm-tech/integration.provider-database](https://lssm.co/docs/packages/integration.provider-database/): `workspace:*`
- [@lssm-tech/integration.provider-email](https://lssm.co/docs/packages/integration.provider-email/): `workspace:*`
- [@lssm-tech/integration.provider-embedding](https://lssm.co/docs/packages/integration.provider-embedding/): `workspace:*`
- [@lssm-tech/integration.provider-messaging](https://lssm.co/docs/packages/integration.provider-messaging/): `workspace:*`
- [@lssm-tech/integration.provider-sms](https://lssm.co/docs/packages/integration.provider-sms/): `workspace:*`
- [@lssm-tech/integration.provider-storage](https://lssm.co/docs/packages/integration.provider-storage/): `workspace:*`
- [@lssm-tech/integration.provider-vector-store](https://lssm.co/docs/packages/integration.provider-vector-store/): `workspace:*`
- [@lssm-tech/integration.runtime](https://lssm.co/docs/packages/integration.runtime/): `workspace:*`
- [@lssm-tech/lib.communication-runtime](https://lssm.co/docs/packages/lib.communication-runtime/): `workspace:*`
- [@lssm-tech/lib.knowledge](https://lssm.co/docs/packages/lib.knowledge/): `workspace:*`
- `resend`: `^6.28.1`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@types/bun`: `catalog:types`
- `typescript`: `catalog:`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "build": "bun build --target bun --packages bundle --outfile dist/server.js src/server.ts",
  "migrate": "bun run src/migrate.ts",
  "start": "bun run src/server.ts",
  "test": "bun test",
  "typecheck": "bun --bun x tsgo --project tsconfig.json --noEmit"
}
```

## Declared documentation links

No additional documentation links are declared in the inspected catalogue.

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/app.communicationos-worker.txt",
  "route": "/llms/app.communicationos-worker",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.communicationos-worker.txt",
  "blobSha": "30ba745f1aef3cbb7e15f3004ecd81c492a9a190",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```