fix(analytics): review round 1 on the duration measure

- The field read gate resolves a duration measure first, as every other seam
  does: a dimension sharing its name no longer hides its two columns.
- MySQL divides by a DOUBLE literal, so the arm is double precision like the
  other two; the docs and changeset claim live parity for SQLite and
  PostgreSQL only.
- getMeta lists a registered dataset's duration measures with their aggregate,
  label and format, and every seam accepts the `<cube>.<name>` spelling it
  lists them under, its scoped filter included.
- Docs: path and expression refusals happen at parse, not in the lint rule.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AKPixnkg91qCkQCVFDJuqW

Author: claude

.changeset/25778-dataset-duration-measure.md

@@ -10,7 +10,7 @@ Clause-②: yes (widening)
 Metadata-protocol: added
 
 - **`@objectstack/spec`**: `DatasetMeasureSchema` gains an optional `duration: { from, to, unit }`, in place of `field`. `from` and `to` name two `datetime` fields of the dataset's own object by their bare names, `unit` is `seconds`, `minutes`, `hours` or `days`, and the measure's `aggregate` is `avg`, `min`, `max` or `sum` of `to` minus `from`. A relationship path, an expression or the row wildcard in either column, the same column twice, another unit, a counting aggregate, or a `field`, `derived` or `currency` beside it is refused at parse. New exports: `DatasetMeasureDurationSchema`, `DatasetDurationUnit`, `DATASET_DURATION_UNIT_SECONDS`, `DATASET_DURATION_AGGREGATES`, `DATASET_DURATION_FIELD_TYPE` and the `DatasetMeasureDuration` / `DatasetDurationUnit` types.
-- **`@objectstack/service-analytics`**: the dataset compile refuses a duration column declared anything but `datetime` (`400 DATASET_INVALID`, naming the column and its type). The native-SQL strategy computes the duration as one statement on SQLite, PostgreSQL and MySQL, with the same number on each: a record missing either instant is left out, a `to` before its `from` counts as negative, and over a group with no such record `sum` answers `0` and the others `null`. Measure filters, derived measures, ordering and the draft preview serve it. A query the native strategy does not serve (a time dimension bucketed by `granularity`, a field-to-field filter, an object served through engine middleware or an external datasource, a non-SQL datasource) is refused with `400 INVALID_FIELD` naming the measure. Its two columns pass the field-level read gate like any measure's field. The temporal half of the aggregate × field-type refusal now names the duration measure instead of a stored "days open" number.
+- **`@objectstack/service-analytics`**: the dataset compile refuses a duration column declared anything but `datetime` (`400 DATASET_INVALID`, naming the column and its type). The native-SQL strategy computes the duration as one statement on SQLite, PostgreSQL and MySQL, in double precision on each; SQLite and PostgreSQL are tested live to answer the same number: a record missing either instant is left out, a `to` before its `from` counts as negative, and over a group with no such record `sum` answers `0` and the others `null`. Measure filters, derived measures, ordering and the draft preview serve it. A query the native strategy does not serve (a time dimension bucketed by `granularity`, a field-to-field filter, an object served through engine middleware or an external datasource, a non-SQL datasource) is refused with `400 INVALID_FIELD` naming the measure. Its two columns pass the field-level read gate like any measure's field. The temporal half of the aggregate × field-type refusal now names the duration measure instead of a stored "days open" number.
 - **`@objectstack/lint`**: `os validate` refuses a duration column not declared `datetime` with the new gating rule `measure-duration-field-type-refused` (at `datasets[N].measures[M].duration.from` / `.to`), with an `os explain` entry. `dataset-field-unknown` now also reports a duration column the object does not declare.
 
 What to do: nothing. A dataset without `duration` parses, compiles and answers exactly as before.

content/docs/data-modeling/analytics.mdx

