Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

module-dependencies

/module-dependencies

Opisuje, czego moduł LangWatch może wymagać i w jaki sposób: reguły zależności, konfigurację i sekrety, warstwy możliwości oraz usuwanie cykli między modułami.

Repozytorium
langwatch ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 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

Opisuje, czego moduł LangWatch może wymagać i w jaki sposób: reguły zależności, konfigurację i sekrety, warstwy możliwości oraz usuwanie cykli między modułami.

Wyzwalacze z opisu

s side with a peer subscriber. Use when someone saysdepend on another modulestatic dependencieswhich Api do I call
Oryginalny opis (EN)

What a LangWatch module may demand and how: the four-way rule (store-derived, peer *Api, config or secret, availability decided inside the module), static dependencies, Config.define and Secret.load in the contract, process facts, the four capability layers (availability, entitlement, permission, release flag), enterprise modules and declared plan gates, and peer cycles: reading the peer-cycles policy and cutting a cycle from the reactor's side with a peer subscriber. Use when someone says 'add a peer', 'depend on another module', 'static dependencies', 'which Api do I call', 'where does this

Jak działa

  1. The four-way rule (§3.3)
  2. Backed by
  3. Capability layers (§3.5)
  4. Enterprise (§11)
  5. Peer cycles (§5)
  6. Traps
  7. Known disagreements (report, do not fix)
  8. Links
Sekcje z nagłówków SKILL.md, w oryginale · 166 linii, 1 698 słów
Podgląd SKILL.md
---
name: module-dependencies
description: "What a LangWatch module may demand and how: the four-way rule (store-derived, peer *Api, config or secret, availability decided inside the module), static dependencies, Config.define and Secret.load in the contract, process facts, the four capability layers (availability, entitlement, permission, release flag), enterprise modules and declared plan gates, and peer cycles: reading the peer-cycles policy and cutting a cycle from the reactor's side with a peer subscriber. Use when someone says 'add a peer', 'depend on another module', 'static dependencies', 'which Api do I call', 'where does this env var go', 'Secret.load', 'secrets.into', 'process fact', 'is this feature available', 'capability', 'entitlement', 'enterprise module', 'withEntitlement', 'peer cycle', 'peer-cycles', 'cut the cycle', 'reverse the dependency', 'withPeerSubscriber', or 'config_collision'."
user-invocable: true
---

# Module dependencies: what a module may demand

The record is `dev/docs/ARCHITECTURE.md` §3.3 (the four-way rule), §3.5 (capability layers),
§5 (peers and peer cycles), §6 (config and secrets) and §11 (enterprise). Search by heading;
section numbers move. This skill restates nothing the record does not say, and names the check
behind each rule. Where none exists it says `unbacked`.

## The four-way rule (§3.3)

Every dependency a module has is exactly one of these. Sort it before you write anything.

| The thing you need                                          | It is                                     | Where it goes                                                                                                                      |
| ----------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Derivable from an opened store (tenant resolver, actor row) | a repository or channel inside the module | the module's `{ live, memory }` registry, which `requires` the store client (§5)                                                   |
| Another module's capability                                 | a peer                                    | the `*Api` token in `static dependencies`; `create()` receives the typed implementation                                            |
| A deployment fact (signing key, base URL)                   | config or a secret                        | the contract's `<name>.config.ts`: `Config.define` leaves and `Secret.load` handles; a shared fact is the shared leaf by name (§6) |
| Whether this deployment has it at all                       | an availability decision                  | decided inside the module from its own config and secrets; off refuses by name with a stable code (§6)                             |

A module class receives `repositories`, `channels`, `dependencies`, `config`, `secrets`, `role`
and `resources`, never a bag of clients or facts. Members and supply tokens are deleted (§3.3,
§15); a test stands in for an uninstalled peer with `testPeer` over a `createApiFixture` double (§13).

