fix(service-analytics): state that the dataset door judges a saved dataset's field too, and pin the saved branch

The `/analytics/dataset/query` route's `body.datasetName` branch loads a
saved dataset from metadata and calls the same `queryDataset`, and the build
probe does too, so the door judges a saved dataset's own `field` text exactly
as an inline one's. Behaviour is unchanged; the docblock, the door test's
header and the changeset said a registered dataset never reaches this door,
which holds only for one registered through the configuration door and
queried by cube name.

- analytics-service.ts: correct the docblock (every branch that supplies the
  dataset; author-time refusal is the dataset schema retirement's job) and
  rename the private method to assertDatasetFieldsJudgeable.
- changeset: the BREAKING note covers saved datasets with a non-column
  field; no shipped dataset carries one.
- rest: pin the saved branch through the real route and driver — a saved
  dataset with a non-column field is refused 403 with nothing executed, and
  a saved plain-column dataset is still answered.

Claude-Session: https://claude.ai/code/session_01MRdbfpy4sQT8bUjmMhxsN7
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/21177-analytics-inline-dataset-field-admission.md

@@ -2,14 +2,14 @@
 '@objectstack/service-analytics': minor
 ---
 
-fix(service-analytics)!: an inline dataset's own caller-supplied `field` text that is not a column reference is refused at the analytics dataset door
+fix(service-analytics)!: a dataset's own `field` text that is not a column reference is refused at the analytics dataset door, inline or saved
 
 Clause-②: no (narrowing)
 
-<!-- adr-0087: not-required (no-migration-prescription) an inline (caller-POSTed) dataset's own dimension or measure `field` text that is not a column reference (a field, a relationship path ending in one, or `*`) is refused at the analytics dataset door, before the dataset is compiled and before any strategy runs, for every caller and whether or not a security service is wired, through the field-read gate's existing judge and envelope (`PERMISSION_DENIED` / 403). No authorable key, spelling, export or stored shape moves, and no stored row is read differently by any metadata consumer; the published surface gains and loses nothing. The other categories are closed on facts: the package publishes (not `unpublished`); no ADR-0087 id covers a caller-supplied dataset `field` (not `registered` / `already-registered`); and the change is runtime behaviour, not a declaration (not `runtime-interface-only` / `type-surface-only`). A caller names a column instead of writing an expression, which is ADR-0021's author surface already ("zero raw expressions"), so there is no FROM → TO mapping to carry. -->
+<!-- adr-0087: not-required (no-migration-prescription) a dataset's own dimension or measure `field` text that is not a column reference (a field, a relationship path ending in one, or `*`) is refused at the analytics dataset door — whichever branch supplied the dataset, an inline `body.dataset` or a saved `body.datasetName` — before the dataset is compiled and before any strategy runs, for every caller and whether or not a security service is wired, through the field-read gate's existing judge and envelope (`PERMISSION_DENIED` / 403). No authorable key, spelling, export or stored shape moves, and no stored row is read differently by any metadata consumer; the published surface gains and loses nothing. The other categories are closed on facts: the package publishes (not `unpublished`); no ADR-0087 id covers a dataset `field` (not `registered` / `already-registered`); and the change is runtime behaviour, not a declaration (not `runtime-interface-only` / `type-surface-only`). A dataset names a column instead of writing an expression, which is ADR-0021's author surface already ("zero raw expressions"), so there is no FROM → TO mapping to carry. -->
 
-**BREAKING**: this narrows what the analytics dataset door accepts. An inline dataset whose dimension or measure `field` is not a column reference is now refused with `403 PERMISSION_DENIED` instead of being evaluated. It ships as `minor` under the launch-window convention for accept-set narrowings. No export or published type changes.
+**BREAKING**: this narrows what the analytics dataset door accepts. A dataset whose dimension or measure `field` is not a column reference is now refused with `403 PERMISSION_DENIED` instead of being evaluated — an inline dataset and a saved dataset queried by name alike, since both reach the same door. No shipped dataset carries a non-column `field`. It ships as `minor` under the launch-window convention for accept-set narrowings. No export or published type changes.
 
-**What changes.** The service compiles an inline dataset into a cube whose members read as declared, so a dimension or measure whose `field` was a raw expression resolved to a declared cube member and was left to the field-level read gate, which stands down with no security service and on an object its reader answers `undefined` for; in those tiers the expression reached the native statement as written. The dataset's own `field` text is now judged at the dataset door, before compile and before any strategy runs, through the field-read gate's existing judge (`PERMISSION_DENIED` / 403, naming the member and never the expression text), for every caller, admin included, and with or without a security service. There is no new error code and no new admission module.
+**What changes.** The service compiles a dataset into a cube whose members read as declared, so a dimension or measure whose `field` was a raw expression resolved to a declared cube member and was left to the field-level read gate, which stands down with no security service and on an object its reader answers `undefined` for; in those tiers the expression reached the native statement as written. The dataset's own `field` text is now judged at the dataset door, before compile and before any strategy runs, through the field-read gate's existing judge (`PERMISSION_DENIED` / 403, naming the member and never the expression text), for every caller, admin included, and with or without a security service. There is no new error code and no new admission module.
 
-**What stays answerable.** Every inline dataset whose fields are columns or relationship paths is unchanged. A registered dataset's own field text is author text, queried by cube name and left to the existing gates. The dataset's own filter, the selection's runtime filter and cube-query members are lowered into the compiled query and already judged on the query path, so they are unchanged.
+**What stays answerable.** Every dataset whose fields are columns or relationship paths is unchanged, inline or saved. A saved dataset whose `field` is an expression is refused the same way as an inline one; refusing such a `field` when it is authored belongs to the dataset schema's own retirement of expression fields, not to this door. The dataset's own filter, the selection's runtime filter and cube-query members are lowered into the compiled query and already judged on the query path, so they are unchanged.

packages/rest/src/analytics-16019-driver-declared-fault.test.ts

@@ -26,6 +26,10 @@
  * THAT — the door refuses the expression `PERMISSION_DENIED` / 403, the one
  * judge #21156 reaches (no new error code) — beside a positive control that a
  * legitimate dataset on declared fields is still served 200 by the real driver.
+ * It pins the route's SAVED branch (`body.datasetName`) the same way: that branch
+ * loads the dataset from metadata and calls the same `queryDataset`, so a saved
+ * dataset whose `field` is not a column reference is refused too, and a saved
+ * plain-column dataset is still served.
  *
  * The second block pins the ordering the ruling's execution notes name. A
  * DECLARED fault is withheld even when its text is one the heuristic does not
@@ -75,11 +79,12 @@ function mockServer() {
     use: vi.fn(), listen: vi.fn().mockResolvedValue(undefined), close: vi.fn().mockResolvedValue(undefined),
   };
 }
