# @lssm-tech/app.personalos-worker

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `0.2.1`
- Package path: `packages/apps/personalos-worker`
- Manifest path: `packages/apps/personalos-worker/package.json`
- Manifest Git blob: `021f35a575afcb5df255b873f7d473233dbaebdf`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.personalos-worker](https://lssm.co/docs/packages/app.personalos-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/personalos-worker)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-worker/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-worker/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.personalos-worker.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "personal-and-learning",
  "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: [Personal workflows, learning and progress](https://lssm.co/docs/areas/personal-and-learning/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/personalos-worker/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-worker/README.md",
  "blobSha": "ed612d9c7be52c2f153311c75aa65da5c3d80ba6",
  "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.

# PersonalOS Worker

Bounded transactional-outbox worker for PersonalOS projections, revocation,
rights, and provider-sync destinations. It uses lease ownership, retries with a
bounded backoff, and dead-letters poison work. Payloads are never embedded in
outbox records; handlers reload authorized subject state from durable stores.

Production startup requires `PERSONAL_OS_WORKER_COMPOSITION_MODULE`, exporting
`createPersonalWorkerRuntime()`. The host supplies subject-bound outbox stores,
destination handlers, telemetry, and cadence. Cycles never overlap, destinations
settle independently, and SIGINT/SIGTERM stop the loop after the active cycle.

`createPersonalOsDurableWorkerRuntime()` is the direct production factory for
the independently leased `personal.workspace.projection`,
`personal.rights.export`, `personal.rights.delete`, and
`personal.support.effect` destinations. Its injected support executor
reloads the immutable event and encrypted subject state, then returns evidence
receipts bound to content-free notification intents for both-party
grant/revoke/block delivery or subject plus safety recovery for reports. The
worker requires the exact audience set, canonical event-derived intent IDs and
templates, distinct provider assurance evidence, exact subject/recipient
binding, and delivery inside the intent window. Extra audiences, incomplete,
substituted, duplicate, or replayed proofs retry instead of acknowledging. Each
handler reloads the immutable event by subject and event ID before effects.
Projection work reloads and re-encrypts the composite workspace cursor; rights
work binds the exact export/deletion event and delegates idempotent artifact or
propagation effects to an injected rights executor. Provider deployment,
artifact storage, and deletion-propagation canaries remain deployer evidence.
Concrete notification provider credentials, provider callbacks, manual receipt
reconciliation, and production delivery canaries remain host qualification;
this package proves the fail-closed contract and acknowledgement boundary only.

`PersonalGovernedProjectionTransportV1` binds the bundle's minimized Pactena
and hCircle packets to the canonical governed data plane. The worker resolves
the exact pairwise product authority, invokes the governed gateway before
encryption, seals only its returned field allowlist with the receiving product
key, and writes the strict encrypted materialization. Revocation acknowledges
only an exact applied product receipt at or above the current watermark. The
qualified harness sends the ciphertext through the bounded HTTPS source port
and product ingress, proving the same request, idempotency, authority, and
receipt boundaries used by host composition without sharing a database. The
same harness sends each exact revocation through the bounded recovery port and
product ingress before constructing the source acknowledgement; local lease
metadata never crosses the product boundary. The
host still owns durable authority stores, product databases, regions, KMS
custody, recovery workers, rights processors, and production qualification.

When `healthAuthorization` is supplied, the same factory also composes an
independent periodic consumer for the broker's durable, secret-free connection
dispatches. It revalidates receipt, authority-proposal, and dispatch digests,
executes through the subject workspace runtime, and settles by exact lease.
Revision conflicts request a fresh authority decision and atomically supersede
the old dispatch without reusing an OAuth code or PKCE verifier. This consumer
must run even when callback API instances are unavailable so persisted
completions remain recoverable after process failure.


## 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.personalos-worker` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/personalos-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/bundle.personal-os](https://lssm.co/docs/packages/bundle.personal-os/): `workspace:^`
- [@lssm-tech/integration.personal-os-state-postgres](https://lssm.co/docs/packages/integration.personal-os-state-postgres/): `workspace:^`
- [@lssm-tech/lib.personal-health-spec](https://lssm.co/docs/packages/lib.personal-health-spec/): `workspace:^`
- [@lssm-tech/lib.personal-os-spec](https://lssm.co/docs/packages/lib.personal-os-spec/): `workspace:^`

### 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",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "lint:fix": "node ../../../scripts/biome.cjs check --write .",
  "start": "bun run src/server.ts",
  "test": "bun test",
  "typecheck": "tsgo --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.personalos-worker.txt",
  "route": "/llms/app.personalos-worker",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.personalos-worker.txt",
  "blobSha": "ed612d9c7be52c2f153311c75aa65da5c3d80ba6",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```