A fifth case is sanctioned for one shape. A channel tier may be **bound to another module's `*Api`**:
it declares `static readonly binds = { judge: InstantEvalApi }` and its `create({ bound })` receives
`bound.judge` (`modules/analytics/process/src/channels/analytics.channels.ts`; billing binds its
notifications the same way). A binding is not a peer: it is not in `static dependencies`, orders
nothing and adds no peer-cycles edge, so the bound API's owner may depend back (§5). A tier binding a
token no installed module provides refuses boot by name. A test supplies the bound API with
`.provide`, the one place it survives.

Members are gone (Alex, 2026-10-05). Where each kind went (record §3.3):

| A member that was                                  | Becomes                                                                                                             |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `encryption`                                       | a registry input: the live registry `requires` it and the live Prisma repository seals; memory twins hold plaintext |
| `rateLimiter`                                      | `<module>-rate-limit.repository.ts` with a memory fixed-window twin, wrapping the store's limiter (keys unchanged)  |
| `publicBaseUrl`, `nlpServiceUrl`, `serviceVersion` | the shared leaf from `@langwatch/config`, added to the contract's config (§6)                                       |
| `nlpInternalSecret`                                | the shared handle from `@langwatch/secrets`                                                                         |
| `logger`                                           | `createLogger("langwatch:<module>[:<part>]")` inside the module                                                     |
| `processName`                                      | the role (deleted, §15)                                                                                             |
| `clock`                                            | `@langwatch/time`; memory twins take it in their registry                                                           |
| anything another module answers                    | a peer `*Api` in `static dependencies`                                                                              |

When a module owns a config fact, others read the owner contract's exported leaf; they do not ask
its `*Api` (§6, §16 "Homes for the no-members migration", which replaced the 2026-09-18
ask-the-owner rule).

## Backed by

Each rule this skill teaches, and what refuses its violation. `unbacked` rows are the lint-rule
backlog; the proposal is a proposal, not a ruling.

| Rule (record)                                                                                      | Backed by                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Another module is reached only through its contract and `*Api` (§3, CLAUDE.md rule 1)              | `langwatch/package-boundaries` (`crossModuleProcess`, `processOutsideModule`, `crossModuleBrowser`)                                                                                                                     |
| Store clients reach repositories and channels only (§3.3 way 1, §5)                                | `langwatch/store-containment` (`storeClientValue`, `storeNamed`, `storeInApplication`)                                                                                                                                  |
| Peers are tokens; `create` is the only builder (§5)                                                | the compiler (a typo in `static dependencies` fails); `langwatch/module-classes` (`create`, `publicConstructor`)                                                                                                        |
| Uninstalling a module a peer depends on fails (§5)                                                 | the compiler, naming the dependent                                                                                                                                                                                      |
| Module code never reads `process.env` (§3.3 way 3, §6)                                             | `langwatch/environment-boundaries`                                                                                                                                                                                      |
| Config is drilled; nothing resolves its own (§6)                                                   | `langwatch/service-loads-its-own-config`                                                                                                                                                                                |
| One env var has one owner (§6)                                                                     | boot: `ConfigCollisionError`, code `config_collision` (`packages/config/src/config.errors.ts`) is the runtime check; policy `feature-configuration` checks config placement and the legacy schema forms, not collisions |
| A secret resolves only inside `secrets.into`, and only during boot (§6)                            | runtime: `SealedSecretsError` (`secret_sealed`), `SecretClaimedTwiceError` (`packages/secrets/src/secrets.errors.ts`); nested `into` is `unbacked`                                                                      |
| No members, supply tokens or bags; no feature leaf in `packages/config` (§3.3, §6, §15)            | policies `deleted-spellings-in-code` and `deleted-spellings-in-teaching` read `dev/docs/deleted-spellings.json` (per-spelling counts only fall); the feature-leaf rule is `feature-configuration`                       |
| A module decides its own availability; public config projects that answer (§3.3 way 4, §3.5)       | `unbacked`; the record names the rule to come: no availability logic in `*.config.ts` projections, off states use the shared notice                                                                                     |
| Plan gates are declared with `withEntitlement`, never hand-rolled (§7 "The plan gate is declared") | `langwatch/no-hand-rolled-plan-gate`                                                                                                                                                                                    |
| Plan limits come from the `@langwatch/plans` catalogue (§3.5 bounds)                               | `langwatch/plan-literals`                                                                                                                                                                                               |
| Enterprise-licensed code lives in an enterprise module (§11)                                       | `langwatch/enterprise-license-header`; `langwatch/package-boundaries` (`coreImportsEnterprise`)                                                                                                                         |
| Enterprise routes are always mounted and refuse per organization (§11)                             | `unbacked`                                                                                                                                                                                                              |
| No package-import cycle (§3)                                                                       | policy `cycles`                                                                                                                                                                                                         |
| No peer cycle (§5)                                                                                 | policy `peer-cycles`; `packages/architecture-enforcer/tests/boundary-ratchets.unit.test.ts` ("No peer cycle edge exists"), red until the last cut, bar the one ruled exception (below)                                  |
| No peer-cycle edge is cut or listed without asking Alex (§5, 2026-10-05)                           | a human gate; not a lint candidate                                                                                                                                                                                      |
| A new `*Api` operation is a design choice (architecture guide rule 5)                              | `unbacked`; a review item in the `architecture-review` skill, not a lint rule                                                                                                                                           |
| Removing a cycle may not make a synchronous precondition eventual (§5)                             | `unbacked`; `architecture-review`                                                                                                                                                                                       |

