fix(dashboards): address deep review on #2383 + e2e shard 2 fix

E2E shard 2 was failing on three pre-existing dashboard tests because
`visibleFilters` in DashboardFilters.tsx was a new array reference every
render, churning useDashboardFilterValues' useQueries and leaving the
chip dropdown disabled while the values query never settled. Memoize
the array so a stable reference flows into the hook.

Deep review fixes:

- P0/P1: MCP hyperdx_save_dashboard inputSchema now exposes
  savedFilterValues, paired with a usage example in the filters param
  description so constant: true filters can actually lock to a value
  via MCP. The body schema already accepts it; only the tool input
  shape was missing.

- P2: DashboardFiltersModal snapshots initialDefaultValues via state
  keyed on filter.id, so a background savedFilterValues refetch no
  longer wipes in-progress edits in the default-value picker.

- P2: Schema-level coherence checks moved to common-utils via two
  reusable refinements applied at the external API boundary:
  refineDashboardFilterCoherence rejects readonly/hidden render modes
  without constant: true; refineDashboardFiltersConstantSiblings
  rejects two filter definitions sharing an expression that disagree
  on constant. Internal callers (MCP, future migrations) get the
  same protection through the shared schemas.

- P2: openapi.json + JSDoc no longer declare default: false /
  default: "editable" on the new constant / renderMode property
  schemas. The Zod schema is .optional() with no .default() so
  generated SDKs would otherwise surface a default the wire format
  never produces; the implied default now lives in the description
  text instead.

- P2: page-level merge logic for "Save default" / URL hydration /
  savedFilterValues upsert is extracted into dashboardFilterUtils
  (normalizeExpression, buildConstantExpressionSet,
  stripConstantsFromUrl, mergeConstantFiltersForSave,
  upsertSavedDefault, removeSavedDefaultForExpression). The matrix
  including bracket-notation expressions is covered by a new unit
  test. useDashboardFilters and DBDashboardPage call the helpers.

- P2: bracket-notation constant filter is now covered in the
  hook unit tests (SpanAttributes['k8s.pod.name'] resolves through
  filterValues, blocks setFilterValue, and survives via
  getFilterQueriesForSource).

P3 polish:

- handleRemoveFilter now strips the matching savedFilterValues entry
  alongside the filter delete so deleting + recreating a filter on the
  same expression doesn't silently re-lock to an orphaned value.
- applyFilterVisibility('editable') returns {} so the spread on save
  no longer leaves constant: undefined / renderMode: undefined keys
  in memory.
- defaultsChanged uses set equality so reordering the same values
  doesn't fire a spurious save write.
- NEVER_USED_RANGE hoisted to module scope.
- FilterVisibility uses z.infer<typeof DashboardFilterRenderMode>
  instead of a hand-rolled string union.
- as DashboardFilter cast dropped on filtersForQuery.
- usePresetDashboardFilters.handleSaveFilter widened to accept the
  optional defaultValues arg so a future supportsConstantFilters=true
  flip on presets doesn't silently drop the second arg.
- parseQuery import uses the @/searchFilters alias for consistency
  with sibling files.
- dashboard?.filters dropped from the URL hydration effect's deps
  (the initializedDashboard.current === dashboard.id guard already
  prevents re-runs).
- HDX-4404 API round-trip test uses toEqual instead of toMatchObject
  so unexpected extra fields fail the assertion.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: alex-fedotyev

packages/api/openapi.json

@@ -2362,8 +2362,7 @@
           },
           "constant": {
             "type": "boolean",
-            "description": "When true, the value from the dashboard's savedFilterValues matched\nby this filter's expression is applied automatically on every tile\nthis filter scopes, and viewers cannot change it. Use this to lock\na dashboard template to a single scope (clone the dashboard, save a\ndifferent default per copy). Pairs with renderMode to control how\nthe locked filter shows in the filter bar.\n",
-            "default": false,
+            "description": "When true, the value from the dashboard's savedFilterValues matched\nby this filter's expression is applied automatically on every tile\nthis filter scopes, and viewers cannot change it. Use this to lock\na dashboard template to a single scope (clone the dashboard, save a\ndifferent default per copy). Pairs with renderMode to control how\nthe locked filter shows in the filter bar. Omit (or send false)\nfor an ordinary editable filter (the implicit default behavior).\n",
             "example": true
           },
           "renderMode": {
@@ -2373,8 +2372,7 @@
               "readonly",
               "hidden"
             ],
