Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

process-composition

/process-composition

Składa procesy LangWatch, czyli apps/api, worker i tasks: plik main.ts, konfigurację, rozruch boot() i role, z sekretami i telemetrią.

Repozytorium
langwatch ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

87/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność17 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Składa procesy LangWatch, czyli apps/api, worker i tasks: plik main.ts, konfigurację, rozruch boot() i role, z sekretami i telemetrią.

Oryginalny opis (EN)

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

Jak działa

  1. The shape in the tree
  2. The rules
  3. Backed by
  4. Worked example: a module gains a deployment value
  5. Traps
  6. Known disagreements between the record and the tree
  7. Checks
  8. Links
Sekcje z nagłówków SKILL.md, w oryginale · 221 linii, 2 220 słów
Podgląd SKILL.md
---
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`.
Pliki w paczce (2)
  • SKILL.md 25 KB
  • evals/evals.json 5 KB

Wersje

W bazie nie ma innych skilli o nazwie process-composition.

Migawka bazy z 13.11.2026 · wersja paczki ffb84551e736 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100backend
    Opisuje stronę Node modułu LangWatch: składanie procesu (api, worker, tasks), deklarowanie endpointów REST i procedur tRPC, rolę workera, budowę nowego modułu procesowego i testy backendu.
  • 90spring-boot-discipline
    Utrzymuje aplikacje Spring Boot jawne dzięki wstrzykiwaniu przez konstruktor, typowanej konfiguracji, test slices i ograniczonej magii.
  • 87platform-primitives
    Pilnuje, by kod modułów korzystał ze wspólnych klocków platformy: identyfikatorów KSUID, czasu, logowania, błędów i konfiguracji.
  • 95backend-spring-config
    Przegląda konfigurację Spring Boot: ConfigurationProperties, profile w application.yml, cykl życia beanów, warunki i sekrety.
  • 100spring-cloud-config
    Wspiera Spring Cloud Config do centralnego zarządzania konfiguracją mikroserwisów: Config Server i Client, backend Git oraz dynamiczne odświeżanie.
  • 100app-secrets
    Opisuje tworzenie i używanie sekretów w backendach aplikacji Fusebase Apps przez CLI, dostęp do nich w kodzie w czasie działania oraz rozróżnianie sekretów od zwykłych zmiennych środowiskowych.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.