@graphoria/server 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphoria/server",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Auto-generated GraphQL and REST APIs from database schema - Connect your database to modern APIs instantly",
   "keywords": [
     "auto-generated",

package/src/analyzeQuery/resolveVariables.ts

@@ -226,6 +226,37 @@ const resolveSessionInArguments = (
   return result;
 };
 
+/**
+ * Recursively replaces `$varName` references with their resolved (already-flattened) values from
+ * `resolvedMap`, walking nested objects/arrays so a reference nested inside an inline argument
+ * object (e.g. `where: { rel: { sub: $where } }`) is substituted like a top-level one. The resolved
+ * value is inserted as-is — it is not walked further, so its own `$static_N` leaves survive for SQL
+ * parameter binding. Refs absent from `resolvedMap` (scalar vars, `$session.*`) pass through.
+ */
+const substituteResolvedRefs = (value: unknown, resolvedMap: Map<string, unknown>): unknown => {
+  if (isString(value)) {
+    if (value.startsWith("$")) {
+      const varName = value.substring(1);
+      if (resolvedMap.has(varName)) return resolvedMap.get(varName);
+    }
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => substituteResolvedRefs(item, resolvedMap));
+  }
+
+  if (value !== null && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, nested] of Object.entries(value)) {
+      result[key] = substituteResolvedRefs(nested, resolvedMap);
+    }
+    return result;
+  }
+
+  return value;
+};
+
 /**
  * Returns a new field tree with:
  * 1. `$varName` argument references replaced with their resolved objects from `resolvedMap`
@@ -245,13 +276,12 @@ export const resolveFieldArguments = (
       // Shallow-copy arguments so we don't mutate originals
       newArguments = { ...field.arguments };
 
-      // Replace object variable references in arguments
-      for (const [key, value] of Object.entries(newArguments)) {
-        if (isString(value) && value.startsWith("$")) {
-          const varName = value.substring(1);
-          if (resolvedMap.has(varName)) {
-            newArguments[key] = resolvedMap.get(varName);
-          }
+      // Replace object variable references anywhere in arguments — top-level (`where: $where`) or
+      // nested inside an inline object (`where: { rel: { sub: $where } }`). Only walk when there is
+      // something to substitute so the session-only path stays a no-op.
+      if (resolvedMap.size > 0) {
+        for (const [key, value] of Object.entries(newArguments)) {
+          newArguments[key] = substituteResolvedRefs(value, resolvedMap);
         }
       }
 

package/src/config/helpers/operationHelper.ts

@@ -1,10 +1,15 @@
+import { print } from "graphql";
 import { z } from "zod";
 
+import type { DocumentNode } from "graphql";
 import type {
+  AnyQueryDocument,
   DefaultInput,
   HandlerOperation,
   OperationHandler,
+  OperationOptions,
   QueryOperation,
+  QueryResultOf,
   TypedOperation,
 } from "../types/operation";
 
@@ -22,6 +27,70 @@ type InferInput<TInputSchema> = TInputSchema extends z.ZodType<infer T> ? T : De
  */
 type InferOutput<TOutputSchema> = TOutputSchema extends z.ZodType<infer T> ? T : unknown;
 