-function mockProtocol() {
+/** `savedDatasets` is what the route's `body.datasetName` branch loads from metadata. */
+function mockProtocol(savedDatasets: unknown[] = []) {
   return {
     getDiscovery: vi.fn().mockResolvedValue({ version: 'v0', routes: { data: '', metadata: '' } }),
     getMetaTypes: vi.fn().mockResolvedValue([]),
-    getMetaItems: vi.fn().mockResolvedValue([]),
+    getMetaItems: vi.fn().mockResolvedValue(savedDatasets),
   };
 }
 function mockRes() {
@@ -90,9 +95,9 @@ function mockRes() {
   return res;
 }
 
-function buildRoute(analyticsProvider?: any) {
+function buildRoute(analyticsProvider?: any, savedDatasets: unknown[] = []) {
   const rest = new RestServer(
-    mockServer() as any, mockProtocol() as any, { api: { requireAuth: false } } as any,
+    mockServer() as any, mockProtocol(savedDatasets) as any, { api: { requireAuth: false } } as any,
     undefined, undefined, undefined, undefined, undefined, undefined, undefined,
     undefined, undefined, undefined, undefined,
     analyticsProvider,
@@ -241,6 +246,38 @@ describe('[#16019] a driver fault on the raw-SQL path reaches the caller by decl
     expect(res.body.rows).toEqual([{ industry: 'tech', account_count: 1 }]);
     expect(warned.filter((m) => m.includes('[sql-driver] DATABASE_ERROR'))).toHaveLength(0);
   });
+
+  // [#21177] The route's SAVED branch: `body.datasetName` loads the dataset from
+  // metadata and calls the same `queryDataset`, so the door judges a saved
+  // dataset's own `field` text exactly as it judges an inline one. The expression
+  // here is one SQLite can run, so without the door it would be served (200).
+  it('[#21177] a SAVED dataset (body.datasetName) whose dimension field is not a column reference is refused 403 PERMISSION_DENIED — nothing executed', async () => {
+    const saved = {
+      ...dataset,
+      name: 'account_metrics_saved_expr',
+      dimensions: [{ name: 'lowered_name', field: 'lower(name)', type: 'string' }],
+    };
+    const execute = vi.spyOn(driver, 'execute');
+    const route = buildRoute(async () => realAnalytics(driver), [saved]);
+    const res = await post(route, { datasetName: saved.name, selection: { measures: ['account_count'], dimensions: ['lowered_name'] } });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.body.code).toBe('PERMISSION_DENIED');
+    expect(execute).not.toHaveBeenCalled();
+    const body = JSON.stringify(res.body);
+    expect(body).toContain('lowered_name');
+    expect(body).not.toMatch(/lower\(name\)/i);
+  });
+
+  it('[#21177] CONTROL: a SAVED plain-column dataset (body.datasetName) → 200 with rows', async () => {
+    const execute = vi.spyOn(driver, 'execute');
+    const route = buildRoute(async () => realAnalytics(driver), [dataset]);
+    const res = await post(route, { datasetName: dataset.name, selection: { measures: ['account_count'], dimensions: ['industry'] } });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body.rows).toEqual([{ industry: 'tech', account_count: 1 }]);
+    expect(execute).toHaveBeenCalled();
+  });
 });
 
 describe('[#16019] at the door: a declaration wins over the heuristic, and the heuristic stays as the fallback', () => {

packages/services/service-analytics/src/__tests__/inline-dataset-field-admission-door.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * [#21177] The INLINE dataset's own `field` text, judged at the analytics door.
+ * [#21177] A dataset's own `field` text, judged at the analytics dataset door.
  *
  * A caller POSTs an inline dataset to `/analytics/dataset/query`. Its
  * dimension/measure `field` text is caller content at query time, and the service
@@ -16,11 +16,16 @@
  * reaches, no new error code — for EVERY caller (admin included) and whether or
  * not a security provider is wired, before any strategy runs.
  *
- * The controls stay served: a plain-column inline dataset, and a REGISTERED
- * dataset queried by cube name (author text left to the existing gates, as #21156
- * leaves it). The `/analytics/query` door's own caller members are #21156's and
- * are pinned in `caller-member-column-reference-gate.test.ts` /
- * `field-read-admission-gate.test.ts`.
+ * The door judges every dataset `queryDataset` is handed — the route's SAVED
+ * branch (`body.datasetName`) included, since it calls the same method; that
+ * branch is pinned end to end in `packages/rest`'s
+ * `analytics-16019-driver-declared-fault.test.ts`.
+ *
+ * The controls stay served: a plain-column inline dataset, and a dataset
+ * registered through the configuration door and queried by cube name (it runs
+ * through `query()`, where #21156 leaves its members to the existing gates). The
+ * `/analytics/query` door's own caller members are #21156's and are pinned in
+ * `caller-member-column-reference-gate.test.ts` / `field-read-admission-gate.test.ts`.
  */
 
 import { describe, it, expect } from 'vitest';
@@ -126,7 +131,7 @@ describe('[#21177] inline-dataset `field` admission — the dataset door', () =>
       expect(executed.length).toBeGreaterThan(0);
     });
 
-    it('still answers a REGISTERED dataset queried by cube name (author text, left to the existing gates)', async () => {
+    it('still answers a dataset registered through the configuration door and queried by cube name', async () => {
       const registered = datasetWith({ name: 'id_registered' });
       const { service, executed } = makeService({ capabilities, getReadableFields: (o) => READABLE[o], datasets: [registered] });
       await service.query({ cube: 'id_registered', measures: ['total'], dimensions: ['status'] } as never, MEMBER);

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

@@ -2001,41 +2001,55 @@ export class AnalyticsService implements IAnalyticsService {
   }
 
   /**
-   * [#21177] An INLINE dataset's own dimension/measure `field` text is CALLER
-   * content at query time, and main does not judge it: {@link answerDataset}
-   * compiles the dataset into a cube whose members read as DECLARED, so a
-   * dimension/measure whose `field` is a raw expression resolves to a declared
-   * cube member whose `sql` is that expression — and #21156's
+   * [#21177] The dimension/measure `field` text of a dataset handed to
+   * {@link queryDataset} is judged here, and main did not judge it:
+   * {@link answerDataset} compiles the dataset into a cube whose members read as
+   * DECLARED, so a dimension/measure whose `field` is a raw expression resolves to
+   * a declared cube member whose `sql` is that expression — and #21156's
    * {@link assertCallerMembersResolvable} leaves a DECLARED expression member to
    * the field-level gate (#20965), which stands down with no security service and
    * on an object its reader answers `undefined` for. In those tiers the
    * expression reached `NativeSQLStrategy`'s statement as written.
    *
-   * So the dataset's own `field` text is judged here, on the one judge: a `field`
-   * that is not a column reference is caller content the admission cannot
+   * ## Every branch that supplies the dataset
+   *
+   * The service cannot tell where the dataset came from, so the judgement does not
+   * depend on it. The `/analytics/dataset/query` route hands this door an INLINE
+   * dataset (`body.dataset`, the caller's own text) and a SAVED one alike — it
+   * loads `body.datasetName` from metadata and calls the same
+   * {@link queryDataset} — and the build probe calls it with a saved dataset too.
+   * One uniform refusal here is the safer reading: a saved dataset whose `field` is
+   * an expression is refused exactly as an inline one is. No shipped dataset
+   * carries a non-column `field`. Refusing such a `field` when it is AUTHORED is
+   * the job of the dataset schema's own retirement of expression fields, not of
+   * this door.
+   *
+   * ## The refusal
+   *
+   * A `field` that is not a column reference names no field the admission can
    * attribute, so it is refused through main's {@link assertCallerMembersJudgeable}
    * / {@link fieldReadUnjudgeableError} — `PERMISSION_DENIED` / 403, the SAME
    * refusal #21156 reaches, no new error code — for EVERY caller (admin included)
    * and whether or not a security provider is wired, BEFORE the dataset is
-   * compiled, so no caller expression reaches a strategy (the draft-preview branch
-   * included). It names the dimension/measure the caller spelled, never the
-   * `field` expression behind it.
+   * compiled, so no such expression reaches a strategy (the draft-preview branch
+   * included). It names the dimension/measure, never the `field` expression
+   * behind it.
    *
    * ## Boundary
    *
-   * Only the dataset's OWN `field` text is caller content here. The dataset's
-   * `filter`, the selection's `runtimeFilter` and the query's members are lowered
-   * into the compiled query's `where` / member list by `DatasetExecutor` and are
-   * already judged by #21156 on the query path (`callCtx` →
+   * Only the dataset's OWN `field` text is judged here. The dataset's `filter`,
+   * the selection's `runtimeFilter` and the query's members are lowered into the
+   * compiled query's `where` / member list by `DatasetExecutor` and are already
+   * judged by #21156 on the query path (`callCtx` →
    * {@link assertCallerMembersResolvable}), so this gate does not re-judge them. A
-   * REGISTERED dataset's own field text is author text, queried by cube name
-   * through {@link query} and never through {@link answerDataset}; it stays with
-   * the field gate / the parse (#20943), exactly as #21156 leaves it.
+   * dataset registered through the configuration door ({@link registerDataset})
+   * and queried by cube name runs through {@link query}, not here; its members
+   * stay with the field gate / the parse (#20943), exactly as #21156 leaves them.
    *
    * A derived measure references other measures BY NAME (the spec enforces that),
    * so it carries no `field` to judge.
    */
-  private assertInlineDatasetFieldsJudgeable(dataset: Dataset, context: ExecutionContext | undefined): void {
+  private assertDatasetFieldsJudgeable(dataset: Dataset, context: ExecutionContext | undefined): void {
     const object = typeof dataset.object === 'string' ? dataset.object : '';
     const caller: NamedRead[] = [];
     for (const d of dataset.dimensions ?? []) {
@@ -2369,12 +2383,12 @@ export class AnalyticsService implements IAnalyticsService {
     context?: ExecutionContext,
     options?: { previewDrafts?: boolean },
   ): Promise<AnalyticsResult> {
-    // [#21177] The inline dataset's own dimension/measure `field` text is caller
-    // content at query time — refuse any that is not a column reference here,
-    // ahead of compile and the draft-preview branch, so no caller expression ever
-    // reaches a strategy (`PERMISSION_DENIED` / 403, the one judge, every tier).
-    // See {@link assertInlineDatasetFieldsJudgeable}.
-    this.assertInlineDatasetFieldsJudgeable(dataset, context);
+    // [#21177] The dataset's own dimension/measure `field` text — inline or saved,
+    // whichever branch supplied it — is judged here: a `field` that is not a
+    // column reference is refused ahead of compile and the draft-preview branch,
+    // so no such expression reaches a strategy (`PERMISSION_DENIED` / 403, the one
+    // judge, every tier). See {@link assertDatasetFieldsJudgeable}.
+    this.assertDatasetFieldsJudgeable(dataset, context);
     const compiled = this.compile(dataset);
     this.logger.debug(`[Analytics] queryDataset "${dataset.name}" (object=${dataset.object}, include=${(dataset.include ?? []).join(',') || '—'})`);