@@ -2,6 +2,7 @@
 "@objectstack/objectql": minor
 "@objectstack/spec": minor
 "@objectstack/lint": patch
+"@objectstack/service-analytics": patch
 ---
 
 fix(objectql,spec)!: a `groupBy` on a multi-value field and a `count_distinct` on a JSON-stored field are refused with `INVALID_FIELD` / 400 at the engine's `aggregate`, on every driver, and the aggregate × field-type table stops accepting `count_distinct` over the JSON-stored types
@@ -28,3 +29,5 @@ Clause-②: no (narrowing)
 **Unchanged.** A `groupBy` or `count_distinct` on a scalar-stored field, a single-value `select` or `lookup` included; `count` over any field; the `having`, filter and sort positions; and an undeclared name, which the REST door answers `INVALID_FIELD` as unknown before the engine is reached.
 
 `@objectstack/lint`: the dataset-measure refusal's hint no longer says `count_distinct` accepts every type.
+
+`@objectstack/service-analytics`: the dataset compile leg's refusal of a `count_distinct` measure over a JSON-stored field says why it diverges (the drivers compare the values for equality three ways) and prescribes `count`, or a scalar field for the part being counted; its other refusals no longer say `count_distinct` accepts every type.
@@ -157,29 +157,31 @@ describe('#16099 — the pairs this leg refuses are the TABLE\'s, not this packa
     expect(isAggregateCompatibleWithFieldType('avg', 'percent')).toBe(true);
   });
 
