@drkmttr/adhere 0.7.3 → 0.9.0

package/presets/alchemy/resources/idempotent-actions-and-seeds.md

@@ -0,0 +1,19 @@
+---
+description: An Action body and a SQL file listed in importFiles must be safe to run again, using IF NOT EXISTS, ON CONFLICT, or upserts, never one-shot inserts or calls that duplicate data or fail when an interrupted deploy retries them.
+---
+
+```ts must
+export const Migrate = Alchemy.Action("Migrate", Effect.fn(function* () {
+  const db = yield* D1Client;
+  yield* db.exec("CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)");
+  yield* db.exec("INSERT INTO users (id, name) VALUES ('admin', 'Admin') ON CONFLICT (id) DO NOTHING");
+}));
+```
+
+```ts never
+export const Seed = Alchemy.Action("Seed", Effect.fn(function* () {
+  const db = yield* D1Client;
+  yield* db.exec("CREATE TABLE users (id TEXT, name TEXT)");
+  yield* db.exec("INSERT INTO users VALUES ('admin', 'Admin')"); // a second admin on every retry
+}));
+```

package/presets/alchemy/resources/previews-reference-shared-resources.md

@@ -0,0 +1,15 @@
+---
+description: Preview stages should reference a long-lived database or cluster with ref and create only cheap per-stage pieces such as a branch, and should not provision a whole project or cluster for every preview.
+---
+
+```ts should
+const project = stage.startsWith("pr-")
+  ? yield* Neon.Project.ref("AppDb", { stage: "staging" })
+  : yield* Neon.Project("AppDb", { region: "aws-us-east-1" });
+const branch = yield* Neon.Branch("Branch", { project });
+```
+
+```ts should not
+const project = yield* Neon.Project("AppDb", { region: "aws-us-east-1" }); // a new project per PR
+const branch = yield* Neon.Branch("Branch", { project });
+```

package/presets/alchemy/resources/protect-irreplaceable-data.md

@@ -0,0 +1,12 @@
+---
+description: A bucket or database holding user or business data should be retained with RemovalPolicy.retain(), at least in production, and forceDestroy should be set only on buckets whose contents are disposable; irreplaceable data should not depend on the default destroy policy.
+---
+
+```ts should
+const uploads = yield* Cloudflare.R2.Bucket("Uploads").pipe(RemovalPolicy.retain(stage === "prod"));
+const cache = yield* Cloudflare.R2.Bucket("Cache", { forceDestroy: true });
+```
+
+```ts should not
+const userUploads = yield* Cloudflare.R2.Bucket("UserUploads", { forceDestroy: true });
+```

package/presets/alchemy/resources/remote-state-for-ci.md

@@ -0,0 +1,22 @@
+---
+description: A stack deployed from CI or by more than one machine must use a shared state store such as Cloudflare.state() or AWS.state(), never Alchemy.localState(), which lives on one machine's disk where CI runners cannot see it.
+---
+
+```ts must
+export default Alchemy.Stack("App", { providers: Cloudflare.providers(), state: Cloudflare.state() },
+  Effect.gen(function* () {
+    const api = yield* Api;
+    return { url: api.url };
+  }),
+);
+```
+
+```ts never
+// deployed by .github/workflows/deploy.yml
+export default Alchemy.Stack("App", { providers: Cloudflare.providers(), state: Alchemy.localState() },
+  Effect.gen(function* () {
+    const api = yield* Api;
+    return { url: api.url };
+  }),
+);
+```

package/presets/alchemy/resources/stable-logical-ids.md

@@ -0,0 +1,13 @@
+---
+description: A resource's logical ID, its first argument, must stay the same from one deploy to the next, never built from timestamps, random values, UUIDs, or commit SHAs, because a new logical ID replaces the resource and deletes the old one with its data.
+---
+
+```ts must
+const uploads = yield* Cloudflare.R2.Bucket("Uploads");
+const jobs = yield* AWS.SQS.Queue("Jobs");
+```
+
+```ts never
+const uploads = yield* Cloudflare.R2.Bucket(`Uploads-${Date.now()}`);
+const db = yield* Neon.Project(`Db-${process.env.GITHUB_SHA}`);
+```

