@graphoria/server 0.2.1 → 0.2.2

package/src/ai/README.md

@@ -0,0 +1,257 @@
+# ollama_helper
+
+An LLM-powered database query agent that uses tool-calling to discover a PostgreSQL schema, inspect tables, and execute queries — all from a natural language prompt. It is **cross-LLM**: the same agent runs against Ollama (default, local), OpenAI, DeepSeek, Anthropic, and any OpenAI-compatible endpoint — selected with a single env var.
+
+## How It Works
+
+```
+User prompt
+    │
+    ▼
+┌─────────────────────────────────────────────────┐
+│  createAgent({ tools, systemPrompt, wrap })     │
+│  → (prompt) => Promise<string>                  │
+│                                                 │
+│  Agent loop (ask function)                      │
+│  1. Send systemPrompt + wrap(prompt) to LLM     │
+│  2. LLM responds with tool_calls?               │
+│     ├─ Yes → strip nulls, validate via Zod,     │
+│     │        execute tool, feed result back      │
+│     └─ No  → return final answer                │
+│  3. Repeat until answer or max iters            │
+└─────────────────────────────────────────────────┘
+    │
+    ▼
+Final answer (text only — tool calls hidden)
+```
+
+The agent follows a fixed 4-step discovery workflow for every query:
+
+| Step | Tool              | Purpose                                             |
+| ---- | ----------------- | --------------------------------------------------- |
+| 1    | `list_entities`   | Find relevant database tables by keyword search     |
+| 2    | `describe_entity` | Get column names, types, and relationships          |
+| 3    | `query_data`      | Execute the query using structured JSON (preferred) |
+| 3\*  | `graphql_execute` | Raw GraphQL fallback for complex queries            |
+| 4    | —                 | Present results as a Markdown table                 |
+
+Anti-hallucination guards prevent the model from answering without actually querying data.
+
+## Quick Start
+
+**Prerequisites:** an LLM backend. The default is [Ollama](https://ollama.com) (local, free, no API key) running a tool-capable model. To use a hosted provider instead, set `LLM_PROVIDER` and the matching API key (see [Providers](#providers)).
+
+```bash
+# Install dependencies
+bun install
+
+# Run with the default provider (Ollama) and default prompt
+bun run index.ts
+
+# Custom prompt
+bun run index.ts "how many students have an active subscription?"
+
+# Switch providers via env vars
+LLM_PROVIDER=openai    LLM_MODEL=gpt-4o-mini               OPENAI_API_KEY=sk-...        bun run index.ts "list all events"
+LLM_PROVIDER=deepseek  LLM_MODEL=deepseek-chat             DEEPSEEK_API_KEY=sk-...      bun run index.ts "list all events"
+LLM_PROVIDER=anthropic LLM_MODEL=claude-haiku-4-5-20251001 ANTHROPIC_API_KEY=sk-ant-... bun run index.ts "list all events"
+```
+
+### Using as a library
+
+```typescript
+import { createAgent } from "ollama_helper";
+import { tools } from "./src/tools";
+
+// Bind domain config once — call with just a prompt
+const ask = createAgent({
+  tools,
+  systemPrompt: "You are a database assistant…",
+  wrap: (prompt) => `Database query:\n> ${prompt}`,
+});
+
+const answer = await ask("list contacts grouped by role");
+```
+
+## Environment Variables
+
+| Variable            | Default                  | Description                                                 |
+| ------------------- | ------------------------ | ----------------------------------------------------------- |
+| `LLM_PROVIDER`      | `ollama`                 | Backend: `ollama`, `openai`, `deepseek`, or `anthropic`     |
+| `LLM_MODEL`         | per-provider             | Overrides the provider's default model                      |
+| `OPENAI_API_KEY`    | —                        | Required when `LLM_PROVIDER=openai`                         |
+| `OPENAI_BASE_URL`   | —                        | Optional: any OpenAI-compatible endpoint (Groq, Mistral, …) |
+| `DEEPSEEK_API_KEY`  | —                        | Required when `LLM_PROVIDER=deepseek`                       |
+| `ANTHROPIC_API_KEY` | —                        | Required when `LLM_PROVIDER=anthropic`                      |
+| `OLLAMA_HOST`       | `http://localhost:11434` | Ollama server URL                                           |
+| `OLLAMA_MODEL`      | `gemma4:e2b`             | Ollama model (alias of `LLM_MODEL`, kept for back-compat)   |
+
+Defined in `.env` or inline on the command line.
+
+## Providers
+
+The agent talks to every backend through a small `Provider` interface (`src/providers/`). Two wire formats cover everything:
+
+| Provider         | `LLM_PROVIDER` | Default model               | How it connects                    |
+| ---------------- | -------------- | --------------------------- | ---------------------------------- |
+| Ollama (default) | `ollama`       | `gemma4:e2b`                | Native `/api/chat`, local, no key  |
+| OpenAI           | `openai`       | `gpt-4o-mini`               | `openai` SDK                       |
+| DeepSeek         | `deepseek`     | `deepseek-chat`             | `openai` SDK (OpenAI-compatible)   |
+| Anthropic        | `anthropic`    | `claude-haiku-4-5-20251001` | `@anthropic-ai/sdk` (Messages API) |
+
+Because the OpenAI adapter is just a `baseURL` + key, **any OpenAI-compatible endpoint** (Groq, Mistral, Together, a local `/v1` server) works by pointing `OPENAI_BASE_URL` at it — no new code. Adding a first-class provider is one entry in the registry in `src/providers/index.ts`.
+
+The agent loop and anti-hallucination guards are provider-agnostic; each adapter only translates the normalized message/tool-call history to and from its provider's wire format.
+
+## Recommended Ollama Models
+
+| Model          | Size   | Quality | Notes                                                                                         |
+| -------------- | ------ | ------- | --------------------------------------------------------------------------------------------- |
+| **gemma4:e2b** | 7.2 GB | ★★★★★   | **Default.** Native function-calling, built for agentic workflows. Google-recommended params. |
+| gemma4:e4b     | 9.6 GB | ★★★★★   | Stronger reasoning, heavier. Same family, better accuracy.                                    |
+| qwen3.5:2b     | 2.7 GB | ★★★★☆   | Good budget option. Fast, decent tool use.                                                    |
+| llama3.2       | 2.0 GB | ★★☆☆☆   | Works but hallucinates more. Use `OLLAMA_MODEL=llama3.2` to test.                             |
+
+Each model family gets optimal sampling parameters automatically (temperature, top_p, top_k) based on vendor recommendations.
+
+## Project Structure
+
+```
+ollama_helper/
+├── index.ts                  # Library barrel — exports ask, createAgent, AgentConfig
+├── .env                      # Environment variables (OLLAMA_MODEL, OLLAMA_HOST)
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── types.ts              # Normalized Message/ToolCall + Provider + Tool interfaces
+    ├── providers/
+    │   ├── index.ts          # getProvider() — selects the backend from LLM_PROVIDER
+    │   ├── ollama.ts         # Native /api/chat adapter + model presets (default)
+    │   ├── openai.ts         # OpenAI-compatible adapter (OpenAI, DeepSeek, …)
+    │   └── anthropic.ts      # Anthropic Messages API adapter
+    ├── tools.ts              # 4 tool definitions (Zod schemas + mock executors)
+    └── agent.ts              # Agent loop: ask() + createAgent() factory
+```
+
+## API
+
+### `createAgent(config: AgentConfig): (prompt: string) => Promise<string>`
+
+Pre-configure an agent with tools, system prompt, and a prompt wrapper. Returns a single-argument function — call it with any prompt string.
+
+```typescript
+import { createAgent } from "ollama_helper";
+
+const ask = createAgent({
+  tools: [...],                              // Tool[] — Zod-based tool definitions
+  systemPrompt: "You are a helpful agent.",  // System-level instruction to the LLM
+  wrap: (p) => `User query:\n> ${p}`,        // Wraps the raw prompt into the user message
+});
+
+const answer = await ask("list all contacts grouped by role");
+```
+
+### `ask(prompt, tools, systemPrompt, wrap): Promise<string>`
+
+Full-control entry point. Same as `createAgent` but without pre-binding — pass all 4 arguments per call.
+
+```typescript
+import { ask } from "ollama_helper";
+
+const answer = await ask(
+  "list contacts grouped by role",
+  tools,
+  "You are a database assistant.",
+  (p) => `Query: ${p}`,
+);
+```
+
+### `AgentConfig`
+
+| Field          | Type                          | Description                                            |
+| -------------- | ----------------------------- | ------------------------------------------------------ |
+| `tools`        | `Tool[]`                      | Zod-based tool definitions (schema + executor)         |
+| `systemPrompt` | `string`                      | System-level instruction sent to the LLM               |
+| `wrap`         | `(content: string) => string` | Transforms the user prompt into the final user message |
+
+### `Tool`
+
+```typescript
+interface Tool<TSchema extends z.ZodTypeAny> {
+  name: string; // Tool name (must match what the LLM calls)
+  description: string; // Description sent to the LLM
+  schema: TSchema; // Zod schema — auto-converted to JSON Schema
+  execute: (args: z.infer<TSchema>) => Promise<unknown>; // Typed executor
+}
+```
+
+JSON Schema is auto-generated via `z.toJSONSchema(tool.schema)`. The framework automatically strips `null` values from LLM arguments (common with small models) before Zod validation. Use the exported `jsonCoerce` helper for fields that may arrive as stringified JSON arrays/objects.
+
+```typescript
+import { z } from "zod";
+import { jsonCoerce } from "./src/tools";
+
+const mySchema = z.object({
+  columns: jsonCoerce(z.array(z.string())).optional(), // Handles "[\"id\"]" → ["id"]
+  filters: jsonCoerce(z.record(z.string(), z.unknown())).optional(),
+});
+```
+
+## Tools
+
+The agent exposes 4 tools to the LLM. Each is defined as a `Tool` object with a Zod schema and executor:
+
+| Tool              | Description                                                                      |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `list_entities`   | Search for database tables by keyword or category                                |
+| `describe_entity` | Get column metadata, relationships, and data types for a table                   |
+| `query_data`      | Execute a query using structured JSON (preferred for all list/aggregate queries) |
+| `graphql_execute` | Execute a raw GraphQL query (fallback for complex/nested queries)                |
+
+**`query_data` input format:**
+
+```json
+{
+  "entity": "contacts",
+  "operation": "aggregate",
+  "groupBy": ["role"],
+  "columns": ["id", "first_name", "last_name"],
+  "filters": { "deleted_at": { "is_null": true } },
+  "limit": 50
+}
+```
+
+Filter operators: `eq`, `neq`, `like`, `ilike`, `gt`, `gte`, `lt`, `lte`, `is_null`.
+
+## Anti-Hallucination Measures
+
+The agent employs multiple layers to prevent the LLM from fabricating data:
+
+1. **Zod validation** — All tool arguments validated before execution; invalid args → error fed back to LLM for self-correction
+2. **Null stripping** — `null` values for optional fields (common LLM mistake) automatically stripped pre-parse
+3. **JSON coercion** — Stringified JSON arrays/objects auto-parsed via `jsonCoerce` helper
+4. **Temperature control** — Model-specific presets (e.g., temp 0 for llama3.2 to suppress creativity)
+5. **Guard clause** — If the model tries to answer without calling `query_data` or `graphql_execute`, a corrective nudge is injected and the loop retries
+6. **Negative constraints** — Prompts explicitly forbid fabrication: _"NEVER fabricate, invent, or guess query results"_
+
+## Mock Tools
+
+When a real Graphoria server is not available, the tools return hardcoded mock data mirroring the capoeira group management schema:
+
+- **5 tables:** contacts, student_profiles, classes, payments, events
+- **18 contacts** with roles: 12 students, 1 master, 2 guardians, 3 guests
+- **Full column metadata** for the contacts table (11 columns including soft-delete `deleted_at`)
+
+To replace mocks with real server calls, update the executors in `src/tools.ts` to use `fetch()` against the Graphoria REST/GraphQL endpoints.
+
+## Design Decisions
+
+- **`createAgent` factory** — Pre-bind domain config (tools, system prompt, wrap); clean `ask(prompt)` API for callers
+- **`ask()` for full control** — 4 positional params when callers need per-call variations
+- **Zod schemas for tools** — `z.toJSONSchema()` auto-generates JSON Schema parameters; `z.infer` gives type-safe executor args; no hand-written JSON Schema
+- **`stripNulls` applied automatically** — LLMs pass `null` for optional fields; stripped pre-parse so callers write plain Zod schemas
+- **`jsonCoerce` opt-in helper** — Small LLMs stringify arrays/objects; opt-in per-field coercion
+- **Non-streaming only** (`stream: false`) — simpler loop logic; no need to buffer partial tool_calls across chunks
+- **JSON query tool over raw GraphQL** — structured JSON has far fewer syntax failure modes for LLMs than raw GraphQL string construction
+- **Max 10 iterations** — safety valve to prevent infinite tool-calling loops
+- **Bun runtime** — native fetch, zero-config TypeScript, fast startup

package/src/analyzeQuery/analyzers/selectionAnalyzer.ts

@@ -59,7 +59,13 @@ export const analyzeSelections = (
             (dir) => dir.name === "include" || dir.name === "skip" || dir.name === "when",
           ).length === 0;
 
-        if (isArray && entities.queriesMap[fieldName]?.rolePermission?.filter) {
+        // Gated on the field resolving to a table type, not on it being a list.
+        // A role filter has to reach every field backed by the table it
+        // restricts: the `_single` root field and any to-one relationship both
+        // return one object, and both accept a `where` the builders honour, so
+        // skipping them let a caller read a row the filter excludes by asking
+        // for it singly or by traversing into it from an unfiltered table.
+        if (fieldObjType && entities.queriesMap[fieldName]?.rolePermission?.filter) {
           if (!args) {
             args = {
               where: entities.queriesMap[fieldName].rolePermission?.filter,

package/src/analyzeQuery/resolveVariables.ts

@@ -72,6 +72,7 @@ export const extractRuntimePrimitivesToVariables = (
   runtimeVariables: Record<string, unknown>,
   startIndex: number,
   referencedVariables: Set<string> = new Set(),
+  declaredVariableNames?: Set<string>,
 ): unknown => {
   // Handle null/undefined
   if (obj === null || obj === undefined) {
@@ -87,13 +88,23 @@ export const extractRuntimePrimitivesToVariables = (
         runtimeVariables,
         startIndex,
         referencedVariables,
+        declaredVariableNames,
       ),
     );
   }
 
   // Handle primitives - convert to static variable references
   if (typeof obj === "string") {
-    if (obj.startsWith("$")) {
+    // A `$name` string is a reference only when the document declares that
+    // variable. These values arrive from the request body, so anything else
+    // beginning with `$` is data the client sent: `$1` resolved to index -1 and
+    // emitted the placeholder `$0`, and a value naming a real generated
+    // variable would have read that parameter's value instead of matching on
+    // its own text.
+    if (
+      obj.startsWith("$") &&
+      (!declaredVariableNames || declaredVariableNames.has(obj.substring(1)))
+    ) {
       referencedVariables.add(obj.substring(1));
       return obj;
     }
@@ -143,6 +154,7 @@ export const extractRuntimePrimitivesToVariables = (
         runtimeVariables,
         startIndex,
         referencedVariables,
+        declaredVariableNames,
       );
     }
     return result;
@@ -166,6 +178,7 @@ export const flattenObjectVariables = (
   const resolvedObjectVarNames = new Set<string>();
   const nestedReferencedVars = new Set<string>();
   const resolvedMap = new Map<string, unknown>();
+  const declaredVariableNames = new Set(variables.map((variable) => variable.name));
 
   for (const varDef of variables) {
     if (varDef.name.startsWith("static_")) continue;
@@ -184,6 +197,7 @@ export const flattenObjectVariables = (
       resolvedRuntimeValues,
       existingStaticCount,
       nestedReferencedVars,
+      declaredVariableNames,
     );
 
     resolvedMap.set(varDef.name, transformed);
@@ -200,15 +214,67 @@ export const flattenObjectVariables = (
 
 // ─── Step 3: Immutable Field Resolution ─────────────────────────────────────
 
+/**
+ * Where late-resolved values are turned into bound parameters.
+ *
+ * Client-supplied argument values are hoisted into `static_N` variables while
+ * the document is analyzed, so by the time they reach the query builders they
+ * are `$name` references the builders emit as placeholders. Two classes of
+ * value never went through that hoisting, because they are not in the document:
+ * the constants written into a role's permission filter, and the claim values
+ * `$session.*` resolves to. Both were interpolated into the SQL text verbatim.
+ */
+export type VariableSink = {
+  generatedVariables: VariableDefinition[];
+  runtimeVariables: Record<string, unknown>;
+  startIndex: number;
+};
+
+const typeOfValue = (value: unknown): string => {
+  if (typeof value === "number") return Number.isInteger(value) ? "Int" : "Float";
+  if (typeof value === "boolean") return "Boolean";
+  return "String";
+};
+
+/** Binds one value as a fresh `static_N` variable and returns its reference. */
+const parameterize = (sink: VariableSink, value: unknown): unknown => {
+  if (value === null || value === undefined) return value;
+
+  // An array operand (`in`) is bound element-wise: the builders emit one
+  // placeholder per element.
+  if (Array.isArray(value)) return value.map((item) => parameterize(sink, item));
+
+  if (typeof value === "object") return value;
+
+  const name = `static_${sink.startIndex + sink.generatedVariables.length}`;
+
+  sink.generatedVariables.push({
+    name,
+    type: typeOfValue(value),
+    required: false,
+    defaultValue: value as never,
+  });
+  sink.runtimeVariables[name] = value;
+
+  return `$${name}`;
+};
+
 /**
  * Replaces `$session.*` placeholders in any argument value.
  * Walks all arguments, not just `where`.
+ *
+ * Substituted claim values are bound as parameters on the way out. Doing it
+ * here rather than in the `where` pass below matters: a claim whose value
+ * happens to begin with `$` would otherwise be indistinguishable from a
+ * variable reference, and would resolve to some other parameter's value.
  */
 const resolveSessionInArguments = (
   args: Record<string, unknown>,
   session: SessionContext,
+  sink?: VariableSink,
 ): Record<string, unknown> => {
   const result: Record<string, unknown> = {};
+  const onResolved = sink ? (value: unknown) => parameterize(sink, value) : undefined;
 
   for (const [key, value] of Object.entries(args)) {
     if (
@@ -217,7 +283,7 @@ const resolveSessionInArguments = (
       !Array.isArray(value) &&
       hasSessionVariables(value as Record<string, unknown>)
     ) {
-      result[key] = replaceSessionVariables(value as Record<string, unknown>, session);
+      result[key] = replaceSessionVariables(value as Record<string, unknown>, session, onResolved);
     } else {
       result[key] = value;
     }
@@ -226,6 +292,33 @@ const resolveSessionInArguments = (
   return result;
 };
 
+/**
+ * Binds every literal still sitting in a `where` argument.
+ *
+ * Only `where` is walked. `orderBy` carries direction enums and `limit`/`offset`
+ * are consumed by the pagination builder, and neither is emitted as a bound
+ * value, so parameterizing them would change the SQL rather than protect it.
+ */
+const parameterizeWhereLiterals = (value: unknown, sink: VariableSink): unknown => {
+  if (value === null || value === undefined) return value;
+
+  if (Array.isArray(value)) return value.map((item) => parameterizeWhereLiterals(item, sink));
+
+  if (typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, nested]) => [
+        key,
+        parameterizeWhereLiterals(nested, sink),
+      ]),
+    );
+  }
+
+  // Already a reference — the analyzer hoisted it out of the document.
+  if (isString(value) && value.startsWith("$")) return value;
+
+  return parameterize(sink, value);
+};
+
 /**
  * Recursively replaces `$varName` references with their resolved (already-flattened) values from
  * `resolvedMap`, walking nested objects/arrays so a reference nested inside an inline argument
@@ -268,6 +361,7 @@ export const resolveFieldArguments = (
   fields: SelectionAnalysis[],
   resolvedMap: Map<string, unknown>,
   session?: SessionContext,
+  sink?: VariableSink,
 ): SelectionAnalysis[] => {
   return fields.map((field) => {
     let newArguments = field.arguments;
@@ -287,13 +381,19 @@ export const resolveFieldArguments = (
 
       // Replace session variables in ALL argument values (not just where)
       if (session) {
-        newArguments = resolveSessionInArguments(newArguments, session);
+        newArguments = resolveSessionInArguments(newArguments, session, sink);
+      }
+
+      // Bind whatever literals remain in `where`. After the two passes above the
+      // only ones left are the constants a role filter was configured with.
+      if (sink && newArguments["where"] !== undefined) {
+        newArguments["where"] = parameterizeWhereLiterals(newArguments["where"], sink);
       }
     }
 
     // Recurse into nested selections
     const newSelections = field.selections
-      ? resolveFieldArguments(field.selections, resolvedMap, session)
+      ? resolveFieldArguments(field.selections, resolvedMap, session, sink)
       : field.selections;
 
     // Only create a new field object if something changed
@@ -381,15 +481,20 @@ export const resolveVariables = (
   const hasVars = operation.variables && operation.variables.length > 0;
 
   if (!hasVars) {
-    // No variable definitions — still need to resolve session variables in fields
-    const fields = session
-      ? resolveFieldArguments(operation.fields, new Map(), session)
-      : operation.fields;
+    // A document with no variables of its own can still carry a role filter,
+    // whose constants and session values both need binding.
+    const sink: VariableSink = {
+      generatedVariables: [],
+      runtimeVariables: {},
+      startIndex: 0,
+    };
+
+    const fields = resolveFieldArguments(operation.fields, new Map(), session, sink);
 
     return {
       fields,
-      variables: operation.variables ?? [],
-      allVariables: { ...variables },
+      variables: [...(operation.variables ?? []), ...sink.generatedVariables],
+      allVariables: { ...variables, ...sink.runtimeVariables },
     };
   }
 
@@ -404,10 +509,15 @@ export const resolveVariables = (
   );
 
   // 3. Resolve field arguments (immutable)
-  const fields =
-    flattenResult.resolvedMap.size > 0 || session
-      ? resolveFieldArguments(operation.fields, flattenResult.resolvedMap, session)
-      : operation.fields;
+  // Numbering continues past the statics flattening just produced, so the two
+  // passes cannot mint the same name.
+  const sink: VariableSink = {
+    generatedVariables: [],
+    runtimeVariables: {},
+    startIndex: existingStaticCount + flattenResult.newStaticVariables.length,
+  };
+
+  const fields = resolveFieldArguments(operation.fields, flattenResult.resolvedMap, session, sink);
 
   // 4. Build final variable list and merged values
   const { variables: resolvedVarDefs, allVariables } = buildFinalVariables(
@@ -416,9 +526,13 @@ export const resolveVariables = (
     variables,
   );
 
+  const finalVarDefs = resolvedVarDefs.length > 0 ? resolvedVarDefs : operation.variables!;
+
   return {
     fields,
-    variables: resolvedVarDefs.length > 0 ? resolvedVarDefs : operation.variables!,
-    allVariables,
+    // Appended, never reordered: the builders emit `$n` from a definition's
+    // index in this list, and the driver binds it from the same list.
+    variables: [...finalVarDefs, ...sink.generatedVariables],
+    allVariables: { ...allVariables, ...sink.runtimeVariables },
   };
 };

package/src/config/types/auth.ts

@@ -64,11 +64,17 @@ export type FilterOperator = (typeof FILTER_OPERATORS)[number];
  * holding more of the same. Operators are constrained to the implemented set so
  * a typo fails at boot instead of evaluating to no condition, which would hand
  * the role the whole table.
+ *
+ * `partialRecord`, not `record`: an enum-keyed `z.record` is exhaustive, and
+ * `z.unknown()` accepts `undefined`, so the plain spelling parses
+ * `{ eq: … }` into an object carrying all twelve operator keys. The extra keys
+ * are invisible to JSON.stringify but reach buildCondition through
+ * Object.entries, which then evaluates operators the filter never declared.
  */
 export const FilterConditionZod: z.ZodType<Record<string, unknown>> = z.lazy(() =>
   z.record(
     z.string(),
-    z.union([z.record(z.enum(FILTER_OPERATORS), z.unknown()), FilterConditionZod]),
+    z.union([z.partialRecord(z.enum(FILTER_OPERATORS), z.unknown()), FilterConditionZod]),
   ),
 );
 

package/src/config/types/db.ts

@@ -138,6 +138,14 @@ export const BunSQLConnectionOptionsZod = z.strictObject({
   maxLifetime: z.number().nonnegative().default(3600),
   /** Whether to use TLS/SSL for the connection */
   tls: z.boolean().default(false),
+  /**
+   * MySQL only: allow the client to fetch the server's RSA public key over a
+   * plain connection when caching_sha2_password asks for full authentication.
+   * Off by default, as it is in Bun: without TLS a man-in-the-middle can answer
+   * with its own key and read the password. Needed for MySQL 8 servers that are
+   * reachable only over plain TCP.
+   */
+  allowPublicKeyRetrieval: z.boolean().default(false),
   /** Automatic creation of prepared statements (default: true) */
   prepare: z.boolean().default(true),
   /** Return values outside i32 range as BigInts instead of strings (default: false) */

package/src/databases/engines/mysql/connection.ts

@@ -22,6 +22,7 @@ export const getPool = async (db: Database) => {
     connectionTimeout: opts?.connectionTimeout,
     maxLifetime: opts?.maxLifetime,
     tls: opts?.tls,
+    allowPublicKeyRetrieval: opts?.allowPublicKeyRetrieval,
     prepare: opts?.prepare,
     bigint: opts?.bigint,
   });

package/src/logging/index.ts

@@ -3,7 +3,9 @@ import pino from "pino";
 const DEFAULT_LEVEL =
   process.env.LOG_LEVEL || (process.env.NODE_ENV === "production" ? "info" : "debug");
 
-const isDev = process.env.NODE_ENV !== "production";
+// `bun test` sets NODE_ENV=test: pino-pretty runs on a worker thread, and
+// Bun's test runner cannot construct one (thread-stream crashes on import).
+const isDev = process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test";
 
 const DEFAULT_OPTIONS: pino.LoggerOptions = {
   level: DEFAULT_LEVEL,

package/src/types/db.ts

@@ -15,7 +15,6 @@ import {
   TableColumnZod,
   TableZod,
   ViewZod,
-  VirtualColumnZod,
 } from "./zod/db";
 
 // Re-export VirtualColumnType from the config module

package/src/types/zod/db.ts

@@ -1,12 +1,6 @@
 import { z } from "zod";
 
-import {
-  BunSQLConnectionOptionsZod,
-  DatabaseConnectionZod,
-  DatabaseSchemaConfigZod,
-  MSSQLConnectionOptionsZod,
-  TableRelationshipZod as TableRelationshipBaseZod,
-} from "../../config";
+import { TableRelationshipZod as TableRelationshipBaseZod } from "../../config";
 import { genResolverName } from "../../databases/transformers/genResolverName";
 import { sanitizeGraphQLName } from "../../databases/transformers/graphqlName";
 

package/src/types/zod/queue.ts

@@ -1,15 +1,7 @@
 import { z } from "zod";
 
-import {
-  BaseQueueConfigZod,
-  KafkaConnectionZod,
-  PublisherConfigZod,
-  RabbitMQConnectionZod,
-  ReconnectConfigZod,
-  SubscriberConfigZod,
-  TopicConfigZod,
-} from "../../config";
-import type { CacheContext, SubscriberHandler } from "../../config";
+import { BaseQueueConfigZod, KafkaConnectionZod, RabbitMQConnectionZod } from "../../config";
+import type { SubscriberHandler } from "../../config";
 
 // Re-export base types and schemas from the config module
 export type {

package/src/utils/sessionVariables.ts

@@ -37,6 +37,10 @@ const resolveDotPath = (obj: Record<string, unknown>, path: string): unknown =>
  *
  * @param filter - Filter object with potential session variables
  * @param session - JWT payload containing user session data
+ * @param onResolved - Called with each substituted claim value; its return value
+ *   is what lands in the filter. The caller uses this to parameterize the value
+ *   rather than letting it be inlined into SQL — a claim is attacker-influenced
+ *   whenever users can change their own profile data.
  * @returns Filter object with session variables replaced
  *
  * @example
@@ -54,6 +58,7 @@ const resolveDotPath = (obj: Record<string, unknown>, path: string): unknown =>
 export const replaceSessionVariables = (
   filter: Record<string, unknown>,
   session: SessionContext | null,
+  onResolved?: (value: unknown) => unknown,
 ): Record<string, unknown> => {
   if (!filter || !session) {
     return filter;
@@ -79,7 +84,7 @@ export const replaceSessionVariables = (
             );
           }
 
-          processedOperators[operator] = sessionValue;
+          processedOperators[operator] = onResolved ? onResolved(sessionValue) : sessionValue;
         }
         // Recursively handle nested objects
         else if (
@@ -90,6 +95,7 @@ export const replaceSessionVariables = (
           processedOperators[operator] = replaceSessionVariables(
             operatorValue as Record<string, unknown>,
             session,
+            onResolved,
           );
         }
         // Keep other values as-is