-  it('⭐ the refused set, enumerated by the card that enforced each part — 155 pairs, 0 left over', () => {
+  it('⭐ the refused set, enumerated by the card that enforced each part — 165 pairs, 0 left over', () => {
     // The arithmetic the PR bodies show, asserted rather than narrated, so a
     // row moving upstream moves this count instead of leaving a stale claim.
     // ⚠️ [#17560] The `minmaxString` / `selecting` split this case used to carry
     // is retired with the reading behind it: the 42 string pairs were counted
     // apart because they were "ruled to be AMENDED" under #17513, and decision
     // batch #127 found no ruling behind that and declined to amend the table.
     // The 42 and the 32 are one population again, enforced in one pass.
-    let refusedByTable = 0, temporal = 0, deriving = 0, selecting = 0;
+    let refusedByTable = 0, temporal = 0, deriving = 0, selecting = 0, distinct = 0;
     for (const a of Object.keys(AGGREGATE_FIELD_TYPE_COMPATIBILITY)) {
       for (const ft of FieldType.options) {
         if (isAggregateCompatibleWithFieldType(a, ft)) continue;
         refusedByTable++;
         if (a === 'min' || a === 'max') { selecting++; continue; }
+        if (a === 'count_distinct') { distinct++; continue; }
         if (TEMPORAL_SOURCE_FIELD_TYPES.has(ft)) { temporal++; continue; }
         deriving++;
       }
     }
-    expect(refusedByTable).toBe(155);
+    expect(refusedByTable).toBe(165);
     expect(temporal).toBe(6);          // commit 357f4992b's — `sum`/`avg` over the temporal class
     expect(deriving).toBe(75);         // #16099's — `sum`/`avg` over everything else
     expect(selecting).toBe(74);        // #17560's — `min`/`max`, 42 string + 32 non-string
-    expect(temporal + deriving + selecting).toBe(refusedByTable);
+    expect(distinct).toBe(10);         // #20808's — `count_distinct` over the JSON-stored types
+    expect(temporal + deriving + selecting + distinct).toBe(refusedByTable);
     // ⭐ And nothing is left declared-but-unenforced: one door judges all six.
     expect(Object.keys(AGGREGATE_FIELD_TYPE_COMPATIBILITY).length).toBe(6);
   });
@@ -326,7 +328,7 @@ describe('#16099 — the controls: every pair the table accepts still compiles',
     expect(err.message).not.toContain('derives a NUMBER');
   });
 
-  it('`count` / `count_distinct` accept every type — they read no arithmetic off the value', async () => {
+  it('`count` / `count_distinct` over a scalar-stored field compile — they read no arithmetic off the value', async () => {
     for (const aggregate of ['count', 'count_distinct'] as const) {
       const { go, sqls } = run(aggregate, 'note');
       const result: any = await go();
@@ -335,6 +337,30 @@ describe('#16099 — the controls: every pair the table accepts still compiles',
     }
   });
 
+  // [#20808] The table's `count_distinct` row stops accepting the JSON-stored
+  // types, and this door judges every row: the refusal says why a distinct
+  // count diverges there (EQUALITY, not arithmetic or order) and never says
+  // `count_distinct` accepts every type.
+  it('[#20808] `count_distinct` over a JSON-stored field → DATASET_INVALID / 400 in the distinct words, before any SQL', async () => {
+    for (const [field, declared] of [['payload', 'json'], ['embedding', 'vector'], ['tags_list', 'multiselect']] as const) {
+      expect(isAggregateCompatibleWithFieldType('count_distinct', declared), declared).toBe(false);
+      const { go, sqls } = run('count_distinct', field);
+      const err = await refusalOf(go);
+      expect({ code: err.code, status: err.status }, declared).toEqual({ code: 'DATASET_INVALID', status: 400 });
+      expect(err.message, declared).toContain(`declares as \`${declared}\``);
+      expect(err.message, declared).toContain('COMPARES the stored values for equality');
+      expect(err.message, declared).not.toContain('derives a NUMBER');
+      expect(err.message, declared).not.toMatch(/count_distinct` accept every type/);
+      expect(err.message, declared).toContain('`count` counts the rows');
+      expect(sqls.length, declared).toBe(0);
+    }
+    // `count` over the same field compiles — it compares nothing.
+    const { go, sqls } = run('count', 'payload');
+    const result: any = await go();
+    expect(result.rows.length).toBe(1);
+    expect(sqls.length).toBe(1);
+  });
+
   it('the three cannot-answer tiers still do not block — unchanged by the widened scope', async () => {
     // 1. a field the hook cannot resolve
     const unknown = run('sum', 'no_such_field');
 
@@ -215,11 +215,22 @@ function aggregateToMetricType(m: DatasetMeasure): Metric['type'] {
  *   the ORDER — collation-dependent for text on every backend, and absent
  *   altogether where the storage form has no ordering operator (`min(jsonb)`
  *   does not exist on PostgreSQL).
+ * - [#20808] `count_distinct` COMPARES the stored values for equality, and
+ *   reaches this sentence only over a JSON-stored field (the table's
+ *   `count_distinct` row refuses the structured-JSON and multi-option types):
+ *   the in-memory driver counted equal documents apart, SQLite compared the
+ *   serialized text, and PostgreSQL has no equality operator for `json`.
  *
- * `count` / `count_distinct` accept every type and never reach this sentence.
+ * `count` accepts every type and never reaches this sentence.
  */
 const DIVERGENCE_BY_AGGREGATE = (aggregate: string, fieldType: string): string =>
-  aggregate === 'min' || aggregate === 'max'
+  aggregate === 'count_distinct'
+    ? `"${aggregate}" COMPARES the stored values for equality, so over a \`${fieldType}\` column `
+      + 'the answer is decided by how each backend compares a JSON-stored value rather than by '
+      + 'the data — one counts every row apart, one compares the serialized text, another has no '
+      + 'equality for the type and fails at query time — and one dataset would mean two things '
+      + 'on two deployments. '
+  : aggregate === 'min' || aggregate === 'max'
     ? `"${aggregate}" SELECTS one of the stored values, so over a \`${fieldType}\` column the `
       + 'answer is decided by the ORDER the SQL dialect happens to impose rather than by the '
       + 'data — string order is collation-dependent, and some storage forms have no ordering '
@@ -244,19 +255,28 @@ const DIVERGENCE_BY_AGGREGATE = (aggregate: string, fieldType: string): string =
  * wants. [#17560] The selecting sentence is the third: an author who wrote
  * `min` over a text column wanted a FIRST ROW, and a sort delivers that in one
  * declared order instead of asking each backend for its own smallest value.
+ * [#20808] The distinct sentence is the fourth: `count_distinct` over a
+ * JSON-stored field has no value every backend compares alike, so the author
+ * counts rows, or counts distinct a scalar field holding the part they meant.
+ * The other two non-temporal sentences no longer say `count_distinct` accepts
+ * every type: since #20808 it accepts every type but the JSON-stored ones.
  */
 const REMEDY_BY_SOURCE_CLASS = (fieldType: string, aggregate: string): string =>
   TEMPORAL_SOURCE_FIELD_TYPES.has(fieldType)
     ? 'For a temporal field, `min`/`max` return a real instant; a DURATION has to be '
       + 'stored as a number (a computed "days open" field) and aggregated as one.'
+    : aggregate === 'count_distinct'
+      ? 'For a JSON-stored field, `count` counts the rows; a distinct count has to be taken '
+        + 'over a field that stores one scalar value, so store the part you count in a field '
+        + 'of its own and `count_distinct` that field.'
     : aggregate === 'min' || aggregate === 'max'
-      ? 'For a field with no backend-independent order, `count`/`count_distinct` accept every '
-        + 'type because they read neither arithmetic nor order off the value; a "first" or '
-        + '"last" record is a SORT on the record list, which orders once in a declared '
+      ? 'For a field with no backend-independent order, `count` accepts every type because it '
+        + 'reads no value, and `count_distinct` every type but the JSON-stored ones; a "first" '
+        + 'or "last" record is a SORT on the record list, which orders once in a declared '
         + 'direction, not an aggregate that asks every backend for its own smallest value.'
-      : 'For a non-numeric field, `count`/`count_distinct` accept every type because they '
-        + 'read no arithmetic off the value; a quantity that should be added up has to be '
-        + 'stored as a numeric field and aggregated as one.';
+      : 'For a non-numeric field, `count` accepts every type because it reads no value, and '
+        + '`count_distinct` every type but the JSON-stored ones; a quantity that should be '
+        + 'added up has to be stored as a numeric field and aggregated as one.';
 
 /**
  * [#16737 / #16099 / #17560] Refuse a measure whose AGGREGATE cannot meaningfully