package/presets/alchemy/resources/stage-unique-physical-names.md

@@ -0,0 +1,15 @@
+---
+description: In a stack deployed to several stages, a resource whose physical name is global to an account or org should omit name, so alchemy derives one per stage, or derive it from the stage, and should not hardcode a single name every stage shares.
+---
+
+```ts should
+const traces = yield* Axiom.Dataset("Traces", Stack.useSync(({ stage }) => ({
+  name: `${stage}-traces`,
+  kind: "otel:traces:v1" as const,
+})));
+const branch = yield* Neon.Branch("Preview", { project });
+```
+
+```ts should not
+const traces = yield* Axiom.Dataset("Traces", { name: "app-traces", kind: "otel:traces:v1" });
+```

package/presets/alchemy/runtime/bind-tag-not-implementation.md

@@ -0,0 +1,27 @@
+---
+description: When a runtime is split into a Tag class and a make Layer, other runtimes must import and bind only the Tag, and only the Stack provides the Layer; another Worker or Function must never import or provide that implementation Layer.
+---
+
+```ts must
+// src/Admin.ts
+import { Api } from "./Api.ts";
+
+export default Cloudflare.Worker("Admin", { main: import.meta.url },
+  Effect.gen(function* () {
+    const api = yield* Cloudflare.Workers.bindWorker(Api);
+    return { fetch: Effect.gen(function* () { return yield* api.fetch(yield* HttpServerRequest.HttpServerRequest); }) };
+  }),
+);
+```
+
+```ts never
+// src/Admin.ts
+import ApiLive, { Api } from "./Api.ts";
+
+export default Cloudflare.Worker("Admin", { main: import.meta.url },
+  Effect.gen(function* () {
+    const api = yield* Cloudflare.Workers.bindWorker(Api);
+    return { fetch: forwardTo(api) };
+  }).pipe(Effect.provide(ApiLive)), // ships a second copy of Api's runtime
+);
+```

package/presets/alchemy/runtime/deterministic-config-defaults.md

@@ -0,0 +1,13 @@
+---
+description: A Config default or fallback used by a runtime must be deterministic, because it is evaluated at deploy time and at runtime, never computed from the clock, randomness, or per-process values.
+---
+
+```ts must
+const port = yield* Config.Number("PORT").pipe(Config.withDefault(3000));
+const region = yield* Config.String("REGION").pipe(Config.withDefault("us-east-1"));
+```
+
+```ts never
+const instanceId = yield* Config.String("INSTANCE_ID").pipe(Config.withDefault(crypto.randomUUID()));
+const startedAt = yield* Config.String("STARTED_AT").pipe(Config.withDefault(new Date().toISOString()));
+```

package/presets/alchemy/runtime/disposables-in-request-scope.md

@@ -0,0 +1,27 @@
+---
+description: Connections, pools, sockets, and anything else with a finalizer must be acquired inside a handler or method, where the event's scope releases them, never at module scope or in a runtime's construction Effect, whose finalizers may never run.
+---
+
+```ts must
+Effect.gen(function* () {
+  const url = yield* Config.Redacted("DATABASE_URL");
+  return {
+    fetch: Effect.gen(function* () {
+      const pool = yield* Effect.acquireRelease(
+        Effect.sync(() => new Pool({ connectionString: Redacted.value(url), max: 1 })),
+        (pool) => Effect.promise(() => pool.end()),
+      );
+      const { rows } = yield* Effect.promise(() => pool.query("select id from users"));
+      return yield* HttpServerResponse.json(rows);
+    }),
+  };
+});
+```
+
+```ts never
+Effect.gen(function* () {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // one pool for the isolate
+  yield* Effect.addFinalizer(() => Effect.promise(() => pool.end())); // workerd never runs this
+  return { fetch: handlerUsing(pool) };
+});
+```

package/presets/alchemy/runtime/lambda-no-post-response-work.md

