@drkmttr/adhere 0.7.3 → 0.9.0

package/README.md

@@ -8,9 +8,10 @@ model) whether the file breaks each rule, gets a calibrated probability per
 rule, and reports the ones above a threshold with the line Jev points at. The
 report uses the same frame as `vp lint`.
 
-Deterministic rules (substring matches, type checks) belong in a normal linter.
+Deterministic rules (substring matches, type checks) belong in a normal linter;
+`adhere validate` points out a rule that looks like one.
 
-A preset for effect is included which can be run without setup: 
+A preset for effect is included which can be run without setup:
 
 ```sh
 TYPESAFE_API_KEY=xxx npx @drkmttr/adhere lint --preset effect
@@ -36,20 +37,25 @@ with a TypeSafe AI API key: the one `adhere login` saved, or
 
 ```sh
 adhere init                          # .adhere/config.ts and two example rules
-echo ".adhere/cache/" >> .gitignore
 adhere login                         # save your TypeSafe AI API key, once
-adhere validate                      # Checks your rules for contradictions using Jev
+adhere validate                      # Checks your rules' wording, and contradictions using Jev
 adhere lint                          # audit the working directory
+git add .adhere                      # commit the rules, and the judgments they cost
 ```
 
 Without a config or rules, `adhere lint --preset effect` audits against the
 built-in Effect rules. A finding looks like this:
 
 ```text
