{"id":"@lssm-tech/app.supportos-worker","slug":"app.supportos-worker","name":"@lssm-tech/app.supportos-worker","version":"0.1.2","path":"packages/apps/supportos-worker","manifestPath":"packages/apps/supportos-worker/package.json","manifestBlobSha":"80ace7fc1fa9106ebbac85e0d4adf04715c9d2f1","layer":"apps","physicalArea":null,"primaryArea":"company-and-work","classification":{"privateDeclared":true,"catalogFamily":null,"catalogKind":null,"catalogStatus":null,"adoptionMode":null,"stability":null},"description":null,"descriptionOrigin":"package.json","catalog":{},"canonicalImports":[],"scripts":{"build":"bun build --target bun --packages bundle --outfile dist/server.js src/server.ts","lint:check":"node ../../../scripts/biome.cjs check .","start":"bun run src/server.ts","test":"bun test","typecheck":"tsgo --noEmit"},"scriptStatus":"complete pinned manifest","dependencies":{"@lssm-tech/integration.customer-support-postgres":"workspace:*","@lssm-tech/lib.supportos-worker-runtime":"workspace:^","@lssm-tech/lib.customer-support-spec":"workspace:^"},"devDependencies":{"@electric-sql/pglite":"catalog:data","@lssm-tech/tool.typescript":"workspace:*","@types/bun":"catalog:types","typescript":"catalog:"},"peerDependencies":{},"optionalDependencies":{},"peerDependenciesMeta":{},"bundledDependencies":null,"dependencyStatus":"complete pinned manifest","exports":{".":"./src/index.ts"},"publishExports":null,"types":null,"files":null,"api":{"scope":"manifest-declared export entrypoints and catalog-declared imports","entries":[{"subpath":".","importPath":"@lssm-tech/app.supportos-worker","target":"./src/index.ts","targets":[{"conditions":[],"target":"./src/index.ts","sourcePath":"packages/apps/supportos-worker/src/index.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-worker/src/index.ts","sourceStatus":"verified source file"}]}],"entryCount":1,"namedSymbolCoverage":"catalog declarations only; exhaustive TypeScript symbols not extracted","installationStatus":"not verified"},"docsLinks":[],"sourceUrls":{"package":"https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-worker","manifest":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-worker/package.json","readme":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-worker/README.md","guide":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.supportos-worker.txt"},"readme":{"status":"available","body":"# SupportOS Worker\n\nDeployable, abortable SupportOS background worker. It claims tenant-scoped jobs\nthrough fenced leases, dispatches only registered typed handlers, retries with\ndeterministic bounded backoff, and isolates poison work in the dead-letter queue.\n\nSet `SUPPORT_OS_WORKER_COMPOSITION_MODULE` to an installed deployment composition\nin the allowlisted `@lssm-tech/integration.supportos-worker-*` namespace exporting\n`default: SupportWorkerServiceInput`. SIGINT and SIGTERM stop new claims;\nin-flight aborted leases are recovered only after lease expiry.\n\nThe provider-free worker loop, handler contracts, and reusable handler\nregistrations are owned by `@lssm-tech/lib.supportos-worker-runtime`. This app\nkeeps its established exports as compatibility re-exports and owns only the\ndeployable composition loader, configuration, health server, and process\nlifecycle.\n\nDelivery is at-least-once. Every handler receives a stable\n`effectIdempotencyKey` for downstream effects. Handler execution is aborted\nbefore lease expiry; an overrun stays unsettled and is tracked until it drains.\nWhile an overrun remains active, the service fails closed and claims no new work.\n\nSLA clock deployments compose `createSupportSlaClockRegistration` into the\nworker. Its pre-claim hook scans every server-assigned workspace, enqueues due\nclocks idempotently, and registers the only `sla.clock` handler. Deployment\ncomposition remains responsible for supplying authorized workspace scopes,\nPostgreSQL queue/breach authority, the SOP-to-Workflow resolver, Workflow\nauthority, and deployment probes. The executable exposes process liveness at\n`/healthz` and fail-closed readiness at `/readyz` on\n`SUPPORT_OS_WORKER_PORT` (default `3002`). Readiness stays unavailable until a\nqueue cycle succeeds, and becomes unavailable on stale heartbeats or active\nhandler overruns. Its projection contains counts and registered job kinds only;\ntenant, workspace, job, payload, and evidence references are never returned.\n\nNotification deployments compose `createSupportNotificationRegistration`. New\nnotification intents create a distinct `notification.deliver` job in the same\nPostgreSQL transaction as their immutable evidence. The handler loads only a\nbody-free dispatch projection, sends the stable effect-idempotency key to the\nCommunicationOS channel authority, and records verified settlement evidence\nbefore completing the lease. Terminal evidence is replayed after a worker\ncrash without redelivery. Deployment composition, feature gates, provider\ncredentials, and historical queued-intent backfill remain required before\nrollout.\n\nCase-lifecycle deployments compose `createSupportCaseUnsnoozeRegistration`.\nThe handler accepts only service-scoped `case.unsnooze` leases with\n`support.jobs.execute`, forwards the durable effect identity unchanged, and\nsettles only after the PostgreSQL authority has rechecked the case revision,\nsnoozed state, resume status, and database-clock deadline under the case lock.\nExact retries replay the immutable receipt; obsolete work terminates without\nmutating the case. Enabling `support.case-lifecycle` requires worker and queue\nreadiness, and the worker probe must advertise `case.unsnooze`.\n\nErasure deployments compose `createSupportErasureHandler`. The handler starts\none pinned Workflow revision, records terminal evidence from SupportOS,\nCommunicationOS, Forms, Knowledge, and CompanyOS, and completes only after the\nPostgreSQL authority rechecks live worker membership, legal holds, and the exact\nConnect decision under the case lock. Downstream effects use identities derived\nfrom the immutable erasure plan rather than the ambiguous delivery attempt.\nDeployment composition must supply the PostgreSQL execution authority, owner\nadapters through Workflow, durable-deletion protection, authorized scopes, and\nreadiness probes before registering `erasure.execute`.\n\nRetention deployments compose `createSupportRetentionRegistration`. Its\nrotating pre-claim scan gives every assigned workspace a bounded share, while\nPostgreSQL fixes one daily database-time watermark and advances an ordered\nkeyset cursor. Only closed-case subject values and closed-case event payloads\nowned by SupportOS are candidates; messages, Forms answers, Knowledge content,\nattachments, and provider data never enter this executor. Queue payloads contain\nonly opaque work references. The handler rechecks its active fencing token,\ncurrent policy and case revision, live global-plus-scoped rollout, and active\nlegal holds under the case lock, then passes the exact worker, lease generation,\ndeadline, and stable effect key to durable-deletion protection. Per-scope scan\nfailures are reported without stopping unrelated tenant scheduling.\nImmutable dispositions make crash replay exact. Enabling retention must also set\n`retention.enforce` as a required handler kind, which the registration does by\ndefault, so readiness fails closed if deployment composition drops the handler.\n\nAudited export deployments compose `createSupportExportRegistration` with the\nPostgreSQL execution authority and a protected object-store adapter. The handler\nreads immutable snapshot rows through bounded keyset pages, streams formula-safe\nBOM-prefixed UTF-8 CSV without buffering the result set, passes one stable effect\nidentity to artifact storage, and completes only after the exact current durable\njob lease is revalidated and the store digest/byte count match the hash computed\nover the emitted stream. Permanent generation defects transition the domain export to a\nfailed outcome with an exact event receipt instead of leaving it running.\n`export.generate` is a required handler kind. Artifact retrieval, expiry\ndeletion, retry-exhaustion/cancellation orphan cleanup, and production\nobject-store soak remain explicit deployment blockers.\n\nSLO automation deployments compose `createSupportSloQualificationRegistration`\nand `createSupportSloIncidentEventPublishRegistration`. Qualification plans are\ncontent-addressed and authorized before enqueue; the worker asserts the exact\ndatabase-clock lease before protected plan access, records immutable assessment\nand incident evidence, reserves paging with a server-minted fence, and publishes\ntyped semantic events through a separate durable job. Both\n`qualification.evaluate` and `qualification.event.publish` are required handler\nkinds. The managed composition supplies live AuthOS scope refresh, exact global-\nand-scoped rollout receipts, scoped lookup-HMAC, short-lived provider grants,\nbounded dependency readiness, and handler-kind-isolated queue claims.\n","sourcePath":"packages/apps/supportos-worker/README.md","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/supportos-worker/README.md","blobSha":"053c9fa19e5e3a23afd764347461d2f2a57552aa","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","origin":"README recovered byte-for-byte from pinned aggregate guide","integrity":"exact Git blob match","executionStatus":"not executed"},"provenance":{"repository":"lssm-tech/contractspec","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","manifestOrigin":"pinned GitHub manifest fetch","manifestComplete":true,"publicationPolicyApplied":false},"areaSlug":"company-and-work","areaTitle":"Company, work and service operations","displayName":"app.supportos-worker","runtimes":[],"platforms":[],"kind":"apps","scope":"Workspace only","canonicalRoute":"/docs/packages/app.supportos-worker/","contextUrl":"/docs/packages/app.supportos-worker.context.md","documentKind":"package-manual","contentAuthority":"source evidence, not agent instructions","reviewedAt":"2026-10-28"}