@@ -0,0 +1,19 @@
+---
+description: In a Lambda handler, anything that must not be lost must be written durably, to a queue or a table, inside the handler before it responds, never left to a dangling promise, a forked fiber, or a finalizer, because Lambda freezes the instance after the response.
+---
+
+```ts must
+fetch: Effect.gen(function* () {
+  const event = yield* HttpServerRequest.schemaBodyJson(AuditEvent);
+  yield* sendMessage({ MessageBody: JSON.stringify(event) });
+  return HttpServerResponse.empty({ status: 202 });
+}),
+```
+
+```ts never
+fetch: Effect.gen(function* () {
+  const event = yield* HttpServerRequest.schemaBodyJson(AuditEvent);
+  void fetch(AUDIT_URL, { method: "POST", body: JSON.stringify(event) }); // may never run
+  return HttpServerResponse.empty({ status: 202 });
+}),
+```

package/presets/alchemy/runtime/no-per-request-work-at-construction.md

@@ -0,0 +1,24 @@
+---
+description: A runtime's construction Effect runs at deploy time and again at cold start, so it must only build resources, bindings, layers, and handler groups, never do per-request work such as queries, writes, bound calls, or starting consumers.
+---
+
+```ts must
+Effect.gen(function* () {
+  const table = yield* AWS.DynamoDB.Table("Jobs", { partitionKey: "id", attributes: { id: "S" } });
+  const putItem = yield* AWS.DynamoDB.PutItem(table);
+  return {
+    fetch: Effect.gen(function* () {
+      yield* putItem({ Item: { id: { S: crypto.randomUUID() } } });
+      return HttpServerResponse.empty({ status: 202 });
+    }),
+  };
+});
+```
+
+```ts never
+Effect.gen(function* () {
+  const putItem = yield* AWS.DynamoDB.PutItem(table);
+  yield* putItem({ Item: { id: { S: "seed" } } }); // runs at deploy and on every cold start
+  return { fetch: handler };
+});
+```

package/presets/alchemy/runtime/resolve-config-and-bindings-at-construction.md

@@ -0,0 +1,31 @@
+---
+description: In a Worker, Function, or Service, Config values and binding factories must be yielded in the outer construction Effect and captured for the handlers, never yielded for the first time inside fetch or another request handler, which does not run at deploy time, so nothing gets bound.
+---
+
+```ts must
+export default Cloudflare.Worker("Api", { main: import.meta.url },
+  Effect.gen(function* () {
+    const apiKey = yield* Config.Redacted("API_KEY");
+    const bucket = yield* Cloudflare.R2.ReadBucket(Uploads);
+    return {
+      fetch: Effect.gen(function* () {
+        const object = yield* bucket.get("report.json");
+        return HttpServerResponse.text(Redacted.value(apiKey).slice(0, 4));
+      }),
+    };
+  }),
+);
+```
+
+```ts never
+export default Cloudflare.Worker("Api", { main: import.meta.url },
+  Effect.gen(function* () {
+    return {
+      fetch: Effect.gen(function* () {
+        const apiKey = yield* Config.Redacted("API_KEY"); // never bound: API_KEY is missing at runtime
+        return HttpServerResponse.text("ok");
+      }),
+    };
+  }),
+);
+```

package/presets/alchemy/secrets/let-alchemy-mint-infra-secrets.md

@@ -0,0 +1,13 @@
+---
+description: A token the infrastructure owns, such as a webhook secret or bearer token, should be minted once with alchemy's Random or left for alchemy to provision, and should not be a hardcoded literal or regenerated on every deploy with crypto.randomUUID().
+---
+
+```ts should
+export const WebhookSecret = Random("WebhookSecret");
+const auth = yield* BetterAuth({ basePath: "/api/auth", emailAndPassword: { enabled: true } });
+```
+
+```ts should not
+const webhookSecret = crypto.randomUUID(); // a new secret on every deploy
+const auth = yield* BetterAuth({ basePath: "/api/auth", secret: Redacted.make("dev-secret") });
+```

package/presets/alchemy/secrets/never-logged-returned-or-output.md