-  × data/brand-ports (0.93): A port is a branded, range-checked integer, not a bare number.
-   ╭─[src/server.ts:4:1]
- 4 │ const port: number = Number(process.env.PORT ?? 3000);
-   · ──────────────────────────────────────────────────────
+  × data/brand-ports (0.93): A port must be a branded, range-checked integer, never a bare number.
+   ╭─[src/server.ts:6:3]
+ 4 │ export const serve = Effect.gen(function* () {
+ 5 │   const host = process.env.HOST ?? "localhost";
+ 6 │   const port: number = Number(process.env.PORT ?? 3000);
+   ·   ──────────────────────────────────────────────────────
+ 7 │   yield* listen({ host, port });
+ 8 │   yield* Effect.log(`Listening on ${host}:${port}`);
+ 9 │ });
    ╰────
   hint: const Port = Schema.Int.pipe(
           Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
@@ -60,7 +66,10 @@ Found 1 error.
 42 files, 3 judged, 39 cached.
 ```
 
-The header is the rule id, Jev's probability, and the rule's description. The
+The header is the rule id, Jev's probability, and the rule's description.
+Under it is the line Jev points at, underlined, with the code around it: the
+largest statement around the line that is 30 lines or fewer, usually the whole
+function, and up to 3 lines of whole statements on either side. The
 hint is the rule's code that must be written; a rule with only code that must
 never be written shows that code, labeled `never:`, instead. On a terminal, the report is in color and the code
 in it is highlighted. The exit code is 0 when nothing is reported and 1 when
@@ -78,7 +87,8 @@ adhere lint --yes              # send the requests without asking first
 adhere lint --limit 500        # judge at most 500 checks; the rest wait for the next run
 adhere lint --rpm 30           # send at most 30 requests a minute
 adhere lint --filter 'src/**'  # read only the files a glob matches
-adhere validate                # load the config and rules, ask Jev whether any contradict
+adhere lint --log-level debug  # log each request to Jev on stderr
+adhere validate                # check the rules' wording; ask Jev whether any contradict
 adhere init [--force]          # scaffold .adhere/config.ts and two example rules
 adhere login                   # save a TypeSafe AI API key for later runs
 adhere logout                  # delete the saved key
@@ -129,6 +139,22 @@ more, and start a pattern with `!` to leave out what it matches. Together:
 adhere lint --filter 'packages/api/**' --filter '!**/generated/**' --limit 200 --rpm 30
 ```
 
+### Logging a run
+
+`--log-level debug` logs a run's work on stderr: the config it loaded, how many
+paths it listed and how many of them it reads, and each request to Jev, with
+the file it is for, about how many tokens it carries, the HTTP status, how long
+it took, and Cloudflare's Ray ID. A failed attempt is logged even when a retry
+hides it. `--log-level trace` adds each file as it is read, planned, and
+answered from the cache, and the first 4000 characters of any error Jev's API
+answers with. The counter stays off at these levels, since its redraws would
+garble the lines, and stdout still carries only the report, so the log can go
+to a file of its own:
+
+```sh
+adhere lint --log-level debug 2> adhere.log
+```
+
 ### What gets read
 
 `adhere lint` reads the `.ts` files under the working directory, except `.d.ts`,
@@ -150,16 +176,45 @@ kept, and no second one is added, even with `--force`.
 
 `adhere validate` loads the config, rule files, and presets the way `lint`
 does, so a file that fails to decode refuses here too, and it prints how many
-rules it loaded. `--preset` adds a built-in rule set, as for `lint`. It then
-asks Jev whether any two rules that apply to the same files contradict, so that
-no code can follow both: one request names, per rule, the rule it conflicts
-with, if any, and each named pair then gets a probability from a request of
-its own, holding only those two rules, since other rules beside them dilute
-the judgment. A pair above
-the threshold is printed with both rule files, and the exit code is 1. Two
-rules with the same id are not compared: a nested rule that shares an id
-shadows the other on purpose. When no two rules share files nothing is sent;
-otherwise `validate` needs the API key, as `lint` does.
+rules it loaded. `--preset` adds a built-in rule set, as for `lint`.
+
+Next it checks each rule's wording against the
+[rule writing tips](#rule-writing-tips), which sends nothing, and prints each
+rule worded otherwise with its file and how:
+
+- its description does not say a word its code is under, such as "never"
+  beside a `never` block;
+- it has code to write but no example of code that breaks it;
+- its description says the other kind of rule's words: "should" in a
+  requirement, or "must" or "never" in a guideline.
+
+A rule with only code that must never be written needs no `must` example, as
+[Rules as Markdown files](#rules-as-markdown-files) explains. The tips are
+advice, so the wording does not change the exit code.
+
+Then it reports the linter check, which also sends nothing. While `lint`
+judges a file against one of the project's own rules, it asks Jev a second
+question beside it: should the rule have been checked by a regular linter, that
+is, could a linter or type checker have decided exactly whether this file
+follows it? It asks on 10 files per rule, spread over the files it judges, and
+keeps the answers in the cache until the rule's text changes. `validate` prints
+each rule flagged on 7 or more of its 10 files as one a regular linter should
+probably check, and each flagged on 3 to 6 as a rule that reads differently
+from file to file, whose description should say more precisely what it
+applies to. A rule with fewer than 10 answers is counted as waiting; `lint`
+collects them as it judges files, so a repo whose files are all cached collects
+them as its files change. Preset rules are left out: they are not the
+project's to change. The linter check is advice too.
+
+It then asks Jev whether any two rules that apply to the same files
+contradict, so that no code can follow both: one request names, per rule, the
+rule it conflicts with, if any, and each named pair then gets a probability
+from a request of its own, holding only those two rules, since other rules
+beside them dilute the judgment. A pair above the threshold is printed with
+both rule files, and the exit code is 1. Two rules with the same id are not
+compared: a nested rule that shares an id shadows the other on purpose. When
+no two rules share files nothing is sent; otherwise `validate` needs the API
+key, as `lint` does.
 
 ### Login
 
@@ -309,17 +364,73 @@ violations with the fewest false positives. In general:
 
 On the Effect preset, rules written this way cut the findings Jev got wrong at
 the default threshold from 6 to 1, and caught as many violations. For more
-about the evaluations, see [the eval](eval/README.md).
+about the evaluations, see [the eval](eval/README.md). `adhere validate` lists
+each rule worded otherwise.
 
 ### Presets
 
 A preset has the shape of a config without `presets`: `rules`, and optionally
-`model` and `threshold`. `effect` is the one preset: 26 Markdown rules in
-[`presets/effect/`](./presets/effect/), lifted from the
-[effect-solutions](https://github.com/kitlangton/effect-solutions) docs and the
-[effect/platform](https://effect.website/docs/platform/introduction/) docs.
-Name it in the config, or on the command line with `--preset effect`, in which
-case the config file is optional.
+`model` and `threshold`. Name one in the config, or on the command line with
+`--preset`, in which case the config file is optional. There are two:
+
+- `effect`: Markdown rules in [`presets/effect/`](./presets/effect/), lifted
+  from the [effect-solutions](https://github.com/kitlangton/effect-solutions)
+  docs and the
+  [effect/platform](https://effect.website/docs/platform/introduction/) docs.
+- `alchemy`: 43 rules in [`presets/alchemy/`](./presets/alchemy/) for code that
+  deploys with [alchemy](https://alchemy.run), lifted from its docs and blog:
+  where Config and bindings are read, which resources keep their data, how
+  secrets stay out of bundles and logs, authorization on public URLs,
+  migrations, durable workflows, and custom providers.
+
+Each preset divides into topics, its subdirectories, and a topic is a preset
+of its own: `--preset effect/basics` applies only the rules under
+`presets/effect/basics/`, and `alchemy/secrets` only alchemy's secrets rules.
+A topic's rules keep the ids they have in the whole preset, so a topic and its
+preset share cached judgments, and naming both applies each rule once.
+
+A preset rule says "must" only where its source makes a requirement, and
+"should" where the source gives advice. In `effect`, three rules are
+guidelines: network calls carry a timeout and a retry schedule, unless their
+client already applies both; test layers are in memory, outside integration
+tests; and tests provide config through a layer. Config validation accepts
+`Config.mapOrFail` as well as `Config.schema`, and the variants rule does not
+rule out a `switch`. The rule that a command handler only parses input is
+gone: the docs show that pattern but do not ask for it.
+
+The preset leaves out conventions a linter checks exactly. Effect's language
+service, [`@effect/tsgo`](https://github.com/Effect-TS/tsgo) on TypeScript 7,
+checks these seven, which the preset checked through 0.7. Most are off by
+default; `npx @effect/tsgo setup` installs it, and these lines in its plugin
+options in `tsconfig.json` turn them on:
+
+```jsonc
+"diagnosticSeverity": {
+  "strictEffectProvide": "warning", // layers are provided once, at the entry point
+  "leakingRequirements": "warning", // service methods have no requirements
+  "effectFnOpportunity": "warning", // a named function returning an Effect uses Effect.fn
+  "preferSchemaOverJson": "warning", // JSON is decoded with Schema, not JSON.parse
+  "nodeBuiltinImport": "warning", // platform services, not node: builtins
+  "globalFetch": "warning",
+  "globalFetchInEffect": "warning",
+  "processEnv": "warning",
+  "processEnvInEffect": "warning",
+  "globalRandom": "warning", // the Random service, not Math.random
+  "globalRandomInEffect": "warning",
+  "globalErrorInEffectFailure": "warning", // tagged errors, not Error
+  "extendsNativeError": "warning"
+}
+```
+
+`npx @effect/tsgo diagnostics --project tsconfig.json` runs them in CI. Bun
+globals, which the old platform rule also ruled out, need a lint rule of their
+own, such as `no-restricted-globals`.
+
+`leakingRequirements` sees a requirement in an operation's type, but not a
+service built by a factory function that takes its dependencies as arguments,
+whose types have no requirements to find. The preset's
+`services/dependencies-through-layers` asks for that, and
+`services/operations-have-no-requirements` for the style it goes with.
 
 ### Precedence
 
@@ -340,7 +451,9 @@ beats all of the above for that rule.
    at the rule's scope, so a file with no code the rule is about is a no. Since
    no rule sits in the shared state, a rule's probability depends only on the
    file and that rule, not on which other rules share the request. Every
-   question shares the state cost of the request.
+   question shares the state cost of the request. On up to 10 files per
+   project rule, the rule's question has a second one beside it, the linter
+   check (see [Validate](#validate)), with the same fields.
 2. A second request only when at least one rule's probability is above its
    threshold: one `choice` question per flagged rule over the file's non-blank
    lines, which yields the line to report. A file with more than 255 non-blank
@@ -356,15 +469,42 @@ beats all of the above for that rule.
 
 ## Cache
 
-Judgments are cached in `.adhere/cache/` (add it to `.gitignore`), one entry
-per file. An entry stores the file's content hash and, per rule, the
-probability, the located line, and a fingerprint of the model and the
-question asked for the rule, which carries the rule's text. A changed file
-re-judges every rule for that file. An edited rule re-judges only that rule,
-and an adhere that asks its questions differently re-judges every rule once.
-A lowered threshold locates cached judgments that are newly above it without
-judging again. Entries depend on content, not on the
-machine, so restoring `.adhere/cache/` between CI runs skips unchanged files.
+Judgments are cached in `.adhere/cache/`. Commit it. Every judgment is a paid
+request, and Jev's answers vary a little from run to run, so a committed cache
+gives everyone and CI the same findings without paying for them again, and a
+pull request changes the judgments of only the files it changes.
+
+`files/` holds Jev's answers by the content they are about: each cache file is
+named for the hash of a source file's content, so a moved or copied file keeps
+its judgments, and identical files share them. Each answer sits under a
+fingerprint of the model and the question asked for the rule, which carries
+the rule's text. A changed file re-judges every rule for that file. An edited
+rule re-judges only that rule, and an adhere that asks its questions
+differently re-judges every rule once. A lowered threshold locates cached
+judgments that are newly above it without judging again. `tallies/` keeps the
+linter check's answers, one tally per rule, under a key that changes with the
+rule's text and the model.
+
+A cache file is written once and never changed: it is also named for the hash
+of its own text. Two branches that judge the same code add files rather than
+edit them, so git merges the cache without a conflict. After a run that reads
+every file, adhere prunes the cache: it deletes answers about content no file
+has and answers to rule texts no rule asks, and folds what is left into one
+file per content. A run narrowed by `--filter` does not prune. To keep the
+cache out of diffs, mark it as generated in `.gitattributes`:
+
+```text
+.adhere/cache/** linguist-generated -diff
+```
+
+Anyone who can commit can also write a cache file saying that code passes.
+Where lint gates a merge, lint a pull request against the cache as merged,
+not as the pull request has it; only the files it changes are judged again:
+
+```sh
+rm -rf .adhere/cache && git checkout origin/main -- .adhere/cache
+adhere lint --yes
+```
 
 The API key is read only when a request is about to be sent. A run where
 every file is cached needs no key and no network.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -11,6 +11,12 @@
   "bin": {
     "adhere": "bin/adhere.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "presets",
+    "skills"
+  ],
   "type": "module",
   "imports": {
     "#*": "./src/*"
@@ -18,12 +24,6 @@
   "exports": {
     ".": "./src/index.ts"
   },
-  "files": [
-    "bin",
-    "src",
-    "presets",
-    "skills"
-  ],
   "publishConfig": {
     "access": "public"
   },
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.7.3",
-    "@drkmttr/adhere-darwin-x64": "0.7.3",
-    "@drkmttr/adhere-linux-arm64": "0.7.3",
-    "@drkmttr/adhere-linux-x64": "0.7.3",
-    "@drkmttr/adhere-win32-x64": "0.7.3"
+    "@drkmttr/adhere-darwin-arm64": "0.9.0",
+    "@drkmttr/adhere-darwin-x64": "0.9.0",
+    "@drkmttr/adhere-linux-arm64": "0.9.0",
+    "@drkmttr/adhere-linux-x64": "0.9.0",
+    "@drkmttr/adhere-win32-x64": "0.9.0"
   }
 }

package/presets/alchemy/apis/match-remote-errors-by-tag.md

@@ -0,0 +1,15 @@
+---
+description: Errors that crossed RPC or a workflow replay must be matched by their tag and data fields, never with instanceof, prototype methods, or object identity, which do not survive serialization, and RPC arguments must be serializable values, never functions or class instances.
+---
+
+```ts must
+const value = yield* stub.get(key).pipe(
+  Effect.catchTag("KeyMissing", (error) => Effect.succeed(`missing: ${error.key}`)),
+);
+```
+
+```ts never
+const value = yield* stub.get(key).pipe(
+  Effect.catchAll((error) => (error instanceof KeyMissing ? Effect.succeed("missing") : Effect.fail(error))),
+);
+```

package/presets/alchemy/apis/schemas-at-trust-boundaries.md

@@ -0,0 +1,18 @@
+---
+description: Input from outside the stack, such as browsers, partners, or public URLs, should be validated with a schema through Effect RPC or HttpApi, while calls between the stack's own runtimes should use schemaless RPC through bindings, and unvalidated payloads should not cross a trust boundary.
+---
+
+```ts should
+const Tasks = HttpApiGroup.make("tasks").add(
+  HttpApiEndpoint.post("create", "/tasks", { payload: Schema.Struct({ title: Schema.String }) }),
+);
+const greeter = yield* Cloudflare.Workers.bindWorker(Greeter); // internal call
+```
+
+```ts should not
+fetch: Effect.gen(function* () {
+  const request = yield* HttpServerRequest.HttpServerRequest;
+  const body = (yield* request.json) as { title: string; ownerId: string }; // public URL, no validation
+  return yield* store.create(body);
+}),
+```

package/presets/alchemy/data/commit-migrations-then-deploy.md

@@ -0,0 +1,15 @@
+---
+description: Migrations must be generated and reviewed ahead of time, committed with the schema, and applied from the committed files; a deploy, deploy hook, or Action must never generate migration SQL, and schema changes must never run from an HTTP route.
+---
+
+```ts must
+// package.json: "db:generate": "drizzle-kit generate" (run locally, then commit ./drizzle)
+const db = yield* Cloudflare.D1.Database("AppDb", { migrations: "./drizzle" });
+```
+
+```ts never
+// package.json: "deploy": "drizzle-kit generate && alchemy deploy"
+fetch: Effect.gen(function* () {
+  if (url.pathname === "/setup") yield* sql`CREATE TABLE users (id text primary key)`;
+}),
+```

package/presets/alchemy/data/hyperdrive-direct-origin.md

@@ -0,0 +1,14 @@
+---
+description: A Hyperdrive connection's origin should be the database's direct endpoint, and clients that connect without Hyperdrive should use the provider's pooled endpoint; Hyperdrive should not point at a provider pooler, which stacks two poolers.
+---
+
+```ts should
+const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("AppHyperdrive", {
+  origin: branch.origin,
+  dev: branch.pooledOrigin,
+});
+```
+
+```ts should not
+const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("AppHyperdrive", { origin: role.pooledOrigin });
+```

package/presets/alchemy/data/migrations-use-direct-url.md

@@ -0,0 +1,11 @@
+---
+description: A migration runner must connect with the database's direct URL, never Hyperdrive's runtime connection string or an Accelerate or pooled URL.
+---
+
+```ts must
+export default defineConfig({ dialect: "postgresql", dbCredentials: { url: process.env.DIRECT_DATABASE_URL! } });
+```
+
+```ts never
+export default defineConfig({ dialect: "postgresql", dbCredentials: { url: process.env.ACCELERATE_URL! } });
+```

package/presets/alchemy/data/never-disable-tls-verification.md

@@ -0,0 +1,16 @@
+---
+description: A database client or migration config must verify the server's TLS certificate, or connect inside the private network, never setting rejectUnauthorized: false or sslmode=no-verify to make a connection work.
+---
+
+```ts must
+const url = new URL(connection.connectionString);
+url.searchParams.set("sslmode", "verify-full");
+const db = yield* Drizzle.Postgres(url.toString());
+```
+
+```ts never
+export default defineConfig({
+  dialect: "postgresql",
+  dbCredentials: { url: process.env.DATABASE_URL!, ssl: { rejectUnauthorized: false } },
+});
+```

package/presets/alchemy/data/parameterized-sql.md

@@ -0,0 +1,13 @@
+---
+description: SQL must pass values as parameters, through tagged-template interpolation, sql.in, sql.insert, or prepare().bind(), never by string concatenation or a template string handed to an unsafe or raw API.
+---
+
+```ts must
+const user = yield* sql`SELECT * FROM users WHERE email = ${email}`;
+const row = yield* Effect.promise(() => d1.prepare("SELECT * FROM users WHERE id = ?").bind(id).first());
+```
+
+```ts never
+const user = yield* sql.unsafe(`SELECT * FROM users WHERE email = '${email}'`);
+const row = yield* Effect.promise(() => d1.prepare("SELECT * FROM users WHERE id = " + id).first());
+```

package/presets/alchemy/data/private-endpoint-at-runtime.md

@@ -0,0 +1,12 @@
+---
+description: Service code should reach its database through the bound private connection, and should not use the public connection URI or TCP proxy, which is meant for laptops and CI.
+---
+
+```ts should
+const conn = yield* Railway.ConnectPostgres(Db);
+const db = yield* Drizzle.Postgres(conn.connectionString);
+```
+
+```ts should not
+const db = yield* Drizzle.Postgres(Db.publicConnectionUri);
+```

package/presets/alchemy/data/single-migration-owner.md

@@ -0,0 +1,13 @@
+---
+description: Each database must have one migration owner: when a resource's migrations prop applies the directory, scripts and CI must never also run drizzle-kit migrate or prisma migrate against the same database.
+---
+
+```ts must
+const branch = yield* Neon.Branch("Main", { project, migrations: "./migrations" });
+// package.json: "deploy": "alchemy deploy"
+```
+
+```ts never
+const branch = yield* Neon.Branch("Main", { project, migrations: "./migrations" });
+// package.json: "deploy": "drizzle-kit migrate && alchemy deploy"
+```

package/presets/alchemy/durable/idempotent-event-handlers.md

@@ -0,0 +1,15 @@
+---
+description: A handler for events delivered at least once, such as Stripe webhooks, scheduled callbacks, or bucket and queue events, must be idempotent, upserting by a stable ID or deduplicating by event ID, never doing blind inserts, increments, or charges.
+---
+
+```ts must
+yield* Stripe.consumeEvents([CustomerSubscriptionUpdated], (event) =>
+  kv.put(`entitlement:${event.data.object.customer}`, JSON.stringify(entitlementOf(event))),
+);
+```
+
+```ts never
+yield* Stripe.consumeEvents([InvoicePaid], (event) =>
+  sql`UPDATE accounts SET credits = credits + 100 WHERE customer = ${event.data.object.customer}`,
+);
+```

package/presets/alchemy/durable/io-inside-steps.md

@@ -0,0 +1,17 @@
+---
+description: In a Workflow or Durable Function, every side effect, such as an HTTP call, binding call, or write, must run inside a task or step, and code outside steps must be deterministic, never doing I/O or reading the clock or randomness, because the body replays.
+---
+
+```ts must
+export default Cloudflare.Workflow("Notify", Effect.fn(function* (input: { roomId: string; message: string }) {
+  const stored = yield* Cloudflare.Workflows.task("store", kv.put(`notify:${input.roomId}`, input.message));
+  yield* Cloudflare.Workflows.sleep("cooldown", "30 seconds");
+  return stored;
+}));
+```
+
+```ts never
+export default Cloudflare.Workflow("Notify", Effect.fn(function* (input: { roomId: string; message: string }) {
+  yield* kv.put(`notify:${input.roomId}:${Date.now()}`, input.message); // repeats on every replay
+}));
+```

package/presets/alchemy/durable/no-self-triggering-bucket-writes.md

@@ -0,0 +1,15 @@
+---
+description: A bucket-event handler that writes back into the bucket it listens to should filter its subscription by prefix or suffix so its own writes do not match, and should not subscribe to every object created in that bucket.
+---
+
+```ts should
+yield* AWS.S3.consumeBucketEvents(bucket, { events: ["s3:ObjectCreated:*"], prefix: "incoming/" }, (stream) =>
+  stream.pipe(Stream.runForEach((event) => putObject({ Key: `processed/${event.key}`, Body: "..." }))),
+);
+```
+
+```ts should not
+yield* AWS.S3.consumeBucketEvents(bucket, { events: ["s3:ObjectCreated:*"] }, (stream) =>
+  stream.pipe(Stream.runForEach((event) => putObject({ Key: `processed/${event.key}`, Body: "..." }))), // triggers itself
+);
+```

package/presets/alchemy/durable/stable-step-names.md

@@ -0,0 +1,11 @@
+---
+description: Workflow task, sleep, and waitForEvent names are replay keys, so they must be stable across replays, never built from the clock, randomness, or other values that change between runs.
+---
+
+```ts must
+yield* Cloudflare.Workflows.task("charge-card", chargeCard(input.orderId));
+```
+
+```ts never
+yield* Cloudflare.Workflows.task(`charge-${Date.now()}`, chargeCard(input.orderId));
+```

package/presets/alchemy/durable/webhook-state-is-truth.md

@@ -0,0 +1,14 @@
+---
+description: Access to paid features must be gated on state recorded from Stripe webhooks in the app's own store, never granted because the user reached a success_url or return_url.
+---
+
+```ts must
+const entitlement = yield* kv.get(`entitlement:${customerId}`);
+if (entitlement === null) return HttpServerResponse.empty({ status: 402 });
+```
+
+```ts never
+if (url.pathname === "/welcome") {
+  yield* kv.put(`entitlement:${customerId}`, "active"); // reached the success URL, not paid
+}
+```

package/presets/alchemy/providers/diff-guards-unresolved-props.md

@@ -0,0 +1,16 @@
+---
+description: A custom provider's diff must check isResolved(news) and return undefined before comparing props that may still be unresolved Outputs, never comparing them directly.
+---
+
+```ts must
+diff: Effect.fn(function* ({ news, olds }) {
+  if (!isResolved(news)) return undefined;
+  if (news.region !== olds.region) return { action: "replace" } as const;
+}),
+```
+
+```ts never
+diff: Effect.fn(function* ({ news, olds }) {
+  if (news.region !== olds.region) return { action: "replace" } as const;
+}),
+```

package/presets/alchemy/providers/idempotent-delete.md

@@ -0,0 +1,14 @@
+---
+description: A custom provider's delete must treat a resource that is already gone as success, catching the not-found error, never failing when it runs again.
+---
+
+```ts must
+delete: ({ output }) =>
+  Effect.tryPromise(() => stripe.products.del(output.productId)).pipe(
+    Effect.catchIf(isNotFound, () => Effect.void),
+  ),
+```
+
+```ts never
+delete: ({ output }) => Effect.promise(() => stripe.products.del(output.productId)),
+```

package/presets/alchemy/providers/lazy-layer-construction.md

@@ -0,0 +1,14 @@
+---
+description: A custom provider, credentials, or state-store Layer must defer resolving credentials and opening connections until an operation runs, never resolving credentials, connecting, or prompting while the Layer is built, because every CLI command builds it.
+---
+
+```ts must
+export const PostgresState = Layer.effect(State, Effect.cached(makePostgresState(props)));
+```
+
+```ts never
+export const PostgresState = Layer.effect(State, Effect.gen(function* () {
+  const sql = postgres(process.env.DATABASE_URL!); // connects on every CLI command
+  return makeState(sql);
+}));
+```

package/presets/alchemy/providers/reconcile-from-observed-state.md

@@ -0,0 +1,20 @@
+---
+description: A custom provider's reconcile must read the resource's live state and converge it in one flow that serves create, update, and adoption, never branching into separate create and update bodies on output === undefined or trusting olds as proof the resource exists.
+---
+
+```ts must
+reconcile: Effect.fn(function* ({ news, output }) {
+  let live = yield* observe(output);
+  if (live === undefined) live = yield* create(news);
+  if (drifted(live, news)) live = yield* update(live.id, news);
+  return toAttributes(live);
+}),
+```
+
+```ts never
+reconcile: Effect.fn(function* ({ news, olds, output }) {
+  if (output === undefined) return yield* create(news);
+  yield* updateTags(output.id, olds.tags, news.tags);
+  return output;
+}),
+```

package/presets/alchemy/resources/anchor-paths-with-import-meta.md

@@ -0,0 +1,14 @@
+---
+description: A path prop such as main or rootDir on a resource declared outside the directory alchemy runs from must be anchored to the declaring file with import.meta, never given as a bare relative string, which resolves from the root instead.
+---
+
+```ts must
+// backend/src/api.ts
+export default Cloudflare.Worker("Api", { main: import.meta.url }, program);
+export const Site = Cloudflare.Website.Vite("Site", { rootDir: path.resolve(import.meta.dirname, "../frontend") });
+```
+
+```ts never
+// backend/src/api.ts
+export default Cloudflare.Worker("Api", { main: "src/api.ts" }, program); // resolves to <root>/src/api.ts
+```