@drkmttr/adhere 0.17.5 → 0.18.1

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";

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

@@ -1,5 +1,7 @@
 import {
   type AppendState,
+  DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH,
+  DEFAULT_MAX_SYMBOL_LENGTH,
   type JevState,
   type ReadState,
   type ResolvedConfig,
@@ -10,6 +12,7 @@ import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { Credentials } from "#services/Credentials.ts";
 import { JevLive } from "#services/Jev.http.ts";
 import {
+  describeState,
   fits,
   Jev,
   judgeBody,
@@ -28,11 +31,11 @@ import { FetchHttpClient } from "effect/http";
 import { describe, expect, it } from "vite-plus/test";
 
 const plain: Rule = { description: "Ports must be named.", must: "const port = PORT;" };
-const lines = ["const port = 3000;"];
+const lines = ["const port = 3000;"] as const;
 const codeState = { code: { "1": lines[0] } };
 const file = { path: "/repo/src/server.ts", contents: lines.join("\n") };
 const symbols = { port: "```typescript\nconst port: number\n```" };
-const references = { PORT: { "src/config.ts": "export const PORT = 3000;\r\n" } };
+const references = { "PORT:src/config.ts": "export const PORT = 3000;\r\n" };
 const codeSufficiency = {
   type: "noul",
   instructions: {
@@ -73,9 +76,12 @@ const recordedJev = (
     Layer.provide([
       Layer.succeed(FetchHttpClient.Fetch, fetch),
       Layer.succeed(AdhereConfig, {
+        typeAware: false,
         model: "jev-latest",
         threshold: 0.8,
         sufficiencyThreshold: 0.6,
+        maxSymbolDocumentationLength: DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH,
+        maxSymbolLength: DEFAULT_MAX_SYMBOL_LENGTH,
         reads,
         rules: {},
         workspacePackages,
@@ -153,7 +159,19 @@ describe("prepared shared Jev reads", () => {
       project: { language: "typescript" },
       code: { "1": "replaced" },
     };
-    const enriched = { ...readState, ...codeState };
+    const enriched = describeState({ ...readState, ...codeState });
+    expect(enriched.__comment).toMatch(/only.*code|code.*only/i);
+    expect(enriched.__comment).toMatch(/context/i);
+    expect(enriched.symbols).toEqual({ ...symbols, __comment: expect.stringMatching(/symbol/i) });
+    expect(enriched.references).toEqual({
+      ...references,
+      __comment: expect.stringMatching(/symbol.*path|symbol.*file/i),
+    });
+    expect(enriched.workspacePackages).toEqual({
+      orders: "packages/orders",
+      __comment: expect.stringMatching(/package/i),
+    });
+    expect(Object.keys(enriched.code)).toEqual(["1"]);
     expect(judgeBody("", lines, rules, [], readState).state).toEqual(enriched);
     expect(locateBody("", lines, rules, readState).state).toEqual(enriched);
     const groups = requestGroups(rules);
@@ -166,8 +184,8 @@ describe("prepared shared Jev reads", () => {
       expect(judgeBody("", lines, group, [], readState).state).toEqual(enriched);
       const body = locateBody("", lines, group, readState);
       expect(body.state).toEqual(enriched);
-      expect(body.state.symbols).toBe(symbols);
-      expect(body.state.references).toBe(references);
+      expect(body.state.symbols).toEqual({ ...symbols, __comment: expect.any(String) });
+      expect(body.state.references).toEqual({ ...references, __comment: expect.any(String) });
       for (const id of Object.keys(group)) {
         expect(body.questions[`sufficient:${id}`]).toEqual(sufficiencyQuestion(plain, readState));
       }
@@ -176,9 +194,56 @@ describe("prepared shared Jev reads", () => {
     expect(locateRequests(lines, rules, readState)).toBe(3);
   });
 
+  it("preserves caller comments and raw context through judge, locate, and appended maps", async () => {
+    const readState = {
+      __comment: "User context: only target code is audited.",
+      symbols: { ...symbols, __comment: "User symbol description." },
+      references: { ...references, __comment: "User reference description." },
+      workspacePackages: { orders: "packages/orders", __comment: "User package description." },
+    };
+    const original = JSON.stringify(readState);
+    const hooked = {
+      ...plain,
+      appendState: () => ({ references: { "port:src/caller.ts": "\tuse(port);\r\n" } }),
+    };
+    const { sent, layer } = recordedJev();
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const jev = yield* Jev;
+        yield* jev.judge(lines, { plain, hooked }, [], file, readState);
+        yield* jev.locate(lines, { plain, hooked }, file, readState);
+      }).pipe(Effect.provide(layer)),
+    );
+    expect(sent).toHaveLength(4);
+    for (const body of sent) {
+      expect(body.state.code).toEqual(codeState.code);
+      expect(body.state.__comment).toBe(readState.__comment);
+      expect(body.state.symbols).toEqual(readState.symbols);
+      expect(body.state.workspacePackages).toEqual(readState.workspacePackages);
+    }
+    expect(sent[0]?.state.references).toEqual(readState.references);
+    expect(sent[2]?.state.references).toEqual(readState.references);
+    for (const index of [1, 3]) {
+      expect(sent[index]?.state.references).toEqual({
+        "port:src/caller.ts": "\tuse(port);\r\n",
+        __comment: expect.stringMatching(/symbol.*path|symbol.*file/i),
+      });
+    }
+    expect(JSON.stringify(readState)).toBe(original);
+    expect(
+      sent
+        .slice(2)
+        .flatMap(({ questions }) => Object.values(questions))
+        .filter(({ type }) => type === "noul")
+        .every(({ instructions }) => !instructions.question.includes("__comment")),
+    ).toBe(true);
+  });
+
   it("names actual shared keys in sufficiency, including packages but excluding duplicate code", () => {
     expect(sufficiencyQuestion(plain)).toEqual(codeSufficiency);
-    expect(sufficiencyQuestion(plain, { code: {} })).toEqual(codeSufficiency);
+    expect(sufficiencyQuestion(plain, { code: {}, __comment: "context description" })).toEqual(
+      codeSufficiency,
+    );
     expect(sufficiencyQuestion({ ...plain, appendState: () => ({ private: true }) })).toEqual(
       codeSufficiency,
     );
@@ -186,22 +251,32 @@ describe("prepared shared Jev reads", () => {
       { workspacePackages: {} },
       { symbols },
       { references },
-      { workspacePackages: {}, symbols, references, project: true, code: {} },
+      {
+        workspacePackages: {},
+        symbols,
+        references,
+        project: true,
+        code: {},
+        __comment: "context description",
+      },
     ]) {
       const question = sufficiencyQuestion(plain, readState);
       expect(question.instructions.question).not.toContain("`code` alone");
-      for (const key of Object.keys(readState).filter((key) => key !== "code")) {
+      for (const key of Object.keys(readState).filter(
+        (key) => key !== "code" && key !== "__comment",
+      )) {
         expect(question.instructions.question).toContain(`\`${key}\``);
         expect(question.criteria.true).toContain(`\`${key}\``);
         expect(question.criteria.false).toContain(`\`${key}\``);
       }
       expect(question.instructions.question.match(/`code`/g)).toHaveLength(2);
+      expect(JSON.stringify(question)).not.toContain("__comment");
     }
   });
 
   it("budgets all shared context beside every rule's questions", () => {
     const source = "export const value = 1;\n".repeat(2200);
-    const readState = { references: { value: { "src/related.ts": source } } };
+    const readState = { references: { "value:src/related.ts": source } };
     const large = { ...plain, must: "x".repeat(60_000) };
     const hooked = { ...plain, appendState: () => ({ private: "x".repeat(120_000) }) };
     expect(fits(lines, { large, hooked })).toBe(true);
@@ -295,7 +370,7 @@ describe("prepared shared Jev reads", () => {
     };
     const rules = { plain, native };
     const readState = {
-      references: { files: { "src/related.ts": "export const value = 1;\n".repeat(1500) } },
+      references: { "value:src/related.ts": "export const value = 1;\n".repeat(1500) },
     };
     const sampled = ["native"];
     expect(fits(long, rules, readState)).toBe(true);
@@ -338,7 +413,7 @@ describe("prepared shared Jev reads", () => {
 
   it("sends shared context once for non-hook rules and inherits it in private hook groups", async () => {
     const seen: Array<JevState> = [];
-    const privateSymbols = [{ name: "private", section: 1, usages: 0 }];
+    const privateSymbols = { private: "const private: number" };
     const appendState: AppendState = (state, receivedFile) => {
       expect(receivedFile).toBe(file);
       seen.push(state);
@@ -373,16 +448,19 @@ describe("prepared shared Jev reads", () => {
     });
     expect(result.judged.linter).toEqual({ plain: 0.9, hooked: 0.9 });
     expect(Object.keys(result.located)).toEqual(Object.keys(rules));
-    const enriched = { ...readState, ...codeState };
+    const enriched = describeState({ ...readState, ...codeState });
     expect(seen).toEqual([enriched, enriched, enriched, enriched]);
     for (const state of seen) {
-      expect(state.symbols).toBe(symbols);
-      expect(state.references).toBe(references);
-      expect(state.workspacePackages).toBe(workspacePackages);
+      expect(state.symbols).toEqual({ ...symbols, __comment: expect.any(String) });
+      expect(state.references).toEqual({ ...references, __comment: expect.any(String) });
+      expect(state.workspacePackages).toEqual({
+        ...workspacePackages,
+        __comment: expect.any(String),
+      });
     }
     const expectedStates = [
       enriched,
-      { ...enriched, private: "first", symbols: privateSymbols },
+      describeState({ ...enriched, private: "first", symbols: privateSymbols }),
       { ...enriched, private: "second" },
     ];
     expect(sent.map((body) => body.state)).toEqual([...expectedStates, ...expectedStates]);
@@ -416,9 +494,10 @@ describe("prepared shared Jev reads", () => {
     expect(readState.code).toEqual({});
   });
 
-  it("does not prepare context in HTTP even with resolved default reads and omitted or partial shared state", async () => {
+  it("uses only caller-prepared context in HTTP with workspace-only defaults", async () => {
     const config = resolveConfig({ presets: [], rules: { plain } });
-    expect(config.reads).toEqual(["workspacePackages", "symbols", "references"]);
+    expect(config.reads).toEqual(["workspacePackages"]);
+    expect(config.typeAware).toBe(false);
     const { sent, layer } = recordedJev({ unused: "packages/unused" }, config.reads);
     await Effect.runPromise(
       Effect.gen(function* () {
@@ -432,8 +511,8 @@ describe("prepared shared Jev reads", () => {
     expect(sent.map((body) => body.state)).toEqual([
       codeState,
       codeState,
-      { symbols, ...codeState },
-      { symbols, ...codeState },
+      describeState({ symbols, ...codeState }),
+      describeState({ symbols, ...codeState }),
     ]);
   });
 });

package/src/services/Jev.ts

@@ -9,8 +9,8 @@ import {
   type Rules,
 } from "#config.ts";
 import { type Range, sectionsOf } from "#excerpt.ts";
-import type { SystemOneRequest } from "#providers/systemOne.ts";
-import { Context, type Effect, Record, Schema } from "effect";
+import type { SystemOneQuestion, SystemOneRequest } from "#providers/systemOne.ts";
+import { Context, Effect, LogLevel, Record, References, Schema } from "effect";
 
 export type { Rules };
 export type Lines = ReadonlyArray<string>;
@@ -139,6 +139,32 @@ const bytesOf = (value: unknown): number => encoder.encode(JSON.stringify(value)
  */
 export const tokensOf = (value: unknown): number => Math.ceil(bytesOf(value) / 3);
 
+const READ_COMMENTS: Readonly<Record<string, string>> = {
+  symbols:
+    "Compiler-rendered types and documentation for symbols used in `code`; keys are symbol names. A declared type, assertion, or type predicate is only a compile-time claim, not proof of runtime validation. When `references` show an implementation, inspect its actual checks. A predicate that returns true, tests only truthiness, or checks only whether a value is an object does not validate the fields it claims.",
+  references:
+    "Declarations of symbols used in `code`. Each key is `symbol:pathname`: the symbol name as used in `code` followed by its repository-relative declaration path. Each value is a complete declaration excerpt.",
+  workspacePackages:
+    "Workspace packages imported by `code`; keys are package names and values are repository-relative package directories. Only packages imported by this file are listed.",
+};
+
+/** Explain the known context maps while preserving caller-provided descriptions and target code. */
+export const describeState = (state: JevState): JevState => {
+  const described = { ...state };
+  for (const [name, comment] of Object.entries(READ_COMMENTS)) {
+    const value = state[name];
+    if (value !== null && typeof value === "object" && !Array.isArray(value))
+      described[name] = { __comment: comment, ...value };
+  }
+  if (
+    described.__comment === undefined &&
+    Object.keys(state).some((name) => name !== "code" && name !== "__comment")
+  )
+    described.__comment =
+      "Only `code` is the audit target; it is split into numbered sections. All other state entries provide context, not additional code to audit.";
+  return described;
+};
+
 /**
  * The file as Jev reads it: its sections, by `sectionsOf`, under their
  * numbers from 1, so the locate question can name one. Prepared context is
@@ -149,15 +175,16 @@ const stateOf = (
   lines: Lines,
   readState: ReadState = {},
   sections: ReadonlyArray<Range> = sectionsOf(lines),
-): JevState => ({
-  ...readState,
-  code: Object.fromEntries(
-    sections.map((section, index) => [
-      String(index + 1),
-      lines.slice(section.first - 1, section.last).join("\n"),
-    ]),
-  ),
-});
+): JevState =>
+  describeState({
+    ...readState,
+    code: Object.fromEntries(
+      sections.map((section, index) => [
+        String(index + 1),
+        lines.slice(section.first - 1, section.last).join("\n"),
+      ]),
+    ),
+  });
 
 /** The field an example goes under in a question: its word, with `should not` as `should_not`. */
 const fieldOf = (example: Example): string => example.word.replace(" ", "_");
@@ -361,7 +388,7 @@ export const judgeBody = (
  * it scored below 0.6, 62% were false, where 22% of all were.
  */
 const sufficiencyQuestionWith = (fields: ReturnType<typeof ruleFields>, readState: ReadState) => {
-  const keys = Object.keys(readState).filter((key) => key !== "code");
+  const keys = Object.keys(readState).filter((key) => key !== "code" && key !== "__comment");
   const context =
     keys.length === 0 ? undefined : ["`code`", ...keys.map((key) => `\`${key}\``)].join(" and ");
   return {
@@ -547,6 +574,43 @@ export const fits = (lines: Lines, rules: Rules, readState: ReadState = {}): boo
 /** A request to Jev, its questions typed as `Q`: `Question`, as adhere asks them, or anything an eval arm asks. */
 export type Body<Q = unknown> = SystemOneRequest<Q>;
 
+type RequestPayload =
+  | Body<SystemOneQuestion>
+  | { readonly judge: Body<SystemOneQuestion>; readonly locate: Body<SystemOneQuestion> };
+
+const traceBody = (body: Body<SystemOneQuestion>) => ({
+  ...body,
+  state: { code: body.state.code, ...body.state },
+  questions: Record.map(body.questions, (question, id) =>
+    question.type === "choice" && /^(start|end):/.test(id)
+      ? { ...question, criteria: undefined }
+      : question,
+  ),
+});
+
+/** Debug/Trace put target code first and omit line-option copies; All retains the complete request. */
+export const logRequestPayload = (
+  message: string,
+  payload: () => RequestPayload,
+  level: "Debug" | "Trace" = "Trace",
+): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const minimum = yield* References.MinimumLogLevel;
+    if (LogLevel.isGreaterThan(minimum, level)) return;
+    const full = payload();
+    const visible =
+      minimum === "All"
+        ? full
+        : "questions" in full
+          ? traceBody(full)
+          : { judge: traceBody(full.judge), locate: traceBody(full.locate) };
+    // Consume escaped backslashes first so source literals such as "\\n" remain literals.
+    const text = JSON.stringify(visible, null, 2).replace(/\\\\|\\[nt]/g, (escaped) =>
+      escaped === "\\n" ? "\n" : escaped === "\\t" ? "\t" : escaped,
+    );
+    yield* (level === "Debug" ? Effect.logDebug : Effect.logTrace)(`${message}\n${text}`);
+  });
+
 /**
  * A body as requests Jev can take: its questions in order, with a new
  * request whenever the next question would not fit beside the state and