@doubleloop-io/oxlint-plugin-effect 0.1.0-rc.0 → 0.1.0-rc.2

package/RULES.md

@@ -1,241 +1,89 @@
 # `@doubleloop-io/oxlint-plugin-effect` rules
 
-The plugin's 30 rules. The `Pxx` identifiers come from the origin catalog; the patterns no rule checks are in [`skill/reference/effect-patterns.md`](skill/reference/effect-patterns.md).
+The plugin's 31 rules.
 
 ## Rules index
 
-| Rule                                                                                    | Pattern  | Severity |
-| --------------------------------------------------------------------------------------- | -------- | -------- |
-| [`service-port-shape-only`](#service-port-shape-only)                                   | P01      | `error`  |
-| [`adapter-import-boundary`](#adapter-import-boundary)                                   | P02      | `error`  |
-| [`run-only-at-entry`](#run-only-at-entry)                                               | P04, P22 | `error`  |
-| [`no-bare-error-in-effect`](#no-bare-error-in-effect)                                   | P05      | `error`  |
-| [`try-object-form`](#try-object-form)                                                   | P08      | `error`  |
-| [`no-effect-promise`](#no-effect-promise)                                               | P08      | `warn`   |
-| [`no-parameterless-catch-all`](#no-parameterless-catch-all)                             | P09      | `error`  |
-| [`redacted-secret-names`](#redacted-secret-names)                                       | P13      | `warn`   |
-| [`prefer-effect-fn`](#prefer-effect-fn)                                                 | P17      | `warn`   |
-| [`untraced-recursion`](#untraced-recursion)                                             | P17      | `warn`   |
-| [`single-style-per-function`](#single-style-per-function)                               | P24      | `error`  |
-| [`error-handling-in-effect-fn-handler`](#error-handling-in-effect-fn-handler)           | P25      | `warn`   |
-| [`no-transport-types-in-generator`](#no-transport-types-in-generator)                   | P26      | `error`  |
-| [`boundary-entrypoint-shape`](#boundary-entrypoint-shape)                               | P27      | `warn`   |
-| [`provide-named-layer`](#provide-named-layer)                                           | P28      | `error`  |
-| [`no-provide-on-definition`](#no-provide-on-definition)                                 | P28      | `error`  |
-| [`no-nested-match`](#no-nested-match)                                                   | P30      | `warn`   |
-| [`no-inline-yield-star`](#no-inline-yield-star)                                         | P32      | `warn`   |
-| [`no-effect-return-type`](#no-effect-return-type)                                       | P33      | `warn`   |
-| [`no-asymmetric-match-handlers`](#no-asymmetric-match-handlers)                         | P34      | `warn`   |
-| [`exported-schema-identifier`](#exported-schema-identifier)                             | P35      | —        |
-| [`no-manual-discriminant-comparison`](#no-manual-discriminant-comparison)               | P36      | —        |
-| [`no-manual-discriminant-construction`](#no-manual-discriminant-construction)           | P37      | —        |
-| [`service-key-matches-name`](#service-key-matches-name)                                 | P38      | —        |
-| [`no-inline-schema-codec`](#no-inline-schema-codec)                                     | P39      | —        |
-| [`no-yielded-match`](#no-yielded-match)                                                 | P40      | —        |
-| [`service-built-with-of`](#service-built-with-of)                                       | P41      | —        |
-| [`anti-slop-no-service-constructor-imports`](#anti-slop-no-service-constructor-imports) | —        | —        |
-| [`anti-slop-no-manual-effect-error-tag`](#anti-slop-no-manual-effect-error-tag)         | —        | —        |
-| [`anti-slop-prefer-effect-match`](#anti-slop-prefer-effect-match)                       | —        | —        |
-
-The `all` preset enables them all at `warn`. Severity is the one each rule was kept at zero noise with on an Effect 4 codebase: a data point about its stability, not a recommendation. `—` means not yet measured.
+| Group                                               | Rule                                                                                    |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [Error channel](#error-channel)                     | [`no-throw-or-primitive-failure`](#no-throw-or-primitive-failure)                       |
+|                                                     | [`try-object-form`](#try-object-form)                                                   |
+|                                                     | [`no-effect-promise`](#no-effect-promise)                                               |
+|                                                     | [`no-parameterless-catch-all`](#no-parameterless-catch-all)                             |
+|                                                     | [`split-success-path-from-error-handling`](#split-success-path-from-error-handling)     |
+|                                                     | [`anti-slop-no-manual-effect-error-tag`](#anti-slop-no-manual-effect-error-tag)         |
+| [Tagged values](#tagged-values)                     | [`no-manual-discriminant-comparison`](#no-manual-discriminant-comparison)               |
+|                                                     | [`no-manual-discriminant-construction`](#no-manual-discriminant-construction)           |
+| [Services and Layers](#services-and-layers)         | [`service-port-shape-only`](#service-port-shape-only)                                   |
+|                                                     | [`service-key-matches-name`](#service-key-matches-name)                                 |
+|                                                     | [`service-built-with-of`](#service-built-with-of)                                       |
+|                                                     | [`provide-named-layer`](#provide-named-layer)                                           |
+|                                                     | [`no-provide-on-definition`](#no-provide-on-definition)                                 |
+|                                                     | [`anti-slop-no-service-constructor-imports`](#anti-slop-no-service-constructor-imports) |
+| [Runtime and entry point](#runtime-and-entry-point) | [`run-only-in-runner`](#run-only-in-runner)                                             |
+|                                                     | [`prefer-effect-vitest`](#prefer-effect-vitest)                                         |
+|                                                     | [`all-errors-handled-at-boundary`](#all-errors-handled-at-boundary)                     |
+| [Design and boundaries](#design-and-boundaries)     | [`adapter-import-boundary`](#adapter-import-boundary)                                   |
+|                                                     | [`no-transport-types-in-generator`](#no-transport-types-in-generator)                   |
+| [Effectful functions](#effectful-functions)         | [`prefer-effect-fn`](#prefer-effect-fn)                                                 |
+|                                                     | [`untraced-recursion`](#untraced-recursion)                                             |
+|                                                     | [`single-style-per-function`](#single-style-per-function)                               |
+| [Code shape](#code-shape)                           | [`no-nested-match`](#no-nested-match)                                                   |
+|                                                     | [`no-yielded-match`](#no-yielded-match)                                                 |
+|                                                     | [`no-inline-yield-star`](#no-inline-yield-star)                                         |
+|                                                     | [`no-effect-return-type`](#no-effect-return-type)                                       |
+|                                                     | [`no-asymmetric-match-handlers`](#no-asymmetric-match-handlers)                         |
+|                                                     | [`anti-slop-prefer-effect-match`](#anti-slop-prefer-effect-match)                       |
+| [Schema](#schema)                                   | [`exported-schema-identifier`](#exported-schema-identifier)                             |
+|                                                     | [`no-inline-schema-codec`](#no-inline-schema-codec)                                     |
+| [Config and secrets](#config-and-secrets)           | [`redacted-secret-names`](#redacted-secret-names)                                       |
+
+The `all` preset enables them all at `warn`.
 
 ## Common limits
 
-- **Syntax only**: no rule uses type information.
+- **Syntax only**: no rule uses type information. Only two rules look past the file: [`adapter-import-boundary`](#adapter-import-boundary), to find which directories are adapters, and [`prefer-effect-vitest`](#prefer-effect-vitest), to find whether `@effect/vitest` is installed.
 - **Literal names**: `Effect.gen` is recognized, `import { Effect as E }` or `import * as L from "effect/Layer"` slip through. On code that uses aliases, silence is not compliance.
-- **Effect 4**: the rules also recognize some v3 APIs (`catchAll`, `Effect.Service`, `Context.Tag`), but they are written and tested against v4.
-
-## File options
-
-When the reason for an exclusion is part of the rule, the rule itself recognizes the files, through an option that **replaces** the defaults (it does not extend them). Globs are matched against the path relative to oxlint's working directory, with `/` on every platform.
-
-- **`entryFiles`**, used by [`run-only-at-entry`](#run-only-at-entry) and [`adapter-import-boundary`](#adapter-import-boundary). Default `**/main.ts`, `**/cli.ts`, `**/bin/**`. `index.ts` is excluded on purpose: it is usually a barrel, and exempting it would let adapters reach the rest of the application through re-exports.
-- **`testFiles`**, used by [`adapter-import-boundary`](#adapter-import-boundary), [`no-effect-promise`](#no-effect-promise), [`provide-named-layer`](#provide-named-layer), [`no-provide-on-definition`](#no-provide-on-definition), [`error-handling-in-effect-fn-handler`](#error-handling-in-effect-fn-handler) and [`anti-slop-no-service-constructor-imports`](#anti-slop-no-service-constructor-imports). Default `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`. A helper directory such as `src/testing/` does not count as tests: it is support code.
-
-The defaults come from a Node CLI. On another layout (Next.js, a monorepo) they must be reconfigured before reading the numbers, and every rule sharing an option must be reconfigured:
+- **Effect 4**: the rules are written against v4. Where a v3 API has the same intent, they recognize its v3 name too (`catchAll`, `Either`, `Context.Tag`, `Config.redacted`, …), and the Trigger names it.
+
+## Shared settings
+
+What describes the project rather than a rule is declared once, under `settings["dl-effect"]` in the oxlint config, and read by every rule that needs it. A value **replaces** the default (it does not extend it). An unknown key or a value that is not an array of strings stops the lint with an error. File globs are matched against the path relative to oxlint's working directory, with `/` on every platform.
+
+- **`entryFiles`**
+    - used by:
+        - [`run-only-in-runner`](#run-only-in-runner)
+        - [`adapter-import-boundary`](#adapter-import-boundary)
+    - default: `**/main.ts`, `**/cli.ts`, `**/bin/**`. `index.ts` is excluded on purpose: it is usually a barrel, and exempting it would let adapters reach the rest of the application through re-exports.
+- **`testFiles`**
+    - used by:
+        - [`run-only-in-runner`](#run-only-in-runner), [`adapter-import-boundary`](#adapter-import-boundary), [`no-effect-promise`](#no-effect-promise), [`provide-named-layer`](#provide-named-layer), [`no-provide-on-definition`](#no-provide-on-definition), [`split-success-path-from-error-handling`](#split-success-path-from-error-handling), [`all-errors-handled-at-boundary`](#all-errors-handled-at-boundary), [`anti-slop-no-service-constructor-imports`](#anti-slop-no-service-constructor-imports): skip test files
+        - [`no-throw-or-primitive-failure`](#no-throw-or-primitive-failure): skips only primitive failures there
+        - [`single-style-per-function`](#single-style-per-function): treats their helpers like tests
+        - [`prefer-effect-vitest`](#prefer-effect-vitest): checks only them
+    - default: `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`. A helper directory such as `src/testing/` does not count as tests: it is support code.
+- **`discriminants`**
+    - used by:
+        - [`no-manual-discriminant-comparison`](#no-manual-discriminant-comparison)
+        - [`no-manual-discriminant-construction`](#no-manual-discriminant-construction)
+    - default: `_tag`. Add the fields your unions discriminate on (`type`, `kind`).
+
+The file defaults come from a Node CLI. On another layout (Next.js, a monorepo) they must be reconfigured before reading the warnings:
 
 ```ts
-const entryFiles = ["apps/web/src/app/**/route.ts", "apps/web/src/runtime.ts"]
-
 export default defineConfig({
     extends: [dlEffectAll],
-    rules: {
-        "dl-effect/run-only-at-entry": ["warn", { entryFiles }],
-        "dl-effect/adapter-import-boundary": ["warn", { entryFiles }],
+    settings: {
+        "dl-effect": { entryFiles: ["apps/web/src/app/**/route.ts", "apps/web/src/runtime.ts"] },
     },
 })
 ```
 
-## Services and Layers
-
-### `service-port-shape-only`
-
-<sup>[↑ rules index](#rules-index)</sup>
-
-**Intent**: a port is a shape-only `Context.Service`, with no implementation attached.
-
-```ts
-// no
-class Agent extends Context.Service<Agent, Shape>()("app/Agent", { make: makeAgent }) {}
-
-// yes
-export class Agent extends Context.Service<
-    Agent,
-    { readonly search: (name: string) => Effect.Effect<RaceCard, AgentError> }
->()("app/agent/Agent") {}
-```
-
-**Trigger**: the second argument of `Context.Service<…>()(id, opts)`; a `static layer` or `static Default` member on the class; the v3 forms `Effect.Service`, `Context.Tag`, `Context.GenericTag`.
-
-**Exemptions and blind spots**: a `Context.Service` assigned to a variable is not seen: see `service-not-as-class` (effecttsgo).
-
-**Why**: `make` and a static layer tie the port to a default implementation, while the port must stay a contract any adapter can satisfy. It is a convention, not Effect's idiom: Effect's own docs put `static readonly layer` on the service.
-
-- **Pattern**: P01 · **Options**: none · **Fix**: none · **Severity**: `error`
-
-### `service-key-matches-name`
-
-<sup>[↑ rules index](#rules-index)</sup>
-
-**Intent**: a service's key is its class name, alone or after a path prefix.
-
-```ts
-// no
-export class ForgerockApis extends Context.Service<ForgerockApis, Shape>()("ForgerockAPIs") {}
-
-// yes
-export class ForgerockApis extends Context.Service<ForgerockApis, Shape>()("ForgerockApis") {}
-
-// yes
-export class ForgerockApis extends Context.Service<ForgerockApis, Shape>()(
-    "app/auth/ForgerockApis",
-) {}
-```
-
-**Trigger**: `class X extends Context.Service<…>()("key")` with a literal key that is neither `"X"` nor ends with `"/X"`.
-
-**Exemptions and blind spots**: keys that are not literals (variables, templates with expressions). A `Context.Service` assigned to a variable is not seen: see `service-not-as-class` (effecttsgo). `deterministic-keys` (effecttsgo) with the `default` or `package-identifier` formula produces keys this rule accepts; with `default-hashed` the two contradict each other: enable only one.
-
-**Why**: the key is the service's identity in errors, traces and `Context` lookups; a key that drifts from the name, as after a rename, makes it hard to find the class behind a message.
-
-- **Pattern**: P38 · **Options**: none · **Fix**: suggestion that replaces the last segment of the key with the class name · **Severity**: —
-
-### `service-built-with-of`
-
-<sup>[↑ rules index](#rules-index)</sup>
-
-**Intent**: the service a Layer provides is built with `Tag.of({…})`, not a bare object literal.
-
-```ts
-// no
-export const RepoLive = Layer.effect(
-    Repo,
-    Effect.gen(function* () {
-        const db = yield* Database
-        return { find: (id: RepoId) => db.get(id) }
-    }),
-)
-
-// yes
-export const RepoLive = Layer.effect(
-    Repo,
-    Effect.gen(function* () {
-        const db = yield* Database
-        return Repo.of({ find: (id: RepoId) => db.get(id) })
-    }),
-)
-```
-
-**Trigger**: an object literal passed as the value of `Layer.succeed(T, {…})`, returned by the function of `Layer.sync(T, () => ({…}))`, or returned by a top-level `return {…}` of the generator of `Layer.effect(T, Effect.gen(…))` or `Layer.scoped`; the curried `Layer.succeed(T)(…)` forms too.
-
-**Exemptions and blind spots**: a named factory (`Layer.sync(Repo, makeRepo)`) and a variable (`Layer.succeed(Repo, repo)`) are not inspected; `return` inside an `if` or a nested block, `Effect.gen(…).pipe(Layer.effect(T))` and generators other than `Effect.gen` slip through.
-
-**Why**: `T.of` names the service the object implements and keeps it checked against the shape if the literal moves out of the Layer; one form for every Layer.
-
-- **Pattern**: P41 · **Options**: none · **Fix**: suggestion that wraps the literal in `T.of(…)` · **Severity**: —
-
-### `adapter-import-boundary`
-
-<sup>[↑ rules index](#rules-index)</sup>
-
-**Intent**: domain code and other adapters do not import an adapter; only entry files choose it.
-
-```ts
-// no: in src/orders/place-order.ts
-import { GoogleCalendar } from "../calendar/google/GoogleCalendar.ts"
-
-// yes: depend on the port, main.ts provides GoogleCalendar.layer
-import { Calendar } from "../calendar/Calendar.ts"
-```
-
-**Trigger**: a relative import of a file in another directory that is an adapter: one of its `.ts` files (tests excluded) builds a `Layer` with `Layer.effect`, `succeed`, `sync`, `scoped`, `effectContext`, `unwrap`, `mock` and similar. Composition alone (`mergeAll`, `provide`, `merge`) does not make an adapter. It is the only rule that reads the filesystem.
-
-**Exemptions and blind spots**: entry files, where adapters are chosen, and test files, which compose the Layers they exercise. Non-relative imports (path aliases such as `@/calendar/google`) and directory imports through an `index.ts` (`"../google"`) slip through. On a layout other than one directory per adapter, observe its behavior before trusting the numbers. Infrastructure requirements in the port's `R` channel need types: see `leaking-requirements` (effecttsgo).
-
-**Why**: the adapter can be replaced without touching its consumers.
-
-- **Pattern**: P02 · **Options**: `entryFiles`, `testFiles` ([File options](#file-options)) · **Fix**: none · **Severity**: `error`
-
-### `anti-slop-no-service-constructor-imports`
-
-<sup>[↑ rules index](#rules-index)</sup>
-
-**Intent**: runtime code obtains a service from its Layer, never by calling its `make…` constructor.
-
-```ts
-// no: in src/runtime.ts
-import { makeIssueService } from "./issue-service.ts"
-
-// yes
-import { IssueService } from "./issue-service.ts"
-const issues = yield * IssueService
-```
-
-**Trigger**: a named import of `make` followed by an uppercase letter (`makeIssueService`, also when renamed) from a relative module.
-
-**Exemptions and blind spots**: test files, which build services from their constructors to inject fakes. Non-relative imports (packages, path aliases), namespace and default imports, and constructors with another prefix slip through. The same import can also fire [`adapter-import-boundary`](#adapter-import-boundary).
-
-**Why**: calling the constructor wires its dependencies by hand, and its requirements stop propagating to the composition root.
-
-- **Pattern**: — · **Options**: `testFiles` ([File options](#file-options)) · **Fix**: none · **Severity**: —
-
-### `run-only-at-entry`
-
-<sup>[↑ rules index](#rules-index)</sup>
-
-**Intent**: Effects run only at the entry point, and tests run them through the test runtime.
-
-```ts
-// no
-export const check = () => Effect.runPromise(pingDb(url))
-
-test("…", async () => {
-    await Effect.runPromise(authorize({ role: "Manager" }))
-})
-
-// yes: in main.ts
-NodeRuntime.runMain(
-    run(process.argv.slice(2)).pipe(Effect.provide(NodeServices.layer)) satisfies Effect.Effect<
-        void,
-        never
-    >,
-)
-
-// yes: in a test, fakes as Layers
-it.effect("…", () => authorize({ role: "Manager" }).pipe(Effect.provide(sheetWith(row))))
-```
-
-**Trigger**: every reference, not just calls, to `Effect.run*`, `NodeRuntime.runMain`, `BunRuntime.runMain` and `ManagedRuntime.make` outside entry files.
-
-**Exemptions and blind spots**: test files are not exempt; a module-level `ManagedRuntime` in a test is the typical catch. Without `@effect/vitest`, a single test runner module that provides the test Layer goes in `entryFiles`, and each test returns one call to it; the test runtime, `TestClock` included, is lost.
-
-**Why**: logger, Layers and defect handling are configured in one place. In tests, the test runtime brings `TestClock` and fakes replace services where the code reads them.
+Settings are not inherited from a preset in `extends` and cannot go in `overrides`: for a value that differs by group of files, override the rules instead.
 
-- **Pattern**: P04, P22 · **Options**: `entryFiles` ([File options](#file-options)) · **Fix**: none · **Severity**: `error`
+## Error channel
 
-## Errors
-
-### `no-bare-error-in-effect`
+### `no-throw-or-primitive-failure`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
@@ -259,11 +107,15 @@ Effect.fail(new SheetTabNotFoundError({ spreadsheetId, message: "tab not found"
 
 **Trigger**: a `throw` directly inside a generator passed to `Effect.gen`/`Effect.fn`; `Effect.fail` with a literal or a template.
 
-**Exemptions and blind spots**: a `throw` inside a nested callback. `Effect.fail(new Error(…))` and `class X extends Error`: see `global-error-in-effect-failure` and `extends-native-error` (effecttsgo).
+**Exemptions and blind spots**: `Effect.fail` with a literal in test files, where a synthetic failure feeds code generic over the error; a `throw` in a test generator is still reported. A `throw` inside a nested callback. `Effect.fail(new Error(…))` and `class X extends Error`: see `global-error-in-effect-failure` and `extends-native-error` (effecttsgo).
 
 **Why**: the typed error channel discriminates only on tags. A `throw` in the generator becomes a defect, outside the error channel.
 
-- **Pattern**: P05 · **Options**: none · **Fix**: none · **Severity**: `error`
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
 
 ### `try-object-form`
 
@@ -288,7 +140,9 @@ Effect.tryPromise({
 
 **Why**: the thunk form types the error as `Cause.UnknownError` (`UnknownException` in v3), which no caller can handle by tag.
 
-- **Pattern**: P08 · **Options**: none · **Fix**: none · **Severity**: `error`
+**Options**: none
+
+**Fix**: none
 
 ### `no-effect-promise`
 
@@ -310,13 +164,17 @@ Effect.tryPromise({ try: () => client.connect(), catch: toConnectionError })
 
 **Why**: `Effect.promise` turns a rejection into a defect.
 
-- **Pattern**: P08 · **Options**: `testFiles` ([File options](#file-options)) · **Fix**: none · **Severity**: `warn`
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
 
 ### `no-parameterless-catch-all`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: errors are caught by tag; a catch-all never ignores what it catches.
+**Intent**: errors are caught by tag; a fallback that ignores the error is spelled `orElseSucceed`/`orElse`, never a catch-all with an ignored parameter.
 
 ```ts
 // no
@@ -325,6 +183,8 @@ Effect.catch(() => Effect.succeed(fallback))
 // yes
 Effect.catchTag("AgentTimeout", () => Effect.succeed(skip))
 Effect.catchTag(["ParseError", "ReservedPortError"], () => Effect.succeed(3000))
+
+// yes: every failure truly means the same fallback
 Effect.orElseSucceed(() => fallback)
 ```
 
@@ -334,7 +194,46 @@ Effect.orElseSucceed(() => fallback)
 
 **Why**: a catch-all that ignores its parameter also swallows the errors added later, which `catchTag` would leave visible in the type.
 
-- **Pattern**: P09 · **Options**: none · **Fix**: none · **Severity**: `error`
+**Options**: none
+
+**Fix**: none
+
+### `split-success-path-from-error-handling`
+
+<sup>[↑ rules index](#rules-index)</sup>
+
+**Intent**: the generator holds only the happy path; error handling lives in the second argument of `Effect.fn`.
+
+```ts
+// no
+function* () {
+    const x = yield* fetchThing.pipe(Effect.catchTag("NotFound", () => Effect.succeed(fallback)))
+}
+
+// yes: naming the error or giving an alternative is not handling
+function* () {
+    const x = yield* fetchThing.pipe(Effect.orElseSucceed(() => fallback))
+    const y = yield* decode(raw).pipe(Effect.mapError((error) => new BadRequest({ message: error.message })))
+}
+
+// yes: translation in the second argument, which also receives the original arguments
+const createEvent = Effect.fn("events.create")(
+    function* (request: Request) { /* success only */ },
+    (effect, request) => effect.pipe(Effect.catchTags({ BadRequest: (e) => refused(400, e.message) })),
+)
+```
+
+**Trigger**: inside a generator passed to `Effect.gen`/`Effect.fn`, callbacks passed to `Effect.*` combinators included, calls to `Effect.catch*` (`catch`, `catchAll`, `catchTag`, `catchTags`, `catchIf`, `catchCause`, `catchDefect`, `catchReason`, …), `either`, `result`, `exit`, `match*` and `sandbox`.
+
+**Exemptions and blind spots**: pipeables of a nested `Effect.fn`. Handlers inside the callback of an iteration (`forEach`, `filter`, `reduce`, `partition`, `validate`, `findFirst`, …): they handle each element on its own, and in the pipeables the first failure would stop the rest. Functions the generator only defines, such as an `HttpApiBuilder` handler or a service method: they are programs of their own. Test files, where the failure is the outcome under observation (`yield* Effect.result(op)` then `expect`). A `catch`, `catchTag`, `catchTags`, `catchIf` or `catchFilter` whose handlers only die (`Effect.die` passed directly or as the sole return): it is a selective `orDie`, declaring the case untracked rather than handling it; a die behind a wrapper or a condition is still reported. A `.pipe(Effect.catch…)` appended to an `Effect.gen` escapes; [`prefer-effect-fn`](#prefer-effect-fn) closes that gap.
+
+**Why**: translation becomes a single exhaustive point instead of catches scattered along the flow.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
 
 ### `anti-slop-no-manual-effect-error-tag`
 
@@ -356,7 +255,9 @@ program.pipe(Effect.catchTag("NotFound", () => recover))
 
 **Why**: a hand-written dispatch keeps the caught errors in the type even when handled, and silently misses tags added later.
 
-- **Pattern**: — · **Options**: none · **Fix**: none · **Severity**: —
+**Options**: none
+
+**Fix**: none
 
 ## Tagged values
 
@@ -380,17 +281,21 @@ Match.value(event).pipe(Match.tagsExhaustive({ Created: onCreated, Deleted: onDe
 
 // yes, with `discriminants: ["_tag", "type"]`
 Match.value(payment).pipe(
-    Match.discriminatorsExhaustive("type")({ demetra: fromDemetra, fexco: fromFexco }),
+    Match.discriminatorsExhaustive("type")({ card: fromCard, transfer: fromTransfer }),
 )
 ```
 
 **Trigger**: an equality comparison between a discriminant (also `["type"]`) and a string literal, or a `switch` on a discriminant. The discriminants are the names in `discriminants`.
 
-**Exemptions and blind spots**: comparisons against a variable rather than a literal. On `_tag`, the handlers covered by [`anti-slop-no-manual-effect-error-tag`](#anti-slop-no-manual-effect-error-tag): the two never fire on the same node. Guard clauses such as `if (x.type === "a") return …` fire too; on `_tag` use `Predicate.isTagged`. An exhaustive ts-pattern match is an equally valid remedy. A name added to `discriminants` also fires on objects outside closed unions (DOM events, external payloads): the list is a choice of the codebase.
+**Exemptions and blind spots**: comparisons against a variable rather than a literal. On `_tag`, the handlers covered by [`anti-slop-no-manual-effect-error-tag`](#anti-slop-no-manual-effect-error-tag): the two never fire on the same node. Guard clauses such as `if (x.type === "a") return …` fire too; on `_tag` use `Predicate.isTagged`. A `_tag` compared with a variant of Effect's own types (`Success`/`Failure` of `Result` and `Exit`, `Left`/`Right`, `Some`/`None`) is reported with their refinement as the remedy, such as `Result.isFailure`: those types cannot gain a variant; a `switch` is reported as usual. An exhaustive ts-pattern match is an equally valid remedy. A name added to `discriminants` also fires on objects outside closed unions (DOM events, external payloads): the list is a choice of the codebase.
 
 **Why**: `Match.tagsExhaustive`, `Match.discriminatorsExhaustive` and `$match` fail to compile when a variant is added; a comparison or a `switch` does not.
 
-- **Pattern**: P36 · **Options**: `discriminants`, replaces the default `["_tag"]`; add the fields your unions discriminate on (`type`, `kind`) · **Fix**: none · **Severity**: —
+**Options**:
+
+- `discriminants`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
 
 ### `no-manual-discriminant-construction`
 
@@ -414,215 +319,316 @@ const event = PaymentStartedEvent.make({ id, payment })
 
 **Trigger**: an object literal with a discriminant property (also `"type"` or `["type"]`) whose value is a string literal. The discriminants are the names in `discriminants`.
 
-**Exemptions and blind spots**: values that are not literals (`"Ready" as const` included). Literals that are patterns or raw input, also nested: the arguments of `Match.when`, `Match.not`, of `.with(…)` on a ts-pattern `match(…)` chain, and the input of `Schema.decode*(X)(…)`/`Schema.encode*(X)(…)`. Transport payloads written as literals fire, and a name added to `discriminants` fires on objects outside closed unions: the list is a choice of the codebase. See `schema-struct-with-tag` (effecttsgo) for `Schema.Struct` with a `_tag` field.
+**Exemptions and blind spots**: values that are not literals (`"Ready" as const` included). Literals that are patterns or raw input, also nested: the arguments of `Match.when`, `Match.not`, of `.with(…)` on a ts-pattern `match(…)` chain, the expected value of an `expect(…)` matcher or `expect.*` helper, the input of `Schema.decode*(X)(…)`/`Schema.encode*(X)(…)`, the argument of `JSON.stringify`, and an argument whose parameter is annotated `unknown` in a function declared in the same file (a fake API's raw body). Transport payloads written as literals fire, as does raw data passed to an imported function or through a variable, and a name added to `discriminants` fires on objects outside closed unions: the list is a choice of the codebase. See `schema-struct-with-tag` (effecttsgo) for `Schema.Struct` with a `_tag` field.
 
 **Why**: a literal skips the constructor, so it carries none of the class's prototype, equality or validation, and drifts silently when the type changes.
 
-- **Pattern**: P37 · **Options**: `discriminants`, shared with [`no-manual-discriminant-comparison`](#no-manual-discriminant-comparison), default `["_tag"]` · **Fix**: none · **Severity**: —
+**Options**:
 
-## Config
+- `discriminants`: shared setting, see [Shared settings](#shared-settings).
 
-### `redacted-secret-names`
+**Fix**: none
+
+## Services and Layers
+
+### `service-port-shape-only`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: a secret read from config or declared in a schema is `Redacted`.
+**Intent**: a port is a shape-only `Context.Service` (v3: `Context.Tag`), with no implementation attached.
 
 ```ts
 // no
-serviceAccount: Config.schema(NonBlank, "GOOGLE_SERVICE_ACCOUNT_JSON")
-const Session = Schema.Struct({ userId: UserId, accessToken: Schema.String })
+class Agent extends Context.Service<Agent, Shape>()("app/Agent", { make: makeAgent }) {}
 
 // yes
-serviceAccount: Config.schema(Schema.Redacted(NonBlank), "GOOGLE_SERVICE_ACCOUNT_JSON")
-const Session = Schema.Struct({ userId: UserId, accessToken: Schema.Redacted(Schema.String) })
+export class Agent extends Context.Service<
+    Agent,
+    { readonly search: (name: string) => Effect.Effect<RaceCard, AgentError> }
+>()("app/agent/Agent") {}
 ```
 
-**Trigger**:
-
-- a literal name read with `Config.*` that ends with `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `CREDENTIAL`, `CREDENTIALS` or `_JSON` (service account keys often travel as inline JSON), when it does not go through `Config.redacted` or `Config.schema(Schema.Redacted…(…), name)`;
-- a field of `Schema.Struct({…})` or `Schema.Class<X>("X")({…})` whose name is a `secretFields` entry or ends with it capitalized (`password` matches `dbPassword`), declared with a `Schema.*` constant such as `Schema.String`, also through `.pipe(…)`, `.check(…)`, `.annotate(…)` or `Schema.optional`/`optionalKey`/`NullOr`/`UndefinedOr`/`NullishOr`, with no `Schema.Redacted…` along the way.
+**Trigger**: the second argument of `Context.Service<…>()(id, opts)`; a `static layer`, `static Default` or `static Live` member on a `Context.Service` or v3 `Context.Tag(id)<…>()` class; any `Effect.Service`.
 
-**Exemptions and blind spots**: a naming heuristic: secrets with other names slip through, non-secrets with these names must be suppressed. Fields declared with a named schema (`accessToken: AccessToken`) are not inspected; other constructors (`Schema.TaggedClass`, `Schema.TaggedStruct`, …) are not seen. `process.env` read outside `Config`: see `process-env` and `process-env-in-effect` (effecttsgo).
+**Exemptions and blind spots**: a `Context.Service` or v3 `Context.GenericTag` assigned to a variable is not seen: see `service-not-as-class` (effecttsgo). Statics with other names slip through.
 
-**Why**: a `Redacted` value does not end up in logs or `toString`.
+**Why**: `make` and a static layer tie the port to a default implementation, while the port must stay a contract any adapter can satisfy. It is a convention, not Effect's idiom: Effect's own docs put `static readonly layer` on the service.
 
-- **Pattern**: P13 · **Options**: `secretFields`, default `["password", "secret", "apiKey", "accessToken", "refreshToken", "idToken"]` (no generic `token`), replaced by the configured list; `Config` names are fixed · **Fix**: none · **Severity**: `warn`
+**Options**: none
 
-## Schema
+**Fix**: none
 
-### `exported-schema-identifier`
+### `service-key-matches-name`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: an exported schema carries an `identifier` equal to its name.
+**Intent**: a service's key is its class name, alone or after a path prefix.
 
 ```ts
 // no
-export const EventBusEvents = Schema.Union([Created, Deleted])
+export class GeocodingApis extends Context.Service<GeocodingApis, Shape>()("GeocodingAPIs") {}
 
 // yes
-export const EventBusEvents = Schema.Union([Created, Deleted]).annotate({
-    identifier: "EventBusEvents",
-})
+export class GeocodingApis extends Context.Service<GeocodingApis, Shape>()("GeocodingApis") {}
+
+// yes
+export class GeocodingApis extends Context.Service<GeocodingApis, Shape>()(
+    "app/geo/GeocodingApis",
+) {}
 ```
 
-**Trigger**: `export const X = Schema.Struct(…)`, `Schema.Union(…)` or `Schema.Array(…)`, also followed by `.pipe(…)`, `.annotate(…)` or `.check(…)`, with no `identifier` in a `.annotate(…)` or `Schema.annotate(…)` of the chain, or with a literal `identifier` other than `"X"`.
+**Trigger**: `class X extends Context.Service<…>()("key")`, or the v3 `Context.Tag("key")<…>()` and `Effect.Service<X>()("key", …)`, with a literal key that is neither `"X"` nor ends with `"/X"`.
 
-**Exemptions and blind spots**: non-exported schemas (fragments reused through `.fields`), and `Schema.Class` and `Schema.TaggedError`, which carry the name already. A computed `identifier` is not compared. Other constructors (`Schema.TaggedStruct`, `Schema.Literals`, …), `export { X }` lists and chains through other methods slip through. An exported fragment reused only through `.fields` fires too, although the annotation does not reach the schemas that spread it: export the plain fields object instead (`export const BaseFields = { … }`).
+**Exemptions and blind spots**: keys that are not literals (variables, templates with expressions). A `Context.Service` assigned to a variable is not seen: see `service-not-as-class` (effecttsgo). `deterministic-keys` (effecttsgo) with the `default` or `package-identifier` formula produces keys this rule accepts; with `default-hashed` the two contradict each other: enable only one.
 
-**Why**: without an `identifier`, decoding errors, JSON Schema and arbitraries describe the schema by its structure instead of its name.
+**Why**: the key is the service's identity in errors, traces and `Context` lookups; a key that drifts from the name, as after a rename, makes it hard to find the class behind a message.
 
-- **Pattern**: P35 · **Options**: none · **Fix**: suggestion that adds or corrects the `identifier` · **Severity**: —
+**Options**: none
 
-### `no-inline-schema-codec`
+**Fix**: suggestion that replaces the last segment of the key with the class name
+
+### `service-built-with-of`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: a decoder or encoder is a named module-level constant, not built and applied inline.
+**Intent**: the service a Layer provides is built with `Tag.of({…})`, not a bare object literal.
 
 ```ts
 // no
-const toPayment = (raw: unknown) => Schema.decodeUnknownSync(PaymentResponse)(raw)
+export const RepoLive = Layer.effect(
+    Repo,
+    Effect.gen(function* () {
+        const db = yield* Database
+        return { find: (id: RepoId) => db.get(id) }
+    }),
+)
 
 // yes
-const decodePaymentResponse = Schema.decodeUnknownSync(PaymentResponse)
+export const RepoLive = Layer.effect(
+    Repo,
+    Effect.gen(function* () {
+        const db = yield* Database
+        return Repo.of({ find: (id: RepoId) => db.get(id) })
+    }),
+)
+```
 
-const toPayment = (raw: unknown) => decodePaymentResponse(raw)
+**Trigger**: an object literal passed as the value of `Layer.succeed(T, {…})`, returned by the function of `Layer.sync(T, () => ({…}))`, or returned by a top-level `return {…}` of the generator of `Layer.effect(T, Effect.gen(…))` or `Layer.scoped`; the curried `Layer.succeed(T)(…)` forms too.
+
+**Exemptions and blind spots**: a named factory (`Layer.sync(Repo, makeRepo)`) and a variable (`Layer.succeed(Repo, repo)`) are not inspected; `return` inside an `if` or a nested block, `Effect.gen(…).pipe(Layer.effect(T))` and generators other than `Effect.gen` slip through.
+
+**Why**: `T.of` names the service the object implements and keeps it checked against the shape if the literal moves out of the Layer; one form for every Layer.
+
+**Options**: none
+
+**Fix**: suggestion that wraps the literal in `T.of(…)`
+
+### `provide-named-layer`
+
+<sup>[↑ rules index](#rules-index)</sup>
+
+**Intent**: `Effect.provide` receives a named Layer, never an inline composition.
+
+```ts
+// no
+printMissing.pipe(Effect.provide(Layer.mergeAll(FileRaceList.layer, GoogleSheet.readerLayer)))
+
+// yes: the Layer is named in the entry point, provided in the dispatch
+const missingLayer = Layer.mergeAll(FileRaceList.layer, GoogleSheet.readerLayer)
+Missing: () => printMissing.pipe(Effect.provide(missingLayer)),
 ```
 
-**Trigger**: an immediate application `Schema.decode*(X)(input)` or `Schema.encode*(X)(input)` (the `Effect`, `Exit`, `Option`, `Promise`, `Result` and `Sync` variants, `Unknown` included) inside a function, test callbacks included.
+**Trigger**: an `Effect.provide` argument composed inline: `Layer.*(…)`, a ternary, an `&&`/`||`, a `match`/`$match`.
 
-**Exemptions and blind spots**: module scope, and the generator of `Layer.effect(T, Effect.gen(…))` or `Layer.effect(T)(Effect.gen(…))` (also `Layer.scoped`), which run once; functions nested in that generator, such as the service methods, are checked. Codecs built inside a function and applied later (`const decode = Schema.decodeUnknownEffect(X)`), codecs passed as callbacks (`Effect.flatMap(Schema.decodeUnknownEffect(X))`) and a Layer built through `.pipe(Layer.effect(T))` slip through. Whether the codec should be synchronous is not this rule's concern: see `schema-sync` (effecttsgo).
+**Exemptions and blind spots**: test files, where different fakes per test are idiomatic. Where `provide` sits (outside the entry point) needs types: see `strict-effect-provide` (effecttsgo).
 
-**Why**: a named codec says what it decodes at the call site and is built once, instead of at every call.
+**Why**: an inline Layer cannot be reused and hides which adapters a branch chooses. When branches need different Layers, there is one `provide` per branch, all in the dispatch: a single Layer with every service would build adapters the command does not use.
 
-- **Pattern**: P39 · **Options**: none · **Fix**: none · **Severity**: —
+**Options**:
 
-## Effectful functions
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
 
-### `prefer-effect-fn`
+**Fix**: none
+
+### `no-provide-on-definition`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: an effectful function is `Effect.fn("name")`, and a named effect value has a span.
+**Intent**: a program does not provide its own Layers; its caller does.
 
 ```ts
 // no
-const outcomeFor = (name: string) => Effect.gen(function* () { … }).pipe(Effect.catch(toFailed))
-const refresh = Effect.gen(function* () { … })
+const printMissing = Effect.gen(function* () { … }).pipe(Effect.provide(missingLayer))
+
+// yes: the program stays unprovided, its caller provides
+const printMissing = Effect.gen(function* () { … })
+Missing: () => printMissing.pipe(Effect.provide(missingLayer)),
+```
+
+**Trigger**: `Effect.provide` applied to `Effect.gen(…)` or to `Effect.fn(…)(…)`, in all three forms: with `.pipe`, as an `Effect.fn` pipeable, data-first.
+
+**Exemptions and blind spots**: test files. A program passed directly to `Effect.run*`, also through `.pipe(…)` or data-first `Effect.*` combinators (`Effect.runPromise(Effect.gen(…).pipe(Effect.provide(layer), Effect.result))`): it is already being dispatched; through any other function it is still reported. A context captured in an enclosing generator with `const ctx = yield* Effect.context<R>()` (also followed by `.pipe(…)`) and handed back to a method of the Layer being built: the caller chose the adapters when it built the Layer. A context obtained through a helper (`yield* contextWithoutSpan()`) is still reported. `provide` on a named program is allowed; `strict-effect-provide` (effecttsgo) reports it too.
+
+**Why**: a program that provides its own Layers can no longer be wired to different adapters by its caller.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
+
+### `anti-slop-no-service-constructor-imports`
+
+<sup>[↑ rules index](#rules-index)</sup>
+
+**Intent**: runtime code obtains a service from its Layer, never by calling its `make…` constructor.
+
+```ts
+// no: in src/runtime.ts
+import { makeIssueService } from "./issue-service.ts"
+
+// yes
+import { IssueService } from "./issue-service.ts"
+
+Effect.gen(function* () {
+    const issues = yield* IssueService
+})
+```
+
+**Trigger**: a named import of `make` followed by an uppercase letter (`makeIssueService`, also when renamed) from a relative module.
+
+**Exemptions and blind spots**: test files, which build services from their constructors to inject fakes. Non-relative imports (packages, path aliases), namespace and default imports, and constructors with another prefix slip through. The same import can also fire [`adapter-import-boundary`](#adapter-import-boundary).
+
+**Why**: calling the constructor wires its dependencies by hand, and its requirements stop propagating to the composition root.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
+
+## Runtime and entry point
+
+### `run-only-in-runner`
+
+<sup>[↑ rules index](#rules-index)</sup>
+
+**Intent**: Effects run only in the program's runner, the entry point.
+
+```ts
+// no
+export const check = () => Effect.runPromise(pingDb(url))
 
-// yes: extra combinators as arguments, not .pipe
-const outcomeFor = Effect.fn("outcomeFor")(function* (name: string) { … }, Effect.catch(toFailed))
-const refresh = Effect.gen(function* () { … }).pipe(Effect.withSpan("refresh"))
+// yes: in main.ts
+NodeRuntime.runMain(
+    run(process.argv.slice(2)).pipe(Effect.provide(NodeServices.layer)) satisfies Effect.Effect<
+        void,
+        never
+    >,
+)
 ```
 
-**Trigger**:
+**Trigger**: every reference, not just calls, to `Effect.run*`, `NodeRuntime.runMain`, `BunRuntime.runMain` and `ManagedRuntime.make` outside entry files.
 
-- a declared function, a variable or an object member that only returns `Effect.gen(…)`, even with `.pipe`;
-- a variable or an object member whose value is `Effect.gen(…)` without `Effect.withSpan` in its `.pipe`;
-- `Effect.fn(body)` without a name;
-- `.pipe` on `Effect.fn(…)(…)`.
+**Exemptions and blind spots**: test files, checked by [`prefer-effect-vitest`](#prefer-effect-vitest) instead.
 
-**Exemptions and blind spots**: `Effect.gen` inline as an argument (`Layer.effect(Tag, Effect.gen(…))`, `Stream.unwrap`, callbacks, `it.effect`). Recursive functions: see [`untraced-recursion`](#untraced-recursion).
+**Why**: logger, Layers and defect handling are configured in one place.
 
-**Why**: named stack traces and spans without wrapper functions. Combinators passed as arguments run inside the function's span and receive its arguments: `(effect, name) => effect.pipe(…)`.
+**Options**:
 
-- **Pattern**: P17 · **Options**: none · **Fix**: none · **Severity**: `warn`
+- `entryFiles`: shared setting, see [Shared settings](#shared-settings).
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
 
-### `untraced-recursion`
+**Fix**: none
+
+### `prefer-effect-vitest`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: a recursive effectful function uses `Effect.fnUntraced`; the entry point that starts the recursion is traced.
+**Intent**: tests hand their Effects to `@effect/vitest` instead of running them.
 
 ```ts
 // no
-const walk = Effect.fn("walk")(function* (node: Node) {
-    for (const child of node.children) yield* walk(child)
+test("…", async () => {
+    await Effect.runPromise(authorize({ role: "Manager" }))
 })
 
-// yes
-const walk = Effect.fnUntraced(function* (node: Node) {
-    for (const child of node.children) yield* walk(child)
-})
-export const scan = Effect.fn("scan")(function* (root: Node) {
-    return yield* walk(root)
-})
+// yes: fakes as Layers
+import { effect } from "@effect/vitest"
+
+effect("…", () => authorize({ role: "Manager" }).pipe(Effect.provide(sheetWith(row))))
 ```
 
-**Trigger**: an `Effect.fn` assigned to a variable that its own body calls again, even by passing it as a callback.
+**Trigger**: the same references as [`run-only-in-runner`](#run-only-in-runner), inside test files only.
 
-**Exemptions and blind spots**: mutual recursion, recursion in pipeables.
+**Exemptions and blind spots**: projects where `@effect/vitest` cannot be found in a `node_modules` from the test file up, since the remedy is out of reach there; scattered runs in their tests go unreported. Every file outside `testFiles`, test helpers such as `src/testing/` included.
 
-**Why**: with `Effect.fn` every level opens a span nested in the previous one.
+**Why**: the test runtime brings `TestClock` and a scope per test, and fixtures provided as Layers replace services where the code reads them.
 
-- **Pattern**: P17 · **Options**: none · **Fix**: none · **Severity**: `warn`
+**Options**:
 
-### `single-style-per-function`
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
+
+### `all-errors-handled-at-boundary`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: a function is entirely Effect or not Effect at all.
+**Intent**: the entry point runs an Effect whose error channel is closed to `never`.
 
 ```ts
 // no
-export const POST = async (request: Request) => {
-    const form = await request.formData()
-    const created = await Effect.runPromise(Effect.either(createEvent(form)))
-    // …
-}
+export const POST = (request: Request) => Effect.runPromise(createEvent(request))
 
-// yes: promises lifted with Effect.tryPromise
-const createEvent = Effect.fn("events.create")(function* (request: Request) {
-    const form = yield* Effect.tryPromise({
-        try: () => request.formData(),
-        catch: () => new BadRequest({ message: "invalid form data" }),
-    })
-    // …
-})
+// yes: in an entry file
+export const POST = (request: Request) =>
+    Effect.runPromise(createEvent(request) satisfies Effect.Effect<Response, never>)
+
+// yes: a typed helper
+const runBoundary = (effect: Effect.Effect<Response, never, never>) => Effect.runPromise(effect)
 ```
 
-**Trigger**: `async`, `await` and `.then(` in a function that builds Effects: an Effect generator, or a function using an `Effect.*` member. In a `test`/`it` callback (`.only`, `.each(…)` and the like included) the mix is reported once, on the callback.
+**Trigger**: `Effect.runPromise`, `runSync`, `runFork` and `runCallback` whose argument is not `… satisfies Effect.Effect<A, never>`, a parameter declared with that type, or a program ending in `Effect.result`/`Effect.exit`, or the v3 `Effect.either` (`Effect.result(program)`, `program.pipe(…, Effect.result)`).
 
-**Exemptions and blind spots**: `Effect.run*` alone does not make a function effectful: it is how an async boundary hands over to Effect, and where it may appear is decided by [`run-only-at-entry`](#run-only-at-entry). In tests the fix is a body that is one Effect (`it.effect`, or one call to the test runner), not a `tryPromise` per promise.
+**Exemptions and blind spots**: the `*Exit` variants, which return failures as values; `NodeRuntime.runMain`/`BunRuntime.runMain`, which log the Cause and exit with code 1, the right outcome for a process that cannot start; runners inside an `async` function that renders JSX itself, a Server Component, which hands failures to React rather than to an HTTP response; test files, where a rejected run fails the test with the error. The rule checks the shape; `tsc` gives the guarantee.
 
-**Why**: errors travel on two channels, exceptions and Effect, and neither sees them all.
+**Why**: `Effect.runPromise` turns any error left over into a rejected promise, a generic 500. With `never`, a new untranslated error does not compile, and `R = never` forces all Layers to be provided.
 
-- **Pattern**: P24 · **Options**: none · **Fix**: none · **Severity**: `error`
+**Options**:
 
-### `error-handling-in-effect-fn-handler`
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
+
+## Design and boundaries
+
+### `adapter-import-boundary`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: the generator holds only the happy path; error handling lives in the second argument of `Effect.fn`.
+**Intent**: domain code and other adapters do not import an adapter; only entry files choose it.
 
 ```ts
-// no
-function* () {
-    const x = yield* fetchThing.pipe(Effect.catchTag("NotFound", () => Effect.succeed(fallback)))
-}
-
-// yes: naming the error or giving an alternative is not handling
-function* () {
-    const x = yield* fetchThing.pipe(Effect.orElseSucceed(() => fallback))
-    const y = yield* decode(raw).pipe(Effect.mapError((error) => new BadRequest({ message: error.message })))
-}
+// no: in src/orders/place-order.ts
+import { GoogleCalendar } from "../calendar/google/GoogleCalendar.ts"
 
-// yes: translation in the second argument, which also receives the original arguments
-const createEvent = Effect.fn("events.create")(
-    function* (request: Request) { /* success only */ },
-    (effect, request) => effect.pipe(Effect.catchTags({ BadRequest: (e) => refused(400, e.message) })),
-)
+// yes: depend on the port, main.ts provides GoogleCalendar.layer
+import { Calendar } from "../calendar/Calendar.ts"
 ```
 
-**Trigger**: inside a generator passed to `Effect.gen`/`Effect.fn`, nested callbacks included, calls to `Effect.catch*` (`catch`, `catchAll`, `catchTag`, `catchTags`, `catchIf`, `catchCause`, `catchDefect`, `catchReason`, …), `either`, `result`, `exit`, `match*` and `sandbox`.
+**Trigger**: a relative import of a file in another directory that is an adapter: one of its `.ts` files (tests excluded) builds a `Layer` with `Layer.effect`, `succeed`, `sync`, `scoped`, `effectContext`, `unwrap`, `mock` and similar, or declares a v3 `Effect.Service`, which always carries its implementation. Composition alone (`mergeAll`, `provide`, `merge`) does not make an adapter.
 
-**Exemptions and blind spots**: pipeables of a nested `Effect.fn`. Test files, where the failure is the outcome under observation (`yield* Effect.result(op)` then `expect`). A `.pipe(Effect.catch…)` appended to an `Effect.gen` escapes; [`prefer-effect-fn`](#prefer-effect-fn) closes that gap.
+**Exemptions and blind spots**: entry files, where adapters are chosen, and test files, which compose the Layers they exercise. Non-relative imports (path aliases such as `@/calendar/google`) and directory imports through an `index.ts` (`"../google"`) slip through. On a layout other than one directory per adapter, check what it reports before trusting it. Infrastructure requirements in the port's `R` channel need types: see `leaking-requirements` (effecttsgo).
 
-**Why**: translation becomes a single exhaustive point instead of catches scattered along the flow.
+**Why**: the adapter can be replaced without touching its consumers.
+
+**Options**:
 
-- **Pattern**: P25 · **Options**: `testFiles` ([File options](#file-options)) · **Fix**: none · **Severity**: `warn`
+- `entryFiles`: shared setting, see [Shared settings](#shared-settings).
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
+
+**Fix**: none
 
 ### `no-transport-types-in-generator`
 
@@ -653,85 +659,119 @@ const createEvent = Effect.fn("events.create")(
 )
 ```
 
-**Trigger**: `new T(…)`, `T.method(…)` and `T(…)` inside an Effect generator, nested callbacks included, when `T` is a transport type.
+**Trigger**: `new T(…)`, `T.method(…)` and `T(…)` inside an Effect generator, callbacks passed to `Effect.*` combinators included, when `T` is a transport type.
 
-**Exemptions and blind spots**: pipeables of `Effect.fn`, where the conversion must live. `return yield* new Unauthenticated(…)` is a declared failure. An early `return` of a domain value that actually signals an error is indistinguishable from a success.
+**Exemptions and blind spots**: pipeables of `Effect.fn`, where the conversion must live. Functions the generator only defines, such as an HTTP handler it registers. `return yield* new Unauthenticated(…)` is a declared failure. An early `return` of a domain value that actually signals an error is indistinguishable from a success.
 
 **Why**: an early `return new Response(…)` on the happy path is an error branch disguised as success, and escapes exhaustive translation.
 
-- **Pattern**: P26 · **Options**: `transportTypes`, replaces the default `["Response", "NextResponse"]`; add your own transport DTOs · **Fix**: none · **Severity**: `error`
+**Options**:
+
+- `transportTypes`: default `["Response", "NextResponse"]`, replaced by the configured list. Add your own transport DTOs.
+
+**Fix**: none
+
+## Effectful functions
 
-### `boundary-entrypoint-shape`
+### `prefer-effect-fn`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: the entry point runs an Effect whose error channel is closed to `never`.
+**Intent**: an effectful function is `Effect.fn("name")`, and a named effect value has a span.
 
 ```ts
 // no
-export const POST = (request: Request) => Effect.runPromise(createEvent(request))
-
-// yes: in an entry file
-export const POST = (request: Request) =>
-    Effect.runPromise(createEvent(request) satisfies Effect.Effect<Response, never>)
+const outcomeFor = (name: string) => Effect.gen(function* () { … }).pipe(Effect.catch(toFailed))
+const refresh = Effect.gen(function* () { … })
 
-// yes: a typed helper
-const runBoundary = (effect: Effect.Effect<Response, never, never>) => Effect.runPromise(effect)
+// yes: extra combinators as arguments, not .pipe
+const outcomeFor = Effect.fn("outcomeFor")(function* (name: string) { … }, Effect.catch(toFailed))
+const refresh = Effect.gen(function* () { … }).pipe(Effect.withSpan("refresh"))
 ```
 
-**Trigger**: `Effect.runPromise`, `runSync`, `runFork`, `runCallback` and `NodeRuntime.runMain`/`BunRuntime.runMain` whose argument is neither `… satisfies Effect.Effect<A, never>` nor a parameter declared with that type.
+**Trigger**:
+
+- a declared function, a variable or an object member that only returns `Effect.gen(…)`, even with `.pipe`;
+- a variable or an object member whose value is `Effect.gen(…)` without `Effect.withSpan` in its `.pipe`;
+- `Effect.fn(body)` without a name;
+- `.pipe` on `Effect.fn(…)(…)`.
 
-**Exemptions and blind spots**: the `*Exit` variants, which return failures as values. The rule checks the shape; `tsc` gives the guarantee.
+**Exemptions and blind spots**: `Effect.gen` inline as an argument (`Layer.effect(Tag, Effect.gen(…))`, `Stream.unwrap`, callbacks, `it.effect`). Recursive functions: see [`untraced-recursion`](#untraced-recursion).
 
-**Why**: `Effect.runPromise` turns any error left over into a rejected promise, a generic 500. With `never`, a new untranslated error does not compile, and `R = never` forces all Layers to be provided.
+**Why**: named stack traces and spans without wrapper functions. Combinators passed as arguments run inside the function's span and receive its arguments: `(effect, name) => effect.pipe(…)`.
 
-- **Pattern**: P27 · **Options**: none · **Fix**: none · **Severity**: `warn`
+**Options**: none
 
-## Wiring and code shape
+**Fix**: none
 
-### `provide-named-layer`
+### `untraced-recursion`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: `Effect.provide` receives a named Layer, never an inline composition.
+**Intent**: a recursive effectful function uses `Effect.fnUntraced`; the entry point that starts the recursion is traced.
 
 ```ts
 // no
-printMissing.pipe(Effect.provide(Layer.mergeAll(FileRaceList.layer, GoogleSheet.readerLayer)))
+const walk = Effect.fn("walk")(function* (node: Node) {
+    for (const child of node.children) yield* walk(child)
+})
 
-// yes: the Layer is named in the entry point, provided in the dispatch
-const missingLayer = Layer.mergeAll(FileRaceList.layer, GoogleSheet.readerLayer)
-Missing: () => printMissing.pipe(Effect.provide(missingLayer)),
+// yes
+const walk = Effect.fnUntraced(function* (node: Node) {
+    for (const child of node.children) yield* walk(child)
+})
+export const scan = Effect.fn("scan")(function* (root: Node) {
+    return yield* walk(root)
+})
 ```
 
-**Trigger**: an `Effect.provide` argument composed inline: `Layer.*(…)`, a ternary, an `&&`/`||`, a `match`/`$match`.
+**Trigger**: an `Effect.fn` assigned to a variable that its own body calls again, even by passing it as a callback.
 
-**Exemptions and blind spots**: test files, where different fakes per test are idiomatic. Where `provide` sits (outside the entry point) needs types: see `strict-effect-provide` (effecttsgo).
+**Exemptions and blind spots**: mutual recursion, recursion in pipeables.
 
-**Why**: an inline Layer cannot be reused and hides which adapters a branch chooses. When branches need different Layers, there is one `provide` per branch, all in the dispatch: a single Layer with every service would build adapters the command does not use.
+**Why**: with `Effect.fn` every level opens a span nested in the previous one.
 
-- **Pattern**: P28 · **Options**: `testFiles` ([File options](#file-options)) · **Fix**: none · **Severity**: `error`
+**Options**: none
 
-### `no-provide-on-definition`
+**Fix**: none
+
+### `single-style-per-function`
 
 <sup>[↑ rules index](#rules-index)</sup>
 
-**Intent**: a program does not provide its own Layers; its caller does.
+**Intent**: a function is entirely Effect or not Effect at all.
 
 ```ts
 // no
-const printMissing = Effect.gen(function* () { … }).pipe(Effect.provide(missingLayer))
+export const POST = async (request: Request) => {
+    const form = await request.formData()
+    const created = await Effect.runPromise(Effect.result(createEvent(form)))
+    // …
+}
 
-// yes: see provide-named-layer
+// yes: promises lifted with Effect.tryPromise
+const createEvent = Effect.fn("events.create")(function* (request: Request) {
+    const form = yield* Effect.tryPromise({
+        try: () => request.formData(),
+        catch: () => new BadRequest({ message: "invalid form data" }),
+    })
+    // …
+})
 ```
 
-**Trigger**: `Effect.provide` applied to `Effect.gen(…)` or to `Effect.fn(…)(…)`, in all three forms: with `.pipe`, as an `Effect.fn` pipeable, data-first.
+**Trigger**: `async`, `await` and `.then(` in a function that builds Effects: an Effect generator, or a function using an `Effect.*` member. A `test`/`it` callback (`.only`, `.each(…)` and the like included) or a `beforeAll`/`afterAll`/`beforeEach`/`afterEach` hook, and in test files any other function except an Effect generator, is reported once, on the function, when more than one of its `await`s, or any `.then(`, involves Effect: has an `Effect.*` member in its expression, nested callbacks and `Effect.run*` included.
 
-**Exemptions and blind spots**: test files. A context captured in an enclosing generator with `const ctx = yield* Effect.context<R>()` (also followed by `.pipe(…)`) and handed back to a method of the Layer being built: the caller chose the adapters when it built the Layer. A context obtained through a helper (`yield* contextWithoutSpan()`) is still reported. `provide` on a named program is allowed; `strict-effect-provide` (effecttsgo) reports it too.
+**Exemptions and blind spots**: `Effect.run*` alone does not make a function effectful: it is how an async boundary hands over to Effect, and where it may appear is decided by [`run-only-in-runner`](#run-only-in-runner). An `async` function that renders JSX itself, not only in nested callbacks, is a Server Component: how it turns failures into UI is left to the application. A test, hook or test helper may await promise-based fixtures (a container, an identity provider), then one Effect program, and assert on its result. A step that reaches Effect only through a helper (`await run(seed)`) is not counted.
 
-**Why**: a program that provides its own Layers can no longer be wired to different adapters by its caller.
+**Why**: errors travel on two channels, exceptions and Effect, and neither sees them all.
+
+**Options**:
+
+- `testFiles`: shared setting, see [Shared settings](#shared-settings).
 
-- **Pattern**: P28 · **Options**: `testFiles` ([File options](#file-options)) · **Fix**: none · **Severity**: `error`
+**Fix**: none
+
+## Code shape
 
 ### `no-nested-match`
 
@@ -773,7 +813,9 @@ const run = Effect.fn("run")(function* (argv: ReadonlyArray<string>) {
 
 **Why**: two nested levels of choice hide which branch is the normal one.
 
-- **Pattern**: P30 · **Options**: none · **Fix**: none · **Severity**: `warn`
+**Options**: none
+
+**Fix**: none
 
 ### `no-yielded-match`
 
@@ -800,13 +842,15 @@ const save = Effect.fn("save")(function* (id: PolicyId) {
 })
 ```
 
-**Trigger**: `yield*` of `Option.match(x, {…})` or `Result.match(x, {…})`, or of a `x.pipe(…)`/`pipe(x, …)` ending in `Option.match({…})`/`Result.match({…})`, in the generator of `Effect.gen` or `Effect.fn`.
+**Trigger**: `yield*` of `Option.match(x, {…})` or `Result.match(x, {…})` (v3: `Either.match`), or of a `x.pipe(…)`/`pipe(x, …)` ending in one of them, in the generator of `Effect.gen` or `Effect.fn`.
 
 **Exemptions and blind spots**: an `Option.match` with `onNone` → `Effect.fail(…)` and `onSome` → `Effect.succeed`: see `option-match-to-from-option` (effecttsgo). A handler that `no-nested-match` reports. Matches not yielded directly (assigned first, or inside `Effect.flatMap`) slip through.
 
 **Why**: the match splits the generator into two equal-weight branches; a guard clause leaves one main path of `yield*`.
 
-- **Pattern**: P40 · **Options**: none · **Fix**: none · **Severity**: —
+**Options**: none
+
+**Fix**: none
 
 ### `no-inline-yield-star`
 
@@ -816,11 +860,15 @@ const save = Effect.fn("save")(function* (id: PolicyId) {
 
 ```ts
 // no
-return yield * missingIn(yield * readSheet())
+function* () {
+    return yield* missingIn(yield* readSheet())
+}
 
 // yes
-const sheet = yield * readSheet()
-return yield * missingIn(sheet)
+function* () {
+    const sheet = yield* readSheet()
+    return yield* missingIn(sheet)
+}
 ```
 
 **Trigger**: a `yield*` whose result is used inside a larger expression: argument, operand, member, property, template.
@@ -829,7 +877,9 @@ return yield * missingIn(sheet)
 
 **Why**: with several `yield*`s in one expression the order of effects can only be inferred from precedence. One `const` per effect makes the order the reading order and names the intermediate value.
 
-- **Pattern**: P32 · **Options**: none · **Fix**: autofix · **Severity**: `warn`
+**Options**: none
+
+**Fix**: autofix
 
 ### `no-effect-return-type`
 
@@ -852,9 +902,13 @@ export const findPrice = (id: PriceId): Effect.Effect<Price, PriceNotFound> =>
 
 **Exemptions and blind spots**: module-level declarations with `export` (`export const`, `export function`, `export default`), unless `checkExported` is on; methods of an exported object, functions an exported function returns, and `export { f }` lists are still checked. Recursion, and returns of different shapes that need unifying (`Effect.succeed` and `Effect.fail`), recognized from the shape of the `return`s. An `import type { Effect }` used as `Effect<…>` slips through.
 
-**Why**: the error and requirement channels collect what comes from everything the function calls; an error or a service added deep down would change every caller's annotation. An exported signature is the module's contract, like a named type: there the annotation makes such a change visible where it is published.
+**Why**: the error and requirement channels collect what comes from everything the function calls; an error or a service added deep down would change every caller's annotation. An exported signature is the module's contract, like a named type: there the annotation makes such a change visible where it is published. To check a returned object against a named type, annotate the callback that builds it (`Effect.map(CurrentSession, (session): OrganizationContext => ({ … }))`) or use `satisfies`.
 
-- **Pattern**: P33 · **Options**: `checkExported`, default `false`: also checks exported declarations · **Fix**: suggestion that removes the annotation · **Severity**: `warn`
+**Options**:
+
+- `checkExported`: default `false`. Also checks exported declarations.
+
+**Fix**: suggestion that removes the annotation
 
 ### `no-asymmetric-match-handlers`
 
@@ -882,7 +936,9 @@ Option.match(only, {
 
 **Why**: a branch saying _what_ next to one showing _how_ forces the reader to switch level halfway through the choice.
 
-- **Pattern**: P34 · **Options**: none · **Fix**: none · **Severity**: `warn`
+**Options**: none
+
+**Fix**: none
 
 ### `anti-slop-prefer-effect-match`
 
@@ -908,4 +964,93 @@ const label = Match.value(kind).pipe(
 
 **Why**: a ternary chain hides which value is the fallback and cannot be made exhaustive.
 
-- **Pattern**: — · **Options**: none · **Fix**: none · **Severity**: —
+**Options**: none
+
+**Fix**: none
+
+## Schema
+
+### `exported-schema-identifier`
+
+<sup>[↑ rules index](#rules-index)</sup>
+
+**Intent**: an exported schema carries an `identifier` equal to its name.
+
+```ts
+// no
+export const EventBusEvents = Schema.Union([Created, Deleted])
+
+// yes
+export const EventBusEvents = Schema.Union([Created, Deleted]).annotate({
+    identifier: "EventBusEvents",
+})
+```
+
+**Trigger**: `export const X = Schema.Struct(…)`, `Schema.Union(…)` or `Schema.Array(…)`, also followed by `.pipe(…)`, `.annotate(…)` or `.check(…)`, with no `identifier` in a `.annotate(…)` or `Schema.annotate(…)` of the chain (v3: `annotations`), or with a literal `identifier` other than `"X"`.
+
+**Exemptions and blind spots**: non-exported schemas (fragments reused through `.fields`), and `Schema.Class` and `Schema.TaggedError`, which carry the name already. A computed `identifier` is not compared. Other constructors (`Schema.TaggedStruct`, `Schema.Literals`, …), `export { X }` lists and chains through other methods slip through. An exported fragment reused only through `.fields` fires too, although the annotation does not reach the schemas that spread it: export the plain fields object instead (`export const BaseFields = { … }`).
+
+**Why**: without an `identifier`, decoding errors, JSON Schema and arbitraries describe the schema by its structure instead of its name.
+
+**Options**: none
+
+**Fix**: suggestion that corrects the `identifier`, or two that add it, `v3:` with `.annotations(…)` and `v4:` with `.annotate(…)`
+
+### `no-inline-schema-codec`
+
+<sup>[↑ rules index](#rules-index)</sup>
+
+**Intent**: a decoder or encoder is a named module-level constant, not built and applied inline.
+
+```ts
+// no
+const toPayment = (raw: unknown) => Schema.decodeUnknownSync(PaymentResponse)(raw)
+
+// yes
+const decodePaymentResponse = Schema.decodeUnknownSync(PaymentResponse)
+
+const toPayment = (raw: unknown) => decodePaymentResponse(raw)
+```
+
+**Trigger**: an immediate application `Schema.decode*(X)(input)` or `Schema.encode*(X)(input)` (the `Effect`, `Exit`, `Option`, `Promise`, `Result` and `Sync` variants, `Unknown` included) inside a function, test callbacks included.
+
+**Exemptions and blind spots**: module scope, and the generator of `Layer.effect(T, Effect.gen(…))` or `Layer.effect(T)(Effect.gen(…))` (also `Layer.scoped`), which run once; functions nested in that generator, such as the service methods, are checked. Codecs built inside a function and applied later (`const decode = Schema.decodeUnknownEffect(X)`), codecs passed as callbacks (`Effect.flatMap(Schema.decodeUnknownEffect(X))`) and a Layer built through `.pipe(Layer.effect(T))` slip through. Whether the codec should be synchronous is not this rule's concern: see `schema-sync` (effecttsgo).
+
+**Why**: a named codec says what it decodes at the call site and is built once, instead of at every call.
+
+**Options**: none
+
+**Fix**: none
+
+## Config and secrets
+
+### `redacted-secret-names`
+
+<sup>[↑ rules index](#rules-index)</sup>
+
+**Intent**: a secret read from config or declared in a schema is `Redacted`.
+
+```ts
+// no
+serviceAccount: Config.schema(NonBlank, "GOOGLE_SERVICE_ACCOUNT_JSON")
+const Session = Schema.Struct({ userId: UserId, accessToken: Schema.String })
+
+// yes
+serviceAccount: Config.schema(Schema.Redacted(NonBlank), "GOOGLE_SERVICE_ACCOUNT_JSON")
+const Session = Schema.Struct({ userId: UserId, accessToken: Schema.Redacted(Schema.String) })
+```
+
+**Trigger**:
+
+- a literal name read with `Config.*` that ends with `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `CREDENTIAL`, `CREDENTIALS` or `_JSON` (service account keys often travel as inline JSON), when it does not go through `Config.Redacted`, the v3 `Config.redacted` (also wrapping a config, `Config.redacted(Config.string(name))`), or `Config.schema(Schema.Redacted…(…), name)`;
+- a field of `Schema.Struct({…})` or `Schema.Class<X>("X")({…})` whose name is a `secretFields` entry or ends with it capitalized (`password` matches `dbPassword`), declared with a `Schema.*` constant such as `Schema.String`, also through `.pipe(…)`, `.check(…)`, `.annotate(…)`/`.annotations(…)` or `Schema.optional`/`optionalKey`/`optionalWith`/`NullOr`/`UndefinedOr`/`NullishOr`, with no `Schema.Redacted…` along the way.
+
+**Exemptions and blind spots**: a naming heuristic: secrets with other names slip through, non-secrets with these names must be suppressed. Fields declared with a named schema (`accessToken: AccessToken`) are not inspected; other constructors (`Schema.TaggedClass`, `Schema.TaggedStruct`, …) are not seen. `process.env` read outside `Config`: see `process-env` and `process-env-in-effect` (effecttsgo).
+
+**Why**: a `Redacted` value does not end up in logs or `toString`.
+
+**Options**:
+
+- `secretFields`: default `["password", "secret", "apiKey", "accessToken", "refreshToken", "idToken"]` (no generic `token`), replaced by the configured list. `Config` names are fixed.
+
+**Fix**: none