@@ -83,6 +83,9 @@ import { evaluateAnalyticsQueryOverRows } from './preview-evaluator.js';
 // member as the request spelled it (see `dataset-refusal.ts`'s header for why
 // that code and not `DATASET_INVALID`).
 import { invalidMemberError } from './dataset-refusal.js';
+// [#20807] A grouped dimension on a structured-JSON field is refused in
+// `ensureCube`, ahead of both strategies, naming the member the caller wrote.
+import { assertNoStructuredJsonDimension } from './structured-json-dimension-door.js';
 // [#16206] The `sqlDialect` hook's DECLARED accept set, and the predicate that
 // says whether a host answered outside it. Both live next to the membership set
 // the compilers read, so the contract has one definition and this file states
@@ -2373,6 +2376,12 @@ export class AnalyticsService implements IAnalyticsService {
    * where), so a query that gets several wrong is answered about one at a time,
    * naming a real mistake either way.
    *
+   * [#20807] One more door runs between the dimension gate and the `where`
+   * gate, on the same paths: {@link assertDimensionsGroupScalarColumns}, which
+   * refuses a grouped dimension whose column EXISTS but is declared
+   * structured JSON — a question about the column's type, not its existence,
+   * and so asked after it.
+   *
    * [#20356] "Registered" means registered in `scope`: the cube is read from it
    * and what this method mints is recorded in it — the call's own request
    * scope, on every door, so nothing minted here reaches the shared registry
@@ -2401,6 +2410,8 @@ export class AnalyticsService implements IAnalyticsService {
       // spelling is in there — which is why the suggestion list is computed by
       // subtraction inside the gate rather than echoed verbatim.
       this.assertDimensionFields(query, cube, Object.keys(cube.dimensions));
+      // [#20807] …and a grouped dimension's column must not be structured JSON.
+      this.assertDimensionsGroupScalarColumns(query, cube);
       // [#5669] …and the `where`'s, third and last of the three request keys that
       // carry a field name. Its members are read from the filter TREE, not from
       // `cube.dimensions` — which on this path was minted from this very query,
@@ -2472,6 +2483,7 @@ export class AnalyticsService implements IAnalyticsService {
       // authored/compiled list IS the vocabulary a caller may name — and the one
       // the rejection suggests.
       this.assertDimensionFields(query, augmented, Object.keys(cube.dimensions));
+      this.assertDimensionsGroupScalarColumns(query, augmented);
       // [#5669] The `where` gate resolves a filter member through dimensions AND
       // measures (that is what the strategies do for a filter member), so it is
       // handed the AUGMENTED cube — a caller filtering on a suffix-inferred
@@ -2486,10 +2498,44 @@ export class AnalyticsService implements IAnalyticsService {
       // authored cube can declare a measure over a field the object dropped.
       this.assertMeasureFields(query, cube, Object.keys(cube.measures));
       this.assertDimensionFields(query, cube, Object.keys(cube.dimensions));
+      this.assertDimensionsGroupScalarColumns(query, cube);
       this.assertWhereFields(query, cube, Object.keys(cube.dimensions));
     }
   }
 
+  /**
+   * [#20807] Refuse a GROUPED dimension whose column is a declared
+   * structured-JSON field — `INVALID_FIELD` / 400, naming the member the caller
+   * wrote — before either strategy builds anything. The rule, the
+   * measurements and the envelope are {@link assertNoStructuredJsonDimension}'s
+   * (`structured-json-dimension-door.ts`); this method supplies the two
+   * answers only the service has.
+   *
+   * - The column a member groups by is {@link resolveMemberSource}'s, the
+   *   resolver the dimension source-field gate above reads, with the same
+   *   `'dimension'` kind the strategies' `resolveDimensionSql` /
+   *   `resolveFieldName(…, 'dimension')` resolve by.
+   * - Its declared type is {@link AnalyticsServiceConfig.sourceFieldMeta}'s.
+   *
+   * Runs after the dimension source-field gate on every `ensureCube` path, so a
+   * member naming a column the object does not have is answered as that first.
+   * Same stand-downs as that gate: no `sourceFieldMeta`, or a cube whose `sql`
+   * is not a bare object name.
+   */
+  private assertDimensionsGroupScalarColumns(query: AnalyticsQuery, cube: Cube): void {
+    const fieldMeta = this.sourceFieldMeta;
+    if (!fieldMeta) return;
+    const object = typeof cube.sql === 'string' ? cube.sql.trim() : '';
+    if (!object || !BARE_IDENTIFIER.test(object)) return;
+    assertNoStructuredJsonDimension(
+      query,
+      cube,
+      object,
+      (member) => resolveMemberSource(cube, member, 'dimension').source,
+      (o, field) => fieldMeta(o, field)?.type,
+    );
+  }
+
   /**
    * [#4437] Reject a measure whose SOURCE FIELD the backing object does not
    * have, BEFORE the strategy compiles it into SQL.
 
@@ -0,0 +1,134 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#20807] A GROUPED dimension on a STRUCTURED-JSON field — `json`,
+ * `composite`, `repeater`, `record`, `location`, `address`, `vector` — is
+ * refused `INVALID_FIELD` / 400 at the analytics door, naming the member the
+ * caller wrote, before either strategy builds anything.
+ *
+ * ## What ran before this door, measured on `origin/main` `793fb839`
+ *
+ * `POST /api/v1/analytics/query` over the service `AnalyticsServicePlugin`
+ * composes on a real engine, three rows with a different `meta` document each:
+ *
+ * | `dimensions` | SQLite | PostgreSQL 16 |
+ * |:--|:--|:--|
+ * | a `text` member (the control) | 200, one group per value | same |
+ * | a cube or dataset member over a `json` field | 200, one group per serialized document | **500 `DATABASE_ERROR`** ("could not identify an equality operator for type json") |
+ *
+ * `NativeSQLStrategy` compiled `GROUP BY meta` itself and ran it once through
+ * the raw-SQL bridge; `engine.aggregate` was asked 0 times, so the engine's own
+ * `groupBy` door (#20783, `packages/objectql`'s
+ * `group-by-structured-json-door.ts`) never saw the query. `ObjectQLStrategy`
+ * (a driver without raw SQL, or any bucketed time dimension) did reach that
+ * door, and was refused there under the engine's position (`groupBy[0]`), a
+ * name the caller never wrote.
+ *
+ * ## Where it stands
+ *
+ * In `AnalyticsService.ensureCube`, right after the dimension source-field
+ * gate, on every path out of it — so it runs ahead of strategy selection, for
+ * `query()` (the `/analytics/query` door, and every query a dataset selection
+ * runs through `DatasetExecutor`) and for `generateSql()` (the `/analytics/sql`
+ * dry run) alike. This is the first compile step that knows both halves of the
+ * verdict: the member the caller wrote (a `dimensions` entry, or a dataset
+ * dimension's name, which is the cube key it compiled to) and the declared type
+ * of the column it resolves to (`sourceFieldMeta`). One door ahead of both
+ * strategies gives one answer on every driver.
+ *
+ * ## What it judges
+ *
+ * - The members that GROUP: every `dimensions` entry, and every
+ *   `timeDimensions` entry that carries a `granularity` (a bucket is a group
+ *   key; no granularity makes a JSON document a date). A `timeDimensions`
+ *   entry with no granularity only bounds a range and groups nothing.
+ * - The class is `@objectstack/spec/data`'s {@link STRUCTURED_JSON_TYPES},
+ *   the predicate the engine's door reads — never a list minted here.
+ *
+ * **Not judged** (the same "cannot answer, do not block" tiering as every
+ * sibling gate in `ensureCube`): a host that wires no `sourceFieldMeta`, a cube
+ * whose `sql` is not a bare object name, a member the resolver cannot pin to a
+ * bare base column (an expression `sql`, a dotted relation traversal: its
+ * column lives on a joined object that `sourceFieldMeta` does not answer for),
+ * and every other field type.
+ *
+ * ## The envelope
+ *
+ * `INVALID_FIELD` / 400 through {@link invalidMemberError} (ADR-0112): the
+ * verdict is about ONE MEMBER the request named, the family the three
+ * source-field gates and the engine's door already answer with
+ * `INVALID_FIELD`. `member` is the entry as the request spelled it; `field` is
+ * the column it groups by — it exists, and its declared type is the verdict —
+ * and `object` is the object that declares it.
+ *
+ * @see https://github.com/objectstack-ai/objectstack/issues/20807
+ */
+
+import type { Cube } from '@objectstack/spec/data';
+import { STRUCTURED_JSON_TYPES } from '@objectstack/spec/data';
+import type { AnalyticsQuery } from '@objectstack/spec/contracts';
+import { invalidMemberError } from './dataset-refusal.js';
+
+/** One grouped member, tagged with the request key that carried it. */
+interface GroupedMember {
+  readonly member: string;
+  readonly param: 'dimensions' | 'timeDimensions';
+}
+
+/**
+ * The members of `query` that group the result, in request-key order:
+ * `dimensions` first, then each bucketed `timeDimensions` entry.
+ */
+function groupedMembers(query: AnalyticsQuery): GroupedMember[] {
+  return [
+    ...(query.dimensions ?? []).map((member) => ({ member, param: 'dimensions' as const })),
+    ...(query.timeDimensions ?? [])
+      .filter((td) => !!td.granularity)
+      .map((td) => ({ member: td.dimension, param: 'timeDimensions' as const })),
+  ];
+}
+
+/**
+ * Refuse the first grouped member of `query` whose column is a declared
+ * structured-JSON field — `INVALID_FIELD` / 400. See the module header.
+ *
+ * @param object - The object `cube.sql` names (the caller has checked it is a
+ *   bare object name).
+ * @param sourceOf - The bare base column a dimension member groups by, or
+ *   `null` when this door cannot pin one (the dimension gate's resolver).
+ * @param declaredFieldType - The declared `FieldType` of a column on
+ *   `object`, or `undefined` when nothing authoritative answers.
+ *
+ * The words put the verdict first, then that the query did not run, then the
+ * route, then the reason: a door that bounds a 4xx message keeps the front of
+ * it.
+ */
+export function assertNoStructuredJsonDimension(
+  query: AnalyticsQuery,
+  cube: Cube,
+  object: string,
+  sourceOf: (member: string) => string | null,
+  declaredFieldType: (object: string, field: string) => string | undefined,
+): void {
+  for (const { member, param } of groupedMembers(query)) {
+    const field = sourceOf(member);
+    if (!field) continue;
+    const type = declaredFieldType(object, field);
+    if (typeof type !== 'string' || !STRUCTURED_JSON_TYPES.has(type)) continue;
+
+    const kind = param === 'timeDimensions' ? 'Time dimension' : 'Dimension';
+    const verb = param === 'timeDimensions' ? 'buckets' : 'groups by';
+    const err = invalidMemberError(
+      `${kind} '${member}' on cube '${cube.name}' ${verb} field '${field}', which object '${object}' `
+      + `declares as ${type} — a structured-JSON value, which analytics does not group by. `
+      + 'The query was NOT run. Group by a field that stores one scalar value: store the part you '
+      + 'group on in a field of its own and group by that field. A JSON document is no group key '
+      + 'the SQL dialects share: one grouped each serialized document apart, another refused the '
+      + 'statement.',
+      { member, param, cube: cube.name },
+    ) as Error & { field?: string; object?: string };
+    err.field = field;
+    err.object = object;
+    throw err;
+  }
+}