## Capability layers (§3.5)

"Capability" means four layers, each with one owner. No layer re-derives another's answer.

1. **Deployment availability**: the owning module, from its own config and secrets; the browser
   reads a public-config boolean projected from that same answer.
2. **Entitlement**: `EntitlementApi`; the route stays mounted and refuses per organization.
   Declare `withEntitlement(entitlement, { feature, when })` on the route or procedure.
3. **Permission**: authz; `.withPermission(...)` on the route, the service for row-dependent checks.
4. **Release flag**: feature flags.

Off is opaque: the screen says only "contact LangWatch support" or "contact your administrator".
Fixed bounds read `@langwatch/plans`; per-organization bounds ask `EntitlementApi`. Host services
(session, navigation, storage, toasts, drawers) are not capabilities.

## Enterprise (§11)

An enterprise module has the module shape and installs from the same catalogue. Core imports an
enterprise contract or client like any peer's; the enterprise owner refuses per organization, and
a core caller never re-checks entitlement first. A licence, signature or flag adapter lives in the
enterprise module that holds the gate. A peer may be enterprise: model provider asks `ManagedProviderApi`, naming the project's
organization itself, so managed-provider holds no project peer (§3.3).

## Peer cycles (§5)

Today the container hands every `*Api` a proxy before install, so two modules naming each other
boot. The rule is still refusal. `pnpm lint:architecture --policies peer-cycles` lists every
declared edge whose peer reaches back; the list that held them is deleted, so the ratchet test
stays red until none remain. **One cycle is ruled and named: organization and identity** (Alex,
2026-10-08, PC-1): `PEER_CYCLE_EXCEPTIONS` in the policy
(`packages/architecture-enforcer/src/policies/boundaries/peer-cycles.ts`) holds it with owner,
reason and ruling; it excuses only that pair and only shrinks. It is no licence for any other cycle. `dev/docs/plans/peer-cycles-2026-10-05.md`
maps the back edges.

Before adding a peer, read your module page's "Peers" table and the target's "Who depends on"
line (`modules/<id>/README.md`): if the target already depends on you, the edge closes a cycle.

Before touching an edge: **ask Alex.** Ruled cuts so far: `secret -> project`, `gateway -> webhook`,
and workflow dropping `ProjectApi` and `OrganizationApi`. Everything else waits.

A cut is made from the reactor's side (§5, §9): the module being told reacts to the other's event
and the teller drops its peer. The reactor declares `.withPeerSubscriber(name, { eventType, data,
handle })` on its own pipeline, naming the event by the owner contract's type and schema, so its
one edge is that contract. The handler is idempotent and throws to be retried. Where reacting would
itself close a cycle, a scheduled process manager pulls instead.

### Worked example: `secret -> project` (cut 2026-10-05)

