app.supportos-worker

SupportOS Worker

Deployable, abortable SupportOS background worker. It claims tenant-scoped jobs through fenced leases, dispatches only registered typed handlers, retries with deterministic bounded backoff, and isolates poison work in the dead-letter queue.

Set SUPPORT_OS_WORKER_COMPOSITION_MODULE to an installed deployment composition in the allowlisted @lssm-tech/integration.supportos-worker-* namespace exporting default: SupportWorkerServiceInput. SIGINT and SIGTERM stop new claims; in-flight aborted leases are recovered only after lease expiry.

The provider-free worker loop, handler contracts, and reusable handler registrations are owned by @lssm-tech/lib.supportos-worker-runtime. This app keeps its established exports as compatibility re-exports and owns only the deployable composition loader, configuration, health server, and process lifecycle.

Delivery is at-least-once. Every handler receives a stable effectIdempotencyKey for downstream effects. Handler execution is aborted before lease expiry; an overrun stays unsettled and is tracked until it drains. While an overrun remains active, the service fails closed and claims no new work.

SLA clock deployments compose createSupportSlaClockRegistration into the worker. Its pre-claim hook scans every server-assigned workspace, enqueues due clocks idempotently, and registers the only sla.clock handler. Deployment composition remains responsible for supplying authorized workspace scopes, PostgreSQL queue/breach authority, the SOP-to-Workflow resolver, Workflow authority, and deployment probes. The executable exposes process liveness at /healthz and fail-closed readiness at /readyz on SUPPORT_OS_WORKER_PORT (default 3002). Readiness stays unavailable until a queue cycle succeeds, and becomes unavailable on stale heartbeats or active handler overruns. Its projection contains counts and registered job kinds only; tenant, workspace, job, payload, and evidence references are never returned.

Notification deployments compose createSupportNotificationRegistration. New notification intents create a distinct notification.deliver job in the same PostgreSQL transaction as their immutable evidence. The handler loads only a body-free dispatch projection, sends the stable effect-idempotency key to the CommunicationOS channel authority, and records verified settlement evidence before completing the lease. Terminal evidence is replayed after a worker crash without redelivery. Deployment composition, feature gates, provider credentials, and historical queued-intent backfill remain required before rollout.

Case-lifecycle deployments compose createSupportCaseUnsnoozeRegistration. The handler accepts only service-scoped case.unsnooze leases with support.jobs.execute, forwards the durable effect identity unchanged, and settles only after the PostgreSQL authority has rechecked the case revision, snoozed state, resume status, and database-clock deadline under the case lock. Exact retries replay the immutable receipt; obsolete work terminates without mutating the case. Enabling support.case-lifecycle requires worker and queue readiness, and the worker probe must advertise case.unsnooze.

Erasure deployments compose createSupportErasureHandler. The handler starts one pinned Workflow revision, records terminal evidence from SupportOS, CommunicationOS, Forms, Knowledge, and CompanyOS, and completes only after the PostgreSQL authority rechecks live worker membership, legal holds, and the exact Connect decision under the case lock. Downstream effects use identities derived from the immutable erasure plan rather than the ambiguous delivery attempt. Deployment composition must supply the PostgreSQL execution authority, owner adapters through Workflow, durable-deletion protection, authorized scopes, and readiness probes before registering erasure.execute.

Retention deployments compose createSupportRetentionRegistration. Its rotating pre-claim scan gives every assigned workspace a bounded share, while PostgreSQL fixes one daily database-time watermark and advances an ordered keyset cursor. Only closed-case subject values and closed-case event payloads owned by SupportOS are candidates; messages, Forms answers, Knowledge content, attachments, and provider data never enter this executor. Queue payloads contain only opaque work references. The handler rechecks its active fencing token, current policy and case revision, live global-plus-scoped rollout, and active legal holds under the case lock, then passes the exact worker, lease generation, deadline, and stable effect key to durable-deletion protection. Per-scope scan failures are reported without stopping unrelated tenant scheduling. Immutable dispositions make crash replay exact. Enabling retention must also set retention.enforce as a required handler kind, which the registration does by default, so readiness fails closed if deployment composition drops the handler.

Audited export deployments compose createSupportExportRegistration with the PostgreSQL execution authority and a protected object-store adapter. The handler reads immutable snapshot rows through bounded keyset pages, streams formula-safe BOM-prefixed UTF-8 CSV without buffering the result set, passes one stable effect identity to artifact storage, and completes only after the exact current durable job lease is revalidated and the store digest/byte count match the hash computed over the emitted stream. Permanent generation defects transition the domain export to a failed outcome with an exact event receipt instead of leaving it running. export.generate is a required handler kind. Artifact retrieval, expiry deletion, retry-exhaustion/cancellation orphan cleanup, and production object-store soak remain explicit deployment blockers.

SLO automation deployments compose createSupportSloQualificationRegistration and createSupportSloIncidentEventPublishRegistration. Qualification plans are content-addressed and authorized before enqueue; the worker asserts the exact database-clock lease before protected plan access, records immutable assessment and incident evidence, reserves paging with a server-minted fence, and publishes typed semantic events through a separate durable job. Both qualification.evaluate and qualification.event.publish are required handler kinds. The managed composition supplies live AuthOS scope refresh, exact global- and-scoped rollout receipts, scoped lookup-HMAC, short-lived provider grants, bounded dependency readiness, and handler-kind-isolated queue claims.