+/**
+ * Infer the parsed shape of an optional REST parameter schema.
+ * Resolves to `undefined` when that source has no schema configured.
+ *
+ * Mirrors the helpers on the `OperationFn` authoring surface so both
+ * `operation()` entry points expose identical `beforeRequest` context types.
+ */
+type InferRestParam<T> = T extends z.ZodType<infer O> ? O : undefined;
+
+/**
+ * REST exposure config with per-source schema generics, so `pathParams`,
+ * `queryParams`, and `body` can be inferred into the `beforeRequest` context.
+ */
+type RestConfigInput<
+  TPathParams extends z.ZodType | undefined,
+  TQueryParams extends z.ZodType | undefined,
+  TBody extends z.ZodType | undefined,
+> = {
+  /** Route path (e.g. `/users/:id`) */
+  path: string;
+  /** HTTP method (defaults to GET) */
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  /** Zod schema for path parameters */
+  pathParams?: TPathParams;
+  /** Zod schema for query-string parameters */
+  queryParams?: TQueryParams;
+  /** Zod schema for the request body */
+  body?: TBody;
+};
+
+/**
+ * Hooks config where `beforeRequest` receives the merged `input` plus each REST
+ * source (`pathParams` / `queryParams` / `body`) typed from its schema, or
+ * `undefined` when that source's schema is omitted.
+ */
+type OperationHooksConfig<
+  TInput,
+  TOutput,
+  TInitData,
+  TPathParams extends z.ZodType | undefined,
+  TQueryParams extends z.ZodType | undefined,
+  TBody extends z.ZodType | undefined,
+  TAfterInput = TOutput,
+> = {
+  init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
+  beforeRequest?: (
+    context: {
+      input: TInput;
+      pathParams: InferRestParam<TPathParams>;
+      queryParams: InferRestParam<TQueryParams>;
+      body: InferRestParam<TBody>;
+    },
+    initData: TInitData | undefined,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  /**
+   * Transforms the result after a successful query/handler. `output` is the
+   * upstream value: for query operations the query result (typed from a gql.tada
+   * `query` document, otherwise `unknown`); for handler operations the handler's
+   * return. The value you return becomes the response payload, typed by the
+   * operation's `output` schema.
+   */
+  afterRequest?: (context: { output: TAfterInput }) => TOutput | Promise<TOutput>;
+};
+
 /**
  * Config type for handler-based operations with inference
  */
@@ -30,13 +99,25 @@ type HandlerOperationConfig<
   TInputSchema extends z.ZodType | undefined,
   TOutputSchema extends z.ZodType | undefined,
   TInitData,
+  TPathParams extends z.ZodType | undefined,
+  TQueryParams extends z.ZodType | undefined,
+  TBody extends z.ZodType | undefined,
 > = Omit<
   HandlerOperation<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TInitData, TRepository>,
-  "handler" | "input" | "output"
+  "handler" | "input" | "output" | "hooks" | "rest"
 > & {
   input?: TInputSchema;
   output?: TOutputSchema;
   handler: OperationHandler<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TRepository>;
+  hooks?: OperationHooksConfig<
+    InferInput<TInputSchema>,
+    InferOutput<TOutputSchema>,
+    TInitData,
+    TPathParams,
+    TQueryParams,
+    TBody
+  >;
+  rest?: RestConfigInput<TPathParams, TQueryParams, TBody>;
 };
 
 /**
@@ -46,12 +127,28 @@ type QueryOperationConfig<
   TInputSchema extends z.ZodType | undefined,
   TOutputSchema extends z.ZodType | undefined,
   TInitData,
+  TPathParams extends z.ZodType | undefined,
+  TQueryParams extends z.ZodType | undefined,
+  TBody extends z.ZodType | undefined,
+  TQuery extends string | AnyQueryDocument,
 > = Omit<
   QueryOperation<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TInitData>,
-  "input" | "output"
+  "input" | "output" | "hooks" | "rest" | "query"
 > & {
+  /** GraphQL query to execute (a string or a gql.tada `graphql()` document) */
+  query: TQuery;
   input?: TInputSchema;
   output?: TOutputSchema;
+  hooks?: OperationHooksConfig<
+    InferInput<TInputSchema>,
+    InferOutput<TOutputSchema>,
+    TInitData,
+    TPathParams,
+    TQueryParams,
+    TBody,
+    QueryResultOf<TQuery>
+  >;
+  rest?: RestConfigInput<TPathParams, TQueryParams, TBody>;
 };
 
 // Overload 1: Query-based operation (has `query`, no `handler`)
@@ -59,8 +156,20 @@ export function operation<
   TInputSchema extends z.ZodType | undefined = undefined,
   TOutputSchema extends z.ZodType | undefined = undefined,
   TInitData = unknown,
+  TPathParams extends z.ZodType | undefined = undefined,
+  TQueryParams extends z.ZodType | undefined = undefined,
+  TBody extends z.ZodType | undefined = undefined,
+  TQuery extends string | AnyQueryDocument = string,
 >(
-  config: QueryOperationConfig<TInputSchema, TOutputSchema, TInitData>,
+  config: QueryOperationConfig<
+    TInputSchema,
+    TOutputSchema,
+    TInitData,
+    TPathParams,
+    TQueryParams,
+    TBody,
+    TQuery
+  >,
 ): QueryOperation<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TInitData>;
 
 // Overload 2: Handler-based operation without custom repository type (no generic provided)