-            "description": "Controls how this filter renders in the dashboard filter bar.\n\"editable\" (default) shows a normal dropdown the viewer can change.\n\"readonly\" shows a disabled chip with a lock icon; the viewer\nsees the locked value but cannot edit it. \"hidden\" omits the chip\nentirely; the locked value still scopes every matching tile.\n",
-            "default": "editable",
+            "description": "Controls how this filter renders in the dashboard filter bar.\nOmit for the implicit \"editable\" behavior (normal dropdown the\nviewer can change). \"readonly\" shows a disabled chip with a lock\nicon; the viewer sees the locked value but cannot edit it.\n\"hidden\" omits the chip entirely; the locked value still scopes\nevery matching tile. \"readonly\" and \"hidden\" require constant: true.\n",
             "example": "readonly"
           }
         }

packages/api/src/mcp/tools/dashboards/saveDashboard.ts

@@ -23,10 +23,12 @@ import {
   resolveSavedQueryLanguage,
   updateDashboardBodySchema,
 } from '@/routers/external-api/v2/utils/dashboards';
-import type {
-  ExternalDashboardFilter,
-  ExternalDashboardFilterWithId,
-  ExternalDashboardTileWithId,
+import {
+  type ExternalDashboardFilter,
+  type ExternalDashboardFilterWithId,
+  type ExternalDashboardSavedFilterValue,
+  externalDashboardSavedFilterValueSchema,
+  type ExternalDashboardTileWithId,
 } from '@/utils/zod';
 
 import { withToolTracing } from '../../utils/tracing';
@@ -62,6 +64,20 @@ export function registerSaveDashboard(
         tags: z.array(z.string()).optional().describe('Dashboard tags'),
         containers: mcpContainersParam.optional(),
         filters: mcpFiltersParam.optional(),
+        savedFilterValues: z
+          .array(externalDashboardSavedFilterValueSchema)
+          .optional()
+          .describe(
+            'Optional saved default values for the dashboard filters. Each ' +
+              'entry is a Lucene or SQL `condition` string keyed by a filter ' +
+              'expression (e.g. `ServiceName:"hdx-private-api"`). ' +
+              'Pair this with `constant: true` on a filter in the `filters` ' +
+              'array to lock that filter to a specific value: the matching ' +
+              'savedFilterValues entry is applied automatically on every ' +
+              'tile and the viewer cannot override it. ' +
+              'If you set `constant: true` without a corresponding ' +
+              'savedFilterValues entry, the filter has no effect.',
+          ),
       }),
     },
     withToolTracing(
@@ -74,6 +90,7 @@ export function registerSaveDashboard(
         tags,
         containers,
         filters: inputFilters,
+        savedFilterValues: inputSavedFilterValues,
       }) => {
         if (!dashboardId) {
           return createDashboard({
@@ -84,6 +101,7 @@ export function registerSaveDashboard(
             tags,
             containers,
             inputFilters,
+            inputSavedFilterValues,
           });
         }
         return updateDashboard({
@@ -95,6 +113,7 @@ export function registerSaveDashboard(
           tags,
           containers,
           inputFilters,
+          inputSavedFilterValues,
         });
       },
     ),
@@ -147,6 +166,7 @@ async function createDashboard({
   tags,
   containers,
   inputFilters,
+  inputSavedFilterValues,
 }: {
   teamId: string;
   frontendUrl: string | undefined;
@@ -157,13 +177,15 @@ async function createDashboard({
   inputFilters:
     | (ExternalDashboardFilter | ExternalDashboardFilterWithId)[]
     | undefined;
+  inputSavedFilterValues: ExternalDashboardSavedFilterValue[] | undefined;
 }) {
   const parsed = createDashboardBodySchema.safeParse({
     name,
     tiles: inputTiles,
     tags,
     containers,
     filters: stripFilterIds(inputFilters),
+    savedFilterValues: inputSavedFilterValues,
   });
   if (!parsed.success) {
     return {
@@ -332,6 +354,7 @@ async function updateDashboard({
   tags,
   containers,
   inputFilters,
+  inputSavedFilterValues,
 }: {
   teamId: string;
   frontendUrl: string | undefined;
@@ -343,6 +366,7 @@ async function updateDashboard({
   inputFilters:
     | (ExternalDashboardFilter | ExternalDashboardFilterWithId)[]
     | undefined;
+  inputSavedFilterValues: ExternalDashboardSavedFilterValue[] | undefined;
 }) {
   if (!mongoose.Types.ObjectId.isValid(dashboardId)) {
     return {
@@ -357,6 +381,7 @@ async function updateDashboard({
     tags,
     containers,
     filters: assignFilterIds(inputFilters),
+    savedFilterValues: inputSavedFilterValues,
   });
   if (!parsed.success) {
     return {

packages/api/src/mcp/tools/dashboards/schemas.ts

@@ -745,7 +745,9 @@ export const mcpFiltersParam = z
       "its value to the dashboard's saved default (matched by `expression`); pair with " +
       '`renderMode: "readonly"` to show a disabled chip or `"hidden"` to drop the chip ' +
       'entirely while keeping the WHERE clause active. Locked filters cannot be cleared by ' +
-      'the viewer.\n\n' +
+      'the viewer. The locked value comes from the dashboard-level `savedFilterValues` ' +
+      "array (matched by this filter's `expression`); set both together in the same " +
+      '`hyperdx_save_dashboard` call.\n\n' +
       'Example (broadcast to every tile):\n' +
       '[\n' +
       '  { "type": "QUERY_EXPRESSION", "name": "Service", "expression": "ServiceName",\n' +
@@ -756,7 +758,18 @@ export const mcpFiltersParam = z
       '  { "type": "QUERY_EXPRESSION", "name": "Service", "expression": "SpanName",\n' +
       '    "sourceId": "<trace-source-id>", "whereLanguage": "sql",\n' +
       '    "appliesToSourceIds": ["<trace-source-id>"] }\n' +
-      ']',
+      ']\n\n' +
+      'Example (locked scope-filter template) - pair with the top-level ' +
+      'savedFilterValues array on the dashboard call so the constant filter ' +
+      'has a value to apply:\n' +
+      '[\n' +
+      '  { "type": "QUERY_EXPRESSION", "name": "Service", "expression": "ServiceName",\n' +
+      '    "sourceId": "<trace-source-id>", "whereLanguage": "sql",\n' +
+      '    "constant": true, "renderMode": "readonly" }\n' +
+      ']\n' +
+      'plus on the dashboard call body:\n' +
+      '  "savedFilterValues": [ { "type": "lucene",\n' +
+      '    "condition": "ServiceName:\\"hdx-private-api\\"" } ]',
   );
 
 export const mcpContainersParam = z

packages/api/src/routers/external-api/__tests__/dashboards.test.ts

@@ -958,21 +958,41 @@ describe('External API v2 Dashboards - old format', () => {
         .expect(200);
 
       expect(response.body.data.filters).toHaveLength(3);
-      expect(response.body.data.filters[0]).toMatchObject({
+      // Use toEqual on the full filter object so extra fields (which would
+      // indicate schema drift) fail the assertion. The bot deep-review at
+      // dashboards.test.ts:961 flagged toMatchObject for letting unexpected
+      // fields slip through silently.
+      expect(response.body.data.filters[0]).toEqual({
+        id: response.body.data.filters[0].id,
+        type: 'QUERY_EXPRESSION',
         name: 'Service (locked, read-only)',
+        expression: 'ServiceName',
+        sourceId: traceSource._id.toString(),
+        whereLanguage: 'sql',
         constant: true,
         renderMode: 'readonly',
       });
-      expect(response.body.data.filters[1]).toMatchObject({
+      expect(response.body.data.filters[1]).toEqual({
+        id: response.body.data.filters[1].id,
+        type: 'QUERY_EXPRESSION',
         name: 'Environment (hidden)',
+        expression: 'environment',
+        sourceId: traceSource._id.toString(),
+        whereLanguage: 'sql',
         constant: true,
         renderMode: 'hidden',
       });
       // Filter 2 omitted the new fields. They must NOT be materialized as
       // defaults on read; the absence is meaningful (default behavior
       // matches today's editable, non-locked filter).
-      expect(response.body.data.filters[2].constant).toBeUndefined();
-      expect(response.body.data.filters[2].renderMode).toBeUndefined();
+      expect(response.body.data.filters[2]).toEqual({
+        id: response.body.data.filters[2].id,
+        type: 'QUERY_EXPRESSION',
+        name: 'Region (default editable)',
+        expression: 'region',
+        sourceId: traceSource._id.toString(),
+        whereLanguage: 'sql',
+      });
 
       // GET round-trip.
       const getResponse = await authRequest(
@@ -1015,9 +1035,13 @@ describe('External API v2 Dashboards - old format', () => {
         .expect(200);
 
       expect(updateResponse.body.data.filters).toHaveLength(2);
-      expect(updateResponse.body.data.filters[1]).toMatchObject({
+      expect(updateResponse.body.data.filters[1]).toEqual({
         id: response.body.data.filters[2].id,
+        type: 'QUERY_EXPRESSION',
         name: 'Region (now read-only)',
+        expression: 'region',
+        sourceId: traceSource._id.toString(),
+        whereLanguage: 'sql',
         constant: true,
         renderMode: 'readonly',
       });

packages/api/src/routers/external-api/v2/dashboards.ts

@@ -1378,19 +1378,19 @@ function getSourceConnectionMismatches(
  *             this filter scopes, and viewers cannot change it. Use this to lock
  *             a dashboard template to a single scope (clone the dashboard, save a
  *             different default per copy). Pairs with renderMode to control how
- *             the locked filter shows in the filter bar.
- *           default: false
+ *             the locked filter shows in the filter bar. Omit (or send false)
+ *             for an ordinary editable filter (the implicit default behavior).
  *           example: true
  *         renderMode:
  *           type: string
  *           enum: [editable, readonly, hidden]
  *           description: |
  *             Controls how this filter renders in the dashboard filter bar.
- *             "editable" (default) shows a normal dropdown the viewer can change.
- *             "readonly" shows a disabled chip with a lock icon; the viewer
- *             sees the locked value but cannot edit it. "hidden" omits the chip
- *             entirely; the locked value still scopes every matching tile.
- *           default: "editable"
+ *             Omit for the implicit "editable" behavior (normal dropdown the
+ *             viewer can change). "readonly" shows a disabled chip with a lock
+ *             icon; the viewer sees the locked value but cannot edit it.
+ *             "hidden" omits the chip entirely; the locked value still scopes
+ *             every matching tile. "readonly" and "hidden" require constant: true.
  *           example: "readonly"
  *
  *     Filter:

packages/api/src/routers/external-api/v2/utils/dashboards.ts

@@ -14,12 +14,14 @@ import {
   DASHBOARD_MAX_CONTAINERS,
   DashboardContainer,
   DashboardContainerSchema,
+  DashboardFilter,
   DisplayType,
   isLogSource,
   isOnClickDashboardById,
   isOnClickSearchById,
   isTraceSource,
   RawSqlSavedChartConfig,
+  refineDashboardFiltersConstantSiblings,
   SavedChartConfig,
 } from '@hyperdx/common-utils/dist/types';
 import { SearchConditionLanguageSchema as whereLanguageSchema } from '@hyperdx/common-utils/dist/types';
@@ -1149,6 +1151,18 @@ function buildDashboardBodySchema(filterSchema: z.ZodTypeAny): z.ZodEffects<
       // (otherwise a tile that references a real preserved container
       // would be rejected against an empty `data.containers ?? []`).
       validateDashboardContainersStructure(data.containers ?? [], ctx);
+
+      // Cross-filter check: reject mixing constant: true with editable
+      // siblings on the same expression. The filter-array element type
+      // is `unknown` from Zod's perspective here, so cast through the
+      // shared shape. Filters are already individually validated by the
+      // `filterSchema` arg, so the cast is safe.
+      if (data.filters && data.filters.length > 0) {
+        refineDashboardFiltersConstantSiblings(
+          data.filters as unknown as DashboardFilter[],
+          ctx,
+        );
+      }
     });
 }
 

packages/api/src/utils/zod.ts

@@ -10,6 +10,7 @@ import {
   NumberFormatSchema,
   OnClickDashboardSchema,
   OnClickSearchSchema,
+  refineDashboardFilterCoherence,
   scheduleStartAtSchema,
   SearchConditionLanguageSchema as whereLanguageSchema,
   validateAlertScheduleOffsetMinutes,
@@ -128,18 +129,28 @@ type ChartSeries = z.infer<typeof chartSeriesSchema>;
 
 export const tagsSchema = z.array(z.string().max(32)).max(50).optional();
 
-export const externalDashboardFilterSchemaWithId = DashboardFilterSchema.omit({
+// Bare object schema (no superRefine) so `.omit`/`.extend` chains still
+// work on the create variant below. Apply the coherence refinement to
+// each shipped schema separately.
+const externalDashboardFilterBaseSchemaWithId = DashboardFilterSchema.omit({
   source: true,
 })
   .extend({ sourceId: objectIdSchema })
   .strict();
 
+export const externalDashboardFilterSchemaWithId =
+  externalDashboardFilterBaseSchemaWithId.superRefine(
+    refineDashboardFilterCoherence,
+  );
+
 export type ExternalDashboardFilterWithId = z.infer<
   typeof externalDashboardFilterSchemaWithId
 >;
 
 export const externalDashboardFilterSchema =
-  externalDashboardFilterSchemaWithId.omit({ id: true });
+  externalDashboardFilterBaseSchemaWithId
+    .omit({ id: true })
+    .superRefine(refineDashboardFilterCoherence);
 
 export type ExternalDashboardFilter = z.infer<
   typeof externalDashboardFilterSchema
@@ -150,7 +161,7 @@ export const externalDashboardSavedFilterValueSchema = z.object({
   condition: z.string().max(10000),
 });
 
-type ExternalDashboardSavedFilterValue = z.infer<
+export type ExternalDashboardSavedFilterValue = z.infer<
   typeof externalDashboardSavedFilterValueSchema
 >;