@@ -0,0 +1,15 @@
+---
+description: A secret, credential, connection string, token, signed URL, or private key must never be logged, returned in an HTTP response, or returned as a stack output; code must expose only names, presence, or non-secret metadata.
+---
+
+```ts must
+if (url.pathname === "/secret") {
+  return yield* HttpServerResponse.json({ name: "API_TOKEN", set: Redacted.value(token).length > 0 });
+}
+return { serial: certificate.serial, expires: certificate.notAfter }; // stack output
+```
+
+```ts never
+yield* Effect.log(`token=${Redacted.value(token)}`);
+return { databaseUrl: connection.databaseUrl, tlsKey: certificate.privateKey }; // stack output
+```

package/presets/alchemy/secrets/none-in-browser-env.md

@@ -0,0 +1,15 @@
+---
+description: A value in an env key that a framework inlines into the browser bundle, such as VITE_, NEXT_PUBLIC_, PUBLIC_, or NUXT_PUBLIC_, must be public configuration, never a secret, credential, or connection string, even wrapped in Redacted.
+---
+
+```ts must
+const site = yield* Cloudflare.Website.Vite("Site", {
+  env: { VITE_API_URL: api.url, STRIPE_SECRET_KEY: Config.Redacted("STRIPE_SECRET_KEY") },
+});
+```
+
+```ts never
+const site = yield* Cloudflare.Website.Vite("Site", {
+  env: { VITE_STRIPE_SECRET_KEY: Config.Redacted("STRIPE_SECRET_KEY"), VITE_DATABASE_URL: branch.connectionUri },
+});
+```

package/presets/alchemy/secrets/redacted-until-use.md

@@ -0,0 +1,19 @@
+---
+description: A secret should be read with Config.Redacted, passed to resources and env as Redacted, and unwrapped with Redacted.value only at the call that needs the raw string; it should not be read with Config.String or process.env, or unwrapped early into plain variables.
+---
+
+```ts should
+const apiKey = yield* Config.Redacted("OPENAI_API_KEY");
+return {
+  fetch: Effect.gen(function* () {
+    const request = HttpClientRequest.post(url).pipe(HttpClientRequest.bearerToken(Redacted.value(apiKey)));
+    return yield* client.execute(request);
+  }),
+};
+```
+
+```ts should not
+const apiKey = Redacted.value(yield* Config.Redacted("OPENAI_API_KEY"));
+const webhook = process.env.SLACK_WEBHOOK_URL!;
+return { fetch: handler(apiKey, webhook) };
+```

package/presets/alchemy/secrets/unwrap-before-compare-or-send.md

@@ -0,0 +1,17 @@
+---
+description: A Redacted value must be unwrapped with Redacted.value before it is compared, sent, or serialized, never put into a template literal, string concatenation, String(), or JSON, where it becomes the literal text <redacted> and silently fails every check.
+---
+
+```ts must
+const expected = yield* Config.Redacted("AUTH_TOKEN");
+if (request.headers.authorization !== `Bearer ${Redacted.value(expected)}`) {
+  return HttpServerResponse.empty({ status: 401 });
+}
+```
+
+```ts never
+const expected = yield* Config.Redacted("AUTH_TOKEN");
+if (request.headers.authorization !== `Bearer ${expected}`) { // compares against "Bearer <redacted>"
+  return HttpServerResponse.empty({ status: 401 });
+}
+```

package/presets/alchemy/security/authorize-public-endpoints.md

@@ -0,0 +1,20 @@
+---
+description: A handler behind a public URL, such as a Function URL, workers.dev route, or a Durable Object chosen by a client-supplied name, must authenticate the caller and check its access before doing protected work, never treating CORS, an obscure URL, or a trusted origin as authorization.
+---
+
+```ts must
+fetch: Effect.gen(function* () {
+  const request = yield* HttpServerRequest.HttpServerRequest;
+  const user = yield* verifySession(request.headers.authorization);
+  if (user === undefined) return HttpServerResponse.empty({ status: 401 });
+  return yield* counters.fetch(user.tenantId, request);
+}),
+```
+
+```ts never
+fetch: Effect.gen(function* () {
+  const request = yield* HttpServerRequest.HttpServerRequest;
+  const name = /^\/counters\/([^/]+)$/.exec(new URL(request.url).pathname)?.[1] ?? "default";
+  return yield* counters.fetch(name, request); // anyone who knows a name can read it
+}),
+```

