process-composition
/process-composition
Compose a LangWatch process (apps/api, apps/worker, apps/tasks, apps/backend): main.ts and config.ts, the Server preamble (withEnvironment, withConfig, withSecrets, withTelemetry, withMetrics, start), server.container(role), exposeTransports, boot(), serve and run; what boot() does with stores, registries, peers, config slices and roles; config declared at its owner and parsed once (Config.define, processConfig, one env var one owner); secrets as handles resolved through into and sealed after boot; stores, the live and memory tiers, and migrations run by the worker's upgrade; installation test
- Author
- langwatch ↗
- Repository
- langwatch ↗
- Licence
- Apache-2.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Compose a LangWatch process (apps/api, apps/worker, apps/tasks, apps/backend): main.ts and config.ts, the Server preamble (withEnvironment, withConfig, withSecrets, withTelemetry, withMetrics, start), server.container(role), exposeTransports, boot(), serve and run; what boot() does with stores, registries, peers, config slices and roles; config declared at its owner and parsed once (Config.define, processConfig, one env var one owner); secrets as handles resolved through into and sealed after boot; stores, the live and memory tiers, and migrations run by the worker's upgrade; installation test
Original author description
Compose a LangWatch process (apps/api, apps/worker, apps/tasks, apps/backend): main.ts and config.ts, the Server preamble (withEnvironment, withConfig, withSecrets, withTelemetry, withMetrics, start), server.container(role), exposeTransports, boot(), serve and run; what boot() does with stores, registries, peers, config slices and roles; config declared at its owner and parsed once (Config.define, processConfig, one env var one owner); secrets as handles resolved through into and sealed after boot; stores, the live and memory tiers, and migrations run by the worker's upgrade; installation test
How it works
- The shape in the tree
- The rules
- Backed by
- Worked example: a module gains a deployment value
- Traps
- Known disagreements between the record and the tree
- Checks
- Links
SKILL.md preview
---
name: process-composition
description: "Compose a LangWatch process (apps/api, apps/worker, apps/tasks, apps/backend): main.ts and config.ts, the Server preamble (withEnvironment, withConfig, withSecrets, withTelemetry, withMetrics, start), server.container(role), exposeTransports, boot(), serve and run; what boot() does with stores, registries, peers, config slices and roles; config declared at its owner and parsed once (Config.define, processConfig, one env var one owner); secrets as handles resolved through into and sealed after boot; stores, the live and memory tiers, and migrations run by the worker's upgrade; installation tests that prove a composition. Use when someone says 'compose a process', 'edit main.ts', 'add to config.ts', 'boot refused', 'needs surface', 'config collision', 'ConfigClaimsSecretError', 'secret sealed', 'preflight failed', 'config parse refused', 'install a module in the api', 'generate:modules', 'run on memory stores', 'LANGWATCH_STORES', 'migration before serve', 'installation test', 'bootInstalledProcess', or opens apps/*/src/main.ts, apps/*/src/config.ts or an *-installation test."
user-invocable: true
---
# Process composition: main.ts, boot(), config, stores
Record: `dev/docs/ARCHITECTURE.md` §4 (a process, whole), §5 (what `boot()` does), §6 (config and
secrets), §7 (stores, the tier, migrations), §13 (the installation test). Deleted spellings are §15;
target names that have not landed are §16. Search the record by heading: numbers move. This skill
teaches the shape the tree has, names the check behind each rule, and says where no check exists.
Not here: a module's own class, services and registries (`process-module`); routes and procedures
(`api-transports`); pipelines, subscribers and process managers on the worker
(`eventing-and-worker`); what a module may demand and how it declares config, secrets and peers,
and cutting a peer cycle (§3.3, §6; `module-dependencies`). This skill takes over where the
declaration ends: how the process parses, resolves, seals and boots it.
The `backend` skill is the map; this skill is the depth for §4-§7.
## The shape in the tree
An app is `src/main.ts` plus `src/config.ts`, and holds no product code (§1, §4).
- `apps/api/src/config.ts` and `apps/worker/src/config.ts` hold one export, `processEnvironment`:
the one place `process.env` reaches the preamble (§4, §6).
- `apps/api/src/main.ts` (`startApi`): `Server.create("langwatch-api")`, then `.withEnvironment`,
`.withConfig(processConfig(processModules))`, `.withSecrets(...)` (env, file, 1Password),
`.withProcessOwnership`, `.withUpgradeGate`, `.withTelemetry`, `.withMetrics` and `.start()`; then
`server.container("api")`, `.exposeTransports(...)` selecting tRPC, REST and the bundle, `.boot()`
and `server.serve(app)`.
- `apps/worker/src/main.ts` (`startWorker`): the same preamble with
`processConfig(processModules, "worker")`, then
`server.container("worker").boot({ classifyEventLogRetention })` (the classifier is required,
`packages/process/src/process-container.ts`) and `server.run(app)`. No `exposeTransports`: it
exists only on the api container. `upgradeOnce` is the run-once entry behind `pnpm task upgrade`.
- `apps/backend/src/main.ts`: `runBackend({ startApi, startWorker })` from
`@langwatch/process/backend-host`, the api and worker in one Node process (the shipped backend,
ADR-168); `tools/dev-runtime` reuses the same host.
- Metrics (ADR-175, `packages/observability/src/node/process-metrics.ts`): `OTEL_METRICS_EXPORTER`
lists `otlp` and/or `prometheus`; `prometheus` serves on its own port, 9464 by default
(`OTEL_EXPORTER_PROMETHEUS_PORT`; the chart's worker sidecar uses 9465). The door is mounted only
when `METRICS_API_KEY` is set, and compares the bearer in constant time. `LANGWATCH_METRICS_*`
names are deleted spellings.
- `apps/tasks/src/main.ts`: migrations by hand; `apps/tasks/src/module-task.ts:29` boots
`server.container("tasks")` to run a module's task (§4 "Tasks").
- `processModules` is generated from `modules/catalogue.json` into each app's
`process-modules.generated.ts` by `pnpm generate:modules` (§5).
`withProcessOwnership` and the `ownsTelemetry` switch let a half run inside the one-process backend
host (ADR-168, Accepted) without owning signals or the telemetry SDK; they are not part of the
record's sample chain.
## The rules
1. **The chain names no module.** There is no `withModules` and no `withPipelines`; the container
takes the owners handed to `withConfig`, and the role decides pipeline participation (api and
tasks produce, worker consumes) (§4, Alex 2026-09-29).
2. **Installing a module edits the catalogue, never a root.** Then `pnpm generate:modules`. The
root never grows: a change that needs it to grow has found a gap in the primitives; report it
(§5).
3. **No deployment-choice lines.** The chain wires nothing conditionally; a module decides its own
availability from its config and secrets (§4, §6, §3.3 rule 4).
4. **The container answers stores and peers, nothing else.** No members, no `withMember`, no supply
tokens (§4, §5, Alex 2026-10-01); `.provide` survives only as a test stand-in for a channel-bound
`*Api` (§5; a missing ordinary peer is `testPeer`, not a supply bag). Stores go only to a module's
repository and channel registries; peers (`*Api` tokens) only to the module class.
5. **`boot()` refuses by name** (§5): a store a registry requires and the process did not open, a
missing required config value (`github.appId ← GITHUB_APP_ID`), a missing required secret, a module
with repositories whose store tier nobody stated (`StoreTierUnstatedError`). Never a runtime
fallback, a logged absence or an absence class.
**Store tiers fail closed** (§7, Alex 2026-10-05): opened stores state `live`; memory runs only when
a test or dev harness hands `memoryStores()`; there is no `LANGWATCH_STORES` knob. **An unselected
surface is skipped** (§4 D3, Alex 2026-10-05): the module still installs, without that transport.
6. **No lifecycle in main.** Transport hosts, eventing consumers and module services register their
own drain phases on the server; no app writes a shutdown phase or a signal handler (§4).
7. **Config is declared at its owner, in the contract** (`<name>.config.ts`, one `Config.define`),
attached on the module class as `static readonly config`, parsed once by the generated
`processConfig`, and drilled as an argument; nothing reads it ambiently (§6).
8. **One environment variable, one owner.** A second claim refuses the parse by name. A fact several
modules read is one picked leaf, never a re-declaration (§6).
9. **A secret is a handle you may only pass through.** `Secret.load(id)`; resolve with `secrets.into`
at the construction site, so only the built collaborator travels. No `get()`, no
`Secret.define`. Today `into` takes one handle, so several secrets nest
(`packages/process-stores/src/open-stores.ts`); the record's `secrets.into({ a, b }, build)` is
the target (§16 maps it) and has not landed. The resolver seals after boot (§6).
10. **Connection strings are the stores' secrets**, and store clients appear in exactly one place:
the chain. A module never names a URL or opens a client (§6, §7).
11. **Migrations run through the upgrade**, never composed by the api (§7, ADR-173,
UPGRADE-IN-WORKER). The worker's gate runs it in-process at boot (`runImageUpgrade`) under the
runner's lease and takes no job until the ledger is current; `pnpm task upgrade` is the run-once
worker that runs the same code. The api serves every route while the ledger catches up
(NO-HOLDS) and reports not ready until it is. Both compose `withUpgradeGate`, which refuses by
name while a blocking step of the image is outstanding. A module declares its steps with
`.withMigrations` (`migration` skill).
12. **Composition is proven by booting it.** The installation test boots the installed list in a
role over memory stores with no server (§4 last paragraph, §13). A unit test with fakes proves
a module's behaviour, never that the process composes.
## Backed by
"Boot refusal" is a check too: the installation tests run the same parse, preflight and boot, so a
refusal there fails CI. Rows marked unbacked feed the lint-rule backlog below.
| Rule (section) | Lint rule / enforcer policy or test | Notes |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| An app holds no product code (§1, §4) | policy `application-boundaries` (`composition-source`) | |
| Only `config.ts` reads `process.env`, apps' `main.ts` included (§4, §6; Alex 2026-10-05) | `langwatch/environment-boundaries` | |
| An app names no module's process package (§4, §5) | `langwatch/package-boundaries` (`compositionRoot`) | |
| `processModules` is the catalogue, the same in api/worker/tasks | enforcer test `packages/architecture-enforcer/tests/generated-module-lists.unit.test.ts` | |
| `main.ts` within 50 lines (§4) | unbacked | `apps/api/src/main.ts` is 70 lines and the worker's 66 today |
| No signal or fatal handler outside the Server (§4) | `langwatch/no-boot-hook-outside-guard` | |
| No raw `{ name, start, stop }` component literal (§4) | unbacked | |
| `exposeTransports` only on the api (§4) | typecheck (`ApiProcessContainer` alone has it) | |
| No `withMember`, supply tokens, ordinary `.provide` (§4, §15) | deleted-spellings policies (`packages/architecture-enforcer/src/policies/index.ts`) | `withMember` is gone from the container; the test fixtures still build with `withMembers` (conversion debt) |
| No store client in an app; clients only in registries (§7) | `langwatch/store-containment` (`storeInApplication`, `storeNamed`, `storeClientValue`); test `packages/architecture-enforcer/tests/redis-ownership.unit.test.ts` | |
| Peer cycles refuse (§5) | policy `peer-cycles`; `packages/architecture-enforcer/tests/boundary-ratchets.unit.test.ts` expects no edge | One named exception: organization and identity (`PEER_CYCLE_EXCEPTIONS`); the boot refusal is not built; cutting one: `module-dependencies` |
| A required store, config value or secret missing refuses by name | boot refusal: `ConfigParseError`, `SecretsPreflightError`; `apps/api/src/__tests__/api-config-refusal.unit.test.ts` | |
| Config drilled; a callee never resolves its own (§6) | `langwatch/service-loads-its-own-config` | |
| One env var, one owner (§6) | policy `feature-configuration`; boot refusal `ConfigCollisionError` (`packages/config/src/config.errors.ts:13`) | |
| A config leaf and a secret never share a name (§6) | boot refusal `ConfigClaimsSecretError`, `SecretClaimedTwiceError` | |
| Feature secret handles live in the owner's contract (§6) | unbacked | github's are in `modules/github/contract/src/github.config.ts` (`githubSecrets`), attached on the class |
| Resolve after boot refuses (§6) | runtime `SealedSecretsError` (`packages/secrets/src/secrets.errors.ts:4`) | |
| No `Secret.define`; nested `into` is today's form until the record form lands (§6, §15) | unbacked | `packages/process-stores/src/open-stores.ts` nests (§16 row) |
| Migrations run before serve, never in the api (§7) | tests `packages/architecture-enforcer/tests/system-migrations-start-order.unit.test.ts`, `apps/api/src/__tests__/start-path.unit.test.ts` | |
| A module's in-place migration reads Prisma only through its own private migration repository (§7) | policy `prisma-migration-access` | |
| Only `packages/eventing` touches the event tables (§7) | policy `eventing-table-access` (shrink-only baseline `packages/architecture-enforcer/tests/baselines/eventing-table-access.json`) | |
| Every Redis cache key expires in the writing command (§7) | enforcer test `packages/architecture-enforcer/tests/redis-cache-ttl.unit.test.ts` | |
| Composition proven by an installation test (§13) | `pnpm --filter @langwatch/architecture-enforcer check:feature-parity` binds `specs/platform/process-installation.feature` | Partial: nothing refuses a composition scenario bound to a unit test with fakes |
| `*.members.ts`, `*-composition.build.ts` deleted (§5, §15) | deleted-spellings policies | no module file of either shape remains; the grammar still accepts both names (`feature-layout-policy.mjs`), a follow-up to remove |
### Unbacked: the lint-rule backlog
Each is a proposal for the `lint-rule` skill, not a ruling; the deleted-spellings guard
(`dev/docs/plans/architecture-teaching-2026-10-05.md` step 2) may cover the §15 rows.
1. **50-line entry point**: oxlint `max-lines` override at 50 on `apps/*/src/main.ts`, after api's
and worker's `main.ts` are cut back (70 and 66 today).
2. **Raw lifecycle literal**: a `langwatch/*` rule refusing an object literal with `name`, `start`
and `stop` passed to the server; the message names the spoken factories.
3. **Fixture members**: the installation fixtures still call `createApp(...).withMembers(...)`;
convert them to `bootInstalledProcess({ peers })`.
4. **Secret handles in the contract**: extend policy `feature-configuration` to `Secret.load` and
`Secret.family` outside `modules/*/contract/src/*.config.ts` and framework owners.
5. **Nested `into`, `Secret.define`**: a ratchet with a count per file, shrink-only.
6. **Members and composition filenames**: remove the two patterns from `PROCESS_PATTERNS`; no
module file uses them any more.
7. **`config.ts` is the seam only**: narrow `environment-boundaries` to `src/config.ts`, and refuse
any export but `processEnvironment` in api's and worker's `config.ts`.
8. **Composition bound by booting**: `check:feature-parity` refuses a scenario in
`specs/platform/process-installation.feature` bound to a test that never calls
`bootInstalledProcess`.
## Worked example: a module gains a deployment value
The question: "github needs the host of a GitHub Enterprise Server. Where does it go, and does any app
change?"
1. **Declare it at the owner, in the contract.** `modules/github/contract/src/github.config.ts:9-13`
is the shape: one `Config.define`, one `c.env("GITHUB_LANGY_HOST", z.string().optional())` leaf.
This file is the only one that names the variable (§6).
2. **Attach it on the module class.** `static readonly config = githubConfig`
(`modules/github/process/src/app/github.app.ts`). `create()` receives the parsed slice and
passes the narrowest piece to the service that needs it (§5 "Registry resolution ends at create").
3. **No app changes.** `processConfig(processModules)` already reads every installed owner's schema:
`main.ts` and `config.ts` stay as they are. If the edit seems to need one, the root is growing:
stop and report the gap (§5).
4. **A credential is a handle, not a leaf.** A private key is `Secret.load(...)` beside the config
(`githubSecrets` in `github.config.ts`, attached as `static readonly secrets`), resolved inside
`create()` or a registry through `secrets.into`, so only the built client escapes (§6).
5. **Prove it composes.** Run the installation tests for each role the module boots in:
`VITEST_MAX_WORKERS=2 pnpm --filter @langwatch/platform-api test src/__tests__/api-installation.integration.test.ts`,
then `@langwatch/worker` and `@langwatch/tasks` likewise. A required leaf with no value refuses
there by name; give the fixture's synthetic environment a harmless invented value
(`apps/api/src/__tests__/api-installation.fixture.ts`), never one read from `.env`.
A brand-new module adds its catalogue entry first, then `pnpm generate:modules`; the
`generated-module-lists` test proves the three lists agree.
## Traps
- **A composition scenario proven by a unit test with fakes.** Hand-built peers and a stub container
prove a module's logic, not that the process boots. Bind composition scenarios to an
`*-installation.integration.test.ts` that boots the installed list (`api-installation.fixture.ts`,
`apps/worker/src/__tests__/worker-installation.integration.test.ts`,
`apps/tasks/src/__tests__/tasks-installation.integration.test.ts`). The `spec-binding-review` skill judges
such a bind.
- **Extending the fixture's `withMembers` bag.** The api, worker and tasks fixtures still build with
`createApp(...).withMembers(...)`: §15 deletes that spelling, and it is conversion debt, not the
shape to copy. New whole-list tests call
`bootInstalledProcess({ role, modules, config, stores: memoryStores(), peers: [testPeer(...)] })`
(`apps/api/src/__tests__/share-link-engine.integration.test.ts`). Add no new member; a missing
one is a module needing a registry.
- **Copying the record's sample chain verbatim.** The tree adds `withEnvironment` and
`withMetrics`; the record names `processFacts` and record `into`, which have not landed (§16).
Write what compiles today and link §16.
- **Splitting `processModules` to appease TS2589.** Cost grows with chain length, not list size;
do not split the list (§5).
- **A fallback for an absent store or credential.** Absence refuses by name; the module answers its
own availability (§5, §6).
- **Running migrations from the api, or DDL from a module.** The worker's upgrade owns migrations (§7).
## Known disagreements between the record and the tree
Prefer the tree for names, the linter for rules; report, do not fix a record you do not own.
- §4 says `main.ts` stays within 50 lines; `apps/api/src/main.ts` is 70 and the worker's 66.
- §16 rows still open: `processFacts` (today single leaves in `deployment-facts.ts`, and `owner.ts`), record `into`
(today nested), "store client" (today "member" in the fixtures' `withMembers`). `hostedStores`
has landed (`packages/process-stores/src/create-members.ts`); the §16 row naming `hostedMembers` is stale.
## Checks
While working: `tsc --noEmit --ignoreConfig <file>`, scoped `oxlint` on the paths you touched, and
the installation test of each role touched. At the end, once:
`pnpm --filter <package> typecheck`;
`pnpm lint:architecture --policies application-boundaries,feature-configuration,peer-cycles,prisma-migration-access,eventing-table-access`;
`pnpm --filter @langwatch/architecture-enforcer check:feature-parity`.
## Links
`dev/docs/ARCHITECTURE.md` §4-§7, §13, §15, §16 · `specs/platform/process-installation.feature` ·
`dev/docs/adr/147-compiler-checked-process-supply.md` · ADR-132 (secrets) · `dev/docs/lint-rules.md` ·
skills `architecture-guide`, `module-dependencies`, `process-module`, `testing`,
`spec-binding-review`, `architecture-review`, `lint-rule`, `linting`.
Files in this package (2)
- SKILL.md 25 KB
- evals/evals.json 5 KB
Versions
The database has no other skills named process-composition.
Database snapshot: 13.11.2026 · package version ffb84551e736 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100backend
Everything on the Node side of a LangWatch module: composing a process (apps/api, apps/worker, apps/tasks), Server/container/boot, a module's process-half shape, the four-way rule for what a module may demand, declaring REST endpoints and tRPC procedures, the worker role (drain… - 90spring-boot-discipline
Keep Spring Boot apps explicit with constructor injection, typed configuration, test slices, and restrained magic. Use when building or reviewing Spring Boot services that must stay debuggable. - 87platform-primitives
The shared building blocks module code uses instead of rolling its own: ids (@langwatch/ksuid generate, strict KSUIDs, never derived from another id), time (@langwatch/time nowInstant and Temporal, no new Date or Date.now), logging (createLogger, no console), errors (contract… - 95backend-spring-config
Use when reviewing Spring Boot configuration code — `@ConfigurationProperties`, `application.yml`/profiles, `@Bean` lifecycle, `@ConditionalOn*`, externalized config, secrets management. Triggers when `application*.yml`/`.properties` files or Spring `@Configuration` beans are in… - 100spring-cloud-config
Spring Cloud Config for centralized configuration management in microservices. Covers Config Server, Config Client, Git backend, and dynamic refresh. USE WHEN: user mentions "spring cloud config", "config server", "centralized configuration", "@RefreshScope", "externalized… - 100app-secrets
Guide for creating and using secrets in Fusebase Apps app backends. Use when: (1) An app backend needs API keys, passwords, or other sensitive config, (2) Creating secrets via the CLI, (3) Accessing secrets at runtime in backend code, (4) Deciding what should be a secret vs. a regular env var.