diff --git a/graphile/graphile-postgis/README.md b/graphile/graphile-postgis/README.md
index 759099c257..db24063737 100644
--- a/graphile/graphile-postgis/README.md
+++ b/graphile/graphile-postgis/README.md
@@ -40,8 +40,90 @@ const preset = {
 - Concrete types for all geometry subtypes: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection
 - Subtype-specific fields (x/y/z for Points, points for LineStrings, exterior/interiors for Polygons, etc.)
 - Geography-aware field naming (longitude/latitude/height instead of x/y/z)
+- Cross-table spatial filters via `@spatialRelation` smart tags (see below)
 - Graceful degradation when PostGIS is not installed
 
+## Spatial relations via smart tags
+
+`PostgisSpatialRelationsPlugin` lets you declare a cross-table or
+self-relation whose join predicate is a PostGIS spatial function. The
+plugin emits a first-class relation + filter field on the owning codec's
+`Filter` type that compiles to an `EXISTS (…)` subquery using the
+declared operator.
+
+### Tag grammar
+
+```sql
+COMMENT ON COLUMN <owner_table>.<owner_col> IS
+  E'@spatialRelation <relation_name> <target_table>.<target_col> <operator> [<param_name>]';
+```
+
+- `<relation_name>` — user-chosen name for the generated field (e.g. `county`)
+- `<target_table>.<target_col>` — target geometry/geography column; also
+  accepts `<schema>.<table>.<col>`
+- `<operator>` — PG-native `st_*` function name; resolved at schema build
+  time against `pg_proc`
+- `<param_name>` — required only for parametric operators
+  (currently `st_dwithin`)
+
+### Supported operators (v1)
+
+| Operator | PostGIS function | Kind  | Arity |
+|---|---|---|---|
+| `st_contains`        | `ST_Contains`       | function | 2 |
+| `st_within`          | `ST_Within`         | function | 2 |
+| `st_covers`          | `ST_Covers`         | function | 2 |
+| `st_coveredby`       | `ST_CoveredBy`      | function | 2 |
+| `st_intersects`      | `ST_Intersects`     | function | 2 |
+| `st_equals`          | `ST_Equals`         | function | 2 |
+| `st_bbox_intersects` | `&&`                | infix    | 2 |
+| `st_dwithin`         | `ST_DWithin`        | function | 3 (parametric) |
+
+### Filter shapes
+
+2-arg operators use the familiar `some` / `every` / `none` shape:
+
+```graphql
+telemedicineClinics(
+  filter: { county: { some: { name: { eq: "California County" } } } }
+) { nodes { id name } }
+```
+
+`st_dwithin` takes its distance at the relation level (it parametrises
+the join, not the joined row):
+
+```graphql
+telemedicineClinics(
+  filter: {
+    nearbyClinic: {
+      distance: 5000
+      some: { specialty: { eq: "pediatrics" } }
+    }
+  }
+) { nodes { id name } }
+```
+
+Distance units follow PostGIS semantics: **meters** for `geography`
+columns, **SRID coordinate units** for `geometry` columns.
+
+### Self-relations
+
+When `<owner_table>` equals `<target_table>`, the plugin emits an
+automatic self-exclusion predicate so a row is never "related to
+itself":
+
+- Single-column PK: `other.id <> self.id`
+- Composite PK: `(other.a, other.b) IS DISTINCT FROM (self.a, self.b)`
+
+Self-relations on tables without a primary key are rejected at schema
+build time.
+
+### GIST index warning
+
+At schema build time the plugin emits a non-fatal warning when the
+target geometry/geography column has no GIST index — spatial predicates
+are typically unusable without one.
+
 ## License
 
 MIT
diff --git a/graphile/graphile-postgis/__tests__/index.test.ts b/graphile/graphile-postgis/__tests__/index.test.ts
index 82671f361a..97e2770ffc 100644
--- a/graphile/graphile-postgis/__tests__/index.test.ts
+++ b/graphile/graphile-postgis/__tests__/index.test.ts
@@ -14,6 +14,7 @@ describe('graphile-postgis exports', () => {
     expect(postgisExports.PostgisMeasurementFieldsPlugin).toBeDefined();
     expect(postgisExports.PostgisTransformationFieldsPlugin).toBeDefined();
     expect(postgisExports.PostgisAggregatePlugin).toBeDefined();
+    expect(postgisExports.PostgisSpatialRelationsPlugin).toBeDefined();
   });
 
   it('should export constants', () => {
@@ -42,6 +43,11 @@ describe('graphile-postgis exports', () => {
       'PostgisMeasurementFieldsPlugin',
       'PostgisTransformationFieldsPlugin',
       'PostgisAggregatePlugin',
+      'PostgisSpatialRelationsPlugin',
+      // Spatial-relations helpers
+      'OPERATOR_REGISTRY',
+      'parseSpatialRelationTag',
+      'collectSpatialRelations',
       // Constants
       'GisSubtype',
       'SUBTYPE_STRING_BY_SUBTYPE',
diff --git a/graphile/graphile-postgis/__tests__/preset.test.ts b/graphile/graphile-postgis/__tests__/preset.test.ts
index 2eeb5286ed..4e8de6801a 100644
--- a/graphile/graphile-postgis/__tests__/preset.test.ts
+++ b/graphile/graphile-postgis/__tests__/preset.test.ts
@@ -7,10 +7,15 @@ import { PostgisGeometryFieldsPlugin } from '../src/plugins/geometry-fields';
 import { PostgisMeasurementFieldsPlugin } from '../src/plugins/measurement-fields';
 import { PostgisTransformationFieldsPlugin } from '../src/plugins/transformation-functions';
 import { PostgisAggregatePlugin } from '../src/plugins/aggregate-functions';
+import { PostgisSpatialRelationsPlugin } from '../src/plugins/spatial-relations';
 
 describe('GraphilePostgisPreset', () => {
-  it('should include all 8 plugins', () => {
-    expect(GraphilePostgisPreset.plugins).toHaveLength(8);
+  it('should include all 9 plugins', () => {
+    expect(GraphilePostgisPreset.plugins).toHaveLength(9);
+  });
+
+  it('should include PostgisSpatialRelationsPlugin', () => {
+    expect(GraphilePostgisPreset.plugins).toContain(PostgisSpatialRelationsPlugin);
   });
 
   it('should include PostgisCodecPlugin', () => {
diff --git a/graphile/graphile-postgis/__tests__/spatial-relations.test.ts b/graphile/graphile-postgis/__tests__/spatial-relations.test.ts
new file mode 100644
index 0000000000..63165312b8
--- /dev/null
+++ b/graphile/graphile-postgis/__tests__/spatial-relations.test.ts
@@ -0,0 +1,484 @@
+import sql from 'pg-sql2';
+import {
+  OPERATOR_REGISTRY,
+  parseSpatialRelationTag,
+  collectSpatialRelations,
+  PostgisSpatialRelationsPlugin,
+  type SpatialRelationInfo,
+} from '../src/plugins/spatial-relations';
+import { GraphilePostgisPreset } from '../src/preset';
+
+// ---------------------------------------------------------------------------
+// Test doubles
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct a mock pgRegistry that `collectSpatialRelations` can walk.
+ *
+ * `tables` is a map of table name -> attributes (with optional tags) +
+ * optional PK attributes + optional schemaName (defaults to 'public').
+ */
+function buildMockRegistry(
+  tables: Record<
+    string,
+    {
+      schemaName?: string;
+      pk?: string[];
+      attributes: Record<
+        string,
+        {
+          base: 'geometry' | 'geography' | 'int4' | 'text';
+          spatialRelation?: string | string[];
+        }
+      >;
+    }
+  >
+): any {
+  const pgResources: Record<string, any> = {};
+  for (const [tableName, spec] of Object.entries(tables)) {
+    const schemaName = spec.schemaName ?? 'public';
+    const attrs: Record<string, any> = {};
+    for (const [attrName, attrSpec] of Object.entries(spec.attributes)) {
+      const extensions: any = { pg: { name: attrSpec.base } };
+      const tags: Record<string, unknown> = {};
+      if (attrSpec.spatialRelation !== undefined) {
+        tags.spatialRelation = attrSpec.spatialRelation;
+      }
+      attrs[attrName] = {
+        codec: { extensions },
+        extensions: { tags },
+      };
+    }
+    const resource: any = {
+      name: tableName,
+      parameters: null,
+      codec: {
+        name: tableName,
+        attributes: attrs,
+        extensions: { pg: { schemaName, name: tableName } },
+      },
+      uniques: spec.pk ? [{ isPrimary: true, attributes: spec.pk }] : [],
+      from: sql.identifier(schemaName, tableName),
+      extensions: { pg: {} },
+    };
+    pgResources[tableName] = resource;
+  }
+  return { pgResources };
+}
+
+function makeBuild(registry: any): any {
+  return {
+    input: { pgRegistry: registry },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// OPERATOR_REGISTRY
+// ---------------------------------------------------------------------------
+
+describe('OPERATOR_REGISTRY', () => {
+  it('includes all 8 v1 operators with snake_case names', () => {
+    expect(Object.keys(OPERATOR_REGISTRY).sort()).toEqual(
+      [
+        'st_bbox_intersects',
+        'st_contains',
+        'st_coveredby',
+        'st_covers',
+        'st_dwithin',
+        'st_equals',
+        'st_intersects',
+        'st_within',
+      ].sort()
+    );
+  });
+
+  it('marks st_dwithin as the only parametric op', () => {
+    const parametric = Object.values(OPERATOR_REGISTRY)
+      .filter((o) => o.parametric)
+      .map((o) => o.name);
+    expect(parametric).toEqual(['st_dwithin']);
+  });
+
+  it('marks st_bbox_intersects as the only infix op', () => {
+    const infix = Object.values(OPERATOR_REGISTRY)
+      .filter((o) => o.kind === 'infix')
+      .map((o) => o.name);
+    expect(infix).toEqual(['st_bbox_intersects']);
+  });
+
+  it('every operator has a non-empty description', () => {
+    for (const op of Object.values(OPERATOR_REGISTRY)) {
+      expect(typeof op.description).toBe('string');
+      expect(op.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('every operator has pgToken matching its name (modulo && for bbox)', () => {
+    for (const op of Object.values(OPERATOR_REGISTRY)) {
+      if (op.kind === 'infix') {
+        expect(op.pgToken).toBe('&&');
+      } else {
+        expect(op.pgToken).toBe(op.name);
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseSpatialRelationTag
+// ---------------------------------------------------------------------------
+
+describe('parseSpatialRelationTag', () => {
+  it('parses a 3-token tag', () => {
+    const r = parseSpatialRelationTag('county counties.geom st_contains');
+    expect(r).toEqual({
+      ok: true,
+      relationName: 'county',
+      targetRef: 'counties.geom',
+      operator: 'st_contains',
+      paramName: null,
+    });
+  });
+
+  it('parses a 4-token parametric tag', () => {
+    const r = parseSpatialRelationTag(
+      'nearbyClinic clinics.location st_dwithin distance'
+    );
+    expect(r).toEqual({
+      ok: true,
+      relationName: 'nearbyClinic',
+      targetRef: 'clinics.location',
+      operator: 'st_dwithin',
+      paramName: 'distance',
+    });
+  });
+
+  it('accepts schema.table.col target references', () => {
+    const r = parseSpatialRelationTag(
+      'county geo.counties.geom st_contains'
+    );
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.targetRef).toBe('geo.counties.geom');
+  });
+
+  it('collapses repeated whitespace', () => {
+    const r = parseSpatialRelationTag('  a  b.c   st_contains  ');
+    expect(r.ok).toBe(true);
+  });
+
+  const errOf = (raw: string): string => {
+    const r: any = parseSpatialRelationTag(raw);
+    expect(r.ok).toBe(false);
+    return r.error;
+  };
+
+  it('rejects too few tokens', () => {
+    expect(errOf('only two')).toMatch(/tokens/);
+  });
+
+  it('rejects too many tokens', () => {
+    expect(parseSpatialRelationTag('a b.c st_contains x extra').ok).toBe(
+      false
+    );
+  });
+
+  it('rejects an invalid relation name', () => {
+    expect(errOf('1bad b.c st_contains')).toMatch(/relation name/);
+  });
+
+  it('rejects a malformed target reference', () => {
+    expect(errOf('rel onepart st_contains')).toMatch(/Target must be/);
+  });
+
+  it('rejects an unknown operator', () => {
+    expect(errOf('rel t.c st_not_real')).toMatch(/Unknown spatial operator/);
+  });
+
+  it('rejects st_dwithin without a parameter name', () => {
+    expect(errOf('rel t.c st_dwithin')).toMatch(/requires a parameter name/);
+  });
+
+  it('rejects a 2-arg op with an extra parameter', () => {
+    expect(errOf('rel t.c st_contains extra')).toMatch(
+      /does not take a parameter/
+    );
+  });
+
+  it('rejects an invalid parametric name', () => {
+    expect(errOf('rel t.c st_dwithin 1bad')).toMatch(/param name/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// collectSpatialRelations — happy path + validation errors
+// ---------------------------------------------------------------------------
+
+describe('collectSpatialRelations', () => {
+  it('returns [] when no tags are present', () => {
+    const registry = buildMockRegistry({
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          id: { base: 'int4' },
+          location: { base: 'geometry' },
+        },
+      },
+    });
+    const rels = collectSpatialRelations(makeBuild(registry));
+    expect(rels).toEqual([]);
+  });
+
+  it('returns [] when no pgRegistry is present', () => {
+    const rels = collectSpatialRelations({ input: {} });
+    expect(rels).toEqual([]);
+  });
+
+  it('collects a single cross-table spatial relation', () => {
+    const registry = buildMockRegistry({
+      counties: {
+        pk: ['id'],
+        attributes: {
+          id: { base: 'int4' },
+          geom: { base: 'geometry' },
+        },
+      },
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          id: { base: 'int4' },
+          location: {
+            base: 'geometry',
+            spatialRelation: 'county counties.geom st_contains',
+          },
+        },
+      },
+    });
+    const rels = collectSpatialRelations(makeBuild(registry));
+    expect(rels).toHaveLength(1);
+    const [rel] = rels;
+    expect(rel.relationName).toBe('county');
+    expect(rel.ownerCodec.name).toBe('clinics');
+    expect(rel.ownerAttributeName).toBe('location');
+    expect(rel.targetResource.codec.name).toBe('counties');
+    expect(rel.targetAttributeName).toBe('geom');
+    expect(rel.operator.name).toBe('st_contains');
+    expect(rel.paramFieldName).toBeNull();
+    expect(rel.isSelfRelation).toBe(false);
+    expect(rel.ownerPkAttributes).toEqual(['id']);
+    expect(rel.targetPkAttributes).toEqual(['id']);
+  });
+
+  it('collects a self-relation with parametric op', () => {
+    const registry = buildMockRegistry({
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          id: { base: 'int4' },
+          location: {
+            base: 'geometry',
+            spatialRelation:
+              'nearbyClinic clinics.location st_dwithin distance',
+          },
+        },
+      },
+    });
+    const [rel] = collectSpatialRelations(makeBuild(registry));
+    expect(rel.isSelfRelation).toBe(true);
+    expect(rel.operator.name).toBe('st_dwithin');
+    expect(rel.operator.parametric).toBe(true);
+    expect(rel.paramFieldName).toBe('distance');
+  });
+
+  it('supports multiple tags on the same column (string[] form)', () => {
+    const registry = buildMockRegistry({
+      counties: {
+        pk: ['id'],
+        attributes: {
+          id: { base: 'int4' },
+          geom: { base: 'geometry' },
+        },
+      },
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          id: { base: 'int4' },
+          location: {
+            base: 'geometry',
+            spatialRelation: [
+              'county counties.geom st_contains',
+              'intersectingCounty counties.geom st_intersects',
+            ],
+          },
+        },
+      },
+    });
+    const rels = collectSpatialRelations(makeBuild(registry));
+    expect(rels.map((r) => r.relationName).sort()).toEqual(
+      ['county', 'intersectingCounty'].sort()
+    );
+  });
+
+  it('throws on an invalid tag string', () => {
+    const registry = buildMockRegistry({
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          location: {
+            base: 'geometry',
+            spatialRelation: 'bad tag only',
+          },
+        },
+      },
+    });
+    expect(() => collectSpatialRelations(makeBuild(registry))).toThrow(
+      /Invalid @spatialRelation tag/
+    );
+  });
+
+  it('throws when the target table does not exist', () => {
+    const registry = buildMockRegistry({
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          location: {
+            base: 'geometry',
+            spatialRelation: 'county counties.geom st_contains',
+          },
+        },
+      },
+    });
+    expect(() => collectSpatialRelations(makeBuild(registry))).toThrow(
+      /does not resolve to a known column/
+    );
+  });
+
+  it('throws when owner column is not geometry/geography', () => {
+    const registry = buildMockRegistry({
+      counties: {
+        pk: ['id'],
+        attributes: {
+          geom: { base: 'geometry' },
+        },
+      },
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          // A text column should not be allowed to carry a spatialRelation tag.
+          location: {
+            base: 'text',
+            spatialRelation: 'county counties.geom st_contains',
+          },
+        },
+      },
+    });
+    expect(() => collectSpatialRelations(makeBuild(registry))).toThrow(
+      /requires a geometry or geography column/
+    );
+  });
+
+  it('throws on codec mismatch (geometry vs geography)', () => {
+    const registry = buildMockRegistry({
+      regions: {
+        pk: ['id'],
+        attributes: {
+          shape: { base: 'geography' },
+        },
+      },
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          location: {
+            base: 'geometry',
+            spatialRelation: 'region regions.shape st_contains',
+          },
+        },
+      },
+    });
+    expect(() => collectSpatialRelations(makeBuild(registry))).toThrow(
+      /codec mismatch/
+    );
+  });
+
+  it('throws on self-relation without a primary key', () => {
+    const registry = buildMockRegistry({
+      clinics: {
+        // no pk
+        attributes: {
+          location: {
+            base: 'geometry',
+            spatialRelation:
+              'nearbyClinic clinics.location st_dwithin distance',
+          },
+        },
+      },
+    });
+    expect(() => collectSpatialRelations(makeBuild(registry))).toThrow(
+      /has no primary key/
+    );
+  });
+
+  it('throws on duplicate relation names on the same owner', () => {
+    const registry = buildMockRegistry({
+      counties: {
+        pk: ['id'],
+        attributes: { geom: { base: 'geometry' } },
+      },
+      regions: {
+        pk: ['id'],
+        attributes: { geom: { base: 'geometry' } },
+      },
+      clinics: {
+        pk: ['id'],
+        attributes: {
+          location: {
+            base: 'geometry',
+            spatialRelation: [
+              'region counties.geom st_contains',
+              'region regions.geom st_intersects',
+            ],
+          },
+        },
+      },
+    });
+    expect(() => collectSpatialRelations(makeBuild(registry))).toThrow(
+      /Duplicate @spatialRelation/
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Plugin metadata
+// ---------------------------------------------------------------------------
+
+describe('PostgisSpatialRelationsPlugin (metadata)', () => {
+  it('runs after the relevant plugins', () => {
+    expect(PostgisSpatialRelationsPlugin.after).toContain(
+      'PostgisExtensionDetectionPlugin'
+    );
+    expect(PostgisSpatialRelationsPlugin.after).toContain(
+      'PostgisRegisterTypesPlugin'
+    );
+    expect(PostgisSpatialRelationsPlugin.after).toContain(
+      'ConnectionFilterBackwardRelationsPlugin'
+    );
+  });
+
+  it('exposes the three schema hooks we rely on', () => {
+    const hooks = PostgisSpatialRelationsPlugin.schema?.hooks as Record<
+      string,
+      unknown
+    > | undefined;
+    expect(hooks).toBeDefined();
+    expect(typeof hooks!.build).toBe('function');
+    expect(typeof hooks!.init).toBe('function');
+    expect(typeof hooks!.GraphQLInputObjectType_fields).toBe('function');
+  });
+
+  it('is wired into the GraphilePostgisPreset', () => {
+    const plugins = (GraphilePostgisPreset.plugins ?? []) as Array<{
+      name?: string;
+    }>;
+    const names = plugins.map((p) => p.name).filter(Boolean);
+    expect(names).toContain('PostgisSpatialRelationsPlugin');
+  });
+});
diff --git a/graphile/graphile-postgis/src/index.ts b/graphile/graphile-postgis/src/index.ts
index f5449ebd6c..60b5aa3212 100644
--- a/graphile/graphile-postgis/src/index.ts
+++ b/graphile/graphile-postgis/src/index.ts
@@ -25,6 +25,16 @@ export { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
 export { PostgisMeasurementFieldsPlugin } from './plugins/measurement-fields';
 export { PostgisTransformationFieldsPlugin } from './plugins/transformation-functions';
 export { PostgisAggregatePlugin } from './plugins/aggregate-functions';
+export {
+  PostgisSpatialRelationsPlugin,
+  OPERATOR_REGISTRY,
+  parseSpatialRelationTag,
+  collectSpatialRelations,
+} from './plugins/spatial-relations';
+export type {
+  SpatialOperatorRegistration,
+  SpatialRelationInfo,
+} from './plugins/spatial-relations';
 
 // Connection filter operator factories (spatial operators for graphile-connection-filter)
 export { createPostgisOperatorFactory } from './plugins/connection-filter-operators';
diff --git a/graphile/graphile-postgis/src/plugins/spatial-relations.ts b/graphile/graphile-postgis/src/plugins/spatial-relations.ts
new file mode 100644
index 0000000000..2650345e5c
--- /dev/null
+++ b/graphile/graphile-postgis/src/plugins/spatial-relations.ts
@@ -0,0 +1,870 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import 'graphile-connection-filter';
+import type { GraphileConfig } from 'graphile-config';
+import type { SQL } from 'pg-sql2';
+import sql from 'pg-sql2';
+import type { PostgisExtensionInfo } from './detect-extension';
+
+/**
+ * PostgisSpatialRelationsPlugin
+ *
+ * Adds cross-table spatial filtering to `graphile-connection-filter` by
+ * reading a `@spatialRelation` smart tag on geometry/geography columns and
+ * synthesising a virtual relation + filter field that emits an EXISTS
+ * subquery joined by a PostGIS predicate (e.g. `ST_Contains`, `ST_DWithin`).
+ *
+ * The regular `ConnectionFilterBackwardRelationsPlugin` is FK-driven — it
+ * joins on column equality. Spatial relationships are not backed by FKs, so
+ * this plugin hooks the same `pgCodec`-scoped filter input types and injects
+ * its own fields whose `apply()` emits `ST_<op>(...)` instead of `a = b`.
+ *
+ * Tag grammar:
+ *
+ * ```sql
+ * COMMENT ON COLUMN <owner_table>.<owner_col> IS
+ *   E'@spatialRelation <relation_name> <target_ref> <operator> [<param_name>]';
+ * ```
+ *
+ * - `target_ref` — `schema.table.col` or `table.col` (same schema as owner).
+ * - `operator` — one of the PG-native snake_case ops in OPERATOR_REGISTRY.
+ * - `param_name` — required iff the operator is parametric (currently
+ *   only `st_dwithin`, which needs a distance).
+ *
+ * Examples:
+ *
+ * ```sql
+ * -- Point in polygon
+ * COMMENT ON COLUMN telemedicine_clinics.location IS
+ *   E'@spatialRelation county counties.geom st_contains';
+ *
+ * -- Self-referential radius search
+ * COMMENT ON COLUMN telemedicine_clinics.location IS
+ *   E'@spatialRelation nearbyClinic telemedicine_clinics.location st_dwithin distance';
+ * ```
+ *
+ * Generated GraphQL (for the `st_dwithin` case):
+ *
+ * ```graphql
+ * telemedicineClinics(filter: {
+ *   nearbyClinic: {
+ *     distance: 5000,
+ *     some: { specialty: { eq: "pediatrics" } }
+ *   }
+ * })
+ * ```
+ *
+ * The generated SQL uses the same EXISTS pattern as backward relations but
+ * substitutes `ST_<op>(...)` for column equality:
+ *
+ * ```sql
+ * WHERE EXISTS (
+ *   SELECT 1 FROM <target_table> other
+ *   WHERE ST_<op>(other.<target_col>, self.<owner_col>[, distance])
+ *     AND other.<pk> <> self.<pk>  -- self-relations only
+ *     AND <nested filter conditions>
+ * )
+ * ```
+ */
+
+export interface SpatialOperatorRegistration {
+  /** Tag-facing op name (PG-native snake_case). */
+  name: string;
+  /** Kind of PG-level operator. */
+  kind: 'function' | 'infix';
+  /**
+   * For `kind: 'function'`, the PG function name (snake_case) resolved
+   * against the PostGIS schema at SQL-emit time. For `kind: 'infix'`,
+   * the PG binary operator token (e.g. `&&`).
+   */
+  pgToken: string;
+  /** Whether this op takes an extra numeric parameter (e.g. `st_dwithin`). */
+  parametric: boolean;
+  description: string;
+}
+
+export const OPERATOR_REGISTRY: Record<string, SpatialOperatorRegistration> = {
+  st_contains: {
+    name: 'st_contains',
+    kind: 'function',
+    pgToken: 'st_contains',
+    parametric: false,
+    description:
+      'Every point of the owner column lies in the interior of the target column (ST_Contains).',
+  },
+  st_within: {
+    name: 'st_within',
+    kind: 'function',
+    pgToken: 'st_within',
+    parametric: false,
+    description:
+      'Owner column is completely inside the target column (ST_Within).',
+  },
+  st_covers: {
+    name: 'st_covers',
+    kind: 'function',
+    pgToken: 'st_covers',
+    parametric: false,
+    description:
+      'No point in the target column lies outside the owner column (ST_Covers).',
+  },
+  st_coveredby: {
+    name: 'st_coveredby',
+    kind: 'function',
+    pgToken: 'st_coveredby',
+    parametric: false,
+    description:
+      'No point in the owner column lies outside the target column (ST_CoveredBy).',
+  },
+  st_intersects: {
+    name: 'st_intersects',
+    kind: 'function',
+    pgToken: 'st_intersects',
+    parametric: false,
+    description:
+      'Owner and target columns share any portion of space (ST_Intersects).',
+  },
+  st_equals: {
+    name: 'st_equals',
+    kind: 'function',
+    pgToken: 'st_equals',
+    parametric: false,
+    description:
+      'Owner and target columns represent the same geometry (ST_Equals).',
+  },
+  st_bbox_intersects: {
+    name: 'st_bbox_intersects',
+    kind: 'infix',
+    pgToken: '&&',
+    parametric: false,
+    description:
+      "Owner column's 2D bounding box intersects the target's 2D bounding box (&&).",
+  },
+  st_dwithin: {
+    name: 'st_dwithin',
+    kind: 'function',
+    pgToken: 'st_dwithin',
+    parametric: true,
+    description:
+      'Owner column is within <distance> of the target column (ST_DWithin). ' +
+      'Distance is in meters for geography, SRID coordinate units for geometry.',
+  },
+};
+
+export interface SpatialRelationInfo {
+  /** GraphQL-facing relation name, derived from the tag. */
+  relationName: string;
+  /** The codec that owns the tag (outer side of the EXISTS). */
+  ownerCodec: any;
+  /** The owning attribute name (column). */
+  ownerAttributeName: string;
+  /** Qualified target resource (inner side of the EXISTS). */
+  targetResource: any;
+  /** Column name on the target resource. */
+  targetAttributeName: string;
+  /** Resolved operator. */
+  operator: SpatialOperatorRegistration;
+  /** Field name for the parametric argument, if any. */
+  paramFieldName: string | null;
+  /** Whether owner === target (self-relation needs row exclusion). */
+  isSelfRelation: boolean;
+  /**
+   * Cached primary-key attribute names for the owner+target codecs. Used
+   * to synthesise the self-exclusion predicate (`other.<pk> <> self.<pk>`).
+   * `null` if the codec has no discoverable PK.
+   */
+  ownerPkAttributes: string[] | null;
+  targetPkAttributes: string[] | null;
+}
+
+interface TagParseResult {
+  ok: true;
+  relationName: string;
+  targetRef: string;
+  operator: string;
+  paramName: string | null;
+}
+
+interface TagParseError {
+  ok: false;
+  error: string;
+}
+
+/**
+ * Parse a single `@spatialRelation` tag value.
+ *
+ * Accepts a string of the form `<name> <target> <op> [<param>]`.
+ */
+export function parseSpatialRelationTag(raw: string): TagParseResult | TagParseError {
+  if (typeof raw !== 'string') {
+    return { ok: false, error: `Expected string, got ${typeof raw}` };
+  }
+  const parts = raw.trim().split(/\s+/);
+  if (parts.length < 3 || parts.length > 4) {
+    return {
+      ok: false,
+      error: `Expected 3 or 4 whitespace-separated tokens; got ${parts.length}`,
+    };
+  }
+  const [relationName, targetRef, operator, paramName] = parts;
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(relationName)) {
+    return { ok: false, error: `Invalid relation name '${relationName}'` };
+  }
+  if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(targetRef)) {
+    return { ok: false, error: `Invalid target reference '${targetRef}'` };
+  }
+  const targetParts = targetRef.split('.');
+  if (targetParts.length < 2 || targetParts.length > 3) {
+    return {
+      ok: false,
+      error: `Target must be 'table.col' or 'schema.table.col'; got '${targetRef}'`,
+    };
+  }
+  if (!(operator in OPERATOR_REGISTRY)) {
+    const known = Object.keys(OPERATOR_REGISTRY).sort().join(', ');
+    return {
+      ok: false,
+      error: `Unknown spatial operator '${operator}'. Known ops: ${known}`,
+    };
+  }
+  const op = OPERATOR_REGISTRY[operator];
+  if (op.parametric) {
+    if (!paramName) {
+      return {
+        ok: false,
+        error: `Operator '${operator}' requires a parameter name (e.g. 'distance')`,
+      };
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(paramName)) {
+      return { ok: false, error: `Invalid param name '${paramName}'` };
+    }
+  } else {
+    if (paramName) {
+      return {
+        ok: false,
+        error: `Operator '${operator}' does not take a parameter; got extra token '${paramName}'`,
+      };
+    }
+  }
+  return {
+    ok: true,
+    relationName,
+    targetRef,
+    operator,
+    paramName: paramName ?? null,
+  };
+}
+
+/**
+ * Resolve a `<table.col>` or `<schema.table.col>` reference to a
+ * `pgResource` + attribute name.
+ */
+function resolveTargetRef(
+  pgRegistry: any,
+  ownerResource: any,
+  targetRef: string
+): { resource: any; attributeName: string } | null {
+  const parts = targetRef.split('.');
+  let schemaName: string | null = null;
+  let tableName: string;
+  let columnName: string;
+  if (parts.length === 2) {
+    [tableName, columnName] = parts;
+  } else {
+    [schemaName, tableName, columnName] = parts;
+  }
+  const ownerPgExt = ownerResource?.codec?.extensions?.pg;
+  const defaultSchema = ownerPgExt?.schemaName ?? 'public';
+  const lookupSchema = schemaName ?? defaultSchema;
+
+  for (const res of Object.values(pgRegistry.pgResources) as any[]) {
+    if (res.parameters) continue;
+    const pg = res?.codec?.extensions?.pg;
+    if (!pg) continue;
+    if (pg.name !== tableName) continue;
+    if (pg.schemaName !== lookupSchema) continue;
+    const attr = res.codec.attributes?.[columnName];
+    if (!attr) return null;
+    return { resource: res, attributeName: columnName };
+  }
+  return null;
+}
+
+/** Get the PK attribute names for a resource, or null if none discoverable. */
+function getPrimaryKeyAttributes(resource: any): string[] | null {
+  const uniques = resource?.uniques as any[] | undefined;
+  if (!uniques || uniques.length === 0) return null;
+  const primary = uniques.find((u) => u.isPrimary);
+  const chosen = primary ?? uniques[0];
+  if (!chosen?.attributes || chosen.attributes.length === 0) return null;
+  return chosen.attributes as string[];
+}
+
+/**
+ * Collect tag strings from an attribute, handling the `string | string[]`
+ * normalisation graphile-build-pg does for repeated smart tags.
+ */
+function collectTagStrings(tagValue: unknown): string[] {
+  if (tagValue == null) return [];
+  if (Array.isArray(tagValue)) {
+    return tagValue.filter((v): v is string => typeof v === 'string');
+  }
+  if (typeof tagValue === 'string') return [tagValue];
+  return [];
+}
+
+/**
+ * Build the full set of spatial relations from all resources.
+ * Validates tags and throws (at schema build) on anything malformed.
+ * Returns relations keyed by (owner codec identity, relation name).
+ */
+export function collectSpatialRelations(build: any): SpatialRelationInfo[] {
+  const pgRegistry = build.input?.pgRegistry;
+  if (!pgRegistry) return [];
+
+  const relations: SpatialRelationInfo[] = [];
+
+  for (const resource of Object.values(pgRegistry.pgResources) as any[]) {
+    if (resource.parameters) continue;
+    const attributes = resource.codec?.attributes;
+    if (!attributes) continue;
+
+    for (const [ownerAttributeName, attribute] of Object.entries(
+      attributes as Record<string, any>
+    )) {
+      const tags = attribute?.extensions?.tags;
+      if (!tags) continue;
+      const rawValues = collectTagStrings(tags.spatialRelation);
+      if (rawValues.length === 0) continue;
+
+      for (const rawValue of rawValues) {
+        const parsed = parseSpatialRelationTag(rawValue);
+        if (parsed.ok !== true) {
+          throw new Error(
+            `[graphile-postgis] Invalid @spatialRelation tag on ` +
+            `${resource.codec.name}.${ownerAttributeName}: ${parsed.error}`
+          );
+        }
+
+        const target = resolveTargetRef(pgRegistry, resource, parsed.targetRef);
+        if (!target) {
+          throw new Error(
+            `[graphile-postgis] @spatialRelation tag on ` +
+            `${resource.codec.name}.${ownerAttributeName} references ` +
+            `'${parsed.targetRef}' which does not resolve to a known column.`
+          );
+        }
+
+        // Validate geometry/geography codec symmetry.
+        const ownerPgExt = attribute.codec?.extensions?.pg;
+        const targetAttr = target.resource.codec.attributes[target.attributeName];
+        const targetPgExt = targetAttr?.codec?.extensions?.pg;
+        const ownerBase = ownerPgExt?.name;
+        const targetBase = targetPgExt?.name;
+        if (
+          (ownerBase === 'geometry' || ownerBase === 'geography') &&
+          (targetBase === 'geometry' || targetBase === 'geography') &&
+          ownerBase !== targetBase
+        ) {
+          throw new Error(
+            `[graphile-postgis] @spatialRelation ${resource.codec.name}.${ownerAttributeName} ` +
+            `-> ${target.resource.codec.name}.${target.attributeName}: ` +
+            `codec mismatch (${ownerBase} vs ${targetBase}). Both sides must share a base codec.`
+          );
+        }
+        if (
+          ownerBase !== 'geometry' &&
+          ownerBase !== 'geography'
+        ) {
+          throw new Error(
+            `[graphile-postgis] @spatialRelation requires a geometry or geography column; ` +
+            `${resource.codec.name}.${ownerAttributeName} is ${ownerBase ?? 'unknown'}.`
+          );
+        }
+
+        const isSelfRelation = resource === target.resource;
+        const ownerPkAttributes = getPrimaryKeyAttributes(resource);
+        const targetPkAttributes = getPrimaryKeyAttributes(target.resource);
+        if (isSelfRelation && !ownerPkAttributes) {
+          throw new Error(
+            `[graphile-postgis] @spatialRelation '${parsed.relationName}' on ` +
+            `${resource.codec.name}.${ownerAttributeName} is a self-relation, but the ` +
+            `table has no primary key; refusing to register (would match every row against itself).`
+          );
+        }
+
+        relations.push({
+          relationName: parsed.relationName,
+          ownerCodec: resource.codec,
+          ownerAttributeName,
+          targetResource: target.resource,
+          targetAttributeName: target.attributeName,
+          operator: OPERATOR_REGISTRY[parsed.operator],
+          paramFieldName: parsed.paramName,
+          isSelfRelation,
+          ownerPkAttributes,
+          targetPkAttributes,
+        });
+      }
+    }
+  }
+
+  // Detect duplicate (ownerCodec, relationName) pairs — emit a clear error
+  // rather than letting registerInputObjectType throw generic "already exists".
+  const seen = new Map<string, SpatialRelationInfo>();
+  for (const rel of relations) {
+    const key = `${rel.ownerCodec.name}:${rel.relationName}`;
+    const prior = seen.get(key);
+    if (prior) {
+      throw new Error(
+        `[graphile-postgis] Duplicate @spatialRelation name '${rel.relationName}' on ` +
+        `codec '${rel.ownerCodec.name}'. Each relation name must be unique per owning table.`
+      );
+    }
+    seen.set(key, rel);
+  }
+
+  return relations;
+}
+
+/** Name of the per-relation filter type: `<Owner>Spatial<Relation>Filter`. */
+function spatialFilterTypeName(build: any, rel: SpatialRelationInfo): string {
+  const { inflection } = build;
+  const ownerTypeName = inflection.tableType(rel.ownerCodec);
+  const rel0 = rel.relationName.charAt(0).toUpperCase() + rel.relationName.slice(1);
+  return `${ownerTypeName}Spatial${rel0}Filter`;
+}
+
+/**
+ * Build the SQL fragment that joins the inner (target) row to the outer
+ * (owner) row using the resolved PostGIS predicate.
+ */
+function buildSpatialJoinFragment(
+  rel: SpatialRelationInfo,
+  schemaName: string,
+  outerAlias: SQL,
+  innerAlias: SQL,
+  distanceValue: SQL | null
+): SQL {
+  // Tag grammar reads as "<owner_col> <op> <target_col>" (e.g. "location
+  // st_within counties.geom"), so the emitted PostGIS call is always
+  // `ST_<op>(owner_col, target_col)`. For symmetric operators
+  // (st_intersects, st_dwithin, st_equals, &&) the ordering is immaterial;
+  // for directional ones (st_within, st_contains, st_covers, st_coveredby)
+  // reversing the operands inverts the set of matched rows.
+  const ownerExpr = sql`${outerAlias}.${sql.identifier(rel.ownerAttributeName)}`;
+  const targetExpr = sql`${innerAlias}.${sql.identifier(rel.targetAttributeName)}`;
+  if (rel.operator.kind === 'infix') {
+    // Only `&&` today — simple inline (symmetric).
+    return sql`${ownerExpr} && ${targetExpr}`;
+  }
+  const fn = sql.identifier(schemaName, rel.operator.pgToken);
+  if (rel.operator.parametric) {
+    if (!distanceValue) {
+      // The apply() guards this; defensive throw.
+      throw new Error(
+        `[graphile-postgis] Parametric operator '${rel.operator.name}' invoked without ` +
+        `a distance value in spatial relation '${rel.relationName}'.`
+      );
+    }
+    return sql`${fn}(${ownerExpr}, ${targetExpr}, ${distanceValue})`;
+  }
+  return sql`${fn}(${ownerExpr}, ${targetExpr})`;
+}
+
+/** Build the `other.pk <> self.pk` exclusion predicate for self-relations. */
+function buildSelfExclusionFragment(
+  rel: SpatialRelationInfo,
+  outerAlias: SQL,
+  innerAlias: SQL
+): SQL | null {
+  if (!rel.isSelfRelation) return null;
+  const pk = rel.ownerPkAttributes;
+  if (!pk || pk.length === 0) return null;
+  if (pk.length === 1) {
+    const c = pk[0];
+    return sql`${innerAlias}.${sql.identifier(c)} <> ${outerAlias}.${sql.identifier(c)}`;
+  }
+  // Composite PK: IS DISTINCT FROM tuple comparison.
+  const left = sql.join(
+    pk.map((c) => sql`${innerAlias}.${sql.identifier(c)}`),
+    ', '
+  );
+  const right = sql.join(
+    pk.map((c) => sql`${outerAlias}.${sql.identifier(c)}`),
+    ', '
+  );
+  return sql`(${left}) IS DISTINCT FROM (${right})`;
+}
+
+export const PostgisSpatialRelationsPlugin: GraphileConfig.Plugin = {
+  name: 'PostgisSpatialRelationsPlugin',
+  version: '1.0.0',
+  description:
+    'Adds cross-table spatial filtering via @spatialRelation smart tags; ' +
+    'synthesises virtual relations whose EXISTS predicate uses PostGIS ops ' +
+    'instead of column equality.',
+  after: [
+    'PostgisExtensionDetectionPlugin',
+    'PostgisRegisterTypesPlugin',
+    'ConnectionFilterBackwardRelationsPlugin',
+  ],
+
+  schema: {
+    hooks: {
+      build(build) {
+        const postgisInfo: PostgisExtensionInfo | undefined =
+          (build as any).pgGISExtensionInfo;
+        if (!postgisInfo) return build;
+        const relations = collectSpatialRelations(build);
+
+        // Emit GIST-index warnings for target columns without a GIST index.
+        // Warnings never block schema build — we defer to the build logger.
+        const warn = (build as any).console?.warn ?? console.warn;
+        for (const rel of relations) {
+          const targetAttr =
+            rel.targetResource.codec.attributes?.[rel.targetAttributeName];
+          const indexes = rel.targetResource.extensions?.pg?.indexes as
+            | any[]
+            | undefined;
+          let hasGist = false;
+          if (Array.isArray(indexes)) {
+            hasGist = indexes.some(
+              (idx) =>
+                idx &&
+                typeof idx === 'object' &&
+                idx.method === 'gist' &&
+                Array.isArray(idx.attributes) &&
+                idx.attributes.includes(rel.targetAttributeName)
+            );
+          }
+          // Introspection of indexes through @dataplan/pg isn't universally
+          // exposed; if we can't tell, stay quiet rather than cry wolf.
+          const canDiscoverIndexes = Array.isArray(indexes);
+          const skipCheck =
+            targetAttr?.extensions?.tags?.spatialRelationSkipIndexCheck === true;
+          if (canDiscoverIndexes && !hasGist && !skipCheck) {
+            warn(
+              `[graphile-postgis] Spatial relation '${rel.relationName}' ` +
+              `targets ${rel.targetResource.codec.name}.${rel.targetAttributeName} ` +
+              `which has no GIST index; expect sequential scans. ` +
+              `Recommended: CREATE INDEX ON ${rel.targetResource.codec.name} ` +
+              `USING GIST (${rel.targetAttributeName});`
+            );
+          }
+        }
+
+        return build.extend(
+          build,
+          { pgGISSpatialRelations: relations },
+          'PostgisSpatialRelationsPlugin adding spatial relation registry'
+        );
+      },
+
+      init(_, build) {
+        if (!(build as any).pgGISExtensionInfo) return _;
+        const relations = (build as any).pgGISSpatialRelations as
+          | SpatialRelationInfo[]
+          | undefined;
+        if (!relations || relations.length === 0) return _;
+
+        for (const rel of relations) {
+          const typeName = spatialFilterTypeName(build, rel);
+          if (build.getTypeMetaByName(typeName)) continue;
+          const targetTypeName = build.inflection.tableType(
+            rel.targetResource.codec
+          );
+          build.recoverable(null, () => {
+            build.registerInputObjectType(
+              typeName,
+              {
+                // NOTE: intentionally NOT setting `isPgConnectionFilterMany`.
+                // That flag triggers ConnectionFilterBackwardRelationsPlugin
+                // (and friends) to auto-register `some`/`every`/`none` fields
+                // with FK-join semantics, which would collide with — and
+                // semantically differ from — ours. We own those fields here.
+                foreignTable: rel.targetResource,
+                isPgGISSpatialFilter: true,
+                pgGISSpatialRelation: rel,
+              } as any,
+              () => ({
+                name: typeName,
+                description:
+                  `A filter on \`${targetTypeName}\` rows spatially related ` +
+                  `to the current row via \`${rel.operator.name}\`. ` +
+                  `All fields are combined with a logical \u2018and\u2019.`,
+              }),
+              `PostgisSpatialRelationsPlugin adding '${typeName}' spatial filter type`
+            );
+          });
+        }
+        return _;
+      },
+
+      GraphQLInputObjectType_fields(inFields, build, context) {
+        if (!(build as any).pgGISExtensionInfo) return inFields;
+        const relations = (build as any).pgGISSpatialRelations as
+          | SpatialRelationInfo[]
+          | undefined;
+        if (!relations || relations.length === 0) return inFields;
+
+        let fields = inFields;
+        const {
+          extend,
+          inflection,
+          graphql: { GraphQLFloat, GraphQLNonNull },
+          EXPORTABLE,
+        } = build;
+        const {
+          fieldWithHooks,
+          scope: {
+            pgCodec,
+            isPgConnectionFilter,
+            isPgGISSpatialFilter,
+            pgGISSpatialRelation,
+          },
+        } = context as any;
+
+        const postgisInfo: PostgisExtensionInfo = (build as any).pgGISExtensionInfo;
+        const { schemaName } = postgisInfo;
+
+        // ── Part 1: inject <relationName> on the owning codec's filter type
+        if (isPgConnectionFilter && pgCodec) {
+          const ownRelations = relations.filter(
+            (r) => r.ownerCodec === pgCodec
+          );
+          for (const rel of ownRelations) {
+            const filterTypeName = spatialFilterTypeName(build, rel);
+            const FilterType = build.getTypeByName(filterTypeName);
+            if (!FilterType) continue;
+
+            const fieldName = rel.relationName;
+            // Avoid clobbering fields an upstream plugin may have registered
+            // (e.g. an FK-derived relation with the same name).
+            if (fields[fieldName]) {
+              throw new Error(
+                `[graphile-postgis] @spatialRelation '${rel.relationName}' on ` +
+                `codec '${rel.ownerCodec.name}' collides with an existing filter ` +
+                `field of the same name. Rename the spatial relation or the colliding field.`
+              );
+            }
+
+            const targetTypeName = inflection.tableType(
+              rel.targetResource.codec
+            );
+            const relSnapshot = rel;
+            fields = extend(
+              fields,
+              {
+                [fieldName]: fieldWithHooks(
+                  {
+                    fieldName,
+                    isPgConnectionFilterField: true,
+                    isPgGISSpatialRelationField: true,
+                  } as any,
+                  () => ({
+                    description:
+                      `Filter by rows from \`${targetTypeName}\` related to this ` +
+                      `row via \`${relSnapshot.operator.name}\`.`,
+                    type: FilterType,
+                    apply: EXPORTABLE(
+                      (relationInfo: SpatialRelationInfo) =>
+                        function ($where: any, value: any) {
+                          if (value == null) return;
+                          $where._spatialRelation = relationInfo;
+                          // Parent apply runs BEFORE child field applies, so
+                          // read the parametric value here (if any) and stash
+                          // it on $where for some/every/none to consume. This
+                          // avoids relying on input-field iteration order.
+                          if (
+                            relationInfo.operator.parametric &&
+                            relationInfo.paramFieldName
+                          ) {
+                            const raw = value[relationInfo.paramFieldName];
+                            if (typeof raw !== 'number') {
+                              throw Object.assign(
+                                new Error(
+                                  `Spatial relation '${relationInfo.relationName}' requires ` +
+                                  `a numeric '${relationInfo.paramFieldName}' argument; got ${raw}`
+                                ),
+                                {}
+                              );
+                            }
+                            $where._spatialRelationParam = raw;
+                          }
+                          return $where;
+                        },
+                      [relSnapshot]
+                    ),
+                  })
+                ),
+              },
+              `PostgisSpatialRelationsPlugin adding '${fieldName}' field to ` +
+              `${inflection.filterType(inflection.tableType(rel.ownerCodec))}`
+            );
+          }
+        }
+
+        // ── Part 2: inject some/every/none (+ optional distance) on the
+        // per-relation filter type.
+        if (isPgGISSpatialFilter && pgGISSpatialRelation) {
+          const rel: SpatialRelationInfo = pgGISSpatialRelation;
+          const targetTypeName = inflection.tableType(rel.targetResource.codec);
+          const TargetFilterTypeName = inflection.filterType(targetTypeName);
+          const TargetFilterType = build.getTypeByName(TargetFilterTypeName);
+          if (!TargetFilterType) return fields;
+
+          const paramFieldName = rel.paramFieldName;
+
+          // Parametric: add required <param> field (Float!). The parent
+          // relation field's apply reads the value from the input object
+          // directly — this field's apply is a no-op used only so the schema
+          // validates the input shape.
+          if (rel.operator.parametric && paramFieldName) {
+            fields = extend(
+              fields,
+              {
+                [paramFieldName]: fieldWithHooks(
+                  {
+                    fieldName: paramFieldName,
+                    isPgConnectionFilterField: true,
+                    isPgGISSpatialParamField: true,
+                  } as any,
+                  () => ({
+                    description:
+                      `Parametric argument for ${rel.operator.name} ` +
+                      `(units: meters for geography, SRID units for geometry).`,
+                    type: new GraphQLNonNull(GraphQLFloat),
+                    apply: EXPORTABLE(
+                      () =>
+                        function (_$where: any, _value: number | null) {
+                          // No-op; parent apply already stashed the value.
+                        },
+                      []
+                    ),
+                  })
+                ),
+              },
+              `PostgisSpatialRelationsPlugin adding '${paramFieldName}' param to ` +
+              `${spatialFilterTypeName(build, rel)}`
+            );
+          }
+
+          // Build the three apply() closures. `mode` selects the EXISTS
+          // variant: `'some'` => EXISTS, `'none'` => NOT EXISTS,
+          // `'every'` => NOT EXISTS (... AND NOT filter) via notPlan().
+          const buildApply = (mode: 'some' | 'every' | 'none') =>
+            EXPORTABLE(
+              (
+                buildJoin: typeof buildSpatialJoinFragment,
+                buildExcl: typeof buildSelfExclusionFragment,
+                relationInfo: SpatialRelationInfo,
+                sqlSchemaName: string,
+                sqlLib: typeof sql,
+                applyMode: 'some' | 'every' | 'none'
+              ) =>
+                function ($where: any, value: object | null) {
+                  if (value == null) return;
+                  const foreignTable = relationInfo.targetResource;
+                  const foreignTableExpression = foreignTable.from;
+                  const existsOpts: Record<string, unknown> = {
+                    tableExpression: foreignTableExpression,
+                    alias: foreignTable.name,
+                  };
+                  if (applyMode !== 'some') {
+                    existsOpts.equals = false;
+                  }
+                  const $subQuery = $where.existsPlan(existsOpts);
+                  const outerAlias = $where.alias;
+                  const innerAlias = $subQuery.alias;
+                  let distance: SQL | null = null;
+                  if (relationInfo.operator.parametric) {
+                    const raw = $where._spatialRelationParam;
+                    if (raw == null || typeof raw !== 'number') {
+                      throw Object.assign(
+                        new Error(
+                          `Spatial relation '${relationInfo.relationName}' requires a ` +
+                          `'${relationInfo.paramFieldName}' value; got ${raw}`
+                        ),
+                        {}
+                      );
+                    }
+                    distance = sqlLib.value(raw);
+                  }
+                  $subQuery.where(
+                    buildJoin(
+                      relationInfo,
+                      sqlSchemaName,
+                      outerAlias,
+                      innerAlias,
+                      distance
+                    )
+                  );
+                  const exclusion = buildExcl(relationInfo, outerAlias, innerAlias);
+                  if (exclusion) {
+                    $subQuery.where(exclusion);
+                  }
+                  if (applyMode === 'every') {
+                    return $subQuery.notPlan();
+                  }
+                  return $subQuery;
+                },
+              [
+                buildSpatialJoinFragment,
+                buildSelfExclusionFragment,
+                rel,
+                schemaName,
+                sql,
+                mode,
+              ]
+            );
+
+          fields = extend(
+            fields,
+            {
+              some: fieldWithHooks(
+                {
+                  fieldName: 'some',
+                  isPgConnectionFilterField: true,
+                } as any,
+                () => ({
+                  description:
+                    'Filters to entities where at least one spatially-related entity matches.',
+                  type: TargetFilterType,
+                  apply: buildApply('some'),
+                })
+              ),
+              every: fieldWithHooks(
+                {
+                  fieldName: 'every',
+                  isPgConnectionFilterField: true,
+                } as any,
+                () => ({
+                  description:
+                    'Filters to entities where every spatially-related entity matches.',
+                  type: TargetFilterType,
+                  apply: buildApply('every'),
+                })
+              ),
+              none: fieldWithHooks(
+                {
+                  fieldName: 'none',
+                  isPgConnectionFilterField: true,
+                } as any,
+                () => ({
+                  description:
+                    'Filters to entities where no spatially-related entity matches.',
+                  type: TargetFilterType,
+                  apply: buildApply('none'),
+                })
+              ),
+            },
+            `PostgisSpatialRelationsPlugin adding some/every/none to ${spatialFilterTypeName(build, rel)}`
+          );
+        }
+
+        return fields;
+      },
+    },
+  },
+};
diff --git a/graphile/graphile-postgis/src/preset.ts b/graphile/graphile-postgis/src/preset.ts
index d2e726e7a2..de789148a7 100644
--- a/graphile/graphile-postgis/src/preset.ts
+++ b/graphile/graphile-postgis/src/preset.ts
@@ -7,6 +7,7 @@ import { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
 import { PostgisMeasurementFieldsPlugin } from './plugins/measurement-fields';
 import { PostgisTransformationFieldsPlugin } from './plugins/transformation-functions';
 import { PostgisAggregatePlugin } from './plugins/aggregate-functions';
+import { PostgisSpatialRelationsPlugin } from './plugins/spatial-relations';
 import { createPostgisOperatorFactory } from './plugins/connection-filter-operators';
 import { createWithinDistanceOperatorFactory } from './plugins/within-distance-operator';
 
@@ -44,7 +45,8 @@ export const GraphilePostgisPreset: GraphileConfig.Preset = {
     PostgisGeometryFieldsPlugin,
     PostgisMeasurementFieldsPlugin,
     PostgisTransformationFieldsPlugin,
-    PostgisAggregatePlugin
+    PostgisAggregatePlugin,
+    PostgisSpatialRelationsPlugin,
   ],
   schema: {
     // connectionFilterOperatorFactories is augmented by graphile-connection-filter
diff --git a/graphql/orm-test/__fixtures__/seed/postgis-spatial-seed.sql b/graphql/orm-test/__fixtures__/seed/postgis-spatial-seed.sql
index d6d650699f..d6b01cce94 100644
--- a/graphql/orm-test/__fixtures__/seed/postgis-spatial-seed.sql
+++ b/graphql/orm-test/__fixtures__/seed/postgis-spatial-seed.sql
@@ -212,3 +212,67 @@ SELECT setval('postgis_test.swarms_geom_id_seq',       2);
 SELECT setval('postgis_test.networks_geom_id_seq',     2);
 SELECT setval('postgis_test.collections_geom_id_seq',  2);
 SELECT setval('postgis_test.towers_geom_id_seq',       2);
+
+-- ============================================================================
+-- SPATIAL RELATIONS FIXTURE — counties + telemedicine_clinics
+--
+-- Exercises the PostgisSpatialRelationsPlugin end-to-end. `@spatialRelation`
+-- smart tags on the owner column synthesise virtual relation + filter fields
+-- whose join predicate is a PostGIS spatial function.
+--
+-- Tag grammar:
+--   @spatialRelation <relationName> <targetTable>.<targetCol> <operator> [param]
+--
+-- All operators here are PG-native snake_case (st_contains, st_intersects,
+-- st_within, st_dwithin, ...) so the plugin can resolve them in pg_proc.
+-- ============================================================================
+
+-- Counties: polygonal regions. Target of cross-table spatial relations.
+CREATE TABLE postgis_test.counties (
+  id serial PRIMARY KEY,
+  name text NOT NULL,
+  geom geometry(Polygon, 4326) NOT NULL
+);
+CREATE INDEX idx_counties_geom ON postgis_test.counties USING gist(geom);
+
+-- Telemedicine clinics: points. Owner of three cross-table relations to
+-- counties and one self-relation for "other clinics within distance".
+CREATE TABLE postgis_test.telemedicine_clinics (
+  id serial PRIMARY KEY,
+  name text NOT NULL,
+  specialty text NOT NULL,
+  location geometry(Point, 4326) NOT NULL
+);
+CREATE INDEX idx_telemedicine_clinics_location
+  ON postgis_test.telemedicine_clinics USING gist(location);
+
+-- Three cross-table relations (clinics -> counties) exercising the three
+-- most common 2-arg spatial predicates, and one parametric self-relation
+-- exercising st_dwithin with a distance argument.
+COMMENT ON COLUMN postgis_test.telemedicine_clinics.location IS
+  E'@spatialRelation county counties.geom st_within\n'
+  '@spatialRelation intersectingCounty counties.geom st_intersects\n'
+  '@spatialRelation coveringCounty counties.geom st_coveredby\n'
+  '@spatialRelation nearbyClinic telemedicine_clinics.location st_dwithin distance';
+
+-- Counties — three polygons with known containment relationships.
+-- Bay County covers SF + Oakland, LA County covers LA, NYC County covers NY.
+INSERT INTO postgis_test.counties (id, name, geom) VALUES
+  (1, 'Bay County',
+     ST_GeomFromText('POLYGON((-122.55 37.70, -122.20 37.70, -122.20 37.85, -122.55 37.85, -122.55 37.70))', 4326)),
+  (2, 'LA County',
+     ST_GeomFromText('POLYGON((-118.70 33.70, -117.60 33.70, -117.60 34.40, -118.70 34.40, -118.70 33.70))', 4326)),
+  (3, 'NYC County',
+     ST_GeomFromText('POLYGON((-74.15 40.60, -73.70 40.60, -73.70 40.90, -74.15 40.90, -74.15 40.60))', 4326));
+
+-- Telemedicine clinics — one per major city plus two extras in the Bay.
+INSERT INTO postgis_test.telemedicine_clinics (id, name, specialty, location) VALUES
+  (1, 'SF Pediatrics',       'pediatrics',  ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 4326)),
+  (2, 'Oakland General',     'general',     ST_SetSRID(ST_MakePoint(-122.2712, 37.8044), 4326)),
+  (3, 'SF Cardio',            'cardiology', ST_SetSRID(ST_MakePoint(-122.4000, 37.7800), 4326)),
+  (4, 'LA Pediatrics',       'pediatrics',  ST_SetSRID(ST_MakePoint(-118.2437, 34.0522), 4326)),
+  (5, 'NYC Cardio',           'cardiology', ST_SetSRID(ST_MakePoint( -74.0060, 40.7128), 4326)),
+  (6, 'Seattle Uncovered',    'general',    ST_SetSRID(ST_MakePoint(-122.3321, 47.6062), 4326));
+
+SELECT setval('postgis_test.counties_id_seq',               3);
+SELECT setval('postgis_test.telemedicine_clinics_id_seq',   6);
diff --git a/graphql/orm-test/__tests__/postgis-spatial-relations.test.ts b/graphql/orm-test/__tests__/postgis-spatial-relations.test.ts
new file mode 100644
index 0000000000..05ca41fb68
--- /dev/null
+++ b/graphql/orm-test/__tests__/postgis-spatial-relations.test.ts
@@ -0,0 +1,397 @@
+/**
+ * PostgisSpatialRelationsPlugin — ORM Integration Test
+ *
+ * Exercises cross-table and self-relation spatial filters declared via
+ * `@spatialRelation` smart tags.
+ *
+ * Fixture (see __fixtures__/seed/postgis-spatial-seed.sql):
+ *   - counties(id, name, geom GEOMETRY(Polygon, 4326))
+ *   - telemedicine_clinics(id, name, specialty, location GEOMETRY(Point, 4326))
+ *   - COMMENT ON telemedicine_clinics.location declares:
+ *       @spatialRelation county            counties.geom               st_within
+ *       @spatialRelation intersectingCounty counties.geom              st_intersects
+ *       @spatialRelation coveringCounty    counties.geom               st_coveredby
+ *       @spatialRelation nearbyClinic      telemedicine_clinics.location st_dwithin distance
+ */
+import { join } from 'path';
+import { getConnectionsObject, seed } from 'graphile-test';
+import type { GraphQLQueryFnObj } from 'graphile-test';
+import { ConstructivePreset } from 'graphile-settings';
+import { runCodegenAndLoad } from './helpers/codegen-helper';
+import { GraphileTestAdapter } from './helpers/graphile-adapter';
+
+jest.setTimeout(120000);
+
+const seedFile = join(
+  __dirname,
+  '..',
+  '__fixtures__',
+  'seed',
+  'postgis-spatial-seed.sql',
+);
+const SCHEMA = 'postgis_test';
+
+// Fixture row IDs (serial, 1-indexed).
+const SF_PEDIATRICS = 1;
+const OAKLAND_GENERAL = 2;
+const SF_CARDIO = 3;
+const LA_PEDIATRICS = 4;
+const NYC_CARDIO = 5;
+const SEATTLE_UNCOVERED = 6;
+
+/** Extract the sole connection field from the ORM response. */
+function unwrap(
+  data: unknown,
+): { nodes: Array<{ id: number | string }>; totalCount?: number } {
+  return Object.values(data as Record<string, unknown>)[0] as any;
+}
+
+/** Sort numeric ids ascending and return them. */
+function ids(nodes: Array<{ id: number | string }>): number[] {
+  return nodes.map((n) => Number(n.id)).sort((a, b) => a - b);
+}
+
+describe('PostgisSpatialRelationsPlugin (ORM, live PG)', () => {
+  let teardown: () => Promise<void>;
+  let query: GraphQLQueryFnObj;
+  let orm: Record<string, any>;
+  let introspection: any;
+
+  beforeAll(async () => {
+    const connections = await getConnectionsObject(
+      {
+        schemas: [SCHEMA],
+        preset: { extends: [ConstructivePreset] },
+        useRoot: true,
+        db: {
+          extensions: ['postgis'],
+        },
+      },
+      [seed.sqlfile([seedFile])],
+    );
+    teardown = connections.teardown;
+    query = connections.query;
+
+    const loaded = await runCodegenAndLoad(query, 'postgis-spatial-relations');
+    const adapter = new GraphileTestAdapter(query);
+    orm = loaded.createClient({ adapter });
+
+    // Capture the live schema for shape assertions below.
+    const { SCHEMA_INTROSPECTION_QUERY } = await import(
+      '@constructive-io/graphql-query'
+    );
+    const introResult = await query<{ __schema: any }>({
+      query: SCHEMA_INTROSPECTION_QUERY,
+    });
+    introspection = introResult.data!;
+  });
+
+  afterAll(async () => {
+    if (teardown) await teardown();
+  });
+
+  // ==========================================================================
+  // SECTION A — Schema shape
+  //
+  // Verify that the plugin actually registered filter fields on the owner
+  // codec's Filter type, with the right types (sub-filter for 2-arg ops,
+  // parametric spatial filter for st_dwithin).
+  // ==========================================================================
+  describe('A. Schema shape', () => {
+    const findType = (name: string) =>
+      introspection.__schema.types.find((t: any) => t.name === name);
+
+    it('registers the 2-arg spatial relations directly as sub-filter fields', () => {
+      const clinicFilter = findType('TelemedicineClinicFilter');
+      expect(clinicFilter).toBeDefined();
+      const fields = (clinicFilter.inputFields as Array<any>).map(
+        (f) => f.name,
+      );
+      expect(fields).toEqual(
+        expect.arrayContaining([
+          'county',
+          'intersectingCounty',
+          'coveringCounty',
+          'nearbyClinic',
+        ]),
+      );
+    });
+
+    it('2-arg relations point at the target table Filter type (via some/every/none)', () => {
+      const clinicFilter = findType('TelemedicineClinicFilter');
+      const countyField = (clinicFilter.inputFields as Array<any>).find(
+        (f) => f.name === 'county',
+      );
+      expect(countyField).toBeDefined();
+      // Wrapped filter type
+      const wrapperTypeName =
+        countyField.type?.name ?? countyField.type?.ofType?.name;
+      const wrapper = findType(wrapperTypeName);
+      expect(wrapper).toBeDefined();
+      const subNames = (wrapper.inputFields as Array<any>).map(
+        (f: any) => f.name,
+      );
+      expect(subNames).toEqual(
+        expect.arrayContaining(['some', 'every', 'none']),
+      );
+    });
+
+    it('parametric st_dwithin relation exposes a required distance Float field', () => {
+      const clinicFilter = findType('TelemedicineClinicFilter');
+      const nearField = (clinicFilter.inputFields as Array<any>).find(
+        (f) => f.name === 'nearbyClinic',
+      );
+      expect(nearField).toBeDefined();
+      const wrapperTypeName =
+        nearField.type?.name ?? nearField.type?.ofType?.name;
+      const wrapper = findType(wrapperTypeName);
+      expect(wrapper).toBeDefined();
+      const distance = (wrapper.inputFields as Array<any>).find(
+        (f: any) => f.name === 'distance',
+      );
+      expect(distance).toBeDefined();
+      // Must be NonNull<Float>
+      expect(distance.type.kind).toBe('NON_NULL');
+      expect(distance.type.ofType.name).toBe('Float');
+    });
+  });
+
+  // ==========================================================================
+  // SECTION B — Cross-table 2-arg relations
+  // ==========================================================================
+  describe('B. Cross-table spatial relations (2-arg operators)', () => {
+    it('st_within: clinics in Bay County → SF Pediatrics, Oakland General, SF Cardio', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true, name: true },
+          where: { county: { some: { name: { equalTo: 'Bay County' } } } },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual(
+        [SF_PEDIATRICS, OAKLAND_GENERAL, SF_CARDIO].sort((a, b) => a - b),
+      );
+    });
+
+    it('st_within: clinics in LA County → LA Pediatrics only', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: { county: { some: { name: { equalTo: 'LA County' } } } },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual([LA_PEDIATRICS]);
+    });
+
+    it('st_within: clinics in NYC County → NYC Cardio only', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: { county: { some: { name: { equalTo: 'NYC County' } } } },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual([NYC_CARDIO]);
+    });
+
+    it('st_within: Seattle Uncovered matches no county', async () => {
+      // Seattle_Uncovered's point is not inside any seeded county polygon,
+      // so `county: { some: {...} }` with no name filter should still exclude it.
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true, name: true },
+          where: { county: { some: {} } },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).not.toContain(SEATTLE_UNCOVERED);
+    });
+
+    it('st_intersects: same sets as st_within for point-in-polygon cases', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: {
+            intersectingCounty: { some: { name: { equalTo: 'Bay County' } } },
+          },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual(
+        [SF_PEDIATRICS, OAKLAND_GENERAL, SF_CARDIO].sort((a, b) => a - b),
+      );
+    });
+
+    it('st_coveredby: clinics coveredBy LA County → LA Pediatrics', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: {
+            coveringCounty: { some: { name: { equalTo: 'LA County' } } },
+          },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual([LA_PEDIATRICS]);
+    });
+  });
+
+  // ==========================================================================
+  // SECTION C — `none` and `every` sub-filters
+  // ==========================================================================
+  describe('C. some / every / none modes on spatial relations', () => {
+    it('none: clinics whose county has name = "NYC County" → everyone except NYC Cardio', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: { county: { none: { name: { equalTo: 'NYC County' } } } },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).not.toContain(NYC_CARDIO);
+      expect(ids(unwrap(r.data).nodes)).toContain(SF_PEDIATRICS);
+    });
+
+    it('every (no sub-filter): all clinics with at least one containing county → matches rows inside some county', async () => {
+      // `every: {}` is tautologically true when there are no matching rows,
+      // so the assertion is weaker here — we just assert no crash + some
+      // expected rows present.
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: { county: { every: { name: { equalTo: 'Bay County' } } } },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+    });
+  });
+
+  // ==========================================================================
+  // SECTION D — Self-relation with parametric st_dwithin
+  // ==========================================================================
+  describe('D. Self-relation with st_dwithin (parametric distance)', () => {
+    it('finds clinics near SF cardiology clinics within 10 SRID units (degrees)', async () => {
+      // 10 degrees is huge in SRID-4326 units — it's easily enough to sweep in
+      // SF Pediatrics, Oakland General, SF Cardio, and LA Pediatrics, but not
+      // NYC (>40 degrees away) or Seattle (~10 degrees north, borderline).
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true, name: true },
+          where: {
+            nearbyClinic: {
+              distance: 10.0,
+              some: { specialty: { equalTo: 'cardiology' } },
+            },
+          },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      const got = ids(unwrap(r.data).nodes);
+      // NYC Cardio is a cardiology clinic itself — BUT the self-exclusion
+      // predicate means NYC Cardio is not "near itself" for this query.
+      // SF Cardio is the only other cardiology clinic, so we expect clinics
+      // within 10 degrees of SF Cardio → SF Pediatrics, Oakland General.
+      // NYC Cardio is within 10 degrees of itself only (excluded).
+      expect(got).toEqual(expect.arrayContaining([SF_PEDIATRICS, OAKLAND_GENERAL]));
+      // Self-exclusion must leave SF Cardio out of its own radius match
+      // when the inner filter requires cardiology — SF Cardio would match
+      // only via itself, which is excluded.
+      expect(got).not.toContain(SF_CARDIO);
+    });
+
+    it('finds no clinic when the distance is 0 (nothing is "near" another clinic at exactly 0 degrees)', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: {
+            nearbyClinic: {
+              distance: 0,
+              some: {},
+            },
+          },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      // Every row self-excluded → empty.
+      expect(ids(unwrap(r.data).nodes)).toEqual([]);
+    });
+
+    it('finds the right pair with small distance (~0.1 degree) → SF cluster only', async () => {
+      // SF Pediatrics and SF Cardio are ~0.02 degrees apart; Oakland General
+      // is ~0.15 degrees from SF. A 0.1-degree radius matches the two SF
+      // clinics to each other but nobody else.
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: {
+            nearbyClinic: {
+              distance: 0.1,
+              some: {},
+            },
+          },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual(
+        [SF_PEDIATRICS, SF_CARDIO].sort((a, b) => a - b),
+      );
+    });
+  });
+
+  // ==========================================================================
+  // SECTION E — Composition with AND/OR/NOT + scalar filters
+  // ==========================================================================
+  describe('E. Composition with logical and scalar filters', () => {
+    it('AND: clinics in Bay County that are cardiology → SF Cardio', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: {
+            and: [
+              { county: { some: { name: { equalTo: 'Bay County' } } } },
+              { specialty: { equalTo: 'cardiology' } },
+            ],
+          },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual([SF_CARDIO]);
+    });
+
+    it('OR: clinics in Bay County OR named "LA Pediatrics" → Bay clinics + LA Pediatrics', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: {
+            or: [
+              { county: { some: { name: { equalTo: 'Bay County' } } } },
+              { name: { equalTo: 'LA Pediatrics' } },
+            ],
+          },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual(
+        [SF_PEDIATRICS, OAKLAND_GENERAL, SF_CARDIO, LA_PEDIATRICS].sort(
+          (a, b) => a - b,
+        ),
+      );
+    });
+
+    it('NOT: clinics NOT in Bay County → LA, NYC, Seattle', async () => {
+      const r = await orm.telemedicineClinic
+        .findMany({
+          select: { id: true },
+          where: {
+            not: { county: { some: { name: { equalTo: 'Bay County' } } } },
+          },
+        })
+        .execute();
+      expect(r.ok).toBe(true);
+      expect(ids(unwrap(r.data).nodes)).toEqual(
+        [LA_PEDIATRICS, NYC_CARDIO, SEATTLE_UNCOVERED].sort((a, b) => a - b),
+      );
+    });
+  });
+});