@drkmttr/adhere 0.17.5 → 0.18.0

package/README.md

@@ -572,11 +572,42 @@ finding its matchers dropped, with their scores.
 
 Beside the file's code, Jev reads three kinds of context, for every rule:
 
-| Name                | What Jev reads                                                                                                                                                                     |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `workspacePackages` | The repo's own packages the file imports, each name with its directory, as in `{ "orders-core": "packages/orders" }`. A package it imports that is not listed is an installed one. |
-| `symbols`           | The compiler's type blocks for each name, plus compiler documentation and JSDoc tags; not literal editor hover text.                                                               |
-| `references`        | The declaration of each name the file uses from another file of the repo, whole: a function with its body, a method without the rest of its class.                                 |
+| Name                | What Jev reads                                                                                                                                                                              |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `workspacePackages` | The repo's own packages the file imports, each name with its directory, as in `{ "orders-core": "packages/orders" }`. A package it imports that is not listed is an installed one.          |
+| `symbols`           | The compiler's type blocks for each name, plus compiler documentation and JSDoc tags; not literal editor hover text.                                                                        |
+| `references`        | Whole declarations of symbols the code uses from other files of the repo, keyed by `symbol:repository-relative pathname`: a function with its body, a method without the rest of its class. |
+
+`symbols` omits standard-library and Node/Bun runtime built-ins, including their
+methods. Project and third-party symbols remain, even when they share a built-in
+name. Built-in type names can still appear inside those symbols' type signatures.
+
+`references` is a flat string-to-string map. Keys keep the symbol's name as used
+in the target code, including import aliases, and the pathname's original casing.
+Values are complete declaration excerpts, not incoming reference call sites.
+Overlapping declarations under one key are merged; disjoint excerpts are joined
+with `…` between them. For example, code importing `twice as scale` can receive:
+
+```json
+{
+  "references": {
+    "__comment": "Declarations of symbols used by the target code, provided only as context. Keys are symbol:repository-relative pathname; values are source excerpts, not incoming call sites.",
+    "scale:src/Math.ts": "export function twice(value: number): number {\n  return value * 2;\n}"
+  }
+}
+```
+
+When sent to Jev, each selected `references`, `symbols`, and `workspacePackages`
+map includes a reserved `__comment` explaining its contents. These comments are
+included before `appendState` hooks and restored after hooks. Top-level guidance
+also tells Jev that these maps are context only: judge the target `code`, not the
+additional declarations or metadata.
+
+Each symbol's complete resolved content is truncated to 256 characters by
+default. Set `maxSymbolLength` in the config to change this limit. Documentation
+and JSDoc tags are first capped separately by `maxSymbolDocumentationLength`, also
+256 by default; `0` omits documentation and tags. Smaller limits reduce request
+size but can cut off type signatures, overloads, useful details, or examples.
 
 To read fewer, list the ones you want in the config's `reads`:
 