@@ -68,12 +177,33 @@ export function operation<
   TInputSchema extends z.ZodType | undefined = undefined,
   TOutputSchema extends z.ZodType | undefined = undefined,
   TInitData = unknown,
+  TPathParams extends z.ZodType | undefined = undefined,
+  TQueryParams extends z.ZodType | undefined = undefined,
+  TBody extends z.ZodType | undefined = undefined,
 >(
-  config: HandlerOperationConfig<unknown, TInputSchema, TOutputSchema, TInitData>,
+  config: HandlerOperationConfig<
+    unknown,
+    TInputSchema,
+    TOutputSchema,
+    TInitData,
+    TPathParams,
+    TQueryParams,
+    TBody
+  >,
 ): HandlerOperation<InferInput<TInputSchema>, InferOutput<TOutputSchema>, TInitData, unknown>;
 
 // Implementation
 export function operation(config: unknown): unknown {
+  // gql.tada's `graphql()` yields a DocumentNode; normalize it to a string so
+  // the rest of the pipeline (validation, analyzeQuery) keeps working on strings.
+  const query = (config as { query?: unknown } | null | undefined)?.query;
+  if (
+    query != null &&
+    typeof query === "object" &&
+    (query as { kind?: unknown }).kind === "Document"
+  ) {
+    return { ...(config as object), query: print(query as DocumentNode) };
+  }
   return config;
 }
 
