feat(spec,analytics): AnalyticsResult.fields[].builtinAggregate discriminator for built-in default measures (#14492) (#15017)

`AnalyticsResult.fields[]` gains an optional `builtinAggregate` carrying the
closed `AggregationFunction` vocabulary (count | sum | avg | min | max |
count_distinct); `AnalyticsResultResponseSchema` mirrors it. The producer
(`queryDataset`'s measure enrichment) sets it from the dataset measure's own
`aggregate` exactly when the measure has NO authored `label` — the header a
renderer draws for it is then the server's built-in default, not an author's
text, so an i18n-aware consumer may substitute its own localized name. The
`dataset` create seed drops its hardcoded `label: 'Count'` so a Studio-created
dataset is a built-in default on the wire rather than an authored English
literal. Authored labels (string or locale map) never carry the field.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: hotlong

.changeset/analytics-result-builtin-aggregate.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-analytics": minor
+---
+
+feat(spec,analytics): `AnalyticsResult.fields[].builtinAggregate` — a closed discriminator for a measure column whose display name is the server's built-in default (#14492)
+
+**What a consumer sees.** `queryDataset()` (and `POST /api/v1/analytics/dataset/query`,
+which relays the result verbatim) now carries an optional
+`fields[].builtinAggregate?: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'`
+on a measure column. It is present exactly when the dataset measure behind the
+column declares an `aggregate` and **no** `label` — the producer then has nothing
+but the aggregate to name the column by, so it says which aggregate that is. It is
+absent whenever the author declared a label (a plain string or an inline locale
+map, even one with no entry for the request locale: an author's text is never
+re-labelled by a consumer), and absent on dimension columns and derived measures.
+The vocabulary is `AggregationFunction` (`data/query.zod.ts`), the one closed
+aggregate enum — no second spelling. `AnalyticsResultResponseSchema`
+(`api/analytics.zod.ts`) mirrors the member, refusing a spelling outside the enum.
+
+**Why.** An AI-built dashboard's "count of customers by status" chart showed the
+English axis title "Count" on a Chinese UI. The renderer (objectui
+`buildChartSeries()` / `labelOf()`) treats `fields[].label` as resolved author
+content and passes it through verbatim — correctly, since a real custom label
+("Tasks") must survive. What it could not tell apart was an author's text from
+the server's built-in default for a bare `count`. Guessing from the label text
+was refused (it would catch an author who really named a field `Count`, and break
+the moment the default is spelled in another language); translating on the
+server was not taken (it copies the front end's language decision into the
+producer and leaves nothing for a per-widget override). The ruling (2026-09-02,
+option B) is a structured discriminator on the contract: the consumer prefers a
+locale lookup keyed by `builtinAggregate` — mirroring its existing
+`report.aggregate.*` keys — and falls back to `label`, then `name`.
+
+**Producer-side changes.**
+
+- `@objectstack/service-analytics` — `queryDataset`'s measure enrichment sets
+  `builtinAggregate` from the dataset measure's own `aggregate` when the measure
+  has no authored `label`. Judged on the authored key, never on the resolved
+  string.
+- `@objectstack/spec` — the `dataset` create seed (`metadata-create-seeds.ts`)
+  drops its hardcoded `label: 'Count'` from the seeded `count` measure, so a
+  dataset created from Studio is a built-in default (wire: `builtinAggregate:
+  'count'`) instead of an authored English literal. `getMeta()` for such a
+  dataset now titles the metric by its name (`count`) rather than `Count`;
+  `CubeMeta.measures[].type` already carried the aggregate there.
+
+Purely additive: no key is removed or renamed, no authorable schema changes shape,
+and a consumer that ignores the member sees exactly the response it saw before.

packages/rest/src/analytics-routes.test.ts

@@ -65,6 +65,22 @@ describe('POST /analytics/dataset/query', () => {
     expect(queryDataset.mock.calls[0][1]).toEqual(selection);
   });
 
+  // #14492 — `fields[].builtinAggregate` is relayed verbatim: the handler ends
+  // in `res.json(result)` with no reshaping, so the discriminator the service
+  // set is exactly what the renderer reads.
+  it('relays fields[].builtinAggregate unchanged (#14492)', async () => {
+    const fields = [
+      { name: 'status', type: 'string', label: 'Status' },
+      { name: 'count', type: 'number', builtinAggregate: 'count' },
+    ];
+    const queryDataset = vi.fn().mockResolvedValue({ rows: [{ status: 'active', count: 3 }], fields });
+    const { route } = buildServer(async () => ({ queryDataset }));
+    const res = mockRes();
+    await route!.handler({ method: 'POST', params: {}, headers: {}, body: { dataset: inlineDataset, selection } } as any, res);
+    expect(res.statusCode).toBe(200);
+    expect(res.body.fields).toEqual(fields);
+  });
+
   it('returns 501 when no analytics service is configured', async () => {
     const { route } = buildServer(undefined);
     const res = mockRes();

packages/services/service-analytics/src/__tests__/query-dataset.test.ts

@@ -531,3 +531,81 @@ describe('AnalyticsService.queryDataset', () => {
     expect(result.rows).toEqual([{ account: 'name-acc1', revenue: 1000 }]);
   });
 });
+
+// ── #14492 — built-in aggregate discriminator ──────────────────────────────
+// `fields[].label` is only ever written from the DATASET MEASURE's own `label`
+// (the enrichment block in `queryDataset`), so the question "is this header the
+// server's default or the author's text?" is answerable from the measure alone:
+// no `label` + an `aggregate` ⇒ built-in default ⇒ the column says which
+// aggregate, and an i18n-aware renderer substitutes its own name for it.
+describe('AnalyticsService.queryDataset — fields[].builtinAggregate (#14492)', () => {
+  const svcFor = (rows: Array<Record<string, unknown>>) => new AnalyticsService({
+    queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: false, inMemory: false }),
+    executeRawSql: async () => rows,
+    getReadScope: (_o, ctx?: ExecutionContext) => (ctx?.tenantId ? { organization_id: ctx.tenantId } : undefined),
+  });
+  const ds = (measures: Array<Record<string, unknown>>) => DatasetSchema.parse({
+    name: 'customers', label: 'Customers', object: 'customer', include: [],
+    dimensions: [{ name: 'status', field: 'status', type: 'string' }],
+    measures,
+  });
+  const run = async (measures: Array<Record<string, unknown>>, names: string[], rows: Array<Record<string, unknown>>) => {
+    const r = await svcFor(rows).queryDataset(ds(measures), { dimensions: ['status'], measures: names }, { tenantId: 'org_A' } as ExecutionContext);
+    return Object.fromEntries((r.fields ?? []).map((f) => [f.name, f]));
+  };
+
+  it('a label-less built-in `count` measure carries builtinAggregate: "count" and no label', async () => {
+    const fields = await run([{ name: 'count', aggregate: 'count' }], ['count'], [{ status: 'active', count: 3 }]);
+    expect(fields.count?.builtinAggregate).toBe('count');
+    expect(fields.count?.label).toBeUndefined();
+    // A dimension column is never a built-in aggregate.
+    expect(fields.status?.builtinAggregate).toBeUndefined();
+  });
+
+  it('an author-labelled measure ("Tasks") keeps its text and carries NO builtinAggregate', async () => {
+    const fields = await run([{ name: 'task_count', aggregate: 'count', label: 'Tasks' }], ['task_count'], [{ status: 'open', task_count: 7 }]);
+    expect(fields.task_count?.label).toBe('Tasks');
+    expect(fields.task_count?.builtinAggregate).toBeUndefined();
+  });
+
+  it('an inline locale-map label with no entry for the request locale is STILL an authored label — no discriminator', async () => {
+    const r = await svcFor([{ status: 'open', task_count: 7 }]).queryDataset(
+      ds([{ name: 'task_count', aggregate: 'count', label: { en: 'Tasks' } }]),
+      { dimensions: ['status'], measures: ['task_count'] },
+      { tenantId: 'org_A', locale: 'fr' } as ExecutionContext,
+    );
+    const f = (r.fields ?? []).find((x) => x.name === 'task_count');
+    expect(f).toBeDefined();
+    expect(f?.builtinAggregate).toBeUndefined();
+  });
+
+  it('every aggregate in the closed vocabulary is carried verbatim when the measure is label-less', async () => {
+    const fields = await run(
+      [
+        { name: 'total', aggregate: 'sum', field: 'amount' },
+        { name: 'mean', aggregate: 'avg', field: 'amount' },
+        { name: 'owners', aggregate: 'count_distinct', field: 'owner' },
+      ],
+      ['total', 'mean', 'owners'],
+      [{ status: 'open', total: 10, mean: 5, owners: 2 }],
+    );
+    expect(fields.total?.builtinAggregate).toBe('sum');
+    expect(fields.mean?.builtinAggregate).toBe('avg');
+    expect(fields.owners?.builtinAggregate).toBe('count_distinct');
+  });
+
+  it('a derived measure has no aggregate and therefore no discriminator, while its label-less inputs keep theirs', async () => {
+    const fields = await run(
+      [
+        { name: 'base', aggregate: 'count' },
+        { name: 'met', aggregate: 'count', field: 'met' },
+        { name: 'rate', derived: { op: 'ratio', of: ['met', 'base'] } },
+      ],
+      ['base', 'met', 'rate'],
+      [{ status: 'open', base: 4, met: 2 }],
+    );
+    expect(fields.base?.builtinAggregate).toBe('count');
+    expect(fields.met?.builtinAggregate).toBe('count');
+    expect(fields.rate?.builtinAggregate).toBeUndefined();
+  });
+});