@@ -107,10 +107,10 @@ in place of `field`:
 ```
 
 - `from` and `to` name two `datetime` fields of the dataset's own object, by
-  their bare names. A relationship path, an expression, or a `date`, `time`,
-  number or text field is refused: `os validate` reports
-  `measure-duration-field-type-refused`, and the dataset compile answers
-  `400 DATASET_INVALID`.
+  their bare names. A relationship path or an expression is refused when the
+  dataset is parsed. A `date`, `time`, number or text field is refused too:
+  `os validate` reports `measure-duration-field-type-refused`, and the dataset
+  compile answers `400 DATASET_INVALID`.
 - `unit` is `seconds`, `minutes`, `hours` or `days`, and the measure answers a
   number of them (`1.5` hours). `aggregate` is `avg`, `min`, `max` or `sum`.
 - A record missing either instant is left out, as a null is left out of an
@@ -119,8 +119,8 @@ in place of `field`:
   nothing.
 - A measure `filter`, and a `derived` measure naming the duration measure in
   `of`, work as they do for any measure.
-- It runs as one SQL statement on SQLite, PostgreSQL and MySQL, and answers the
-  same number on each. A query the service cannot compile to one such
+- It runs as one SQL statement on SQLite, PostgreSQL and MySQL, computed in
+  double precision on each. A query the service cannot compile to one such
   statement is refused with `400 INVALID_FIELD` naming the measure, rather than
   answered another way: a time dimension bucketed by `granularity` (a monthly
   trend), a field-to-field comparison in a filter, an object served through

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

@@ -277,7 +277,7 @@ for (const cell of CELLS) {
         );
         expect(run.error, run.error?.message).toBeUndefined();
         expect(run.rawSql).toBe(1);
-        expect(reads.statements.at(-1)).toContain('ORDER BY "total_seconds" ASC');
+        expect(reads.statements[reads.statements.length - 1]).toContain('ORDER BY "total_seconds" ASC');
         expect(run.value!.rows).toEqual([{ category: 'b', total_seconds: -3599.25 }]);
       });
 

packages/services/service-analytics/src/__tests__/native-sql-duration-measure.test.ts

@@ -77,8 +77,8 @@ describe('[#25778] NativeSQLStrategy — the duration measure as a statement', (
     ],
     [
       'mysql',
-      'AVG(((TIMESTAMPDIFF(MICROSECOND, opened_at, resolved_at) / 1000000.0) / 3600.0)) AS "avg_hours"',
-      'SUM(CASE WHEN priority = $1 THEN (TIMESTAMPDIFF(MICROSECOND, opened_at, resolved_at) / 1000000.0) END) AS "total_seconds"',
+      'AVG(((TIMESTAMPDIFF(MICROSECOND, opened_at, resolved_at) / 1.0E6) / 3600.0)) AS "avg_hours"',
+      'SUM(CASE WHEN priority = $1 THEN (TIMESTAMPDIFF(MICROSECOND, opened_at, resolved_at) / 1.0E6) END) AS "total_seconds"',
     ],
   ])('%s: the per-dialect difference, divided by the unit, under the aggregate and its measure filter', async (dialect, avg, filteredSum) => {
     const { sql, params } = await native.generateSql(q(), nativeCtx({ dialect }));
@@ -258,6 +258,88 @@ describe('[#25778] AnalyticsService — the gates a duration measure passes thro
     expect(executed).toEqual([]);
   });
 
+  it('a dimension sharing its name does not hide its columns from the read gate', async () => {
+    const shadowed = DatasetSchema.parse({
+      ...DATASET_BASE,
+      dimensions: [...DATASET_BASE.dimensions, { name: 'resolution_seconds_sum', field: 'category', type: 'string' }],
+    });
+    const { service, executed } = makeService({ readable: FIELDS.filter((f) => f !== 'resolved_at') });
+    const err = await refusalOf(service.queryDataset(shadowed, { measures: ['resolution_seconds_sum'], dimensions: ['category'] } as never, MEMBER));
+    expect(err?.code, err?.message).toBe('PERMISSION_DENIED');
+    expect(err?.status).toBe(403);
+    expect(err?.message).toContain('resolved_at');
+    expect(executed).toEqual([]);
+  });
+
+  describe('on the cube door, under the `<cube>.<name>` spelling the discovery surface lists', () => {
+    const listed = DatasetSchema.parse({
+      ...DATASET_BASE,
+      measures: [
+        ...DATASET_BASE.measures,
+        {
+          name: 'high_hours',
+          label: 'High-priority hours',
+          aggregate: 'avg',
+          format: '0.0',
+          filter: { priority: 'high' },
+          duration: { from: 'opened_at', to: 'resolved_at', unit: 'hours' },
+        },
+      ],
+    });
+
+    it('getMeta lists each duration measure with its aggregate, label and format', async () => {
+      const { service } = makeService();
+      service.registerDataset(listed);
+      const [meta] = await service.getMeta(listed.name);
+      expect(meta.measures.filter((m) => m.name !== `${listed.name}.tickets`)).toEqual([
+        { name: 'resolution.resolution_seconds_sum', type: 'sum', title: 'resolution_seconds_sum' },
+        { name: 'resolution.high_hours', type: 'avg', title: 'High-priority hours', format: '0.0' },
+      ]);
+    });
+
+    it('the listed spelling is served as the bare one, its scoped filter included, under the name asked', async () => {
+      const { service, executed } = makeService();
+      service.registerDataset(listed);
+      await service.query({ cube: listed.name, measures: ['resolution.high_hours'], dimensions: ['category'] } as never, MEMBER);
+      expect(executed).toHaveLength(1);
+      expect(executed[0]).toContain('AVG(CASE WHEN priority = $1 THEN ((ROUND((julianday(resolved_at) - julianday(opened_at))');
+      expect(executed[0]).toContain('AS "resolution.high_hours"');
+    });
+
+    it('the read gate and the strategy refusal know the listed spelling too', async () => {
+      const gated = makeService({ readable: FIELDS.filter((f) => f !== 'opened_at') });
+      gated.service.registerDataset(listed);
+      const denied = await refusalOf(gated.service.query({ cube: listed.name, measures: ['resolution.high_hours'] } as never, MEMBER));
+      expect(denied?.code, denied?.message).toBe('PERMISSION_DENIED');
+      expect(denied?.status).toBe(403);
+      expect(gated.executed).toEqual([]);
+
+      const offNative = makeService({ capabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }) });
+      offNative.service.registerDataset(listed);
+      const refused = await refusalOf(offNative.service.query({ cube: listed.name, measures: ['resolution.high_hours'] } as never, MEMBER));
+      expect(refused?.code, refused?.message).toBe('INVALID_FIELD');
+      expect(refused?.status).toBe(400);
+      expect(refused?.member).toBe('resolution.high_hours');
+      expect(offNative.executed).toEqual([]);
+    });
+  });
+
+  it('a field-to-field filter routes the query off the native strategy, and the measure is refused by name', async () => {
+    const { service, executed } = makeService();
+    service.registerDataset(dataset);
+    const err = await refusalOf(
+      service.query({
+        cube: dataset.name,
+        measures: ['resolution_seconds_sum'],
+        where: { resolved_at: { $gt: { $field: 'opened_at' } } },
+      } as never, MEMBER),
+    );
+    expect(err?.code, err?.message).toBe('INVALID_FIELD');
+    expect(err?.status).toBe(400);
+    expect(err?.member).toBe('resolution_seconds_sum');
+    expect(executed).toEqual([]);
+  });
+
   describe('a dataset that reaches the service without meeting the spec\'s parse', () => {
     const stored = (duration: Record<string, unknown>) => ({
       ...DATASET_BASE,

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

@@ -112,7 +112,7 @@ import {
 } from './dimension-labels.js';
 import { evaluateAnalyticsQueryOverRows } from './preview-evaluator.js';
 // [#25778] The one lookup of a dataset duration measure by name.
-import { durationMeasureIn } from './duration-measure-sql.js';
+import { durationMeasureIn, durationMeasureKey } from './duration-measure-sql.js';
 // [#5918] The measure mint refuses a dotted member through the SAME constructor
 // the strategies' member-level refusals use — `INVALID_FIELD` / 400, naming the
 // member as the request spelled it (see `dataset-refusal.ts`'s header for why
@@ -547,10 +547,13 @@ function namedQueryFields(
   };
   // [#25778] A dataset duration measure is absent from the cube (fail-closed,
   // `DatasetScope.measureDurations`), so `name` would read nothing for it. It
-  // reads its two columns, and is judged on both.
+  // reads its two columns, and is judged on both. Resolved FIRST, as the mint,
+  // `assertCallerMembersResolvable` and `NativeSQLStrategy` resolve it: a
+  // dimension may share the measure's name, and that dimension's column is not
+  // what the measure aggregates.
   const durationColumns = (member: string, role: FieldReadRole): boolean => {
-    const duration = durationMeasureIn(datasetScope?.measureDurations, member);
-    if (!duration || declaredMemberEntry(cube, member, 'any')) return false;
+    const duration = durationMeasureIn(datasetScope?.measureDurations, member, cube.name);
+    if (!duration) return false;
     for (const column of [duration.from, duration.to]) {
       const fields = fieldsOfColumnSql(cube, baseObject, column, role, referenceOf);
       if (fields) out.push(...fields);
@@ -572,12 +575,17 @@ function namedQueryFields(
   for (const member of query.measures ?? []) if (!durationColumns(member, 'aggregate')) name(member, 'measure', 'aggregate');
   for (const member of filterMembers((query as { where?: unknown }).where)) name(member, 'any', 'predicate');
   for (const measure of query.measures ?? []) {
-    for (const member of filterMembers(datasetScope?.measureFilters?.[measure])) name(member, 'any', 'predicate');
+    const filterKey = durationMeasureKey(datasetScope?.measureDurations, measure, cube.name) ?? measure;
+    for (const member of filterMembers(datasetScope?.measureFilters?.[filterKey])) name(member, 'any', 'predicate');
   }
   for (const member of filterMembers(datasetScope?.filter)) name(member, 'any', 'predicate');
   const order = (query as { order?: unknown }).order;
   if (order && typeof order === 'object' && !Array.isArray(order)) {
-    for (const key of Object.keys(order)) if (!durationColumns(key, 'predicate')) name(key, 'any', 'predicate');
+    // An order key naming both a duration measure and a declared member is
+    // judged as both.
+    for (const key of Object.keys(order)) {
+      if (!durationColumns(key, 'predicate') || declaredMemberEntry(cube, key, 'any')) name(key, 'any', 'predicate');
+    }
   }
   return [...out.filter((f) => f.object === baseObject), ...out.filter((f) => f.object !== baseObject)];
 }
@@ -2171,7 +2179,7 @@ export class AnalyticsService implements IAnalyticsService {
       // Author-declared measures are not this gate's business. [#25778] A
       // dataset's duration measure is one, declared beside the cube.
       if (authorCube && declaredMemberEntry(authorCube, measure, 'measure')) continue;
-      if (durationMeasureIn(scope.getCompiledDataset(name)?.durations, measure)) continue;
+      if (durationMeasureIn(scope.getCompiledDataset(name)?.durations, measure, name)) continue;
       const inferredSql = inferredCallerMeasureSql(measure, name);
       // `null` — a dotted non-qualifier measure #5918 already refused — and a
       // column reference (`'*'`, a bare identifier, a relationship path) both
@@ -3238,13 +3246,24 @@ export class AnalyticsService implements IAnalyticsService {
       name: cube.name,
       title: cube.title,
       ...(cube.description === undefined ? {} : { description: cube.description }),
-      measures: Object.entries(cube.measures).map(([key, measure]) => ({
-        name: `${cube.name}.${key}`,
-        type: measure.type,
-        title: measure.label,
-        ...(measure.description === undefined ? {} : { description: measure.description }),
-        ...(measure.format === undefined ? {} : { format: measure.format }),
-      })),
+      measures: [
+        ...Object.entries(cube.measures).map(([key, measure]) => ({
+          name: `${cube.name}.${key}`,
+          type: measure.type,
+          title: measure.label,
+          ...(measure.description === undefined ? {} : { description: measure.description }),
+          ...(measure.format === undefined ? {} : { format: measure.format }),
+        })),
+        // [#25778] A registered dataset's duration measures are absent from
+        // `cube.measures` (fail-closed) yet answer on the cube door, so the
+        // discovery surface lists them from the compiled dataset of THIS cube.
+        ...Object.entries(this.compiledDatasetOf(cube)?.durations ?? {}).map(([key, duration]) => ({
+          name: `${cube.name}.${key}`,
+          type: duration.aggregate,
+          title: duration.label ?? key,
+          ...(duration.format === undefined ? {} : { format: duration.format }),
+        })),
+      ],
       dimensions: Object.entries(cube.dimensions).map(([key, dimension]) => ({
         name: `${cube.name}.${key}`,
         type: dimension.type,
@@ -3300,6 +3319,12 @@ export class AnalyticsService implements IAnalyticsService {
 
   // ── Internal ─────────────────────────────────────────────────────
 
+  /** The compiled dataset a registered cube came from, or nothing when another cube took the name. */
+  private compiledDatasetOf(cube: Cube): CompiledDataset | undefined {
+    const compiled = this.datasetRegistry.get(cube.name);
+    return compiled?.cube === cube ? compiled : undefined;
+  }
+
   /**
    * [#25778] Refuse a dataset duration measure the chosen strategy does not
    * serve — `INVALID_FIELD` / 400, naming the measure, before anything runs.
@@ -3318,7 +3343,7 @@ export class AnalyticsService implements IAnalyticsService {
   private assertDurationMeasuresServed(query: AnalyticsQuery, scope: CubeScope, strategy: AnalyticsStrategy): void {
     if (strategy instanceof NativeSQLStrategy) return;
     const durations = scope.getCompiledDataset(query.cube!)?.durations;
-    const measure = (query.measures ?? []).find((m) => durationMeasureIn(durations, m));
+    const measure = (query.measures ?? []).find((m) => durationMeasureIn(durations, m, query.cube));
     if (measure === undefined) return;
     throw invalidMemberError(
       `Measure "${measure}" of dataset "${query.cube}" is a duration, the time between two datetime fields ` +
@@ -3468,7 +3493,7 @@ export class AnalyticsService implements IAnalyticsService {
     const durations = scope.getCompiledDataset(name)?.durations;
     for (const m of query.measures || []) {
       if (cube.measures[m] || extraMeasures[m]) continue;
-      if (durationMeasureIn(durations, m)) continue;
+      if (durationMeasureIn(durations, m, name)) continue;
       const key = mintableMeasureKey(m, name);
       if (cube.measures[key] || extraMeasures[key]) continue;
       // [#21437] A spelling whose source names no field (`_sum`, `*`) is

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

@@ -456,7 +456,12 @@ function assertAggregateFieldTypeCompatible(
   );
 }
 
-/** One column of the base object by its bare name — the spec's `duration.from` / `to` shape. */
+/**
+ * One column of the base object by its bare name — the spec's `duration.from` /
+ * `to` shape (`ANALYTICS_BASE_COLUMN`, which `@objectstack/spec` does not
+ * export). Judged again here because a dataset can reach the compile without
+ * passing the schema.
+ */
 const DURATION_BASE_COLUMN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 /**
@@ -519,7 +524,15 @@ function compileDurationMeasure(
       );
     }
   }
-  return { aggregate: aggregate as DurationMeasureSpec['aggregate'], from, to, unit };
+  return {
+    aggregate: aggregate as DurationMeasureSpec['aggregate'],
+    from,
+    to,
+    unit,
+    // [#6761] The same registry-locale label a cube metric gets.
+    label: resolveI18nLabel(measure.label, REGISTRY_LOCALE) ?? measure.name,
+    ...(typeof measure.format === 'string' ? { format: measure.format } : {}),
+  };
 }
 
 /** Map a dataset dimension type to the Cube dimension `type`. */

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

@@ -1196,7 +1196,7 @@ export class DatasetExecutor {
     // aggregate beside it.
     const fillColumns: Record<string, string | undefined> = {};
     for (const m of baseMeasures) {
-      const aggregate = compiled.cube.measures?.[m]?.type ?? durationMeasureIn(compiled.durations, m)?.aggregate;
+      const aggregate = compiled.cube.measures?.[m]?.type ?? durationMeasureIn(compiled.durations, m, compiled.cube.name)?.aggregate;
       fillColumns[m] = aggregate;
       if (selection.compareTo) fillColumns[`${m}__compare`] = aggregate;
     }