@drkmttr/adhere 0.15.0 → 0.18.0

package/src/cli.ts

@@ -1,7 +1,13 @@
 import { AdhereConfig, AdhereConfigLive } from "#services/AdhereConfig.ts";
 import { AuditCacheLive } from "#services/AuditCache.ts";
-import { Credentials, CredentialsLive, CredentialsUnavailable } from "#services/Credentials.ts";
+import {
+  Credentials,
+  CredentialsLive,
+  CredentialsUnavailable,
+  KEYS,
+} from "#services/Credentials.ts";
 import { JevLive } from "#services/Jev.http.ts";
+import { SourceReadsLive } from "#services/SourceReads.ts";
 import { SourceWalkerLive } from "#services/SourceWalker.ts";
 import { Status } from "#services/Status.ts";
 import {
@@ -26,6 +32,7 @@ import { type Install, initProject } from "#init.ts";
 import { installRules, listRules, parseSource } from "#install.ts";
 import { formatLinterCheck, tallyProjectRules } from "#mechanical.ts";
 import { type PresetName, presetNames } from "#presets.ts";
+import type { SavedKey } from "#providers/provider.ts";
 import { globalRuleSet } from "#rules.ts";
 import { formatStrays, straysAmong } from "#wording.ts";
 import {
@@ -44,7 +51,6 @@ import {
   Stream,
 } from "effect";
 import { Argument, Command, Flag, Prompt } from "effect/cli";
-import { FetchHttpClient } from "effect/http";
 // A Bun text import (https://bun.sh/docs/bundler/loaders#text): the file's
 // contents become a string at bundle time, so the compiled binary carries the
 // skill without an --asset flag. `skills/` sits beside `src/`, outside the `#`
@@ -110,12 +116,12 @@ const sufficiencyThreshold = Flag.Finite("sufficiency-threshold").pipe(
 
 const limit = Flag.Int("limit").pipe(
   Flag.filter(
-    (checks) => checks >= 0,
-    (checks) => `--limit is a number of checks, 0 or more, not ${checks}.`,
+    (files) => files >= 0,
+    (files) => `--limit is a number of files, 0 or more, not ${files}.`,
   ),
   Flag.optional,
   Flag.withDescription(
-    "Judge at most this many checks. The rest wait for a later run, which picks up where this one stopped, since judgments are cached. --limit 0 shows the plan and judges nothing.",
+    "Process at most this many files needing requests, in path order, including every pending rule per selected file. Fully cached and located files do not count. A file can send multiple requests. --limit 0 shows the plan without resolving native reads or sending requests.",
   ),
 );
 
@@ -221,8 +227,9 @@ const force = Flag.Boolean("force").pipe(
 export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
   Layer.mergeAll(
     SourceWalkerLive(filter),
+    SourceReadsLive(),
     AuditCacheLive,
-    JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
+    JevLive.pipe(Layer.provide(CredentialsLive)),
   ).pipe(Layer.provideMerge(AdhereConfigLive(flags)), Layer.provideMerge(statusLayer));
 
 /** `adhere lint`: the audit. */
@@ -235,10 +242,19 @@ export const lintCommand = Command.make(
       const plan = yield* planAudit({ limit: Option.getOrUndefined(input.limit) });
       const limits = { filter: input.filter, rpm: Option.getOrUndefined(input.rpm) };
       yield* toStderr(`${describePlan(plan, limits).join("\n")}\n`);
+      if (plan.planOnly === true) {
+        // Planning still knows the live content keys, so a complete walk can prune without sending.
+        if (input.filter.length === 0) yield* pruneCache(plan);
+        return;
+      }
       // A prompt draws on stdout, so it needs a terminal at both ends: none when
       // the report is redirected, or in CI.
       const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
-      if (plan.requests > 0 && interactive && !input.yes) {
+      if (
+        (plan.requests > 0 || (plan.cachedLocateRequests ?? 0) > 0) &&
+        interactive &&
+        !input.yes
+      ) {
         const send = yield* Prompt.run(
           Prompt.Confirm({ message: sendQuestion(plan), initial: true }),
         );
@@ -263,6 +279,7 @@ export const lintCommand = Command.make(
           root: path.resolve(),
           threshold: plan.threshold,
           sufficiencyThreshold: plan.sufficiencyThreshold,
+          ...(plan.provider === undefined ? {} : { provider: plan.provider }),
         }).join("\n"),
       );
       // Only errors fail the run, unless --deny-warnings: a warning is for a nit or a noisy rule.
@@ -290,10 +307,10 @@ export const lintCommand = Command.make(
 
 /** Jev, with the key `lint` uses, and the config it reads the model and threshold from. */
 export const validateLayer = (flags: Flags) =>
-  Layer.merge(
-    JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
-    AuditCacheLive,
-  ).pipe(Layer.provideMerge(AdhereConfigLive(flags)), Layer.provideMerge(statusLayer));
+  Layer.merge(JevLive.pipe(Layer.provide(CredentialsLive)), AuditCacheLive).pipe(
+    Layer.provideMerge(AdhereConfigLive(flags)),
+    Layer.provideMerge(statusLayer),
+  );
 
 /**
  * `adhere validate`: everything `lint` loads, then how each rule's wording
@@ -439,10 +456,10 @@ export const installCommand = Command.make(
  * The key typed at a masked prompt, or piped in: `adhere login < key.txt`.
  * Whitespace around it, like the newline a pipe ends with, is dropped.
  */
-const readApiKey = Effect.fn("login.readApiKey")(function* () {
+const readApiKey = Effect.fn("login.readApiKey")(function* (label: string) {
   const stdio = yield* Stdio.Stdio;
   const typed: string = (yield* stdio.stdinIsTerminal)
-    ? Redacted.value(yield* Prompt.run(Prompt.Password({ message: "TypeSafe AI API key" })))
+    ? Redacted.value(yield* Prompt.run(Prompt.Password({ message: label })))
     : yield* stdio.stdin.pipe(
         Stream.decodeText(),
         Stream.mkString,
@@ -461,33 +478,49 @@ const readApiKey = Effect.fn("login.readApiKey")(function* () {
   return Redacted.make(key);
 });
 
-/** `adhere login`: save the API key, so a run needs no TYPESAFE_API_KEY. */
-export const loginCommand = Command.make("login", {}, () =>
+/** `--openai`: the OpenAI key, for the `openai` provider, in place of TypeSafe AI's. */
+const openaiKey = Flag.Boolean("openai").pipe(
+  Flag.withDefault(false),
+  Flag.withDescription(
+    "The OpenAI API key, for a config whose provider is openai(), in place of the TypeSafe AI key Jev asks with.",
+  ),
+);
+
+/** Which saved key a command means, and how it names it: TypeSafe AI's by default. */
+const keyOf = (openai: boolean) => {
+  const name: SavedKey = openai ? "openai" : "typesafe";
+  return { name, ...KEYS[name] };
+};
+
+/** `adhere login`: save an API key, so a run needs no TYPESAFE_API_KEY, or with `--openai`, no OPENAI_API_KEY. */
+export const loginCommand = Command.make("login", { openai: openaiKey }, ({ openai }) =>
   Effect.gen(function* () {
+    const { name, label, said } = keyOf(openai);
     const credentials = yield* Credentials;
-    yield* credentials.save(yield* readApiKey());
-    yield* Console.log(`Saved the API key to ${yield* credentials.file}.`);
+    yield* credentials.save(name, yield* readApiKey(label));
+    yield* Console.log(`Saved the ${said} to ${yield* credentials.file}.`);
   }),
 ).pipe(
   Command.withDescription(
-    "Save a TypeSafe AI API key in ~/.config/adhere ($XDG_CONFIG_HOME/adhere when set), readable only by you, so lint runs without TYPESAFE_API_KEY. Prompts for the key, or reads it from stdin when piped.",
+    "Save a TypeSafe AI API key in ~/.config/adhere ($XDG_CONFIG_HOME/adhere when set), readable only by you, so lint runs without TYPESAFE_API_KEY. With --openai, save an OpenAI API key beside it instead, for the openai provider. Prompts for the key, or reads it from stdin when piped.",
   ),
   Command.provide(CredentialsLive),
 );
 
-/** `adhere logout`: delete the saved API key. */
-export const logoutCommand = Command.make("logout", {}, () =>
+/** `adhere logout`: delete a saved API key. */
+export const logoutCommand = Command.make("logout", { openai: openaiKey }, ({ openai }) =>
   Effect.gen(function* () {
+    const { name, said } = keyOf(openai);
     const credentials = yield* Credentials;
     const file = yield* credentials.file;
-    const removed = yield* credentials.remove;
+    const removed = yield* credentials.remove(name);
     yield* Console.log(
-      removed ? `Deleted the API key saved in ${file}.` : `No API key is saved in ${file}.`,
+      removed ? `Deleted the ${said} saved in ${file}.` : `No ${said} is saved in ${file}.`,
     );
   }),
 ).pipe(
   Command.withDescription(
-    "Delete the API key adhere login saved. TYPESAFE_API_KEY, when set, still applies.",
+    "Delete the API key adhere login saved, or with --openai, the OpenAI one. TYPESAFE_API_KEY or OPENAI_API_KEY, when set, still applies.",
   ),
   Command.provide(CredentialsLive),
 );

package/src/config.ts

@@ -1,12 +1,17 @@
 import { type PresetName, presetNames } from "#presets.ts";
+import { type Provider, SAVED_KEYS } from "#providers/provider.ts";
 import type { RuleSet } from "#rules.ts";
-import { Effect, Schema, SchemaTransformation } from "effect";
+import { Effect, Predicate, Schema, SchemaTransformation } from "effect";
 
 export type RuleId = string;
 
-/** The state a request to Jev carries: the file's code as numbered sections, which every question reads. */
+/** Shared context prepared for a file's requests; it does not affect cache validity. */
+export type ReadState = Readonly<Record<string, unknown>>;
+
+/** The file's numbered sections and the context enabled by its config. */
 export interface JevState {
   readonly code: Readonly<Record<string, string>>;
+  readonly [key: string]: unknown;
 }
 
 /** The file a request is about, as a rule's hook gets it: its absolute path, and its text as written. */
@@ -15,6 +20,21 @@ export interface JudgedFile {
   readonly contents: string;
 }
 
+/**
+ * A config's provider, as `Provider` in `providers/provider.ts` describes it:
+ * a model, and how to ask it. Checked rather than copied, so a class keeps
+ * what its `ask` reads off `this`.
+ */
+const ProviderSchema = Schema.declare(
+  (value: unknown): value is Provider =>
+    Predicate.hasProperty(value, "model") &&
+    Predicate.isString(value.model) &&
+    Predicate.hasProperty(value, "ask") &&
+    Predicate.isFunction(value.ask) &&
+    (!Predicate.hasProperty(value, "savedKey") || SAVED_KEYS.some((key) => key === value.savedKey)),
+  { expected: "a provider: a model, and a function to ask it" },
+);
+
 /**
  * Bun's API, typed when the project has Bun's types. Read off `globalThis`,
  * so this package's source type-checks in a project without them.
@@ -33,13 +53,15 @@ export type AppendState = (
 ) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
 
 /**
- * What a rule can have Jev read beside the code, each by the name of the key
- * the state carries it under, which the rule's description can name in
- * backticks. `workspacePackages` is the workspace's packages: each one's name
- * with its directory, so a rule can tell an import of the repository's own
- * package from an installed one's.
+ * What the config can have Jev read beside each file's code, shared by all
+ * its rules. Each name is the key the state carries it under, which a rule's
+ * description can name in backticks. `workspacePackages` maps only workspace
+ * packages imported by this file to their directories. `symbols` maps names
+ * to native compiler types, with documentation and JSDoc tags shared across variants.
+ * `references` maps used names to complete AST declaration scopes by
+ * repo-relative path, rather than fixed line windows or full related files.
  */
-export const Reads = Schema.Array(Schema.Literals(["workspacePackages"]));
+export const Reads = Schema.Array(Schema.Literals(["workspacePackages", "symbols", "references"]));
 
 /**
  * A rule's examples, named in RFC 2119's words, which Jev reads as written. A
@@ -83,12 +105,6 @@ const RuleFields = Schema.Struct({
    * that breaks the rule is as it describes, and a yes to any drops the finding.
    */
   excludeIf: Schema.optionalKey(Schema.Array(Schema.String)),
-  /**
-   * What Jev reads for the rule beside the code, by name (see `Reads`). The
-   * rule's questions go in requests of their own, so only they read it, and
-   * a change to what is read judges the rule again.
-   */
-  reads: Schema.optionalKey(Reads),
   /**
    * A hook on the state Jev reads for the rule, in a rule written in
    * TypeScript (see `AppendState`). The rule's questions go in requests of
@@ -106,6 +122,12 @@ export const Rule = Schema.Struct({
   ...RuleFields.fields,
   reference: Schema.optionalKey(Schema.String),
   avoid: Schema.optionalKey(Schema.String),
+  // Guard the removed key instead of silently dropping it as an excess property.
+  reads: Schema.optionalKey(
+    Schema.declare((_value: unknown): _value is never => false, {
+      expected: "no rule-level reads; move reads to the top level of defineConfig({...})",
+    }),
+  ),
 })
   .pipe(
     Schema.decodeTo(
@@ -179,6 +201,8 @@ export const AdhereConfig = Schema.Struct({
    * The model id sent to typesafe. Defaults to "jev-latest"
    */
   model: Schema.optionalKey(Schema.String),
+  /** Where the questions go in place of TypeSafe's Jev, with its own model (see `Provider`). */
+  provider: Schema.optionalKey(ProviderSchema),
   /**
    * The minimum confidence threshold for a positive match. Defaults to 0.8
    */
@@ -196,6 +220,12 @@ export const AdhereConfig = Schema.Struct({
   presets: Schema.Array(Schema.Literals(presetNames)).pipe(
     Schema.withDecodingDefaultKey(Effect.succeed([])),
   ),
+  /** 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
@@ -303,10 +333,15 @@ export type Loaded<T extends { readonly rules?: unknown }> = Omit<T, "rules"> &
 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 {
   readonly model: string;
+  /** Where the questions go in place of Jev; `model` is its model. */
+  readonly provider?: Provider;
   readonly threshold: number;
   /** Below this, a finding's sufficiency adds a warning to it. */
   readonly sufficiencyThreshold: number;
@@ -318,9 +353,15 @@ export interface ResolvedConfig {
   readonly exclude?: ReadonlyArray<string>;
   /** Whether Jev reads every comment; unset, only the `@adhere` notes. */
   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 a rule's `reads`
+   * directory, read from its manifests on every run when the config's reads
    * names them.
    */
   readonly workspacePackages?: Readonly<Record<string, string>>;
@@ -370,7 +411,8 @@ export const resolveConfig = (
   const last = <K extends "model" | "threshold">(key: K) =>
     applied.map((preset) => preset[key]).findLast((value) => value !== undefined);
   return {
-    model: config.model ?? last("model") ?? DEFAULT_MODEL,
+    model: config.provider?.model ?? config.model ?? last("model") ?? DEFAULT_MODEL,
+    ...(config.provider === undefined ? {} : { provider: config.provider }),
     threshold: flags.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
     sufficiencyThreshold:
       flags.sufficiencyThreshold ?? config.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD,
@@ -378,6 +420,10 @@ export const resolveConfig = (
     ...(flags.rpm === undefined ? {} : { rpm: flags.rpm }),
     ...(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/index.ts

@@ -12,6 +12,20 @@ export {
   type RuleSource,
 } from "#config.ts";
 export { findContradictions, formatContradictions, type Contradiction } from "#contradictions.ts";
+export { cloudflare, type CloudflareOptions } from "#providers/cloudflare.ts";
+export { jev, type JevOptions } from "#providers/jev.ts";
+export { openai, type OpenAIOptions } from "#providers/openai.ts";
+export {
+  type Answered,
+  type AskOptions,
+  ContextOverflow,
+  type Provider,
+  type Question,
+  RequestBlocked,
+  RequestFailed,
+  type SavedKey,
+  type State,
+} from "#providers/provider.ts";
 export { initProject, type InitOptions, type InitResult, type Install } from "#init.ts";
 export { parseRuleMarkdown } from "#markdown.ts";
 export { type PresetName, presetNames } from "#presets.ts";

package/src/markdown.ts

@@ -1,4 +1,4 @@
-import { ConfigUnavailable, type Example, Reads, type Rule } from "#config.ts";
+import { ConfigUnavailable, type Example, type Rule } from "#config.ts";
 import { Effect, Schema } from "effect";
 
 /**
@@ -34,8 +34,7 @@ import { Effect, Schema } from "effect";
  * `warning` reports the rule's findings as warnings, which do not fail a run.
  * `appliesTo` and `excludeIf`, the rule's scope, are JSON arrays of strings on
  * one line, as in `excludeIf: ["a type that mirrors a third-party format"]`.
- * So is `reads`, of the names of what Jev reads for the rule beside the code,
- * as in `reads: ["workspacePackages"]`.
+
  */
 const Matchers = Schema.fromJsonString(Schema.Array(Schema.String));
 
@@ -46,7 +45,6 @@ const FrontMatter = Schema.Struct({
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
   appliesTo: Schema.optionalKey(Matchers),
   excludeIf: Schema.optionalKey(Matchers),
-  reads: Schema.optionalKey(Schema.fromJsonString(Reads)),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -209,7 +207,13 @@ export const parseRuleMarkdown = (
         message: `${file}: a rule starts with front matter between --- lines`,
       });
     }
-    const front = yield* Schema.decodeUnknownEffect(FrontMatter)(parseFrontMatter(match[1])).pipe(
+    const fields = parseFrontMatter(match[1]);
+    if (Object.hasOwn(fields, "reads")) {
+      return yield* ConfigUnavailable.make({
+        message: `${file}: move reads from the rule's front matter to the top level of defineConfig({...}) in your config file.`,
+      });
+    }
+    const front = yield* Schema.decodeUnknownEffect(FrontMatter)(fields).pipe(
       Effect.mapError((problem) =>
         ConfigUnavailable.make({ message: `${file}: ${problem.message}` }),
       ),

package/src/providers/cloudflare.ts

@@ -0,0 +1,84 @@
+/**
+ * Cloudflare's Clef on Workers AI. Clef follows System One, so adhere's
+ * questions go as Jev's provider sends them, but for three differences: at
+ * most 64 questions to a request, ids of letters, digits, `_`, `.` and `-`
+ * where adhere's hold `/` and `:`, and no `choice` of one option. So the
+ * questions go in chunks of 64, each under its place in its chunk, and a
+ * choice of one option is answered by it, unasked.
+ *
+ * Clef cuts a state too long for it short rather than refuse it, and says so
+ * only by the tokens it read: on 2026-10-10, clef read at most 64,000 and
+ * clef-flash 24,000, well under the 65,536 their pages give. A request that
+ * reads that many, or that Workers AI refuses as too large with a 413, is
+ * over the model's context, and skips the file.
+ */
+import { decoded, failed, post } from "#providers/post.ts";
+import { ContextOverflow, type Provider, withoutSingleChoices } from "#providers/provider.ts";
+import { answersOf, requestOf, SystemOneAnswered } from "#providers/systemOne.ts";
+import { Schema } from "effect";
+
+const QUESTIONS_PER_REQUEST = 64;
+const MOST_TOKENS = { clef: 64_000, "clef-flash": 24_000 } as const;
+
+/** Workers AI's envelope around Clef's answers. */
+const Ran = Schema.fromJsonString(Schema.Struct({ result: SystemOneAnswered }));
+
+export interface CloudflareOptions {
+  /** The Cloudflare account that runs the model. */
+  readonly accountId: string;
+  /** A Cloudflare API token that can run Workers AI models. */
+  readonly apiToken: string;
+  /** The model to ask. Defaults to "clef". */
+  readonly model?: "clef" | "clef-flash";
+  /** What sends the requests. Defaults to `fetch`. */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+export const cloudflare = ({
+  accountId,
+  apiToken,
+  model = "clef",
+  fetch,
+}: CloudflareOptions): Provider => ({
+  model,
+  ask: async (state, questions, { signal }) => {
+    const { answers, asked } = withoutSingleChoices(questions);
+    const chunks = Array.from({ length: Math.ceil(asked.length / QUESTIONS_PER_REQUEST) }, (_, n) =>
+      asked.slice(n * QUESTIONS_PER_REQUEST, (n + 1) * QUESTIONS_PER_REQUEST),
+    );
+    const ran = await Promise.all(
+      chunks.map(async (chunk) => {
+        const { response, text } = await post(
+          "Cloudflare",
+          `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/run/@cf/cloudflare/${model}`,
+          { Authorization: `Bearer ${apiToken}` },
+          requestOf(
+            model,
+            state,
+            chunk.map((question, place) => ({ ...question, id: `q${place}` })),
+          ),
+          signal,
+          fetch,
+        );
+        const overflow = () => new ContextOverflow(`The request is over ${model}'s context`);
+        if (response.status === 413) throw overflow();
+        if (!response.ok) throw failed("Cloudflare", response, text);
+        const { result } = decoded("Cloudflare", Ran, text);
+        if ((result.usage?.input_tokens ?? 0) >= MOST_TOKENS[model]) throw overflow();
+        return { chunk, result };
+      }),
+    );
+    for (const { chunk, result } of ran) {
+      const answered = answersOf(result.answers);
+      chunk.forEach((question, place) => {
+        const answer = answered[`q${place}`];
+        if (answer !== undefined) answers[question.id] = answer;
+      });
+    }
+    return {
+      answers,
+      inputTokens: ran.reduce((sum, { result }) => sum + (result.usage?.input_tokens ?? 0), 0),
+      model,
+    };
+  },
+});

package/src/providers/jev.ts

@@ -0,0 +1,66 @@
+/**
+ * TypeSafe's Jev, adhere's default provider: adhere's questions as System One
+ * requests to TypeSafe's API, as adhere built them. With no provider in the
+ * config, adhere asks this one with the key `adhere login` saved, or
+ * `TYPESAFE_API_KEY`; a config names it to ask with another key or model.
+ */
+import { decoded, failed, post } from "#providers/post.ts";
+import { ContextOverflow, type Provider, RequestBlocked } from "#providers/provider.ts";
+import { answersOf, requestOf, SystemOneAnswered } from "#providers/systemOne.ts";
+import { Option, Schema } from "effect";
+
+const SYSTEM_ONE = "https://api.typesafe.ai/v1/systemone";
+
+const Answer = Schema.fromJsonString(SystemOneAnswered);
+
+/** What Jev answers, with a 400, to a request over its context. */
+const Overflowed = Schema.fromJsonString(
+  Schema.Struct({ detail: Schema.Struct({ error_type: Schema.Literal("max_tokens_exceeded") }) }),
+);
+
+export interface JevOptions {
+  /** A TypeSafe AI API key. Defaults to `TYPESAFE_API_KEY`, or the key `adhere login` saved. */
+  readonly apiKey?: string;
+  /** The model to ask. Defaults to "jev-latest". */
+  readonly model?: string;
+  /** What sends the requests. Defaults to `fetch`. */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+export const jev = ({ apiKey, model = "jev-latest", fetch }: JevOptions = {}): Provider => ({
+  model,
+  ...(apiKey === undefined ? { savedKey: "typesafe" as const } : {}),
+  ask: async (state, questions, { apiKey: saved, signal }) => {
+    const key = apiKey ?? saved;
+    if (key === undefined) throw new Error("No TypeSafe AI API key to ask Jev with");
+    const { response, text } = await post(
+      "Jev",
+      SYSTEM_ONE,
+      { Authorization: `Bearer ${key}` },
+      requestOf(model, state, questions),
+      signal,
+      fetch,
+    );
+    if (response.ok) {
+      const answered = decoded("Jev", Answer, text);
+      return {
+        answers: answersOf(answered.answers),
+        inputTokens: answered.usage?.input_tokens,
+        model: answered.model,
+      };
+    }
+    // Over Jev's context, a 400 that skips the file. The firewall in front of
+    // TypeSafe's API answers a 403 with an HTML page, where Jev answers JSON:
+    // a block, with the Ray ID TypeSafe can look it up by.
+    if (response.status === 400 && Option.isSome(Schema.decodeUnknownOption(Overflowed)(text))) {
+      throw new ContextOverflow("The request is over Jev's context");
+    }
+    const html =
+      (response.headers.get("content-type") ?? "").includes("text/html") ||
+      text.trimStart().startsWith("<");
+    if (response.status === 403 && html) {
+      throw new RequestBlocked(response.headers.get("cf-ray") ?? "none given");
+    }
+    throw failed("Jev", response, text);
+  },
+});

package/src/providers/openai.ts

@@ -0,0 +1,89 @@
+/**
+ * OpenAI's Decisions API: each of adhere's questions as a decision question,
+ * a `noul` as a `predicate` and a `choice` as a `choice`. A decision
+ * question's instructions are one string, so they hold the question as
+ * System One asks it, in JSON: the question beside the fields it names, and
+ * what yes and no mean. On the providers study's four repos, gpt-6-luna
+ * ranked findings better and located them more often than with the same parts
+ * in prose. The state is the input, in JSON. A question OpenAI refuses goes
+ * unanswered.
+ */
+import { decoded, failed, post } from "#providers/post.ts";
+import { type Provider, type Question, withoutSingleChoices } from "#providers/provider.ts";
+import { systemOneQuestionOf } from "#providers/systemOne.ts";
+import { Schema } from "effect";
+
+const DECISIONS = "https://api.openai.com/v1/decisions";
+
+/** A decision's answers, in question order: a predicate's probability, a choice's value, or a refusal, which has neither. */
+const Decided = Schema.fromJsonString(
+  Schema.Struct({
+    answers: Schema.Array(
+      Schema.Struct({
+        name: Schema.NullOr(Schema.String),
+        probability: Schema.optionalKey(Schema.Finite),
+        choice: Schema.optionalKey(Schema.Union([Schema.String, Schema.Boolean])),
+      }),
+    ),
+    model: Schema.optionalKey(Schema.String),
+    usage: Schema.optionalKey(Schema.Struct({ input_tokens: Schema.Finite })),
+  }),
+);
+
+/** System One's question without its type, in JSON, or its instructions alone when it says nothing of what yes and no mean. */
+const instructionsOf = (question: Question): string => {
+  const { type, ...asked } = systemOneQuestionOf(question);
+  if (type === "noul" && asked.criteria !== undefined) return JSON.stringify(asked);
+  return typeof asked.instructions === "string"
+    ? asked.instructions
+    : JSON.stringify(asked.instructions);
+};
+
+const decisionOf = (question: Question) =>
+  question.type === "noul"
+    ? { type: "predicate", name: question.id, instructions: instructionsOf(question) }
+    : {
+        type: "choice",
+        name: question.id,
+        instructions: instructionsOf(question),
+        choices: Object.entries(question.options).map(([value, description]) =>
+          description === null ? { value } : { value, description },
+        ),
+      };
+
+export interface OpenAIOptions {
+  /** An OpenAI API key. Defaults to `OPENAI_API_KEY`, or the key `adhere login --openai` saved. */
+  readonly apiKey?: string;
+  /** The model to ask. Defaults to "gpt-6-luna", the only one the Decisions API takes. */
+  readonly model?: string;
+  /** What sends the requests. Defaults to `fetch`. */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+export const openai = ({ apiKey, model = "gpt-6-luna", fetch }: OpenAIOptions = {}): Provider => ({
+  model,
+  ...(apiKey === undefined ? { savedKey: "openai" as const } : {}),
+  ask: async (state, questions, { apiKey: saved, signal }) => {
+    const key = apiKey ?? saved;
+    if (key === undefined) throw new Error("No OpenAI API key to ask gpt-6-luna with");
+    // OpenAI takes no choice of one option.
+    const { answers, asked } = withoutSingleChoices(questions);
+    if (asked.length === 0) return { answers };
+    const { response, text } = await post(
+      "OpenAI",
+      DECISIONS,
+      { Authorization: `Bearer ${key}` },
+      { model, input: JSON.stringify(state), questions: asked.map(decisionOf) },
+      signal,
+      fetch,
+    );
+    if (!response.ok) throw failed("OpenAI", response, text);
+    const decided = decoded("OpenAI", Decided, text);
+    for (const { name, probability, choice } of decided.answers) {
+      if (name === null) continue;
+      if (probability !== undefined) answers[name] = probability;
+      else if (choice !== undefined) answers[name] = String(choice);
+    }
+    return { answers, inputTokens: decided.usage?.input_tokens, model: decided.model };
+  },
+});