packages/services/service-analytics/src/analytics-service.ts

@@ -1355,6 +1355,22 @@ export class AnalyticsService implements IAnalyticsService {
           const label = resolveI18nLabel(m.label, requestLocale);
           if (label !== undefined) f.label = label;
         }
+        // #14492 — the built-in aggregate discriminator. A measure that declares
+        // an `aggregate` and NO `label` has nothing but the aggregate to be named
+        // by: whatever header a renderer draws for it is the server's built-in
+        // default, not an author's text, so the column says WHICH aggregate that
+        // is and an i18n-aware renderer may substitute its own localized name
+        // (objectui keys `report.aggregate.*` on it — objectui#7258).
+        // Judged on the AUTHORED key, never on the resolved string: an inline
+        // locale map with no entry for `requestLocale` resolves to nothing above,
+        // yet it IS an author's label and must never be re-labelled — so the
+        // test is `m.label == null`, not `f.label == null`. A derived measure
+        // carries no aggregate and gets nothing; an authored label ("Tasks")
+        // keeps its text and gets nothing. The other spelling that would work
+        // here — a heuristic on the label TEXT ("Count") — was refused on
+        // #14492: it would catch an author who really named a field `Count`,
+        // and break the moment the default is spelled in another language.
+        if (f.builtinAggregate == null && m.label == null && m.aggregate) f.builtinAggregate = m.aggregate;
         if (f.format == null && m.format) f.format = m.format;
         // ADR-0053 currency chain. A MONETARY measure resolves its display
         // currency from: explicit measure `currency` → source-field