package/presets/alchemy/security/github-secret-not-variable.md

@@ -0,0 +1,12 @@
+---
+description: A sensitive CI value, such as a token, key, password, or connection string, must be stored with GitHub.Secret, never with GitHub.Variable, which is plain text and visible in logs.
+---
+
+```ts must
+yield* GitHub.Secret("CloudflareToken", { owner, repository, name: "CLOUDFLARE_API_TOKEN", value: token.value });
+yield* GitHub.Variable("AwsRegion", { owner, repository, name: "AWS_REGION", value: "us-east-1" });
+```
+
+```ts never
+yield* GitHub.Variables({ owner, repository, variables: { CLOUDFLARE_API_TOKEN: token.value } });
+```

package/presets/alchemy/security/identity-from-verified-session.md

@@ -0,0 +1,14 @@
+---
+description: The acting user must come from the session or token verified in that request, never from an ID in the request body, query, or headers, and never from a user cached in a process-wide layer.
+---
+
+```ts must
+const session = yield* auth.getSession();
+if (session === null) return yield* Effect.fail(new Unauthorized());
+const rows = yield* sql`SELECT * FROM uploads WHERE owner_id = ${session.user.id}`;
+```
+
+```ts never
+const { ownerId } = yield* HttpServerRequest.schemaBodyJson(Schema.Struct({ ownerId: Schema.String }));
+const rows = yield* sql`SELECT * FROM uploads WHERE owner_id = ${ownerId}`;
+```

package/presets/alchemy/security/keep-auth-protections-on.md

@@ -0,0 +1,19 @@
+---
+description: Auth configuration must keep state, PKCE, origin and CSRF checks, ID-token verification, and email verification enabled, never disable them or merge accounts by email alone to work around an error or a cross-origin setup.
+---
+
+```ts must
+const auth = yield* BetterAuth({
+  trustedOrigins: [siteOrigin],
+  emailAndPassword: { enabled: true, requireEmailVerification: true },
+  account: { accountLinking: { disableImplicitLinking: true } },
+});
+```
+
+```ts never
+const auth = yield* BetterAuth({
+  trustedOrigins: ["*"],
+  advanced: { disableCSRFCheck: true },
+  account: { accountLinking: { trustedProviders: ["github", "google", "company"] } },
+});
+```

package/presets/alchemy/security/least-privilege-bindings.md

@@ -0,0 +1,13 @@
+---
+description: A runtime should bind the narrowest capability its calls need, a Read or Write binding when it only reads or only writes, and should not bind ReadWrite for one-sided use.
+---
+
+```ts should
+const bucket = yield* Cloudflare.R2.ReadBucket(Uploads);
+return { fetch: Effect.gen(function* () { return yield* bucket.get("report.json"); }) };
+```
+
+```ts should not
+const bucket = yield* Cloudflare.R2.ReadWriteBucket(Uploads); // only get is ever called
+return { fetch: Effect.gen(function* () { return yield* bucket.get("report.json"); }) };
+```

package/presets/alchemy/security/least-privilege-ci-credentials.md

@@ -0,0 +1,24 @@
+---
+description: Credentials a stack mints for CI should be scoped to what the app deploys, using a GitHub OIDC role pinned to the repository on AWS and a trimmed permission list on Cloudflare, and should not grant AdministratorAccess or unused write scopes.
+---
+
+```ts should
+const role = yield* AWS.IAM.Role("GitHubDeploy", {
+  assumeRolePolicyDocument: { Version: "2012-10-17", Statement: [{
+    Effect: "Allow", Principal: { Federated: oidc.openIDConnectProviderArn },
+    Action: ["sts:AssumeRoleWithWebIdentity"],
+    Condition: { StringLike: { "token.actions.githubusercontent.com:sub": "repo:acme/app:*" } },
+  }] },
+  policies: [deployPolicy],
+});
+```
+
+```ts should not
+const role = yield* AWS.IAM.Role("GitHubDeploy", {
+  assumeRolePolicyDocument: { Version: "2012-10-17", Statement: [{
+    Effect: "Allow", Principal: { Federated: oidc.openIDConnectProviderArn },
+    Action: ["sts:AssumeRoleWithWebIdentity"],
+  }] },
+  managedPolicyArns: ["arn:aws:iam::aws:policy/AdministratorAccess"],
+});
+```

