app.worker-application-monolith

Managed CompanyOS Worker Application Monolith

Production status (Vercel-only Managed CompanyOS): this package is not part of the managed CompanyOS production deployment while the cost-capped Vercel topology is active. Production duties are absorbed by packages/apps/api-application-monolith through API snapshots and Vercel Cron, and the web app uses manual refresh/request-time snapshots. Keep this Bun runtime for deterministic proofs, local monitoring, and future VPS mode only; do not wire it as a production readiness dependency for Vercel.

This deferral is part of the canonical private-pilot contract^†. Do not activate this worker for the first design-partner pilot.

VPS-suitable Bun worker and WebSocket runtime for Managed CompanyOS background jobs. It publishes deterministic operating-graph snapshots, tracks worker supervision health, and keeps all job projection side-effect-free until production queue, persistence, and provider adapters are approved.

No queue, provider, network, or credential side effects start at module load. The runtime starts only through bun src/server.ts / bun run start.

Special Ops projection contract

The worker-side Special Ops production contract is documented in docs/runbooks/special-ops-monolith-production.md^†. Worker projections must consume a repository-compatible tenant/workspace/capability snapshot, preserve correlation IDs across jobs, WebSocket events, replay, and evidence, and surface degraded/stale Special Ops state instead of hiding it behind a green worker response.

Runtime surface

HTTP endpoints

Unknown paths return { error: "…" } with status 404.

Worker supervision health

GET /worker-supervision returns a ManagedWorkerSupervisionHealth object:

WebSocket message schema

Every /ws push and /graph-snapshot response is a ManagedCompanyOsWebSocketMessage:

{
  type: 'managed-companyos.graph.snapshot';
  tenantId: string;
  correlationId: string;        // links jobs, replay events, and evidence receipt
  nodeCount: number;
  edgeCount: number;
  replayEventCount: number;
  replayEventIds: readonly string[];
  evidenceReceiptId: string;
  workerJobIds: readonly string[];
  workerStatus: 'queued' | 'running' | 'completed' | 'degraded' | 'stale';
  degraded: boolean;
  stale: boolean;
  idempotentReplay: boolean;    // true when the same idempotencyKey was replayed
  degradedReasons: readonly string[];
}

WebSocket event stream

projectWorkerWebSocketEvents(proof) projects the worker proof into an ordered sequence of typed events. All events carry correlationId and sequence:

Events are ordered by ascending sequence numbers. Degraded proofs emit job-failed instead of job-completed.

Worker job inventory

Job lifecycle: queued → running → completed (healthy) or degraded / stale (unhealthy).

Correlation ID contract

A single correlationId links the entire proof chain:

proof.correlationId
  == each job.correlationId
  == each WS event.correlationId
  == each replay event.correlationId
  == evidenceReceipt.correlationId

Validate with assertManagedWorkerCorrelation(proof) — returns { valid: boolean, reasons: string[] }.

Degraded-state detection

The runtime surfaces degraded and stale conditions instead of hiding them behind healthy status:

In future VPS mode, a green API response must not hide a degraded realtime runtime. In the active Vercel-only topology, /api/companyos/health/degraded reports API and scheduled snapshot duty health instead of requiring this package.

Stale-job cleanup and idempotency

The deterministic in-memory store (createDeterministicManagedWorkerStore) enforces idempotency:

• A run with the same idempotencyKey returns the cached proof with idempotentReplay: true.
• Stale jobs are counted and surfaced — they are not silently discarded.
• Pass a fresh idempotencyKey to force a new run: GET /graph-snapshot?idempotencyKey=fresh-key-001

WebSocket reconnect client

import { connectManagedCompanyOsLiveClientWithReconnect } from './src/live-client';

const proof = await connectManagedCompanyOsLiveClientWithReconnect({
  url: 'ws://worker.host/ws?tenantId=tenant_id',
  maxAttempts: 3,       // default: 3
  initialBackoffMs: 100, // default: 100ms; doubles each retry (100 → 200 → 400)
  timeoutMs: 1000,      // per-attempt timeout; default: 1000ms
});
// proof.connected, proof.attempts, proof.lastBackoffMs, proof.message

Environment variables

Copier deploy/env/worker.env.example to /etc/managed-companyos/worker.env and fill values from the secret manager. Never write raw provider credentials to logs, fixtures, or API responses.

Local commands

bun run --cwd packages/apps/worker-application-monolith dev
bun run --cwd packages/apps/worker-application-monolith test
bun run --cwd packages/apps/worker-application-monolith typecheck
bun run --cwd packages/apps/worker-application-monolith lint:check
bun run --cwd packages/apps/worker-application-monolith build

Build output: dist/index.js (Bun target). Production start: bun dist/index.js.

Integration Points

WebSocket Client Integration

External systems receive real-time graph updates by connecting a WebSocket client to /ws:

import { connectManagedCompanyOsLiveClientWithReconnect } from '@lssm-tech/app.worker-application-monolith/src/live-client';

const proof = await connectManagedCompanyOsLiveClientWithReconnect({
  url: 'ws://worker.host/ws?tenantId=tenant_123',
  maxAttempts: 3,
  initialBackoffMs: 100, // doubles each retry
  timeoutMs: 1000
});

// proof.message is ManagedCompanyOsWebSocketMessage
// proof.connected indicates success

Each message carries a correlationId that links to API requests, replay packets, and evidence receipts.

Health Polling

External monitoring can poll worker health via HTTP:

# Instant health snapshot (no stale-job cleanup)
curl http://worker.host/health?tenantId=tenant_id

# Worker supervision health (includes job/replay/WebSocket metrics)
curl http://worker.host/worker-supervision?tenantId=tenant_id

# Graph snapshot (deterministic projected state)
curl http://worker.host/graph-snapshot?tenantId=tenant_id&idempotencyKey=key_xyz

A degraded Bun runtime returns { degraded: true, degradedReasons: [...] } for local/future-VPS monitoring. In the active Vercel-only topology, production readiness is proven by API snapshot routes and Vercel Cron evidence rather than this process.

MCP Tool Integration

For AI agents, the planned @lssm-tech/app.managed-companyos-mcp server exposes worker health, job status, replay packet fetching, and evidence verification as MCP tools. Agents can query job state and fetch replay/evidence receipts without holding open a WebSocket connection.

Correlation ID Guarantees

Every worker run produces a correlationId that persists across:

• Job execution (job.correlationId)
• WebSocket messages (ManagedCompanyOsWebSocketMessage.correlationId)
• Replay events (replayEvent.correlationId)
• Evidence receipts (evidenceReceipt.correlationId)

Validate the full chain with assertManagedWorkerCorrelation(proof) in production health checks.

Build output: dist/index.js (Bun target). Production start: bun dist/index.js.

For the full operator runbook (deploy, start/stop, degraded triage, replay regen, evidence verification), see docs/runbooks/managed-companyos.md^†.