packages/spec/src/api/analytics.test.ts

@@ -205,6 +205,31 @@ describe('AnalyticsResultResponseSchema', () => {
     expect(resp.data.fields[2].format).toBe('0.0%');
   });
 
+  // #14492 — the built-in aggregate discriminator rides the same channel, and
+  // it is the CLOSED `AggregationFunction` vocabulary: a spelling outside it is
+  // refused at the member, not stripped or passed through.
+  it('should preserve fields[].builtinAggregate and refuse a spelling outside the closed enum', () => {
+    const resp = AnalyticsResultResponseSchema.parse({
+      success: true,
+      data: {
+        rows: [{ status: 'active', count: 3 }],
+        fields: [
+          { name: 'status', type: 'string', label: 'Status' },
+          { name: 'count', type: 'number', builtinAggregate: 'count' },
+        ],
+      },
+    });
+    expect(resp.data.fields[1].builtinAggregate).toBe('count');
+    expect(resp.data.fields[0].builtinAggregate).toBeUndefined();
+
+    const bad = AnalyticsResultResponseSchema.safeParse({
+      success: true,
+      data: { rows: [], fields: [{ name: 'count', type: 'number', builtinAggregate: 'total' }] },
+    });
+    expect(bad.success).toBe(false);
+    expect(bad.success ? [] : bad.error.issues.map((i) => i.path.join('.'))).toContain('data.fields.0.builtinAggregate');
+  });
+
   it('should preserve totals — the marginal-aggregate channel, grand total included', () => {
     const resp = AnalyticsResultResponseSchema.parse({
       success: true,

packages/spec/src/api/analytics.zod.ts

@@ -2,6 +2,7 @@
 
 import { z } from 'zod';
 import { AnalyticsQuerySchema } from '../data/analytics.zod';
+import { AggregationFunction } from '../data/query.zod';
 import { BaseResponseSchema } from './contract.zod';
 import { retiredKey } from '../shared/retired-key';
 
@@ -110,6 +111,13 @@ export const AnalyticsResultResponseSchema = lazySchema(() => BaseResponseSchema
         + 'not a percentage. Renderers that receive it must scale by it instead '
         + 'of guessing from the value.',
       ),
+      builtinAggregate: AggregationFunction.optional().describe(
+        'Closed aggregate discriminator for a measure column whose display name '
+        + 'is the server\'s built-in default: the dataset measure declared an '
+        + '`aggregate` and no `label`. A renderer may substitute its own localized '
+        + 'name for the aggregate. Absent whenever the author declared a label, and '
+        + 'on dimension / derived columns.',
+      ),
     })).describe('Column metadata'),
     sql: z.string().optional().describe('Executed SQL (if debug enabled)'),
     totals: z.array(z.object({

packages/spec/src/contracts/analytics-service.test.ts

@@ -70,6 +70,24 @@ describe('Analytics Service Contract', () => {
     expect(meta[0].measures).toHaveLength(1);
   });
 
+  // #14492 — `fields[].builtinAggregate` is optional and is the closed
+  // `AggregationFunction` vocabulary, nothing else. The first two literals are
+  // the two shapes the producer emits (built-in default vs authored label); the
+  // third pins the closure at compile time.
+  it('carries builtinAggregate on a built-in default measure column and refuses a spelling outside the enum', () => {
+    const builtin: AnalyticsResult['fields'][number] = { name: 'count', type: 'number', builtinAggregate: 'count' };
+    const authored: AnalyticsResult['fields'][number] = { name: 'task_count', type: 'number', label: 'Tasks' };
+    expect(builtin.builtinAggregate).toBe('count');
+    expect(authored.builtinAggregate).toBeUndefined();
+    const offEnum: AnalyticsResult['fields'][number] = {
+      name: 'count',
+      type: 'number',
+      // @ts-expect-error — `total` is not an AggregationFunction; the discriminator is closed
+      builtinAggregate: 'total',
+    };
+    expect(offEnum.name).toBe('count');
+  });
+
   it('should generate SQL without executing', async () => {
     const service: IAnalyticsService = {
       query: async () => ({ rows: [], fields: [] }),

packages/spec/src/contracts/analytics-service.ts

@@ -66,6 +66,23 @@ export interface AnalyticsResult {
          * by it instead of guessing from the value (objectui#3136).
          */
         percentScale?: PercentScale;
+        /**
+         * #14492 — the closed aggregate discriminator for a measure column whose
+         * display name is the SERVER's built-in default rather than an author's
+         * text. Present exactly when the dataset measure behind the column
+         * declares an `aggregate` and NO `label`: the producer then has nothing
+         * but the aggregate to name the column by, so it says which aggregate
+         * that is (`count` for the seeded / auto-derived `count` measure) and a
+         * renderer may substitute its own localized name for it — objectui keys
+         * a locale lookup on this value (its `report.aggregate.*` family) and
+         * falls back to `label`, then `name`. Absent whenever the author declared
+         * a label (a plain string OR an inline locale map, even one with no entry
+         * for the request locale — an author's text is never re-labelled by a
+         * consumer), and absent on dimension columns and derived measures.
+         * Reuses `AggregationFunction` (data/query.zod.ts), the one closed
+         * aggregate vocabulary; no second spelling.
+         */
+        builtinAggregate?: AggregationFunction;
     }>;
     /** Generated SQL (if available) */
     sql?: string;

packages/spec/src/kernel/metadata-create-seeds.ts

@@ -95,7 +95,12 @@ const BUILTIN_METADATA_CREATE_SEEDS: Partial<Record<MetadataType, unknown>> = {
     object: PLACEHOLDER_OBJECT,
     dimensions: [],
     // A dataset needs at least one measure to be useful; seed a count.
-    measures: [{ name: 'count', label: 'Count', aggregate: 'count' }],
+    // [#14492] No `label` on purpose: an authored label is the author's text
+    // and reaches the wire verbatim (`AnalyticsResult.fields[].label`), which
+    // made this seeded "Count" an English literal on every non-English chart.
+    // Label-less, the measure is the server's built-in default — the response
+    // carries `builtinAggregate: 'count'` and the renderer localizes the name.
+    measures: [{ name: 'count', aggregate: 'count' }],
   },
   object: {
     name: 'new_object',