package/presets/alchemy/security/lookup-failure-is-not-anonymous.md

@@ -0,0 +1,15 @@
+---
+description: Only a null session may be treated as anonymous; a failed session lookup must stay in the error channel or map to a server error, never be collapsed into signed out.
+---
+
+```ts must
+const session = yield* auth.getSession().pipe(
+  Effect.mapError(() => new AuthenticationUnavailable()),
+);
+if (session === null) return yield* Effect.fail(new Unauthorized());
+```
+
+```ts never
+const session = yield* auth.getSession().pipe(Effect.orElseSucceed(() => null));
+if (session === null) return yield* Effect.fail(new Unauthorized());
+```

package/presets/effect/basics/external-calls-are-resilient.md

@@ -1,8 +1,8 @@
 ---
-description: A call over the network, such as an HTTP request, a database query, or a third-party API, must carry a timeout and a retry schedule. Calls through the platform FileSystem and Path services are local and are not in scope.
+description: A call over the network, such as an HTTP request, a database query, or a third-party API, should carry a timeout and a retry schedule, and should not go out bare. A call through a client that already applies both, such as an HttpClient built with a timeout and retryTransient or an SDK with its own retries, has them. Calls through the platform FileSystem and Path services are local and are not in scope.
 ---
 
-```ts must
+```ts should
 const retryPolicy = Schedule.exponential("100 millis").pipe(Schedule.both(Schedule.recurs(3)));
 
 const resilientCall = HttpClient.get("https://api.example.com/users").pipe(
@@ -12,6 +12,6 @@ const resilientCall = HttpClient.get("https://api.example.com/users").pipe(
 );
 ```
 
-```ts never
+```ts should not
 const response = yield* HttpClient.get(`https://api.example.com/users/${id}`);
 ```

package/presets/effect/config/tests-provide-values-directly.md

@@ -1,8 +1,8 @@
 ---
-description: A test must supply config with Layer.succeed on the config service, never by setting environment variables or a ConfigProvider.
+description: A test should supply config with Layer.succeed on the config service, and should not set environment variables or a ConfigProvider to do it.
 ---
 
-```ts must
+```ts should
 Effect.runPromise(
   program.pipe(
     Effect.provide(
@@ -15,7 +15,7 @@ Effect.runPromise(
 );
 ```
 
-```ts never
+```ts should not
 beforeAll(() => {
   process.env.DATABASE_URL = "postgres://localhost/test";
 });

package/presets/effect/config/validate-with-schema.md

@@ -1,5 +1,5 @@
 ---
-description: A config value with constraints must be read with Config.schema, never mapped and checked by hand.
+description: A config value with constraints must be validated as it is read, with Config.schema or Config.mapOrFail, never checked by hand after reading.
 ---
 
 ```ts must
@@ -12,8 +12,19 @@ const Environment = Schema.Literals(["development", "staging", "production"]);
 const program = Effect.gen(function* () {
   const port = yield* Config.schema(Port, "PORT");
   const env = yield* Config.schema(Environment, "ENV");
+  const timeoutMs = yield* Config.int("TIMEOUT_MS").pipe(
+    Config.mapOrFail((ms) =>
+      ms > 0 && ms <= 60_000
+        ? Effect.succeed(ms)
+        : Effect.fail(
+            new Config.ConfigError(
+              new ConfigProvider.SourceError({ message: "TIMEOUT_MS must be 1 to 60000" }),
+            ),
+          ),
+    ),
+  );
 
-  return { port, env };
+  return { port, env, timeoutMs };
 });
 ```
 

package/presets/effect/data/variants-are-tagged-unions.md

@@ -1,5 +1,5 @@
 ---
-description: Structured variants must be Schema.TaggedClass in a Schema.Union, matched with Match.tag and Match.exhaustive, never a plain union checked with a switch.
+description: Structured variants, alternatives that carry fields, must be Schema.TaggedClass members of a Schema.Union, never hand-written object types joined by a tag field. Simple alternatives without fields may be Schema.Literals.
 ---
 
 ```ts must

package/presets/effect/services/dependencies-through-layers.md

@@ -0,0 +1,42 @@
+---
+description: A service that depends on other services must be a Context.Service built by a Layer that yields those services as it is constructed, never a factory function or class that takes services, clients, or their implementations as arguments.
+---
+
+```ts must
+class Users extends Context.Service<
+  Users,
+  {
+    readonly find: (id: UserId) => Effect.Effect<User, UserNotFound>;
+  }
+>()("@app/Users") {}
+
+export const UsersLive = Layer.effect(
+  Users,
+  Effect.gen(function* () {
+    const database = yield* Database;
+    const logger = yield* Logger;
+    return Users.of({
+      find: (id) =>
+        Effect.gen(function* () {
+          yield* logger.log(`finding ${id}`);
+          return yield* database.findUser(id);
+        }),
+    });
+  }),
+);
+```
+
+```ts never
+export const makeUsers = (database: Database["Service"], logger: Logger["Service"]) => ({
+  find: (id: UserId) =>
+    Effect.gen(function* () {
+      yield* logger.log(`finding ${id}`);
+      return yield* database.findUser(id);
+    }),
+});
+
+export const program = Effect.gen(function* () {
+  const users = makeUsers(yield* Database, yield* Logger);
+  return yield* users.find(userId);
+});
+```

package/presets/effect/services/operations-have-no-requirements.md

@@ -0,0 +1,46 @@
+---
+description: A service's operations must have no requirements, typed Effect<A, E, never>, with their dependencies acquired when the service's Layer is built, never left in an operation's requirements type, as in Effect<A, E, Database>.
+---
+
+```ts must
+class Users extends Context.Service<
+  Users,
+  {
+    readonly find: (id: UserId) => Effect.Effect<User, UserNotFound, never>;
+  }
+>()("@app/Users") {}
+
+export const UsersLive = Layer.effect(
+  Users,
+  Effect.gen(function* () {
+    const database = yield* Database;
+    const logger = yield* Logger;
+    return Users.of({
+      find: (id) =>
+        Effect.gen(function* () {
+          yield* logger.log(`finding ${id}`);
+          return yield* database.findUser(id);
+        }),
+    });
+  }),
+);
+```
+
+```ts never
+class Users extends Context.Service<
+  Users,
+  {
+    readonly find: (id: UserId) => Effect.Effect<User, UserNotFound, Database | Logger>;
+  }
+>()("@app/Users") {}
+
+export const UsersLive = Layer.succeed(Users, {
+  find: (id) =>
+    Effect.gen(function* () {
+      const database = yield* Database;
+      const logger = yield* Logger;
+      yield* logger.log(`finding ${id}`);
+      return yield* database.findUser(id);
+    }),
+});
+```

package/presets/effect/services/test-layers-are-in-memory.md

@@ -1,8 +1,8 @@
 ---
-description: A test implementation of a service must be built with Layer.sync or Layer.succeed over in-memory state, never over a real database, network, or file.
+description: A test implementation of a service should be built with Layer.sync or Layer.succeed over in-memory state, and should not reach a real database, network, or file. Integration tests that exercise the real service are not in scope.
 ---
 
-```ts must
+```ts should
 static readonly testLayer = Layer.sync(Cache, () => {
   const store = new Map<string, string>()
 
@@ -13,7 +13,7 @@ static readonly testLayer = Layer.sync(Cache, () => {
 })
 ```
 
-```ts never
+```ts should not
 const EmailTest = Layer.effect(
   Email,
   Effect.gen(function* () {