1. The policy reported `secret depends on project's Api, and project reaches back`.
2. Alex ruled the cut (§5). The plan named the only use: `getWithTeam` in `getAttributedUserId`.
3. An existing operation answers it, so no new `*Api` operation: `AuthzApi.getScope({ projectId })`,
   as `modules/api-key/process/src/services/run-key-mint.service.ts:76` already did.
4. `modules/secret/process/src/app/secret.app.ts:42` became `{ permissions: AuthzApi }`; the
   service takes `Pick<AuthzApi, "getScope" | "listTeamMemberBindings">`
   (`modules/secret/process/src/services/secret.service.ts:35`).
5. Doubles and the installation test (`secret-installation.unit.test.ts`) dropped the project peer;
   the policy re-run showed the edges gone.

The reversed shape is `gateway -> webhook`: gateway's spend event types and schemas live in
`modules/gateway/contract/src/features/spend/gateway.spend-events.ts`, and webhook declares six peer subscribers
in `modules/webhook/process/src/eventing/webhook-delivery.pipeline.ts:68`. Gateway holds no
`WebhookApi`.

## Traps

- **A new `*Api` operation is a design choice.** Look for an existing one (secret used authz's
  `getScope`). If none answers, propose the operation with options; do not write it.
- **A cut leaves stale tests.** The worker installation test still asserted gateway's own webhook
  subscriber after the cut (`apps/worker/src/__tests__/worker-installation.integration.test.ts:292`
  now reads webhook's peer subscribers). After a cut, search every `*-installation.*.test.ts` and
  `apps/*/src/__tests__` for the old subscriber, peer key and fixture.
- **Generalising the gateway cut.** §9 says a delivery is not a reaction: a producer asks the
  destination kind's owner to send it (the intended `requestDelivery`, ADR-167, is not built
  yet). `gateway -> webhook` was ruled by name; another delivery edge is a question for Alex, not
  a precedent to copy.
- **Dropping the token but still reaching the module.** Importing its services, repositories or
  tables instead is a violation even when the import resolves (CLAUDE.md rule 1).
- **Copying a module class you find in the tree.** Some still carry deleted statics (§15);
  check §15 before copying a spelling.

## Known disagreements (report, do not fix)

- `dev/docs/plans/peer-cycles-2026-10-05.md` still names a shrink-only edge list; §5 deleted it.

## Links

`dev/docs/ARCHITECTURE.md` §3.3, §3.5, §5, §6, §9, §11, §15, §16 · `dev/docs/lint-rules.md` ·
`packages/architecture-enforcer/src/policies/index.ts` · skills `architecture-guide`, `linting`,
`process-composition` (boot, config parse, secrets), `eventing-and-worker`, `contract`,
`process-module`, `testing`.
Pliki w paczce (2)
  • SKILL.md 18 KB
  • evals/evals.json 5 KB

Wersje

W bazie nie ma innych skilli o nazwie module-dependencies.

Migawka bazy z 13.11.2026 · wersja paczki e149f0357252 (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

  • 100module
    Wyjaśnia, czym jest moduł LangWatch i jak go założyć: cztery pakiety, katalog modułów, foldery specs i adrs oraz kierunek zależności między połówkami.
  • 100linting
    Wyjaśnia, jak działają lintery LangWatch (wtyczka oxlint, egzekwowanie architektury całego drzewa, gramatyka nazw plików, baseline'y) i jak reagować na ich ustalenia.
  • 100architecture
    Mapuje architekturę projektu: zależności między modułami, sprzężenie, graf zależności i granice modułów.
  • 100name-module-cycle
    Proponuje kosmiczną nazwę dla cyklicznego klastra modułów backendowych, gdy test module-cycles-test w Metabase zgłasza klaster bez nazwy, i dopisuje linię do cycle-clusters.edn.
  • 90circular-dependencies
    Znajduje cykle zależności między modułami i rozrywa je przez warstwy, wydzielanie interfejsów lub odwrócenie zależności, gdy importy tworzą pętlę blokującą kompilację lub testy.
  • 90ue5-architecture
    Planuje architekturę UE5.6-UE5.8: układ modułów, zależności Build.cs, ekspozycję refleksji i granice API publicznego i prywatnego, by uniknąć cykli.

Uwagi i zgłoszenia

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