@@ -750,6 +781,8 @@ export default defineConfig({
   sufficiencyThreshold: 0.6,
   reads: ["workspacePackages", "symbols", "references"],
   presets: ["effect"],
+  maxSymbolDocumentationLength: 256,
+  maxSymbolLength: 256,
   exclude: ["**/generated/**"],
   overrides: { "effect/basics/instrument-with-pipe": "off" },
   rules: {
@@ -767,18 +800,20 @@ type UserId = typeof UserId.Type
 });
 ```
 
-| Key                    | Default                                          | Meaning                                                                                                                                                                |
-| ---------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `model`                | `"jev-latest"`                                   | The model id sent to TypeSafe.                                                                                                                                         |
-| `threshold`            | `0.8`                                            | Report a rule when Jev's probability is above this.                                                                                                                    |
-| `sufficiencyThreshold` | `0.6`                                            | Below it, a finding warns that Jev may not see enough to decide.                                                                                                       |
-| `presets`              | none                                             | Built-in rule sets, or their topics. See [Presets](#presets).                                                                                                          |
-| `rules`                | `.adhere/rules/`                                 | Rules inline, as above, or a directory (see [Where rules live](#where-rules-live)). Either replaces `.adhere/rules/`: none of its rules, root or nested, is read then. |
-| `exclude`              | none                                             | Globs, relative to the working directory, of files no rule judges.                                                                                                     |
-| `overrides`            | none                                             | Settings for a rule by its id. See [Overrides](#overrides).                                                                                                            |
-| `includeComments`      | `false`                                          | Send every comment to Jev. See [Comments](#comments).                                                                                                                  |
-| `reads`                | `["workspacePackages", "symbols", "references"]` | What Jev reads beside each file's code, for every rule. `[]` is the code alone. See [What Jev reads](#what-jev-reads).                                                 |
-| `provider`             | TypeSafe's Jev                                   | Where the questions go instead, with its own model. See [Providers](#providers).                                                                                       |
+| Key                            | Default                                          | Meaning                                                                                                                                                                |
+| ------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`                        | `"jev-latest"`                                   | The model id sent to TypeSafe.                                                                                                                                         |
+| `threshold`                    | `0.8`                                            | Report a rule when Jev's probability is above this.                                                                                                                    |
+| `sufficiencyThreshold`         | `0.6`                                            | Below it, a finding warns that Jev may not see enough to decide.                                                                                                       |
+| `presets`                      | none                                             | Built-in rule sets, or their topics. See [Presets](#presets).                                                                                                          |
+| `rules`                        | `.adhere/rules/`                                 | Rules inline, as above, or a directory (see [Where rules live](#where-rules-live)). Either replaces `.adhere/rules/`: none of its rules, root or nested, is read then. |
+| `exclude`                      | none                                             | Globs, relative to the working directory, of files no rule judges.                                                                                                     |
+| `overrides`                    | none                                             | Settings for a rule by its id. See [Overrides](#overrides).                                                                                                            |
+| `includeComments`              | `false`                                          | Send every comment to Jev. See [Comments](#comments).                                                                                                                  |
+| `reads`                        | `["workspacePackages", "symbols", "references"]` | What Jev reads beside each file's code, for every rule. `[]` is the code alone. See [What Jev reads](#what-jev-reads).                                                 |
+| `maxSymbolDocumentationLength` | `256`                                            | Maximum characters of each symbol's combined documentation and JSDoc tags, before `maxSymbolLength` applies. A non-negative integer; `0` omits them.                   |
+| `maxSymbolLength`              | `256`                                            | Maximum characters of each complete `symbols[name]` string, including type signatures and documentation. A non-negative integer; `0` leaves names with empty content.  |
+| `provider`                     | TypeSafe's Jev                                   | Where the questions go instead, with its own model. See [Providers](#providers).                                                                                       |
 
 - An invalid shape refuses the run.
 - A config can import other files by relative path, but no packages besides
@@ -866,9 +901,10 @@ export default defineConfig({ provider: mine });
   `choice`'s key. An id left out goes unanswered: its rule is not reported, and
   is asked again on the next run.
 - A rejection stops the run, but for three errors adhere exports:
-  `ContextOverflow` skips the file, `RequestBlocked` reports it blocked, and
-  `RequestFailed` is tried again, up to three times, when its `status` is 0,
-  for no answer, or a 408, 429, or 5xx.
+  `ContextOverflow` gets one retry without `references` when that map is present;
+  if the request still overflows, the file is skipped. `RequestBlocked` reports
+  it blocked, and `RequestFailed` is tried again, up to three times, when its
+  `status` is 0, for no answer, or a 408, 429, or 5xx.
 - adhere paces calls with `--rpm`, aborts `signal` after 30 seconds, and splits
   requests to fit Jev's 64,000 tokens. A model that takes less splits further in
   its `ask`.
@@ -1422,10 +1458,13 @@ about three bytes a token, and leaves 1k of room for what Jev wraps around it.
 
 - When a file's questions would not fit in one request, they are split across
   several.
-- A file whose state and longest question would not fit together, or that has
-  more than 255 sections, is skipped and counted in the summary, and the rest of
-  the run goes on. What adhere reads is never cut short to fit, so large
-  `references` can skip a file.
+- If a file's state and longest question would not fit together, or a provider
+  reports a context overflow, adhere retries once without `references` when that
+  map is present. Target code, `symbols`, and other context remain intact; no
+  declaration excerpt is shortened to fit. Removing references may still leave
+  the request too large, in which case the file is skipped and counted in the
+  summary. A file with more than 255 code sections is also skipped, and the rest
+  of the run goes on.
 - So is a file Jev itself counts as over its context, which text denser than the
   estimate, such as CJK, can cause.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.17.5",
+  "version": "0.18.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -90,10 +90,10 @@
     "--force"
   ],
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.17.5",
-    "@drkmttr/adhere-darwin-x64": "0.17.5",
-    "@drkmttr/adhere-linux-arm64": "0.17.5",
-    "@drkmttr/adhere-linux-x64": "0.17.5",
-    "@drkmttr/adhere-win32-x64": "0.17.5"
+    "@drkmttr/adhere-darwin-arm64": "0.18.0",
+    "@drkmttr/adhere-darwin-x64": "0.18.0",
+    "@drkmttr/adhere-linux-arm64": "0.18.0",
+    "@drkmttr/adhere-linux-x64": "0.18.0",
+    "@drkmttr/adhere-win32-x64": "0.18.0"
   }
 }

package/src/config.ts

@@ -222,6 +222,10 @@ export const AdhereConfig = Schema.Struct({
   ),
   /** Shared context for every audited file and all its rules. Unset: all built-in reads; []: code only. */
   reads: Schema.optionalKey(Reads),
+  /** Maximum characters of each symbol's complete resolved content. Defaults to 256. */
+  maxSymbolLength: Schema.optionalKey(Schema.Natural),
+  /** Maximum characters of documentation and JSDoc tags per symbol. Defaults to 256; 0 omits them. */
+  maxSymbolDocumentationLength: Schema.optionalKey(Schema.Natural),
   /**
    * A record of rules, or a directory path relative to the config file,
    * which holds its rules as `.adhere/rules/` does. Unset: the rules in
@@ -330,6 +334,8 @@ export const DEFAULT_MODEL = "jev-latest";
 export const DEFAULT_THRESHOLD = 0.8;
 export const DEFAULT_SUFFICIENCY_THRESHOLD = 0.6;
 export const DEFAULT_READS: typeof Reads.Type = ["workspacePackages", "symbols", "references"];
+export const DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH = 256;
+export const DEFAULT_MAX_SYMBOL_LENGTH = 256;
 
 /** A config with its presets folded in and every default applied. */
 export interface ResolvedConfig {
@@ -349,6 +355,10 @@ export interface ResolvedConfig {
   readonly includeComments?: boolean;
   /** Built-in context shared by every rule, with the default applied. */
   readonly reads: typeof Reads.Type;
+  /** Maximum characters of each symbol's complete resolved content. */
+  readonly maxSymbolLength: number;
+  /** Maximum characters of documentation and JSDoc tags before the complete symbol limit applies. */
+  readonly maxSymbolDocumentationLength: number;
   /**
    * The workspace's packages, each name with its directory from the working
    * directory, read from its manifests on every run when the config's reads
@@ -411,6 +421,9 @@ export const resolveConfig = (
     ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
     ...(config.includeComments === undefined ? {} : { includeComments: config.includeComments }),
     reads: config.reads ?? DEFAULT_READS,
+    maxSymbolLength: config.maxSymbolLength ?? DEFAULT_MAX_SYMBOL_LENGTH,
+    maxSymbolDocumentationLength:
+      config.maxSymbolDocumentationLength ?? DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH,
   };
 };
 

package/src/services/Jev.http.ts

@@ -14,6 +14,7 @@ import { Credentials } from "#services/Credentials.ts";
 import {
   type Body,
   type ComparedRule,
+  describeState,
   edgeKey,
   conflictBody,
   contradictBody,
@@ -36,6 +37,7 @@ import {
   type Rules,
   sufficiencyKey,
   tokensOf,
+  logRequestPayload,
 } from "#services/Jev.ts";
 import {
   Duration,
@@ -87,7 +89,7 @@ const hooked = (
   return Effect.tryPromise({
     try: async () => ({
       ...body,
-      state: { ...body.state, ...(await appendState(body.state, file, bun)) },
+      state: describeState({ ...body.state, ...(await appendState(body.state, file, bun)) }),
     }),
     catch: (cause) => refused(`the appendState of ${id} failed: ${messageOf(cause)}`),
   });
@@ -190,6 +192,7 @@ export const JevLive = Layer.effect(Jev)(
     const limiter = yield* RateLimiter.RateLimiter;
 
     const provider: Provider = config.provider ?? jev({ model: config.model, fetch });
+    const previewed = new Set<string>();
     // The key it asks with, when it names one `adhere login` saves. Read when
     // a request needs it, not in the layer: a run with nothing pending needs none.
     const apiKey: Effect.Effect<string | undefined, JevUnavailable> =
@@ -226,8 +229,23 @@ export const JevLive = Layer.effect(Jev)(
         yield* Effect.logDebug(
           `${kind}: asking ${provider.model} ${questions} ${questions === 1 ? "question" : "questions"}, about ${tokensOf(body)} tokens`,
         );
+        if ((kind === "judge" || kind === "locate") && !previewed.has(kind)) {
+          previewed.add(kind);
+          yield* logRequestPayload(
+            `${kind}: first ${kind === "locate" ? "match-to-lines " : ""}request payload`,
+            () => body,
+            "Debug",
+          );
+        }
         const [elapsed, answered] = yield* Effect.timed(
-          askProvider(provider, body.state, questionsOf(body.questions), Answers, key, pace),
+          askProvider(provider, body.state, questionsOf(body.questions), Answers, key, pace).pipe(
+            Effect.tapErrorTag("JevOverflow", () =>
+              logRequestPayload(
+                `${kind}: too long request payload (provider overflow)`,
+                () => body,
+              ),
+            ),
+          ),
         );
         yield* Effect.logDebug(
           `${kind}: ${provider.model} answered in ${Math.round(Duration.toMillis(elapsed))} ms`,

package/src/services/Jev.provider.test.ts

@@ -1,4 +1,4 @@
-import { decodeConfig, resolveConfig, type Rule, type Rules } from "#config.ts";
+import { decodeConfig, resolveConfig, type JevState, type Rule, type Rules } from "#config.ts";
 import {
   type AskOptions,
   ContextOverflow,
@@ -12,8 +12,9 @@ import {
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { Credentials } from "#services/Credentials.ts";
 import { JevLive } from "#services/Jev.http.ts";
-import { Jev } from "#services/Jev.ts";
-import { Effect, Layer, Redacted } from "effect";
+import { describeState, Jev, judgeBody, locateBody, requestsOf } from "#services/Jev.ts";
+import { questionsOf, requestOf, type SystemOneRequest } from "#providers/systemOne.ts";
+import { Effect, Layer, Logger, Redacted, References } from "effect";
 import { FetchHttpClient } from "effect/http";
 import { describe, expect, it } from "vite-plus/test";
 
@@ -25,6 +26,12 @@ const named: Rule = {
 const lines = ["const port = 3000;"];
 const file = { path: "/repo/src/server.ts", contents: lines.join("\n") };
 
+// Restore JSON escapes only inside string tokens, leaving layout and source backslashes intact.
+const jsonFromDiagnostic = (text: string): string =>
+  text.replace(/"(?:\\[\s\S]|[^"\\])*"/g, (token) =>
+    token.replace(/\n/g, "\\n").replace(/\t/g, "\\t"),
+  );
+
 /**
  * Jev under a config whose provider answers: any request Jev's own provider
  * sends, or any read of its key, dies. The saved OpenAI key is "sk-saved".
@@ -38,10 +45,13 @@ const judged = (
     ask,
     ...(savedKey === undefined ? {} : { savedKey }),
   },
+  kind: "judge" | "locate" = "judge",
 ) =>
   Effect.gen(function* () {
     const jev = yield* Jev;
-    return yield* jev.judge(lines, rules, [], file);
+    return kind === "judge"
+      ? yield* jev.judge(lines, rules, [], file)
+      : yield* jev.locate(lines, rules, file);
   }).pipe(
     Effect.provide(
       JevLive.pipe(
@@ -117,6 +127,272 @@ describe("a config's provider", () => {
     expect(blocked).toMatchObject({ _tag: "JevBlocked", ray: "ref-7" });
   });
 
+  it.each([
+    ["All", "judge"],
+    ["Trace", "judge"],
+    ["Debug", "judge"],
+    ["All", "locate"],
+    ["Trace", "locate"],
+    ["Debug", "locate"],
+  ] as const)(
+    "logs split requests after appendState with line criteria only at All (minimum: %s, kind: %s)",
+    async (minimum, kind) => {
+      const context = `export function caller() {\n\tconst escaped = "\\n\\t";\n\treturn "${"hook-context".repeat(40_000)}";\n}`;
+      const added = { references: { "port:caller.ts": context } };
+      const hooked: Rule = {
+        ...plain,
+        appliesTo: ["a server"],
+        appendState: async () => added,
+      };
+      const body = (
+        kind === "judge"
+          ? judgeBody("clef-flash", lines, { plain: hooked })
+          : locateBody("clef-flash", lines, { plain: hooked })
+      ) as SystemOneRequest & { readonly state: JevState };
+      const requests = requestsOf({ ...body, state: describeState({ ...body.state, ...added }) });
+      expect(requests.length).toBeGreaterThan(1);
+      const request = requests[0]!;
+      const asked: Array<{
+        state: State;
+        questions: ReadonlyArray<Question>;
+        apiKey: string | undefined;
+      }> = [];
+      let originalBody = "";
+      const originalAdded = JSON.stringify(added);
+      const logs: Array<Logger.Options<unknown>> = [];
+      const overflowed = await Effect.runPromise(
+        Effect.flip(
+          judged(
+            async (state, questions, { apiKey }) => {
+              asked.push({ state, questions, apiKey });
+              originalBody = JSON.stringify(requestOf("clef-flash", state, questions));
+              throw new ContextOverflow("too long");
+            },
+            "openai",
+            { plain: hooked },
+            undefined,
+            kind,
+          ),
+        ).pipe(
+          Effect.provide(Logger.layer([Logger.make((entry) => logs.push(entry))])),
+          Effect.provideService(References.MinimumLogLevel, minimum),
+        ),
+      );
+      expect(overflowed._tag).toBe("JevOverflow");
+      expect(asked).toEqual([
+        { state: request.state, questions: questionsOf(request.questions), apiKey: "sk-saved" },
+      ]);
+      const messages = logs.flatMap(({ message }) =>
+        Array.isArray(message) ? message : [message],
+      );
+      const oversized = messages.filter((message) =>
+        String(message).includes("too long request payload"),
+      );
+      if (minimum !== "Debug") {
+        const label = `${kind}: too long request payload (provider overflow)\n`;
+        expect(oversized).toHaveLength(1);
+        expect(String(oversized[0]).startsWith(label)).toBe(true);
+        const json = jsonFromDiagnostic(String(oversized[0]).slice(label.length));
+        const logged = JSON.parse(json) as typeof request;
+        const id = kind === "judge" ? "plain" : "start:plain:1";
+        expect(Object.keys(request.questions)).toEqual([id]);
+        const question = request.questions[id]!;
+        expect(question.instructions).toMatchObject({ rule: plain.description, must: plain.must });
+        if (minimum === "Trace" && question.type === "choice") {
+          const { criteria, ...withoutCriteria } = question;
+          expect(criteria).toEqual({ "1": lines[0] });
+          expect(logged.questions[id]).not.toHaveProperty("criteria");
+          expect(logged).toEqual({ ...request, questions: { [id]: withoutCriteria } });
+          expect(json).toBe(JSON.stringify(logged, null, 2));
+        } else {
+          expect(json).toBe(JSON.stringify(request, null, 2));
+          expect(logged).toEqual(request);
+          expect(logged.questions[id]?.criteria).toBeDefined();
+        }
+        expect(logged.state).toMatchObject(added);
+        if (minimum === "Trace") expect(Object.keys(logged.state)[0]).toBe("code");
+        expect(logged.model).toBe("clef-flash");
+        expect(
+          logs.find(({ message }) => Array.isArray(message) && message.includes(oversized[0]))
+            ?.logLevel,
+        ).toBe("Trace");
+      } else {
+        expect(oversized).toEqual([]);
+        const label = `${kind}: first ${kind === "locate" ? "match-to-lines " : ""}request payload\n`;
+        const previews = messages.filter((message) => String(message).startsWith(label));
+        expect(previews).toHaveLength(1);
+        const logged = JSON.parse(
+          jsonFromDiagnostic(String(previews[0]).slice(label.length)),
+        ) as SystemOneRequest;
+        expect(logged.state).toEqual(request.state);
+        expect(Object.keys(logged.state)[0]).toBe("code");
+        expect(logged.model).toBe(request.model);
+        const id = kind === "judge" ? "plain" : "start:plain:1";
+        if (kind === "locate") {
+          const { criteria, ...question } = request.questions[id]!;
+          expect(criteria).toBeDefined();
+          expect(logged.questions).toEqual({ [id]: question });
+        } else {
+          expect(logged.questions).toEqual(request.questions);
+        }
+      }
+      for (const message of messages.filter((message) =>
+        String(message).includes("request payload"),
+      )) {
+        expect(String(message)).toContain("\n\tconst escaped = ");
+        expect(String(message)).toContain(String.raw`\\n\\t`);
+        expect(String(message)).not.toContain(String.raw`\n\tconst escaped`);
+      }
+      expect(originalBody).toContain(String.raw`\n\tconst escaped`);
+      expect(JSON.stringify(added)).toBe(originalAdded);
+      const sent = asked[0]!;
+      expect(JSON.stringify(requestOf("clef-flash", sent.state, sent.questions))).toBe(
+        originalBody,
+      );
+      expect(JSON.parse(originalBody)).toEqual(request);
+      expect(JSON.stringify(messages)).not.toContain("sk-saved");
+      expect(request).not.toHaveProperty("apiKey");
+      expect(request).not.toHaveProperty("signal");
+      expect(messages).toContain("attempt failed: too long");
+    },
+  );
+
+  it.each(["All", "Trace", "Debug", "Info"] as const)(
+    "previews only the first judge and match-to-lines request per shared JevLive (minimum: %s)",
+    async (minimum) => {
+      const context = `export function caller() {\n\tconst escaped = "\\n\\t";\n\treturn "${"preview-context".repeat(40_000)}";\n}`;
+      const added = { references: { "port:caller.ts": context } };
+      const readState = { workspacePackages: { server: "src" } };
+      const hookedRules = {
+        plain: { ...plain, appliesTo: ["a server"], appendState: async () => added },
+        named: { ...named, appliesTo: ["a server"], appendState: async () => added },
+      };
+      const files = [file, { path: "/repo/src/other.ts", contents: "  const port = 8080;" }, file];
+      const expected = files.flatMap((current) => {
+        const code = current.contents.split("\n");
+        return ["judge", "locate"].flatMap((kind) =>
+          Object.entries(hookedRules).flatMap(([id, rule]) => {
+            const body = (
+              kind === "judge"
+                ? judgeBody("clef-flash", code, { [id]: rule }, [], readState)
+                : locateBody("clef-flash", code, { [id]: rule }, readState)
+            ) as SystemOneRequest & { readonly state: JevState };
+            const split = requestsOf({
+              ...body,
+              state: describeState({ ...body.state, ...added }),
+            });
+            expect(split.length).toBeGreaterThan(1);
+            return split;
+          }),
+        );
+      });
+      const firstJudge = expected[0]!;
+      const firstLocate = expected.find((body) =>
+        Object.keys(body.questions)[0]?.startsWith("start:"),
+      )!;
+      const asked: Array<SystemOneRequest> = [];
+      const snapshots: string[] = [];
+      const keys: Array<string | undefined> = [];
+      const logs: Array<Logger.Options<unknown>> = [];
+      const provider: Provider = {
+        model: "clef-flash",
+        savedKey: "openai",
+        ask: async (state, questions, { apiKey }) => {
+          const body = requestOf("clef-flash", state, questions);
+          asked.push(body);
+          snapshots.push(JSON.stringify(body));
+          keys.push(apiKey);
+          if (asked.length === 1) throw new RequestFailed("retry first request", 503);
+          return { answers: {} };
+        },
+      };
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const jev = yield* Jev;
+          for (const current of files) {
+            const code = current.contents.split("\n");
+            const judged = yield* jev.judge(code, hookedRules, [], current, readState);
+            expect(judged.probabilities).toEqual({});
+            expect(yield* jev.locate(code, hookedRules, current, readState)).toEqual({});
+          }
+        }).pipe(
+          Effect.provide(
+            JevLive.pipe(
+              Layer.provide([
+                Layer.succeed(FetchHttpClient.Fetch, (() => {
+                  throw new Error("preview tests send no HTTP requests");
+                }) as unknown as typeof globalThis.fetch),
+                Layer.succeed(AdhereConfig, resolveConfig({ presets: [], rules: {}, provider })),
+                Layer.succeed(Credentials, {
+                  key: () => Effect.succeed(Redacted.make("sk-saved")),
+                  file: Effect.die("unused"),
+                  save: () => Effect.die("unused"),
+                  remove: () => Effect.die("unused"),
+                }),
+              ]),
+            ),
+          ),
+          Effect.provide(Logger.layer([Logger.make((entry) => logs.push(entry))])),
+          Effect.provideService(References.MinimumLogLevel, minimum),
+        ),
+      );
+      expect(asked).toEqual([firstJudge, ...expected]);
+      expect(asked.map((body) => JSON.stringify(body))).toEqual(snapshots);
+      expect(snapshots[0]).toContain(String.raw`\n\tconst escaped`);
+      expect(snapshots.map((json) => JSON.parse(json))).toEqual(asked);
+      expect(keys).toEqual(asked.map(() => "sk-saved"));
+      const messages = logs.flatMap(({ message }) =>
+        Array.isArray(message) ? message : [message],
+      );
+      const previews = messages.filter((message) => String(message).includes("request payload"));
+      if (minimum === "Info") {
+        expect(previews).toEqual([]);
+        expect(JSON.stringify(messages)).not.toContain("preview-context");
+      } else {
+        const labels = [
+          "judge: first request payload\n",
+          "locate: first match-to-lines request payload\n",
+        ];
+        expect(previews).toHaveLength(2);
+        for (const [index, body] of [firstJudge, firstLocate].entries()) {
+          const label = labels[index]!;
+          expect(String(previews[index]).startsWith(label)).toBe(true);
+          const text = String(previews[index]).slice(label.length);
+          expect(text).toContain("\n\tconst escaped = ");
+          expect(text).toContain(String.raw`\\n\\t`);
+          expect(text).not.toContain(String.raw`\n\tconst escaped`);
+          const json = jsonFromDiagnostic(text);
+          const logged = JSON.parse(json) as SystemOneRequest;
+          expect(logged.model).toBe(body.model);
+          expect(logged.state).toEqual(body.state);
+          expect(logged.state).toMatchObject({ ...readState, ...added });
+          if (minimum === "All") {
+            expect(json).toBe(JSON.stringify(body, null, 2));
+            expect(logged).toEqual(body);
+          } else {
+            expect(Object.keys(logged.state)[0]).toBe("code");
+            if (index === 0) {
+              expect(logged.questions).toEqual(body.questions);
+              expect(logged.questions.plain?.criteria).toBeDefined();
+            } else {
+              const { criteria, ...question } = body.questions["start:plain:1"]!;
+              expect(criteria).toEqual({ "1": lines[0] });
+              expect(logged.questions).toEqual({ "start:plain:1": question });
+            }
+          }
+          expect(
+            logs.find(({ message }) => Array.isArray(message) && message.includes(previews[index]))
+              ?.logLevel,
+          ).toBe("Debug");
+        }
+      }
+      expect(JSON.stringify(messages)).not.toContain("sk-saved");
+      expect(messages.some((message) => String(message).includes("too long request payload"))).toBe(
+        false,
+      );
+    },
+  );
+
   it("is asked as a method, so a class can implement it", async () => {
     class Fixed implements Provider {
       readonly model = "fixed";