@@ -106,8 +236,19 @@ operation.typed = <TRepository>() => {
     TInputSchema extends z.ZodType | undefined = undefined,
     TOutputSchema extends z.ZodType | undefined = undefined,
     TInitData = unknown,
+    TPathParams extends z.ZodType | undefined = undefined,
+    TQueryParams extends z.ZodType | undefined = undefined,
+    TBody extends z.ZodType | undefined = undefined,
   >(
-    config: HandlerOperationConfig<TRepository, TInputSchema, TOutputSchema, TInitData>,
+    config: HandlerOperationConfig<
+      TRepository,
+      TInputSchema,
+      TOutputSchema,
+      TInitData,
+      TPathParams,
+      TQueryParams,
+      TBody
+    >,
   ): HandlerOperation<
     InferInput<TInputSchema>,
     InferOutput<TOutputSchema>,

package/src/config/index.ts

@@ -22,6 +22,7 @@
 import { z } from "zod";
 
 import type {
+  AnyQueryDocument,
   ConfigurationInput,
   CreateOneToBooleanMSSQLFn,
   CreateYAndNToBooleanMSSQLFn,
@@ -30,7 +31,7 @@ import type {
   OperationGraphQLConfig,
   OperationHandler,
   OperationOptions,
-  OperationRestConfig,
+  QueryResultOf,
   TypedOperation,
   VirtualColumnExpressionFn,
   VirtualColumnFunctionFn,
@@ -52,6 +53,67 @@ type InferZodOutput<T> = T extends z.ZodType<infer O, any, any> ? O : never;
 type InferOutput<TOutputSchema> =
   TOutputSchema extends z.ZodType<any> ? InferZodOutput<TOutputSchema> : unknown;
 
+/**
+ * Infer the parsed shape of an optional REST parameter schema.
+ * Resolves to `undefined` when that source has no schema configured.
+ */
+type InferRestParam<T> = T extends z.ZodType<any> ? z.infer<T> : undefined;
+
+/**
+ * REST exposure config with per-source schema generics, so `pathParams`,
+ * `queryParams`, and `body` can be inferred into the `beforeRequest` context.
+ */
+type RestConfigInput<
+  TPathParams extends z.ZodType<any> | undefined,
+  TQueryParams extends z.ZodType<any> | undefined,
+  TBody extends z.ZodType<any> | undefined,
+> = {
+  /** Route path (e.g. `/users/:id`) */
+  path: string;
+  /** HTTP method (defaults to GET) */
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  /** Zod schema for path parameters */
+  pathParams?: TPathParams;
+  /** Zod schema for query-string parameters */
+  queryParams?: TQueryParams;
+  /** Zod schema for the request body */
+  body?: TBody;
+};
+
+/**
+ * Hooks config shared by every operation overload. `beforeRequest` receives the
+ * merged `input` plus each REST source (`pathParams` / `queryParams` / `body`)
+ * typed from its schema, or `undefined` when that source's schema is omitted.
+ */
+type OperationHooks<
+  TInput,
+  TOutput,
+  TInitData,
+  TPathParams extends z.ZodType<any> | undefined,
+  TQueryParams extends z.ZodType<any> | undefined,
+  TBody extends z.ZodType<any> | undefined,
+  TAfterInput = TOutput,
+> = {
+  init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
+  beforeRequest?: (
+    context: {
+      input: TInput;
+      pathParams: InferRestParam<TPathParams>;
+      queryParams: InferRestParam<TQueryParams>;
+      body: InferRestParam<TBody>;
+    },
+    initData: TInitData | undefined,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  /**
+   * Transforms the result after a successful query/handler. `output` is the
+   * upstream value: for query operations the query result (typed from a gql.tada
+   * `query` document, otherwise `unknown`); for handler operations the handler's
+   * return. The value you return becomes the response payload, typed by the
+   * operation's `output` schema.
+   */
+  afterRequest?: (context: { output: TAfterInput }) => TOutput | Promise<TOutput>;
+};
+
 /**
  * Type for the operation helper function provided by @graphoria/server.
  *
@@ -64,9 +126,13 @@ export type OperationFn = {
     TInputSchema extends z.ZodObject<any>,
     TOutputSchema extends z.ZodType<any> | undefined = undefined,
     TInitData = unknown,
+    TPathParams extends z.ZodType<any> | undefined = undefined,
+    TQueryParams extends z.ZodType<any> | undefined = undefined,
+    TBody extends z.ZodType<any> | undefined = undefined,
+    TQuery extends string | AnyQueryDocument = string,
   >(config: {
-    /** GraphQL query to execute */
-    query: string;
+    /** GraphQL query to execute (a string or a gql.tada `graphql()` document) */
+    query: TQuery;
     /** Custom handler is not allowed with query */
     handler?: never;
     /** Description for documentation */
@@ -76,18 +142,17 @@ export type OperationFn = {
     /** Output schema (Zod) */
     output?: TOutputSchema;
     /** Hooks for initialization and request transformation */
-    hooks?: {
-      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
-      beforeRequest?: (
-        context: { input: z.infer<TInputSchema> },
-        initData: TInitData | undefined,
-      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
-      afterRequest?: (context: {
-        output: InferOutput<TOutputSchema>;
-      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
-    };
+    hooks?: OperationHooks<
+      z.infer<TInputSchema>,
+      InferOutput<TOutputSchema>,
+      TInitData,
+      TPathParams,
+      TQueryParams,
+      TBody,
+      QueryResultOf<TQuery>
+    >;
     /** REST exposure configuration */
-    rest?: OperationRestConfig;
+    rest?: RestConfigInput<TPathParams, TQueryParams, TBody>;
     /** GraphQL exposure configuration (enabled by default) */
     graphql?: OperationGraphQLConfig;
     /** Cache configuration */
@@ -95,9 +160,16 @@ export type OperationFn = {
   }): TypedOperation<z.infer<TInputSchema>, InferOutput<TOutputSchema>, TInitData, unknown>;
 
   // Query operation overload - without input schema
-  <TOutputSchema extends z.ZodType<any> | undefined = undefined, TInitData = unknown>(config: {
-    /** GraphQL query to execute */
-    query: string;
+  <
+    TOutputSchema extends z.ZodType<any> | undefined = undefined,
+    TInitData = unknown,
+    TPathParams extends z.ZodType<any> | undefined = undefined,
+    TQueryParams extends z.ZodType<any> | undefined = undefined,
+    TBody extends z.ZodType<any> | undefined = undefined,
+    TQuery extends string | AnyQueryDocument = string,
+  >(config: {
+    /** GraphQL query to execute (a string or a gql.tada `graphql()` document) */
+    query: TQuery;
     /** Custom handler is not allowed with query */
     handler?: never;
     /** Description for documentation */
@@ -107,18 +179,17 @@ export type OperationFn = {
     /** Output schema (Zod) */
     output?: TOutputSchema;
     /** Hooks for initialization and request transformation */
-    hooks?: {
-      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
-      beforeRequest?: (
-        context: { input: DefaultInput },
-        initData: TInitData | undefined,
-      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
-      afterRequest?: (context: {
-        output: InferOutput<TOutputSchema>;
-      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
-    };
+    hooks?: OperationHooks<
+      DefaultInput,
+      InferOutput<TOutputSchema>,
+      TInitData,
+      TPathParams,
+      TQueryParams,
+      TBody,
+      QueryResultOf<TQuery>
+    >;
     /** REST exposure configuration */
-    rest?: OperationRestConfig;
+    rest?: RestConfigInput<TPathParams, TQueryParams, TBody>;
     /** GraphQL exposure configuration (enabled by default) */
     graphql?: OperationGraphQLConfig;
     /** Cache configuration */
@@ -130,6 +201,9 @@ export type OperationFn = {
     TInputSchema extends z.ZodObject<any>,
     TOutputSchema extends z.ZodType<any> | undefined = undefined,
     TInitData = unknown,
+    TPathParams extends z.ZodType<any> | undefined = undefined,
+    TQueryParams extends z.ZodType<any> | undefined = undefined,
+    TBody extends z.ZodType<any> | undefined = undefined,
   >(config: {
     /** Query is not allowed with handler */
     query?: never;
@@ -142,18 +216,16 @@ export type OperationFn = {
     /** Output schema (Zod) */
     output?: TOutputSchema;
     /** Hooks for initialization and request transformation */
-    hooks?: {
-      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
-      beforeRequest?: (
-        context: { input: z.infer<TInputSchema> },
-        initData: TInitData | undefined,
-      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
-      afterRequest?: (context: {
-        output: InferOutput<TOutputSchema>;
-      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
-    };
+    hooks?: OperationHooks<
+      z.infer<TInputSchema>,
+      InferOutput<TOutputSchema>,
+      TInitData,
+      TPathParams,
+      TQueryParams,
+      TBody
+    >;
     /** REST exposure configuration */
-    rest?: OperationRestConfig;
+    rest?: RestConfigInput<TPathParams, TQueryParams, TBody>;
     /** GraphQL exposure configuration (enabled by default) */
     graphql?: OperationGraphQLConfig;
     /** Cache configuration */
@@ -161,7 +233,13 @@ export type OperationFn = {
   }): TypedOperation<z.infer<TInputSchema>, InferOutput<TOutputSchema>, TInitData, unknown>;
 
   // Handler operation overload - without input schema
-  <TOutputSchema extends z.ZodType<any> | undefined = undefined, TInitData = unknown>(config: {
+  <
+    TOutputSchema extends z.ZodType<any> | undefined = undefined,
+    TInitData = unknown,
+    TPathParams extends z.ZodType<any> | undefined = undefined,
+    TQueryParams extends z.ZodType<any> | undefined = undefined,
+    TBody extends z.ZodType<any> | undefined = undefined,
+  >(config: {
     /** Query is not allowed with handler */
     query?: never;
     /** Custom handler function */
@@ -173,18 +251,16 @@ export type OperationFn = {
     /** Output schema (Zod) */
     output?: TOutputSchema;
     /** Hooks for initialization and request transformation */
-    hooks?: {
-      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
-      beforeRequest?: (
-        context: { input: DefaultInput },
-        initData: TInitData | undefined,
-      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
-      afterRequest?: (context: {
-        output: InferOutput<TOutputSchema>;
-      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
-    };
+    hooks?: OperationHooks<
+      DefaultInput,
+      InferOutput<TOutputSchema>,
+      TInitData,
+      TPathParams,
+      TQueryParams,
+      TBody
+    >;
     /** REST exposure configuration */
-    rest?: OperationRestConfig;
+    rest?: RestConfigInput<TPathParams, TQueryParams, TBody>;
     /** GraphQL exposure configuration (enabled by default) */
     graphql?: OperationGraphQLConfig;
     /** Cache configuration */
@@ -203,6 +279,9 @@ export type OperationFn = {
     TInputSchema extends z.ZodObject<any>,
     TOutputSchema extends z.ZodType<any> | undefined = undefined,
     TInitData = unknown,
+    TPathParams extends z.ZodType<any> | undefined = undefined,
+    TQueryParams extends z.ZodType<any> | undefined = undefined,
+    TBody extends z.ZodType<any> | undefined = undefined,
   >(config: {
     /** Query is not allowed with handler */
     query?: never;
@@ -215,18 +294,16 @@ export type OperationFn = {
     /** Output schema (Zod) */
     output?: TOutputSchema;
     /** Hooks for initialization and request transformation */
-    hooks?: {
-      init?: (options: OperationOptions) => TInitData | Promise<TInitData>;
-      beforeRequest?: (
-        context: { input: z.infer<TInputSchema> },
-        initData: TInitData | undefined,
-      ) => Record<string, unknown> | Promise<Record<string, unknown>>;
-      afterRequest?: (context: {
-        output: InferOutput<TOutputSchema>;
-      }) => InferOutput<TOutputSchema> | Promise<InferOutput<TOutputSchema>>;
-    };
+    hooks?: OperationHooks<
+      z.infer<TInputSchema>,
+      InferOutput<TOutputSchema>,
+      TInitData,
+      TPathParams,
+      TQueryParams,
+      TBody
+    >;
     /** REST exposure configuration */
-    rest?: OperationRestConfig;
+    rest?: RestConfigInput<TPathParams, TQueryParams, TBody>;
     /** GraphQL exposure configuration (enabled by default) */
     graphql?: OperationGraphQLConfig;
     /** Cache configuration */

package/src/config/types/ai.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
  * Model Context Protocol (MCP) server configuration, nested under `ai.mcp`.
  * When enabled, exposes a `/mcp` endpoint for LLM agents.
  */
-export const MCPZod = z.object({
+export const MCPZod = z.strictObject({
   /** Whether the MCP server is enabled. Off by default. */
   enabled: z.boolean().default(false),
 });
@@ -20,7 +20,7 @@ export type MCPConfig = z.input<typeof MCPZod>;
  * (`LLM_PROVIDER`, `LLM_MODEL`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
  * `DEEPSEEK_API_KEY`, `OLLAMA_HOST`), not from this config.
  */
-export const AIZod = z.object({
+export const AIZod = z.strictObject({
   /** Whether the AI agent is enabled. Off by default. */
   enabled: z.boolean().default(false),
   /** Overrides the built-in system prompt sent to the LLM. */

package/src/config/types/auth.ts

@@ -28,18 +28,49 @@ export type DirectionUnion = z.input<typeof DirectionUnionZod>;
 /**
  * Order by clause for role-based default ordering
  */
-export const OrderByClauseZod = z.object({
+export const OrderByClauseZod = z.strictObject({
   column: z.string(),
   direction: DirectionUnionZod,
 });
 
 export type OrderByClause = z.input<typeof OrderByClauseZod>;
 
+/**
+ * Every operator the query builder implements. `databases/common.ts` imports this
+ * list rather than keeping its own: an operator that exists in one place and not
+ * the other is how a role filter ends up matching every row.
+ */
+export const FILTER_OPERATORS = [
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "like",
+  "in",
+  "between",
+  "is_null",
+  "is_not_null",
+  "not_null",
+] as const;
+
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+
 /**
  * Filter condition — matches GraphQL where argument structure.
- * Supports operators: eq, neq, gt, gte, lt, lte, like, in, is_null, not_null.
+ *
+ * A value is either a column filter (`{ eq: … }`) or a nested relation filter
+ * 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.
  */
-export const FilterConditionZod = z.record(z.string(), z.record(z.string(), z.unknown()));
+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]),
+  ),
+);
 
 export type FilterCondition = z.input<typeof FilterConditionZod>;
 
@@ -50,7 +81,7 @@ export type FilterCondition = z.input<typeof FilterConditionZod>;
 /**
  * Table-level permission configuration
  */
-export const TablePermissionZod = z.object({
+export const TablePermissionZod = z.strictObject({
   /** Allowed columns — "ALL" or array of column names */
   columns: z.union([z.literal("ALL"), z.array(z.string())]),
   /** Role-based query filtering (WHERE clause) */
@@ -65,7 +96,7 @@ export type TablePermission = z.input<typeof TablePermissionZod>;
  * Permission configuration for a role
  */
 export const RolePermissionZod = z
-  .object({
+  .strictObject({
     /** Tables accessible by this role */
     tables: z
       .union([
@@ -120,7 +151,7 @@ export type RolePermission = z.input<typeof RolePermissionZod>;
  * Authentication configuration
  */
 export const AuthConfigZod = z
-  .object({
+  .strictObject({
     /** Whether authentication is enabled */
     enabled: z.boolean(),
     /** Database name where auth tables are stored */