diff --git a/docs/dashboard-agent-api.md b/docs/dashboard-agent-api.md
new file mode 100644
index 000000000..ffef60de2
--- /dev/null
+++ b/docs/dashboard-agent-api.md
@@ -0,0 +1,326 @@
+# Agent-driven dashboards
+
+Dashboard editing runs inside the existing Parseable server. REST, the native
+frontend, and external tool calls use the same authoritative write service.
+Configuration validation and change preview never execute queries.
+
+## Agent workflow
+
+1. Discover `get_dashboard_capabilities`, available datasets, and their schemas.
+2. Create a dashboard using `create_dashboard` and a caller-generated stable
+   `idempotencyKey`. The result contains the dashboard ID and opaque revision.
+3. Build a batch of configuration changes using stable tile IDs, section IDs,
+   and variable names. Keep those identities across retries.
+4. Call `preview_dashboard_changes` with the observed revision. Inspect its
+   candidate document, validation report, and diff, including layout changes.
+5. Call `update_dashboard` with that revision, operations, and a new stable
+   idempotency key. On a revision conflict, fetch the current dashboard and
+   reconsider the intended edits before retrying. Never silently overwrite.
+6. Explicitly call `run_dashboard_queries` with selected tiles, time bounds, and
+   variable values. Query results do not change the saved configuration.
+7. Read the dashboard back to verify the accepted revision and configuration.
+
+An agent can create and edit SQL, visual-builder, and multi-query PromQL tiles,
+chart styles, sections, variables, layouts, and saved time/refresh defaults.
+The dashboard's `dataset` is the default for newly authored tiles. It does not
+rewrite existing SQL or switch every tile's own `dbName`.
+
+## External tool policy
+
+The canonical registry and executor remain at:
+
+- `GET /api/prism/v1/llm/tools/list`
+- `POST /api/prism/v1/llm/tools/call`
+
+Set `P_DASHBOARD_AGENT_WRITES=true` (or `--dashboard-agent-writes=true`) to enable
+the four external dashboard mutation tools: `create_dashboard`,
+`update_dashboard`, `save_tile`, and `delete_dashboard`. This is an explicit
+operator standing policy. Normal dashboard RBAC, tenant suspension, and
+owner/administrator checks still apply to every call. A grant to create or edit
+dashboards does not grant dataset query access. No alert or notification mutation
+is enabled by this setting.
+
+The tool transport authenticates the session/API key independently of the chosen
+tool. Catalog discovery retains its existing `Query` authorization and suspension
+gate. Dashboard configuration calls do not require `Query`. Explicit query
+execution requires `Query` and access to every referenced dataset; saved dashboard
+execution also requires `GetDashboard`. Credentials and API keys keep their
+existing scope, expiry and revocation behavior.
+
+`get_dashboard_capabilities`, `validate_dashboard`, `preview_dashboard_changes`,
+and `run_dashboard_queries` are available as separately described tools. Discovery
+includes effect annotations and dashboard output schemas. Completed tool failures
+retain MCP's HTTP 200 + `isError: true` shape and include machine-readable error
+code/status/details under `structuredContent.error`.
+
+The external MCP adapter remains a client of this registry. A current adapter
+that forwards registry tools and calls can discover these tools from the server;
+REST endpoint additions alone do not become tools.
+
+## REST endpoints
+
+| Method | Path | Behavior |
+| --- | --- | --- |
+| GET | `/api/v1/dashboards/capabilities` | Supported configuration, patch operations and limits |
+| POST | `/api/v1/dashboards/validate` | Validate a complete raw dashboard document without saving |
+| POST | `/api/v1/dashboards` | Create a raw dashboard document; optional `Idempotency-Key` |
+| GET | `/api/v1/dashboards` | Fresh summaries; optional `query`, `tags`, `after`, `limit` |
+| GET | `/api/v1/dashboards/{id}` | Authoritative document, JSON `revision`, and quoted `ETag` |
+| PATCH | `/api/v1/dashboards/{id}` | Atomic ID-addressed batch; requires observed revision |
+| POST | `/api/v1/dashboards/{id}/validate` | The same batch as a dry run |
+| PUT | `/api/v1/dashboards/{id}` | Full replacement; optional header or body revision for legacy unkeyed PUT |
+| PUT | `/api/v1/dashboards/{id}/add_tile` | Add one raw tile using shared delta semantics |
+| DELETE | `/api/v1/dashboards/{id}` | Conditional logical deletion |
+| POST | `/api/v1/dashboards/preview` | Explicit bounded query execution without saving |
+
+REST returns a dashboard document for existing create/GET/PUT/add-tile routes.
+PATCH and change preview return `{dashboard, revision, validation, diff}`;
+replays add `replayed` and `appliedRevision`. `validation` contains `valid`,
+`errors`, and `warnings`. Errors identify the operation/entity/field where
+possible. The tool list response uses `dashboards` and `nextCursor` so agents can
+page through larger tenants; pass that cursor as `after`.
+
+## Patch format
+
+This is a Parseable patch envelope with RFC 6901 field pointers, not the RFC 6902
+JSON Patch media type. Collection targets use stable identities rather than array
+indices. Unknown legacy fields retain their values.
+
+```http
+PATCH /api/v1/dashboards/01ARZ3NDEKTSV4RRFFQ69G5FAV
+If-Match: "<revision-returned-by-GET>"
+Idempotency-Key: agent-layout-change-01
+Content-Type: application/json
+```
+
+```json
+{
+  "operations": [
+    {
+      "op": "replace",
+      "target": {"type": "tile", "id": "01ARZ3NDEKTSV4RRFFQ69G5FAW"},
+      "path": "/chartQuery",
+      "value": "SELECT COUNT(*) AS requests FROM app_logs"
+    },
+    {
+      "op": "placeTile",
+      "tileId": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
+      "layout": {"x": 6, "y": 0, "w": 6, "h": 4}
+    }
+  ]
+}
+```
+
+Targets are `{type:"dashboard"}`, `{type:"tile",id}`, `{type:"section",id}`,
+and `{type:"variable",name}`. For an entity target, an empty pointer adds,
+replaces or removes that whole entity while keeping its identity. Paths within
+an entity use normal JSON Pointer escaping (`~0`, `~1`). Root replacement through
+the dashboard target is rejected. Edit collections using entity targets.
+
+`add` follows JSON Patch member/array insertion semantics; `replace` and `remove`
+require an existing value. Named operations handle compound behavior:
+
+- `placeTile`: section-aware movement and deterministic placement/compaction.
+- `renameVariable`: rename a definition and rewrite supported references.
+- `reorderSections`: an exact permutation of addressable section IDs.
+- `removeSection`: explicitly unsection, move, or delete its tiles.
+
+Use capability schemas for exact argument shapes and chart-specific settings.
+IDs for added tiles/sections are supplied by the caller and remain stable across
+dry run and apply. The capabilities response supplies fresh `generatedIds` for
+agents that need tile/section IDs without a local ULID generator. A batch is bounded and validates only its final candidate,
+so query language and its dependent fields can change together.
+
+## Validation and runtime separation
+
+Saving checks configuration structure and relationships: title, identities,
+section references, variable definitions/dependencies, 12-column layout bounds,
+query-mode field shapes, and known chart/style constraints. It does not promise
+that datasets, SQL, PromQL, schemas, query results, or future executions are valid.
+Existing unsupported legacy defects are reported separately from newly introduced
+invalid changes. Unknown extension fields are preserved rather than interpreted
+as newly supported renderer features.
+
+Server-owned identity, tenant, owner, creation/modification metadata, revision,
+and `_parseableDashboard` internals cannot be patched by an agent. Full
+replacements preserve trusted identity and ownership and never accept a tenant
+from the request body as a storage location.
+
+Explicit query preview accepts exactly one of `dashboardId` or `document`,
+optional proposed operations/source revision/selected `tileIds`, RFC3339
+`startTime`/`endTime`, variable selections, and `rowLimit`. It uses the caller's
+normal query paths and returns results/errors per tile. SQL builder compilation,
+variable substitution, and PromQL instant/range/sparkline selection mirror the
+native frontend's supported execution rules.
+
+Runtime bounds: 16 admitted preview requests, 8 global SQL executions, 4 concurrent
+tiles per preview, 32 selected tiles, 8 actual PromQL executions per tile, 31-day
+range, 30-second total deadline, at most 500 rows, and 1 MiB response. Dataset and
+PromQL label-metadata variables require explicit selections in preview. Text,
+list, SQL and PromQL-query variables can resolve automatically. A missing saved
+default in bounded dynamic options is reported instead of silently substituting
+a different selection. Runtime selections do not alter saved defaults.
+PromQL preview uses a separate eight-request admission pool and at most two
+evaluations, leaving two shared evaluation slots available to normal browser
+queries. Timed-out blocking evaluations retain their permits until they finish.
+
+## Concurrency and retries
+
+Every dashboard write uses authoritative object bytes and a storage precondition.
+The opaque public revision fingerprints document content and a per-commit nonce;
+changes invalidate it even if an older writer preserves internal metadata.
+A same-revision race yields one accepted mutation and revision conflicts for the
+others. A `412` includes the current revision. Missing required revision is `428`.
+Pass a single strong quoted ETag in `If-Match`; raw JSON revisions are accepted
+for compatibility. Weak/wildcard/list preconditions are rejected.
+
+Legacy unkeyed REST PUT accepts a full replacement without a revision. The
+server captures the authoritative source revision once and commits through the
+same conditional storage path; an intervening write returns 412 without retrying
+the replacement against newer data. A client body prepared before the request
+can still overwrite earlier edits: detecting that intent requires the caller to
+send its observed header/body revision. This is an inherent limit of the legacy
+unversioned replacement contract. PATCH, keyed mutations and agent tools retain
+the explicit revision requirement. Legacy unkeyed favorite/tags/add-tile
+operations apply their delta to fresh state, retrying storage contention at most
+eight times.
+
+Agent mutation keys are bound to the authenticated principal, tenant, dashboard,
+operation and arguments. Creates use a deterministic ID for keyed retries. Recent
+mutation receipts are durable and bounded to 64; the create receipt is retained
+separately. A replay returns current configuration with
+`replayed: true` and the original `appliedRevision`. The original source revision
+still prevents accidental reapplication after receipt eviction. Reusing a key
+with different arguments is an error. Replaying a create or update after deletion
+returns `410 resource_deleted` with its original applied revision; retrying an
+already applied delete still succeeds.
+
+The native UI sends its observed revision for saves and deletion confirmations.
+If another writer changes the dashboard, the UI keeps the conflict visible and
+requires a fresh decision; it does not automatically repeat the deletion.
+
+Deletes write a conditional tombstone because cloud object storage does not offer
+conditional deletion through the current storage interface. Tombstoned dashboard
+IDs never resurrect. Per-title reservations enforce unique titles without a
+network-held global dashboard lock; unrelated dashboards can make progress.
+Write commits survive cancellation of the calling request. Interrupted claims
+after a process crash resume with the original idempotency key. A pending rename
+whose source write is fenced out can be recovered; an interrupted unkeyed create
+before document commit can require operator recovery. This limitation is reported
+as an explicit reservation conflict, never handled by unsafe lease stealing.
+Storage write errors are reconciled against the commit nonce. When an unkeyed
+write can be safely fenced, its unused title reservation is released; a later
+edit using the committed title keeps that reservation. If storage stays
+unavailable during reconciliation, recovery can still require an operator.
+
+All serving/writing nodes must be upgraded before relying on conditional-write
+semantics; old binaries or direct object-store writes do not participate in the
+protocol. Unsupported conditional storage fails explicitly. Rolling back to old
+binaries while tombstones exist is unsupported. Tombstones/locators/title records
+are metadata, not a separately deployed service.
+
+LocalFS upgrades require stopping all writers and restarting them on the new
+binary; mixed old and new writers are unsupported. Stable private lock files
+retain checksummed generations across identical rewrites and delete/recreate
+cycles. Never remove or replace those lock files. Reads open existing locks
+read-only and create no directories or files. Before the first lock exists,
+reads use generation zero; a concurrent first mutation can cause a safe revision
+conflict, requiring a fresh read. The first generation initialization syncs the
+lock directory and storage root before persisting a nonzero generation. Later
+mutations still sync each new generation before changing object content, without
+repeating those two directory syncs. Corrupt generation records fail closed and
+require operator recovery.
+
+Legacy dashboard discovery runs once per tenant and server process, with
+singleflight initialization. Unknown IDs still check their canonical locator,
+so new dashboards created by another server remain visible. Cached legacy title
+candidates are rechecked against authoritative documents. Listing currently
+reads all dashboard documents in the tenant, including compact tombstones, before
+filtering and pagination; it is not an indexed constant-cost listing operation.
+Malformed JSON records are skipped in listings/tags, as in the legacy loader;
+storage failures still surface. Default REST listing sorts by modified time
+(descending), `limit=0` means all, positive limits have no new cap, `tags` ignores
+`limit`, and an empty tags filter is a 400. An explicit `after` parameter opts
+into ID-ordered cursor pagination; dashboard tools also use ID order. Legacy
+not-found, ownership, duplicate-title, duplicate-tile and metadata errors retain
+their plaintext status/body contracts; PATCH/tool and new concurrency errors are
+structured.
+
+Legacy REST create/replace/add-tile use the original `Dashboard`/`Tile` typed
+extractors and a separate internal validation mode. Arbitrary flattened tile and
+dashboard configuration (including `tileType: "ai"` and opaque chart/layout
+shapes) is accepted; typed fields retain their original deserialization rules
+and 400 errors. Optional PUT bodies retain the original missing-body behavior
+when typed extraction fails. Missing/null tiles, dashboard type and favorite
+values receive the legacy defaults. Non-nil, unique tile identities are still
+required, including on create. Internal metadata is rejected on input, and
+owner/identity/creation metadata is generated or restored from storage. The
+shared title-reservation, revision and conditional-write protocol is unchanged.
+PATCH, validation endpoints and all dashboard tool mutations retain strict
+configuration validation; an accidentally routed PATCH cannot select legacy
+validation. Idempotency receipts distinguish these validation modes so a tool
+cannot replay a legacy write that has not passed strict validation. Untouched stored defects remain warnings on strict updates.
+
+Regression coverage exercises arbitrary-config create/replace/add, strict
+create/replace/add/PATCH rejection, malformed typed 400 errors, defaults, required
+tile identities, owner/server-field protection and stale-revision rejection.
+The existing concurrent unversioned-PUT test still checks that a full replacement
+cannot retry over a newer edit. These additions require a passing CI test run
+before API compatibility is considered validated.
+
+Rollout remains blocked until supported S3/MinIO, Azure and GCS configurations
+are checked for conditional writes and parent-owned CPU/RAM benchmarks pass.
+Mixed old/new serving nodes are unsafe: old nodes may expose tombstones as live
+dashboards or overwrite metadata without CAS. Upgrade all nodes together and do
+not roll back with tombstones present. No unconditional fallback is implemented
+for backends that reject conditional writes.
+Dry runs check current title availability without reserving it; concurrent writes
+can change that availability before commit.
+
+## Verification
+
+Run pure patch/validation, shared-service concurrency, storage-CAS and runtime
+parity tests with the server's Rust test suite. The frontend suite covers quoted
+If-Match, conflict/retry/overwrite races, unknown-field preservation, and saved
+refresh defaults. The separate `pb-rs` repository has dashboard CLI commands and
+mock-server tests.
+
+A disposable real-server smoke is provided:
+
+```sh
+PARSEABLE_URL=http://127.0.0.1:9084 \
+DASHBOARD_AGENT_REPORT=/path/to/report.json \
+python3 scripts/test-dashboard-agent.py
+```
+
+Start that server with `P_DASHBOARD_AGENT_WRITES=true`. The smoke creates uniquely
+named logs/metrics datasets and an empty dashboard, configures SQL/builder/PromQL
+panels through tools, checks dry-run/validation/retry/identity behavior, races 24
+same-revision writes, rebases eight concurrent tile additions, renames a variable,
+moves a tile, and explicitly executes all three query modes. It cleans up its own
+resources and reports observed latency; measurements describe that local run,
+not a production throughput guarantee.
+
+### Local verification, 2026-10-17
+
+- Rust library suite: 756 passed, one ignored; server binary built successfully.
+- Frontend full suite: 2,418 passed, 14 skipped. After conditional-delete support,
+  37 focused tests, two browser regressions and the TypeScript/Vite build passed.
+- Rust `pb` suite: 160 passed. All ten dashboard commands also passed a real
+  loopback-server lifecycle (22 invocations, 18 assertions), including SQL preview.
+- Final-server agent lifecycle: empty dashboard to SQL, visual-builder and PromQL
+  panels; expected results were 20 requests, five errors, and metric value 20.
+  Dry-run, invalid-batch rollback, retry replay, variable rename, tile movement,
+  unknown-field preservation and unchanged configuration after query execution passed.
+- Twenty-four concurrent same-revision writes produced one winner and 23 revision
+  conflicts. Eight agents explicitly rebased additions and retained all eight.
+  Observed local request latency was 16.08 ms median and 21.82 ms maximum for that
+  same-revision race. This single disposable run is not a throughput guarantee.
+- Live scoped-reader checks allowed own dashboard configuration, refused another
+  owner's mutation and denied queries against an ungranted dataset. Disabled-write
+  policy hid/refused mutation tools; anonymous and invalid credentials were rejected.
+
+Cloud adapters compile and their shared conditional-write path is tested through
+`MetricLayer`/`LimitStore` with an in-memory object store. Live S3, GCS and Azure
+services were not exercised in this workspace; verify the target provider's
+conditional-write behavior before rollout. No deployment was performed.
diff --git a/docs/tool-api.md b/docs/tool-api.md
index d14c8f491..73e0241e3 100644
--- a/docs/tool-api.md
+++ b/docs/tool-api.md
@@ -42,7 +42,7 @@ matching `If-None-Match` receives `304 Not Modified`.
 
 The catalog is edition-specific:
 
-- OSS returns externally callable OSS read tools.
+- OSS returns externally callable OSS read tools and explicitly enabled dashboard write tools.
 - Enterprise returns OSS read tools plus Enterprise read tools.
 - Parseable Cloud uses the Enterprise server catalog and exposes the tools
   enabled by that deployment.
@@ -63,10 +63,13 @@ Request:
 }
 ```
 
-`arguments` must satisfy the tool's `inputSchema`. The external registry
-currently exposes only read-only and expensive-read tools. Mutation and
-external-side-effect tools remain unavailable until Parseable supports a
-server-verifiable confirmation flow bound to the session, tool, and arguments.
+`arguments` must satisfy the tool's `inputSchema`. The external registry exposes read-only and expensive-read tools by default.
+Dashboard mutation tools can be enabled with `P_DASHBOARD_AGENT_WRITES=true`;
+normal dashboard RBAC, tenant and owner/admin policy, revisions and idempotency
+still apply. This explicit standing operator policy applies only to dashboard
+writes. Other mutation/external-side-effect tools remain unavailable until
+Parseable supports their server-verifiable confirmation flows. See
+[Agent-driven dashboards](dashboard-agent-api.md) for the full contract.
 
 Successful and failed executions use the MCP `CallToolResult` shape:
 
diff --git a/frontend/e2e/dashboards.spec.ts b/frontend/e2e/dashboards.spec.ts
index ac6dfe873..9f1dddefd 100644
--- a/frontend/e2e/dashboards.spec.ts
+++ b/frontend/e2e/dashboards.spec.ts
@@ -48,6 +48,7 @@ type Call = {
   method: string;
   body?: Record<string, unknown>;
   params: URLSearchParams;
+  headers: Record<string, string>;
 };
 async function mockServer(
   page: Page,
@@ -82,7 +83,7 @@ async function mockServer(
         ? Object.fromEntries(new URLSearchParams(request.postData()!))
         : request.postDataJSON()
       : undefined;
-    calls.push({ path, method, body, params: url.searchParams });
+    calls.push({ path, method, body, params: url.searchParams, headers: request.headers() });
     if (path === options.denied)
       return route.fulfill({ status: 403, body: 'Dashboard permission denied' });
     if (path === '/api/v1/about')
@@ -146,7 +147,7 @@ async function mockServer(
         json:
           options.rows ??
           [...documents.values()].map(
-            ({ title, dataset, author, dashboardId, created, modified, tags, isFavorite }) => ({
+            ({
               title,
               dataset,
               author,
@@ -155,6 +156,17 @@ async function mockServer(
               modified,
               tags,
               isFavorite,
+              revision,
+            }) => ({
+              title,
+              dataset,
+              author,
+              dashboardId,
+              created,
+              modified,
+              tags,
+              isFavorite,
+              revision,
             }),
           ),
       });
@@ -177,6 +189,13 @@ async function mockServer(
         return route.fulfill({ json: doc });
       }
       if (method === 'DELETE') {
+        const document = documents.get(requestedId);
+        const observed = request.headers()['if-match'];
+        if (document?.revision && observed && observed !== `"${document.revision}"`)
+          return route.fulfill({
+            status: 412,
+            json: { error: { code: 'revision_conflict', message: 'Dashboard changed' } },
+          });
         documents.delete(requestedId);
         return route.fulfill({ status: 200, body: '' });
       }
@@ -330,6 +349,64 @@ test('list favourites and rename preserve the full document; typed deletion rest
   await expect(page.getByLabel('Search dashboards')).toBeFocused();
 });
 
+for (const location of ['list', 'detail'] as const) {
+  test(`conditional deletion from ${location} keeps agent edits until a fresh confirmation`, async ({
+    page,
+  }) => {
+    const source = { ...classic, revision: 'revision-1', tiles: [], variables: [], sections: [] };
+    const server = await mockServer(page, { document: source });
+    await page.goto(location === 'list' ? '/dashboards' : detail);
+    async function openDelete(title: string) {
+      await page
+        .getByRole('button', {
+          name: location === 'list' ? `Actions for ${title}` : 'Dashboard actions',
+          exact: true,
+        })
+        .click();
+      await page
+        .getByRole('menuitem', {
+          name: location === 'list' ? 'Delete' : 'Delete dashboard',
+          exact: true,
+        })
+        .click();
+      const dialog = page.getByRole('dialog', { name: 'Delete dashboard', exact: true });
+      await dialog.getByLabel('Confirmation name').fill(title);
+      return dialog;
+    }
+    const dialog = await openDelete(source.title);
+    server.change({ revision: 'revision-2', title: 'Agent saved a newer dashboard' });
+    await dialog.locator('[data-dialog-confirm]').click();
+    await expect(dialog.getByRole('alert')).toHaveText(
+      'This dashboard changed. Reload and review it before deleting.',
+    );
+    await expect(dialog).toBeVisible();
+    const deletes = () => server.calls.filter((call) => call.method === 'DELETE');
+    expect(deletes()).toHaveLength(1);
+    expect(deletes()[0].headers['if-match']).toBe('"revision-1"');
+    expect(server.current()).toMatchObject({
+      revision: 'revision-2',
+      title: 'Agent saved a newer dashboard',
+    });
+    await dialog.getByRole('button', { name: 'Cancel', exact: true }).click();
+    if (location === 'list') {
+      await page.getByRole('button', { name: 'Refresh', exact: true }).click();
+      await expect(
+        page.getByRole('link', { name: 'Agent saved a newer dashboard', exact: true }),
+      ).toBeVisible();
+    } else {
+      await page.reload();
+      await expect(
+        page.getByRole('heading', { name: 'Agent saved a newer dashboard', exact: true }),
+      ).toBeVisible();
+    }
+    const fresh = await openDelete('Agent saved a newer dashboard');
+    await fresh.locator('[data-dialog-confirm]').click();
+    await expect(fresh).not.toBeVisible();
+    expect(deletes()).toHaveLength(2);
+    expect(deletes()[1].headers['if-match']).toBe('"revision-2"');
+  });
+}
+
 test('demo PromQL tile add/edit/delete and variable selection', async ({ page }) => {
   await demo(page, '/dashboards/01M4J000000000000000000002');
   await expect(tile(page, 'Host load').getByRole('img')).toHaveAccessibleName(/4 series from/);
diff --git a/frontend/src/features/dashboards/DashboardDialogs.tsx b/frontend/src/features/dashboards/DashboardDialogs.tsx
index 15ce4b562..b0bf2253b 100644
--- a/frontend/src/features/dashboards/DashboardDialogs.tsx
+++ b/frontend/src/features/dashboards/DashboardDialogs.tsx
@@ -218,7 +218,7 @@ export function DashboardDialogs({
         error={dashboardError(mutation.error)}
         onConfirm={() =>
           void mutation.run(async () => {
-            await client.deleteDashboard(draft.dashboardId);
+            await client.deleteDashboard(draft.dashboardId, draft.revision);
             if (mutation.isActive()) {
               workspace.markSaved();
               onDashboardDeleted();
diff --git a/frontend/src/features/dashboards/DashboardRefresh.test.tsx b/frontend/src/features/dashboards/DashboardRefresh.test.tsx
new file mode 100644
index 000000000..2d2c8a4dc
--- /dev/null
+++ b/frontend/src/features/dashboards/DashboardRefresh.test.tsx
@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { createDemoDashboards } from '../../lib/demoDashboards';
+import {
+  DashboardRefreshControls,
+  DashboardRefreshProvider,
+  savedRefreshInterval,
+} from './DashboardRefresh';
+
+afterEach(() => vi.unstubAllGlobals());
+describe('saved dashboard refresh defaults', () => {
+  it('starts older documents and unsupported intervals with refresh off', () => {
+    for (const value of [undefined, null, -1, 1000, '30000', Number.NaN])
+      expect(savedRefreshInterval(value)).toBe(0);
+    for (const value of [0, 15_000, 30_000, 60_000, 300_000])
+      expect(savedRefreshInterval(value)).toBe(value);
+  });
+  it('reloads an explicitly saved default into the live refresh controls', async () => {
+    const client = createDemoDashboards();
+    const created = await client.createDashboard({ title: 'Refresh default', tiles: [] });
+    expect(created.refreshInterval).toBeUndefined();
+    await client.updateDashboard(created.dashboardId, { ...created, refreshInterval: 30_000 });
+    const reloaded = await client.getDashboard(created.dashboardId);
+    vi.stubGlobal('document', { hidden: false });
+    const markup = renderToStaticMarkup(
+      <DashboardRefreshProvider onRefresh={() => {}} savedInterval={reloaded.refreshInterval}>
+        <DashboardRefreshControls savedInterval={reloaded.refreshInterval} />
+      </DashboardRefreshProvider>,
+    );
+    expect(markup).toContain('<option value="30000" selected="">30s</option>');
+    expect(markup).not.toContain('Use as saved default');
+  });
+});
diff --git a/frontend/src/features/dashboards/DashboardRefresh.tsx b/frontend/src/features/dashboards/DashboardRefresh.tsx
index 5c2a62de8..ed35d2aab 100644
--- a/frontend/src/features/dashboards/DashboardRefresh.tsx
+++ b/frontend/src/features/dashboards/DashboardRefresh.tsx
@@ -20,6 +20,8 @@ export const refreshIntervals = [
   { value: 60_000, label: '1m' },
   { value: 300_000, label: '5m' },
 ];
+export const savedRefreshInterval = (value: unknown): number =>
+  refreshIntervals.some((interval) => interval.value === value) ? Number(value) : 0;
 
 type Tracker = {
   track: <T>(
@@ -47,12 +49,15 @@ const Refresh = createContext<
 /** One completion-based timer for the whole view, including variable queries. */
 export function DashboardRefreshProvider({
   onRefresh,
+  savedInterval = 0,
   children,
 }: {
   onRefresh: () => void;
+  savedInterval?: number;
   children: ReactNode;
 }) {
-  const [interval, setRefreshInterval] = useState(0);
+  const [interval, setRefreshInterval] = useState(() => savedRefreshInterval(savedInterval));
+  useEffect(() => setRefreshInterval(savedRefreshInterval(savedInterval)), [savedInterval]);
   const [hidden, setHidden] = useState(() => document.hidden);
   const [activity, setActivity] = useState(0);
   const [lastUpdated, setLastUpdated] = useState<number>();
@@ -161,7 +166,15 @@ export function useDashboardQuery<T>(
   return useAsync(tracked);
 }
 
-export function DashboardRefreshControls({ onManualRefresh }: { onManualRefresh?: () => void }) {
+export function DashboardRefreshControls({
+  onManualRefresh,
+  savedInterval = 0,
+  onSaveDefault,
+}: {
+  onManualRefresh?: () => void;
+  savedInterval?: number;
+  onSaveDefault?: (interval: number) => void;
+}) {
   const state = useContext(Refresh);
   const [announcement, setAnnouncement] = useState('');
   const previouslyFailed = useRef(false);
@@ -185,6 +198,9 @@ export function DashboardRefreshControls({ onManualRefresh }: { onManualRefresh?
           </option>
         ))}
       </Select>
+      {onSaveDefault && state.interval !== savedRefreshInterval(savedInterval) && (
+        <Button onClick={() => onSaveDefault(state.interval)}>Use as saved default</Button>
+      )}
       <Button
         className="dashboard-refresh-button"
         aria-disabled={state.busy || state.hidden}
diff --git a/frontend/src/features/dashboards/DashboardView.tsx b/frontend/src/features/dashboards/DashboardView.tsx
index 035349a1b..2f221f4e9 100644
--- a/frontend/src/features/dashboards/DashboardView.tsx
+++ b/frontend/src/features/dashboards/DashboardView.tsx
@@ -99,7 +99,7 @@ function DashboardFields({ original }: { original: Dashboard }) {
       );
   }
   return (
-    <DashboardRefreshProvider onRefresh={url.refresh}>
+    <DashboardRefreshProvider onRefresh={url.refresh} savedInterval={draft.refreshInterval}>
       <div
         ref={page}
         className={`page dashboards-page${presentation.presenting ? ' dashboard-presentation' : ''}`}
@@ -215,6 +215,16 @@ function DashboardFields({ original }: { original: Dashboard }) {
             }}
           />
           <DashboardRefreshControls
+            savedInterval={draft.refreshInterval}
+            onSaveDefault={
+              editing
+                ? (refreshInterval) =>
+                    workspace.changeDraft(
+                      (current) => ({ ...current, refreshInterval }),
+                      'Refresh default updated. Save to keep this change.',
+                    )
+                : undefined
+            }
             onManualRefresh={() =>
               workspace.announce(
                 `Refreshing ${(draft.tiles ?? []).length} ${(draft.tiles ?? []).length === 1 ? 'tile' : 'tiles'}.`,
diff --git a/frontend/src/features/dashboards/DashboardsPage.tsx b/frontend/src/features/dashboards/DashboardsPage.tsx
index 42b9e6e66..87348b480 100644
--- a/frontend/src/features/dashboards/DashboardsPage.tsx
+++ b/frontend/src/features/dashboards/DashboardsPage.tsx
@@ -9,7 +9,13 @@ import { useCollection } from '../../hooks/useCollection';
 import { useMutation } from '../../hooks/useMutation';
 import type { Dashboard, DashboardSummary } from '../../lib/types';
 import { useLeaveGuard } from '../../hooks/useLeaveGuard';
-import { dashboardError, duplicateDashboard, metadataPatch, patchConflicts } from './helpers';
+import {
+  dashboardError,
+  duplicateDashboard,
+  metadataPatch,
+  patchConflicts,
+  saveDashboardDocument,
+} from './helpers';
 import { patchedDocument } from './draft';
 import { useDashboardAccess } from './owner';
 import { DashboardsList } from './DashboardsList';
@@ -55,14 +61,22 @@ export function DashboardsPage() {
   }
   /** Applies a metadata patch to the latest stored copy, so newer tiles and settings survive. */
   async function save(loaded: Dashboard, patch: Partial<Dashboard>, overwrite = false) {
-    const latest = await client.getDashboard(loaded.dashboardId, readSignal());
+    const signal = readSignal();
+    // An overwrite is conditional on the copy shown in the conflict dialog.
+    const latest = overwrite ? loaded : await client.getDashboard(loaded.dashboardId, signal);
     if (!mutation.isActive()) return;
     if (!overwrite && patchConflicts(loaded, latest, patch)) {
       setForm(undefined);
       setConflict({ latest, patch });
       return;
     }
-    await client.updateDashboard(latest.dashboardId, patchedDocument(latest, patch));
+    const result = await saveDashboardDocument(client, patchedDocument(latest, patch), signal);
+    if (!mutation.isActive()) return;
+    if (result.conflict) {
+      setForm(undefined);
+      setConflict({ latest: result.conflict, patch });
+      return;
+    }
     if (mutation.isActive()) {
       markSaved();
       completed('Dashboard updated.');
@@ -239,7 +253,7 @@ export function DashboardsPage() {
         onConfirm={() =>
           void mutation.run(async () => {
             if (!deleting) return;
-            await client.deleteDashboard(deleting.dashboardId);
+            await client.deleteDashboard(deleting.dashboardId, deleting.revision);
             if (mutation.isActive()) {
               setDeleted(deleting.dashboardId);
               setDeleting(undefined);
diff --git a/frontend/src/features/dashboards/helpers.test.ts b/frontend/src/features/dashboards/helpers.test.ts
index 167f437fd..42a58ca71 100644
--- a/frontend/src/features/dashboards/helpers.test.ts
+++ b/frontend/src/features/dashboards/helpers.test.ts
@@ -65,8 +65,21 @@ describe('dashboard helpers', () => {
     getDashboard.mockRejectedValue(new Error('Denied'));
     await expect(checkDashboardConflict(client, classic, signal)).rejects.toThrow('Denied');
   });
+  it('detects revision changes even when modified timestamps are unchanged', async () => {
+    const loaded = { ...classic, revision: 'r1' };
+    const latest = { ...classic, revision: 'r2' };
+    const getDashboard = vi.fn().mockResolvedValue(latest);
+    const client = { getDashboard } as unknown as ParseableClient;
+    expect(await checkDashboardConflict(client, loaded, new AbortController().signal)).toEqual(
+      latest,
+    );
+    getDashboard.mockResolvedValue({ ...loaded, modified: 'Different display timestamp' });
+    expect(
+      await checkDashboardConflict(client, loaded, new AbortController().signal),
+    ).toBeUndefined();
+  });
   it('duplicates all extras with fresh tile ULIDs and no old metadata', () => {
-    const result = duplicateDashboard(classic, [classic.title]);
+    const result = duplicateDashboard({ ...classic, revision: 'r1' }, [classic.title]);
     expect(result.title).toBe('Service health (Copy)');
     expect(result.isFavorite).toBe(false);
     expect(result.tiles.every((tile) => ulid(tile.tile_id))).toBe(true);
@@ -78,6 +91,7 @@ describe('dashboard helpers', () => {
     expect(result.timeRange).toEqual(classic.timeRange);
     expect(result.future).toEqual(classic.future);
     expect(result.dashboardId).toBeUndefined();
+    expect(result).not.toHaveProperty('revision');
     expect(result).not.toHaveProperty('tenantId');
     expect(result.dashboardType).toBe('Report');
   });
diff --git a/frontend/src/features/dashboards/helpers.ts b/frontend/src/features/dashboards/helpers.ts
index fcea275d5..8a698b174 100644
--- a/frontend/src/features/dashboards/helpers.ts
+++ b/frontend/src/features/dashboards/helpers.ts
@@ -6,6 +6,7 @@ import type {
   ParseableClient,
 } from '../../lib/types';
 import { createUlid } from '../../lib/ids';
+import { ApiError } from '../../lib/apiError';
 
 export const dashboardError = (error?: string) =>
   error?.replace(/^Cannot perform this operation: /, '');
@@ -27,8 +28,22 @@ export function dashboardDate(value: string | null | undefined) {
   return Number.isFinite(date) ? new Date(date).toISOString() : undefined;
 }
 function hasConflict(loaded: Dashboard, latest: Dashboard): boolean {
+  if (loaded.revision && latest.revision) return loaded.revision !== latest.revision;
   return loaded.modified !== latest.modified;
 }
+/** A rejected conditional write is shown with the freshly observed server copy. */
+export async function saveDashboardDocument(
+  client: ParseableClient,
+  document: Dashboard,
+  signal: AbortSignal,
+): Promise<{ saved: Dashboard; conflict?: never } | { saved?: never; conflict: Dashboard }> {
+  try {
+    return { saved: await client.updateDashboard(document.dashboardId, document) };
+  } catch (error) {
+    if (!(error instanceof ApiError) || error.status !== 412) throw error;
+    return { conflict: await client.getDashboard(document.dashboardId, signal) };
+  }
+}
 export async function checkDashboardConflict(
   client: ParseableClient,
   loaded: Dashboard,
@@ -80,7 +95,8 @@ export function duplicateDashboard(
   titles: Iterable<string>,
 ): DashboardRequest & { tiles: DashboardTile[] } {
   const body = structuredClone(source);
-  for (const key of ['dashboardId', 'author', 'created', 'modified', 'tenantId']) delete body[key];
+  for (const key of ['dashboardId', 'author', 'created', 'modified', 'tenantId', 'revision'])
+    delete body[key];
   return {
     ...body,
     title: availableTitle(`${source.title} (Copy)`, new Set(titles)),
diff --git a/frontend/src/features/dashboards/importExport.test.ts b/frontend/src/features/dashboards/importExport.test.ts
index a3f4f766f..dc7ef7e3a 100644
--- a/frontend/src/features/dashboards/importExport.test.ts
+++ b/frontend/src/features/dashboards/importExport.test.ts
@@ -19,12 +19,13 @@ describe('classic portable JSON', () => {
     expect(result.variables).toEqual(classic.variables);
   });
   it('imports promql_query, empty tiles, saved timeRange and unknown fields', () => {
-    const result = importDashboard(JSON.stringify(classic), 'Imported');
+    const result = importDashboard(JSON.stringify({ ...classic, revision: 'r1' }), 'Imported');
     expect(result.title).toBe('Imported');
     expect(result.variables).toEqual(classic.variables);
     expect(result.timeRange).toEqual(classic.timeRange);
     expect(result.future).toEqual(classic.future);
     expect(result).not.toHaveProperty('tenantId');
+    expect(result).not.toHaveProperty('revision');
     expect(result.dashboardType).toBe('Report');
     expect(result.tiles?.every((tile) => ulid(tile.tile_id))).toBe(true);
     expect(result.tiles?.[0].tile_id).not.toBe(classic.tiles[0].tile_id);
diff --git a/frontend/src/features/dashboards/importExport.ts b/frontend/src/features/dashboards/importExport.ts
index 20268adf7..17106a2c3 100644
--- a/frontend/src/features/dashboards/importExport.ts
+++ b/frontend/src/features/dashboards/importExport.ts
@@ -44,7 +44,8 @@ export function importDashboard(json: string, title: string): DashboardRequest {
     throw new Error('Invalid dashboard variables.');
   if (!title.trim()) throw new Error('Enter a dashboard title.');
   const body = structuredClone(value);
-  for (const key of ['dashboardId', 'author', 'created', 'modified', 'tenantId']) delete body[key];
+  for (const key of ['dashboardId', 'author', 'created', 'modified', 'tenantId', 'revision'])
+    delete body[key];
   const tiles: DashboardTile[] = value.tiles.map((tile) => ({
     ...structuredClone(tile),
     tile_id: createUlid(),
diff --git a/frontend/src/features/dashboards/useDashboardDraft.ts b/frontend/src/features/dashboards/useDashboardDraft.ts
index 6578aa2c9..81a8236e8 100644
--- a/frontend/src/features/dashboards/useDashboardDraft.ts
+++ b/frontend/src/features/dashboards/useDashboardDraft.ts
@@ -4,7 +4,7 @@ import { useLeaveGuard } from '../../hooks/useLeaveGuard';
 import { useMutation } from '../../hooks/useMutation';
 import type { Dashboard, TimeRange } from '../../lib/types';
 import { dashboardPayload, loadDraft } from './draft';
-import { checkDashboardConflict } from './helpers';
+import { checkDashboardConflict, saveDashboardDocument } from './helpers';
 import { dashboardRange } from './timeRange';
 
 export function useDashboardDraft(original: Dashboard, focusHeading: () => void) {
@@ -66,7 +66,7 @@ export function useDashboardDraft(original: Dashboard, focusHeading: () => void)
     void mutation.run(async () => {
       read.current?.abort();
       read.current = new AbortController();
-      if (!overwrite) {
+      if (!overwrite && !loaded.revision) {
         const latest = await checkDashboardConflict(client, loaded, read.current.signal);
         if (!mutation.isActive()) return;
         if (latest) {
@@ -74,11 +74,18 @@ export function useDashboardDraft(original: Dashboard, focusHeading: () => void)
           return;
         }
       }
-      const saved = await client.updateDashboard(
-        draft.dashboardId,
-        dashboardPayload(draft, range, rangeDirty),
+      const result = await saveDashboardDocument(
+        client,
+        dashboardPayload(
+          { ...draft, revision: (overwrite ? conflict : loaded)?.revision },
+          range,
+          rangeDirty,
+        ),
+        read.current.signal,
       );
-      if (mutation.isActive()) accept(saved, 'Dashboard saved.');
+      if (!mutation.isActive()) return;
+      if (result.conflict) setConflict(result.conflict);
+      else accept(result.saved, 'Dashboard saved.');
     });
   }
   return {
diff --git a/frontend/src/features/sql/SqlChartPanel.tsx b/frontend/src/features/sql/SqlChartPanel.tsx
index f67061a1b..1578697c0 100644
--- a/frontend/src/features/sql/SqlChartPanel.tsx
+++ b/frontend/src/features/sql/SqlChartPanel.tsx
@@ -6,6 +6,7 @@ import { Button, Dialog, Input, InlineError, Select } from '../../components/ui'
 import { QueryState } from '../../components/explorer/QueryState';
 import { useAsync } from '../../hooks/useAsync';
 import { useMutation } from '../../hooks/useMutation';
+import { ApiError } from '../../lib/apiError';
 import type { Dashboard, LogRecord, TimeRange } from '../../lib/types';
 import { timeBounds } from '../../lib/query';
 import { TileChart } from '../dashboards/TileChart';
@@ -197,10 +198,20 @@ export function SqlChartPanel({
                       'This dashboard changed. Review the latest version and add the chart again.',
                     );
                   }
-                  result = await client.updateDashboard(
-                    loaded.dashboardId,
-                    appendSqlTile(latest, tile),
-                  );
+                  try {
+                    result = await client.updateDashboard(
+                      loaded.dashboardId,
+                      appendSqlTile(latest, tile),
+                    );
+                  } catch (error) {
+                    if (error instanceof ApiError && error.status === 412) {
+                      selected.reload();
+                      throw new Error(
+                        'This dashboard changed. Review the latest version and add the chart again.',
+                      );
+                    }
+                    throw error;
+                  }
                 }
                 if (mutation.isActive()) {
                   setSaved(result);
diff --git a/frontend/src/lib/client.ts b/frontend/src/lib/client.ts
index de351a94a..79944f5a1 100644
--- a/frontend/src/lib/client.ts
+++ b/frontend/src/lib/client.ts
@@ -125,6 +125,9 @@ async function readText(endpoint: string, init: RequestInit, onUnauthorized?: ()
 function jsonBody(method: string, body: unknown): RequestInit {
   return { method, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) };
 }
+function dashboardRevisionHeaders(revision?: string): Record<string, string> {
+  return revision ? { 'If-Match': revision.startsWith('"') ? revision : `"${revision}"` } : {};
+}
 
 const seconds = (value: number) => String(Math.round(value * 1000) / 1000);
 
@@ -249,10 +252,32 @@ export function createClient({
     },
     getDashboard: (id, signal) => readDashboard(dashboardPath(id), { signal }),
     createDashboard: (body) => readDashboard(`${base}/dashboards`, jsonBody('POST', body)),
-    updateDashboard: (id, body) => readDashboard(dashboardPath(id), jsonBody('PUT', body)),
+    updateDashboard: (id, body) =>
+      readDashboard(dashboardPath(id), {
+        ...jsonBody('PUT', body),
+        headers: {
+          'Content-Type': 'application/json',
+          ...dashboardRevisionHeaders(body.revision),
+        },
+      }),
     setDashboardFavorite: (id, isFavorite) =>
       readDashboard(`${dashboardPath(id)}?isFavorite=${isFavorite}`, { method: 'PUT' }),
-    deleteDashboard: (id) => mutate(dashboardPath(id), { method: 'DELETE' }),
+    async deleteDashboard(id, revision) {
+      try {
+        await mutate(dashboardPath(id), {
+          method: 'DELETE',
+          headers: dashboardRevisionHeaders(revision),
+        });
+      } catch (error) {
+        if (error instanceof ApiError && error.status === 412)
+          throw new ApiError(
+            'This dashboard changed. Reload and review it before deleting.',
+            412,
+            error.detail,
+          );
+        throw error;
+      }
+    },
     async listAlerts(signal) {
       // The server caps each page at 1000 and returns no total. Never silently truncate.
       // It sorts by state, severity and title before offsetting, so an alert changing state
diff --git a/frontend/src/lib/dashboardsClient.test.ts b/frontend/src/lib/dashboardsClient.test.ts
index 8854c8e8a..72af4833f 100644
--- a/frontend/src/lib/dashboardsClient.test.ts
+++ b/frontend/src/lib/dashboardsClient.test.ts
@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createClient } from './client';
 import classic from '../features/dashboards/__fixtures__/classic.json';
 import type { ParseableClient } from './types';
-import { checkDashboardConflict } from '../features/dashboards/helpers';
+import { checkDashboardConflict, saveDashboardDocument } from '../features/dashboards/helpers';
 import { applyTile, dashboardPayload, loadDraft } from '../features/dashboards/draft';
 const path = '/api/v1/dashboards/id%2Fwith%20space';
 const cases: Array<{
@@ -55,6 +55,102 @@ const cases: Array<{
 ];
 afterEach(() => vi.unstubAllGlobals());
 describe('dashboard requests', () => {
+  it.each(['observed-revision', '"observed-revision"'])(
+    'deletes only revision %s using a strong If-Match header',
+    async (revision) => {
+      const fetch = vi.fn().mockResolvedValue(new Response(''));
+      vi.stubGlobal('fetch', fetch);
+      await createClient({ mode: 'live' }).deleteDashboard(classic.dashboardId, revision);
+      const init = fetch.mock.calls[0][1];
+      expect(init.method).toBe('DELETE');
+      expect(new Headers(init.headers).get('If-Match')).toBe('"observed-revision"');
+      expect(init.body).toBeUndefined();
+    },
+  );
+  it('keeps revision-less legacy deletes and never retries a rejected conditional delete', async () => {
+    const fetch = vi
+      .fn()
+      .mockResolvedValueOnce(new Response(''))
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ error: { code: 'revision_conflict' } }), { status: 412 }),
+      );
+    vi.stubGlobal('fetch', fetch);
+    const client = createClient({ mode: 'live' });
+    await client.deleteDashboard(classic.dashboardId);
+    expect(new Headers(fetch.mock.calls[0][1].headers).has('If-Match')).toBe(false);
+    await expect(client.deleteDashboard(classic.dashboardId, 'stale')).rejects.toMatchObject({
+      status: 412,
+      message: 'This dashboard changed. Reload and review it before deleting.',
+      detail: { error: { code: 'revision_conflict' } },
+    });
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
+  it.each(['server-revision-1', '"server-revision-1"'])(
+    'sends revision %s as a strong If-Match ETag and preserves the complete document',
+    async (revision) => {
+      const body = { ...classic, revision, refreshInterval: 30_000 };
+      const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify(body)));
+      vi.stubGlobal('fetch', fetch);
+      await createClient({ mode: 'live' }).updateDashboard(classic.dashboardId, body);
+      const init = fetch.mock.calls[0][1];
+      expect(new Headers(init.headers).get('If-Match')).toBe('"server-revision-1"');
+      expect(JSON.parse(init.body)).toEqual(body);
+    },
+  );
+  it('keeps unconditional legacy requests when a document has no revision', async () => {
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify(classic)));
+    vi.stubGlobal('fetch', fetch);
+    await createClient({ mode: 'live' }).updateDashboard(classic.dashboardId, classic);
+    expect(new Headers(fetch.mock.calls[0][1].headers).has('If-Match')).toBe(false);
+  });
+  it('shows a 412 conflict and conditions each intentional overwrite on the observed copy', async () => {
+    const remote = {
+      ...classic,
+      revision: 'revision-2',
+      title: 'Agent saved',
+      future: { kept: true },
+    };
+    const newer = { ...remote, revision: 'revision-3', title: 'Another concurrent edit' };
+    const fetch = vi
+      .fn()
+      .mockResolvedValueOnce(new Response('Dashboard changed', { status: 412 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify(remote)))
+      .mockResolvedValueOnce(new Response('Dashboard changed again', { status: 412 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify(newer)))
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ ...newer, title: 'UI edit', revision: 'revision-4' })),
+      );
+    vi.stubGlobal('fetch', fetch);
+    const client = createClient({ mode: 'live' }),
+      signal = new AbortController().signal;
+    const first = await saveDashboardDocument(
+      client,
+      { ...classic, revision: 'revision-1', title: 'UI edit' },
+      signal,
+    );
+    expect(first).toEqual({ conflict: remote });
+    const second = await saveDashboardDocument(
+      client,
+      { ...first.conflict!, title: 'UI edit' },
+      signal,
+    );
+    expect(second).toEqual({ conflict: newer });
+    const third = await saveDashboardDocument(
+      client,
+      { ...second.conflict!, title: 'UI edit' },
+      signal,
+    );
+    expect(third.saved).toMatchObject({
+      revision: 'revision-4',
+      title: 'UI edit',
+      future: { kept: true },
+    });
+    expect(
+      fetch.mock.calls
+        .filter(([, init]) => init.method === 'PUT')
+        .map(([, init]) => new Headers(init.headers).get('If-Match')),
+    ).toEqual(['"revision-1"', '"revision-2"', '"revision-3"']);
+  });
   it('loads, edits and saves a complete classic document without narrowing it', async () => {
     const fetch = vi
       .fn()
diff --git a/frontend/src/lib/dashboardsContract.test.ts b/frontend/src/lib/dashboardsContract.test.ts
index 22e1d08ae..1b240360e 100644
--- a/frontend/src/lib/dashboardsContract.test.ts
+++ b/frontend/src/lib/dashboardsContract.test.ts
@@ -28,6 +28,8 @@ describe('dashboard wire guards', () => {
   it('validates known metadata and required snake-case tile IDs', () => {
     expect(dashboard({ ...classic, dataset: 'application_logs' })).toBe(true);
     expect(dashboard({ ...classic, dataset: null })).toBe(true);
+    expect(dashboard({ ...classic, revision: 'opaque-revision' })).toBe(true);
+    expect(dashboard({ ...classic, revision: 42 })).toBe(false);
     expect(dashboard({ ...classic, dataset: ['application_logs'] })).toBe(false);
     expect(dashboard({ ...classic, tiles: [{ tileId: classic.tiles[0].tile_id }] })).toBe(false);
     expect(dashboardSummary({ ...classic, tags: 'x' })).toBe(false);
diff --git a/frontend/src/lib/dashboardsContract.ts b/frontend/src/lib/dashboardsContract.ts
index 70f5795a5..26ccdf21d 100644
--- a/frontend/src/lib/dashboardsContract.ts
+++ b/frontend/src/lib/dashboardsContract.ts
@@ -11,6 +11,7 @@ export function dashboardSummary(value: unknown): value is DashboardSummary {
     object(value) &&
     ulid(value.dashboardId) &&
     typeof value.title === 'string' &&
+    (value.revision === undefined || typeof value.revision === 'string') &&
     ['author', 'created', 'modified', 'dataset'].every((key) => optionalString(value[key])) &&
     (value.tags == null || strings(value.tags)) &&
     (value.isFavorite == null || typeof value.isFavorite === 'boolean')
diff --git a/frontend/src/lib/types.ts b/frontend/src/lib/types.ts
index ab53a6427..d540b63df 100644
--- a/frontend/src/lib/types.ts
+++ b/frontend/src/lib/types.ts
@@ -372,6 +372,8 @@ export type ApiKey = {
 // intact and patch it; a narrower editor model must never become the PUT body.
 export type DashboardTile = { tile_id: string; [key: string]: unknown };
 export type DashboardSummary = {
+  /** Opaque server revision. Older servers may omit it. */
+  revision?: string;
   dataset?: string | null;
   dashboardId: string;
   title: string;
@@ -383,6 +385,9 @@ export type DashboardSummary = {
   [key: string]: unknown;
 };
 export type DashboardRequest = {
+  revision?: string;
+  /** Saved auto refresh default, in milliseconds; absent means off. */
+  refreshInterval?: number;
   dataset?: string | null;
   title: string;
   tiles?: DashboardTile[] | null;
@@ -460,7 +465,7 @@ export interface ParseableClient {
   updateDashboard(id: string, body: DashboardRequest): Promise<Dashboard>;
   /** Bodyless partial PUT: the server skips tile validation and keeps the stored document. */
   setDashboardFavorite(id: string, isFavorite: boolean): Promise<Dashboard>;
-  deleteDashboard(id: string): Promise<void>;
+  deleteDashboard(id: string, revision?: string): Promise<void>;
   listAlerts(signal?: AbortSignal): Promise<AlertSummary[]>;
   getAlert(id: string, signal?: AbortSignal): Promise<Alert>;
   createAlert(alert: AlertRequest): Promise<Alert>;
diff --git a/scripts/test-dashboard-agent.py b/scripts/test-dashboard-agent.py
new file mode 100755
index 000000000..f8f15fe8a
--- /dev/null
+++ b/scripts/test-dashboard-agent.py
@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""Disposable real-server dashboard-agent lifecycle and concurrency smoke.
+
+Requires dashboard-agent writes enabled on the target server. Creates uniquely
+named dashboards/datasets and removes only those resources in finally blocks.
+No queries run during configuration validation or change preview.
+"""
+import base64
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timedelta, timezone
+import json
+import os
+from pathlib import Path
+from threading import Barrier
+import time
+import urllib.error
+import urllib.request
+import uuid
+
+BASE = os.environ.get('PARSEABLE_URL', 'http://127.0.0.1:9084').rstrip('/')
+AUTH = base64.b64encode((os.environ.get('P_USERNAME', 'admin') + ':' + os.environ.get('P_PASSWORD', 'admin')).encode()).decode()
+PREFIX = '/api/v1/dashboards'
+TOOLS = '/api/prism/v1/llm/tools'
+
+
+def request(path, method='GET', body=None, headers=None):
+    hdr = {'Authorization': 'Basic ' + AUTH, 'Accept': 'application/json', **(headers or {})}
+    data = None
+    if body is not None:
+        data = json.dumps(body).encode()
+        hdr['Content-Type'] = 'application/json'
+    req = urllib.request.Request(BASE + path, data=data, method=method, headers=hdr)
+    try:
+        with urllib.request.urlopen(req, timeout=40) as res:
+            raw = res.read()
+            try:
+                value = json.loads(raw) if raw else None
+            except (ValueError, UnicodeError):
+                value = raw.decode(errors='replace')
+            return res.status, value, dict(res.headers)
+    except urllib.error.HTTPError as exc:
+        raw = exc.read()
+        try:
+            value = json.loads(raw)
+        except (ValueError, UnicodeError):
+            value = raw.decode(errors='replace')
+        return exc.code, value, dict(exc.headers)
+
+
+def ok(path, method='GET', body=None, headers=None):
+    status, result, response_headers = request(path, method, body, headers)
+    assert status == 200, (method, path, status, result)
+    return result, response_headers
+
+
+def tool(name, args, expect_error=False):
+    value, _ = ok(TOOLS + '/call', 'POST', {'name': name, 'arguments': args})
+    assert value['isError'] is expect_error, (name, value)
+    return value['structuredContent']['error' if expect_error else 'result']
+
+
+def ulid():
+    value = int.from_bytes(uuid.uuid4().bytes, 'big')
+    result = ''
+    alphabet = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+    for _ in range(26):
+        result = alphabet[value & 31] + result
+        value >>= 5
+    return result
+
+
+def operation(op, target, path='', value=None):
+    result = {'op': op, 'target': target, 'path': path}
+    if op != 'remove':
+        result['value'] = value
+    return result
+
+
+def main():
+    suffix = uuid.uuid4().hex[:12]
+    dashboard_id = None
+    stream = 'agent_dashboard_' + suffix
+    metrics = stream + '_metrics'
+    created_streams = []
+    start = datetime.now(timezone.utc) - timedelta(minutes=5)
+    end = datetime.now(timezone.utc) + timedelta(minutes=1)
+    counters = {'sameRevisionWinners': 0, 'sameRevisionConflicts': 0}
+    try:
+        caps = tool('get_dashboard_capabilities', {})
+        assert caps['permissions']['agentWritesEnabled'], 'Start server with P_DASHBOARD_AGENT_WRITES=true'
+        spec, _ = ok(TOOLS + '/list')
+        names = {entry['name'] for entry in spec['tools']}
+        assert {'create_dashboard', 'update_dashboard', 'delete_dashboard', 'preview_dashboard_changes', 'run_dashboard_queries'} <= names
+        assert 'create_alert' not in names, 'Dashboard policy must not enable unrelated action tools'
+        for dataset in [stream]:
+            ok('/api/v1/logstream/' + dataset, 'PUT')
+            created_streams.append(dataset)
+        records = [{'service': 'api', 'level': 'error' if i % 4 == 0 else 'info', 'duration_ms': 10 + i} for i in range(20)]
+        ok('/api/v1/ingest', 'POST', records, {'X-P-Stream': stream})
+        now_ns = time.time_ns() - 1_000_000_000
+        metric_query = '{__name__="dashboard_requests",service="api"}'
+        otlp = {'resourceMetrics': [{'resource': {'attributes': [{'key': 'service.name', 'value': {'stringValue': 'api'}}]}, 'scopeMetrics': [{'metrics': [{'name': 'dashboard_requests', 'gauge': {'dataPoints': [{'timeUnixNano': str(now_ns), 'asDouble': 20.0, 'attributes': [{'key': 'service', 'value': {'stringValue': 'api'}}]}]}}]}]}]}
+        status, value, _ = request('/v1/metrics', 'POST', otlp, {'X-P-Stream': metrics})
+        assert status in [200, 202], (status, value)
+        created_streams.append(metrics)
+        create_args = {'dashboard': {'title': 'Agent health ' + suffix, 'dataset': stream, 'tiles': [], 'customExtension': {'preserve': True}}, 'idempotencyKey': 'create-' + suffix}
+        created = tool('create_dashboard', create_args)
+        dashboard_id = created['dashboard']['dashboardId']
+        replayed = tool('create_dashboard', create_args)
+        assert replayed['dashboard']['dashboardId'] == dashboard_id and replayed['replayed']
+        document, headers = ok(PREFIX + '/' + dashboard_id)
+        assert {key.lower(): value for key, value in headers.items()}.get('etag') == '"' + document['revision'] + '"', headers
+        section_id, sql_id, builder_id, promql_id = [ulid() for _ in range(4)]
+        ids = [sql_id, builder_id, promql_id]
+        tiles = [
+            {'tile_id': sql_id, 'title': 'Requests per minute', 'tileType': 'code', 'chartType': 'timeseries', 'dbName': [stream], 'chartQuery': 'SELECT DATE_TRUNC(\'minute\', p_timestamp) AS time, COUNT(*) AS requests FROM "' + stream + '" WHERE service = \'$service\' GROUP BY time ORDER BY time', 'sectionId': section_id, 'layout': {'x': 0, 'y': 0, 'w': 6, 'h': 4}, 'config': {'type': 'line', 'colourScheme': 'classic', 'axes': {'x': {'field': 'time'}, 'y': {'field': 'requests'}}, 'layout': {'legendPosition': 'bottom'}}},
+            {'tile_id': builder_id, 'title': 'Errors by service', 'tileType': 'builder', 'chartType': 'table', 'dbName': [stream], 'chartQuery': {'x': {'fields': [{'name': 'service'}], 'groupBy': []}, 'y': {'fields': [{'name': '*', 'aggregate': 'COUNT'}], 'groupBy': [], 'limit': 100}, 'filters': [{'column': 'level', 'operator': '=', 'value': 'error', 'type': 'string'}]}, 'sectionId': section_id, 'layout': {'x': 6, 'y': 0, 'w': 6, 'h': 4}, 'config': {'type': 'table'}},
+            {'tile_id': promql_id, 'title': 'Live request metric', 'tileType': 'promql', 'chartType': 'query-value', 'dbName': metrics, 'chartQuery': [metric_query], 'promqlQueryType': ['instant'], 'layout': {'x': 0, 'y': 0, 'w': 6, 'h': 4}, 'config': {'type': 'query-value', 'layout': {'sparkline': False}}},
+        ]
+        ops = [operation('add', {'type': 'section', 'id': section_id}, value={'title': 'Application health', 'collapsed': False}), operation('add', {'type': 'variable', 'name': 'service'}, value={'label': 'Service', 'type': 'list', 'options': ['api'], 'defaultValue': 'api'})]
+        ops += [operation('add', {'type': 'tile', 'id': tile['tile_id']}, value=tile) for tile in tiles]
+        ops += [operation('add', {'type': 'dashboard'}, '/refreshInterval', 30000), operation('add', {'type': 'dashboard'}, '/timeRange', {'type': 'fixed', 'startTime': '1h', 'endTime': 'now', 'interval': 3600000, 'shiftInterval': 1})]
+        args = {'dashboardId': dashboard_id, 'revision': document['revision'], 'operations': ops}
+        preview = tool('preview_dashboard_changes', args)
+        assert preview['validation']['valid'] and len(preview['dashboard']['tiles']) == 3
+        unchanged, _ = ok(PREFIX + '/' + dashboard_id)
+        assert unchanged['revision'] == document['revision'] and unchanged['tiles'] == []
+        updated = tool('update_dashboard', {**args, 'idempotencyKey': 'configure-' + suffix})
+        replay = tool('update_dashboard', {**args, 'idempotencyKey': 'configure-' + suffix})
+        assert replay['replayed'] and len(replay['dashboard']['tiles']) == 3
+        document = updated['dashboard']
+        assert document['customExtension'] == {'preserve': True} and '_parseableDashboard' not in document
+        invalid = [operation('replace', {'type': 'dashboard'}, '/title', 'should-not-save'), operation('replace', {'type': 'tile', 'id': sql_id}, '/layout/w', 13)]
+        error = tool('update_dashboard', {'dashboardId': dashboard_id, 'revision': document['revision'], 'operations': invalid, 'idempotencyKey': 'invalid-' + suffix}, expect_error=True)
+        assert error['status'] == 422, error
+        after_invalid, _ = ok(PREFIX + '/' + dashboard_id)
+        assert after_invalid == document, 'Invalid final candidate partially committed'
+        protected = [operation('replace', {'type': 'dashboard'}, '/tenantId', 'another-tenant')]
+        error = tool('update_dashboard', {'dashboardId': dashboard_id, 'revision': document['revision'], 'operations': protected, 'idempotencyKey': 'protected-' + suffix}, expect_error=True)
+        assert error['status'] in [400, 422], error
+        barrier = Barrier(24)
+        timings = []
+
+        def contend(index):
+            barrier.wait(timeout=10)
+            began = time.perf_counter()
+            result = request(PREFIX + '/' + dashboard_id, 'PATCH', {'operations': [operation('replace', {'type': 'tile', 'id': sql_id}, '/title', 'Request rate ' + str(index))]}, {'If-Match': '"' + document['revision'] + '"'})
+            return result[0], (time.perf_counter() - began) * 1000
+
+        with ThreadPoolExecutor(max_workers=24) as pool:
+            for status, elapsed in pool.map(contend, range(24)):
+                assert status in [200, 412], status
+                counters['sameRevisionWinners' if status == 200 else 'sameRevisionConflicts'] += 1
+                timings.append(elapsed)
+        assert counters['sameRevisionWinners'] == 1 and counters['sameRevisionConflicts'] == 23, counters
+
+        def add_from_agent(index):
+            tile_id = ulid()
+            tile = {**tiles[2], 'tile_id': tile_id, 'title': 'Agent counter ' + str(index), 'layout': {'x': 0, 'y': 4 + index * 4, 'w': 6, 'h': 4}}
+            for attempt in range(40):
+                base, _ = ok(PREFIX + '/' + dashboard_id)
+                status, result, _ = request(PREFIX + '/' + dashboard_id, 'PATCH', {'operations': [operation('add', {'type': 'tile', 'id': tile_id}, value=tile)]}, {'If-Match': '"' + base['revision'] + '"', 'Idempotency-Key': 'append-' + suffix + '-' + str(index)})
+                if status == 200:
+                    return tile_id
+                assert status == 412, (status, result)
+                time.sleep(min(.002 * (attempt + 1), .03))
+            raise AssertionError('Concurrent agent retry budget exhausted')
+
+        with ThreadPoolExecutor(max_workers=8) as pool:
+            added_ids = list(pool.map(add_from_agent, range(8)))
+        document, _ = ok(PREFIX + '/' + dashboard_id)
+        stored_ids = [tile['tile_id'] for tile in document['tiles']]
+        assert len(stored_ids) == 11 and len(set(stored_ids)) == 11 and set(added_ids) <= set(stored_ids)
+        rename = [{'op': 'renameVariable', 'from': 'service', 'to': 'application'}, {'op': 'placeTile', 'tileId': promql_id, 'sectionId': section_id, 'layout': {'x': 0, 'y': 4, 'w': 12, 'h': 4}}]
+        document = tool('update_dashboard', {'dashboardId': dashboard_id, 'revision': document['revision'], 'operations': rename, 'idempotencyKey': 'rename-' + suffix})['dashboard']
+        assert '$application' in document['tiles'][0]['chartQuery'] and '$service' not in document['tiles'][0]['chartQuery']
+        runtime = {'dashboardId': dashboard_id, 'revision': document['revision'], 'tileIds': ids, 'startTime': start.isoformat(), 'endTime': end.isoformat(), 'variables': {'application': 'api'}}
+        deadline = time.monotonic() + 30
+        while True:
+            result = tool('run_dashboard_queries', runtime)
+            successful = all(item['status'] == 'success' for item in result['results'])
+            rows_present = successful and all(item.get('rows') for item in result['results'] if item['tileId'] in [sql_id, builder_id])
+            promql_present = successful and any(item.get('promql', [{}])[0].get('instant', {}).get('result') for item in result['results'] if item['tileId'] == promql_id)
+            if successful and rows_present and promql_present:
+                break
+            assert time.monotonic() < deadline, result
+            time.sleep(.5)
+        assert len(result['results']) == 3
+        assert rows_present and promql_present, result
+        executed = {item['tileId']: item for item in result['results']}
+        assert sum(row['requests'] for row in executed[sql_id]['rows']) == 20, result
+        assert executed[builder_id]['rows'][0]['COUNT_STAR'] == 5, result
+        assert float(executed[promql_id]['promql'][0]['instant']['result'][0]['value'][1]) == 20.0, result
+        assert result['revision'] == document['revision']
+        untouched, _ = ok(PREFIX + '/' + dashboard_id)
+        assert untouched == document, 'Runtime preview mutated configuration'
+        timings.sort()
+        counters['sameRevisionLatencyMsP50'] = round(timings[len(timings)//2], 2)
+        counters['sameRevisionLatencyMsMax'] = round(timings[-1], 2)
+        counters['concurrentRebasedAdditions'] = 8
+        counters['runtimeTiles'] = len(result['results'])
+        counters['dashboardId'] = dashboard_id
+        counters['status'] = 'passed'
+        output = os.environ.get('DASHBOARD_AGENT_REPORT')
+        if output:
+            Path(output).write_text(json.dumps({'checks': counters, 'dashboard': document, 'runtime': result}, indent=2))
+        print(json.dumps(counters))
+    finally:
+        if dashboard_id:
+            status, document, _ = request(PREFIX + '/' + dashboard_id)
+            if status == 200:
+                status, result, _ = request(PREFIX + '/' + dashboard_id, 'DELETE', headers={'If-Match': '"' + document['revision'] + '"'})
+                assert status == 200, ('cleanup-dashboard', status, result)
+        for stream in reversed(created_streams):
+            status, result, _ = request('/api/v1/logstream/' + stream, 'DELETE')
+            assert status in [200, 404], ('cleanup-dataset', status, result)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/src/cli.rs b/src/cli.rs
index bbe0923d0..82f7111ca 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -141,6 +141,10 @@ pub struct Options {
     #[arg(long, env = "P_PASSWORD", help = "Admin password to be set for this Parseable server", default_value = DEFAULT_PASSWORD)]
     pub password: String,
 
+    #[arg(long, env = "P_DASHBOARD_AGENT_WRITES", default_value = "false", action = clap::ArgAction::Set,
+        help = "Allow authenticated dashboard mutation tools through the external tool API; dashboard RBAC and ownership still apply")]
+    pub dashboard_agent_writes: bool,
+
     // Server configuration
     #[arg(
         long,
diff --git a/src/handlers/http/middleware.rs b/src/handlers/http/middleware.rs
index d5418704e..4507a9b8d 100644
--- a/src/handlers/http/middleware.rs
+++ b/src/handlers/http/middleware.rs
@@ -79,12 +79,20 @@ pub struct CommonAttributes {
 }
 
 pub trait RouteExt {
+    /// Authenticate a multiplexed endpoint whose handler authorizes each operation.
+    fn authenticate(self) -> Self;
     fn authorize(self, action: Action) -> Self;
     fn authorize_for_resource(self, action: Action) -> Self;
     fn authorize_for_user(self, action: Action) -> Self;
 }
 
 impl RouteExt for Route {
+    fn authenticate(self) -> Self {
+        self.wrap(Auth {
+            action: Action::Query,
+            method: auth_session_only,
+        })
+    }
     fn authorize(self, action: Action) -> Self {
         self.wrap(Auth {
             action,
@@ -635,6 +643,24 @@ pub fn auth_no_context(req: &mut ServiceRequest, action: Action) -> Result<rbac:
     creds.map(|key| Users.authorize(key, action, None, None))
 }
 
+fn auth_session_only(req: &mut ServiceRequest, _action: Action) -> Result<rbac::Response, Error> {
+    let cached = { req.extensions().get::<SessionKey>().cloned() };
+    let key = match cached {
+        Some(key) => key,
+        None => extract_session_key(req)?,
+    };
+    if !Users.session_exists(&key) {
+        // Basic credentials are verified and lazily registered by authorize.
+        // Its resource decision is intentionally left to the selected tool.
+        let _ = Users.authorize(key.clone(), Action::GetAbout, None, None);
+    }
+    Ok(if Users.session_exists(&key) {
+        rbac::Response::Authorized
+    } else {
+        rbac::Response::ReloadRequired
+    })
+}
+
 pub fn auth_resource_context(
     req: &mut ServiceRequest,
     action: Action,
diff --git a/src/handlers/http/modal/server.rs b/src/handlers/http/modal/server.rs
index c40be0234..b914e57fd 100644
--- a/src/handlers/http/modal/server.rs
+++ b/src/handlers/http/modal/server.rs
@@ -213,6 +213,12 @@ impl ParseableServer for Server {
 impl Server {
     pub fn get_llm_webscope() -> Scope {
         web::scope("/llm")
+            .app_data(web::JsonConfig::default().limit(2 * 1024 * 1024))
+            .app_data(web::Data::new(
+                crate::users::dashboard_tools::DashboardToolPolicy {
+                    writes_enabled: PARSEABLE.options.dashboard_agent_writes,
+                },
+            ))
             .service(
                 web::resource("/tools/list").route(
                     web::get()
@@ -224,7 +230,7 @@ impl Server {
                 web::resource("/tools/call").route(
                     web::post()
                         .to(crate::tool_executor::call_tool_registry)
-                        .authorize(Action::Query),
+                        .authenticate(),
                 ),
             )
     }
@@ -438,6 +444,33 @@ impl Server {
     // get the dashboards web scope
     pub fn get_dashboards_webscope() -> Scope {
         web::scope("/dashboards")
+            .app_data(web::JsonConfig::default().limit(2 * 1024 * 1024))
+            .app_data(web::Data::new(
+                crate::users::dashboard_tools::DashboardToolPolicy {
+                    writes_enabled: PARSEABLE.options.dashboard_agent_writes,
+                },
+            ))
+            .service(
+                web::resource("/preview").route(
+                    web::post()
+                        .to(crate::users::dashboard_runtime::preview)
+                        .authorize(Action::Query),
+                ),
+            )
+            .service(
+                web::resource("/capabilities").route(
+                    web::get()
+                        .to(dashboards::dashboard_capabilities)
+                        .authorize(Action::GetDashboard),
+                ),
+            )
+            .service(
+                web::resource("/validate").route(
+                    web::post()
+                        .to(dashboards::validate_dashboard)
+                        .authorize(Action::CreateDashboard),
+                ),
+            )
             .service(
                 web::resource("")
                     .route(
@@ -476,8 +509,20 @@ impl Server {
                                 web::put()
                                     .to(dashboards::update_dashboard)
                                     .authorize(Action::CreateDashboard),
+                            )
+                            .route(
+                                web::patch()
+                                    .to(dashboards::patch_dashboard)
+                                    .authorize(Action::CreateDashboard),
                             ),
                     )
+                    .service(
+                        web::resource("/validate").route(
+                            web::post()
+                                .to(dashboards::validate_dashboard_changes)
+                                .authorize(Action::CreateDashboard),
+                        ),
+                    )
                     .service(
                         web::resource("/add_tile").route(
                             web::put()
diff --git a/src/handlers/http/promql.rs b/src/handlers/http/promql.rs
index 78a153a7b..66473f8f4 100644
--- a/src/handlers/http/promql.rs
+++ b/src/handlers/http/promql.rs
@@ -26,10 +26,22 @@ use crate::utils::{
 const MAX_RANGE_MS: i64 = 31 * 24 * 60 * 60 * 1000;
 const MAX_QUERY_BYTES: usize = 16 * 1024;
 const MAX_BATCH_BYTES: usize = 64 * 1024 * 1024;
-static REQUEST_SLOTS: Lazy<Arc<Semaphore>> = Lazy::new(|| Arc::new(Semaphore::new(32)));
-static QUERY_SLOTS: Lazy<Arc<Semaphore>> = Lazy::new(|| Arc::new(Semaphore::new(4)));
+const REQUEST_CAPACITY: usize = 32;
+const QUERY_CAPACITY: usize = 4;
+const PREVIEW_REQUEST_CAPACITY: usize = 8;
+const PREVIEW_QUERY_CAPACITY: usize = 2;
+const ALERT_CAPACITY: usize = 2;
+static REQUEST_SLOTS: Lazy<Arc<Semaphore>> =
+    Lazy::new(|| Arc::new(Semaphore::new(REQUEST_CAPACITY)));
+static QUERY_SLOTS: Lazy<Arc<Semaphore>> = Lazy::new(|| Arc::new(Semaphore::new(QUERY_CAPACITY)));
+/// Previews have a separate request queue and may occupy at most two of the
+/// four shared evaluator slots, leaving capacity for interactive queries.
+static PREVIEW_REQUEST_SLOTS: Lazy<Arc<Semaphore>> =
+    Lazy::new(|| Arc::new(Semaphore::new(PREVIEW_REQUEST_CAPACITY)));
+static PREVIEW_QUERY_SLOTS: Lazy<Arc<Semaphore>> =
+    Lazy::new(|| Arc::new(Semaphore::new(PREVIEW_QUERY_CAPACITY)));
 /// Alerts evaluate in their own slots so dashboard load cannot starve them.
-static ALERT_SLOTS: Lazy<Arc<Semaphore>> = Lazy::new(|| Arc::new(Semaphore::new(2)));
+static ALERT_SLOTS: Lazy<Arc<Semaphore>> = Lazy::new(|| Arc::new(Semaphore::new(ALERT_CAPACITY)));
 
 pub fn scope() -> Scope {
     web::scope("/prometheus/api/v1")
@@ -502,6 +514,83 @@ async fn handle(
         .map_err(|_| ApiError::unavailable("timeout", "PromQL query timed out"))?
 }
 
+fn admit_preview(slots: &Arc<Semaphore>) -> Result<tokio::sync::OwnedSemaphorePermit, ApiError> {
+    slots
+        .clone()
+        .try_acquire_owned()
+        .map_err(|_| ApiError::unavailable("unavailable", "PromQL preview request queue is full"))
+}
+
+/// In-process dashboard preview. Shares authorization and bounded evaluation
+/// with the public endpoints, with separate admission and a two-slot budget.
+pub(crate) async fn dashboard_query(
+    req: &HttpRequest,
+    dataset: &str,
+    query: &str,
+    start: i64,
+    end: i64,
+    step: Option<i64>,
+) -> Result<Value, ApiError> {
+    if query.len() > MAX_QUERY_BYTES {
+        return Err(ApiError::bad("query exceeds 16 KiB"));
+    }
+    if start < 0 || end < start || end > 253_402_300_799_000 || end - start > MAX_RANGE_MS {
+        return Err(ApiError::bad("range must be ordered and at most 31d"));
+    }
+    if step.is_some_and(|step| step <= 0 || (end - start) / step + 1 > promql::MAX_STEPS as i64) {
+        return Err(ApiError::bad("invalid step or too many evaluation steps"));
+    }
+    let plan = QueryPlan::parse(query).map_err(|e| match e {
+        promql::PromqlError::Unsupported(_) => ApiError::execution(e.to_string()),
+        _ => ApiError::bad(e.to_string()),
+    })?;
+    if plan.required_history_ms() > MAX_RANGE_MS {
+        return Err(ApiError::bad("selector history exceeds 31d"));
+    }
+    let dataset = dataset_from_request(req, &HashMap::from([("stream".into(), dataset.into())]))?;
+    let _request_permit = admit_preview(&PREVIEW_REQUEST_SLOTS)?;
+    tokio::time::timeout(Duration::from_secs(30), async {
+        let tenant = get_tenant_id_from_request(req);
+        authorize_dataset(req, &dataset, &tenant).await?;
+        let preview_permit = PREVIEW_QUERY_SLOTS
+            .clone()
+            .acquire_owned()
+            .await
+            .map_err(|_| {
+                ApiError::unavailable("unavailable", "PromQL preview service unavailable")
+            })?;
+        execute_query(
+            &QUERY_SLOTS,
+            plan,
+            &dataset,
+            &tenant,
+            start,
+            end,
+            step,
+            move |data| {
+                // The finish closure moves into the blocking evaluator. Keep
+                // this permit there too, so a caller timeout cannot release
+                // preview capacity while its CPU work still occupies a slot.
+                let _preview_permit = preview_permit;
+                let result = data.into_json();
+                if serde_json::to_vec(&result)
+                    .map_err(|e| ApiError::execution(e.to_string()))?
+                    .len()
+                    > 1024 * 1024
+                {
+                    return Err(ApiError::execution(
+                        "preview result exceeds 1 MiB; narrow the query",
+                    ));
+                }
+                Ok(result)
+            },
+        )
+        .await
+    })
+    .await
+    .map_err(|_| ApiError::unavailable("timeout", "PromQL query timed out"))?
+}
+
 /// Shared storage/evaluation worker. Callers authorize the concrete dataset,
 /// bound admission and apply a deadline before entering this service.
 #[allow(clippy::too_many_arguments)]
@@ -1012,6 +1101,47 @@ fn finish_series(grouped: BTreeMap<Labels, Vec<Sample>>) -> Result<Vec<Series>,
 mod tests {
     use super::*;
 
+    #[test]
+    fn saturated_preview_admission_preserves_browser_request_capacity() {
+        // Use private pools so parallel HTTP/evaluator tests retain capacity.
+        let preview = Arc::new(Semaphore::new(PREVIEW_REQUEST_CAPACITY));
+        let browser = Arc::new(Semaphore::new(REQUEST_CAPACITY));
+        let permits = (0..PREVIEW_REQUEST_CAPACITY)
+            .map(|_| admit_preview(&preview).unwrap())
+            .collect::<Vec<_>>();
+        assert_eq!(
+            admit_preview(&preview).unwrap_err().message,
+            "PromQL preview request queue is full"
+        );
+        let browser_permits = browser
+            .try_acquire_many_owned(REQUEST_CAPACITY as u32)
+            .unwrap();
+        drop((browser_permits, permits));
+    }
+
+    #[test]
+    fn preview_evaluation_budget_leaves_interactive_and_alert_capacity() {
+        let preview = Arc::new(Semaphore::new(PREVIEW_QUERY_CAPACITY));
+        let workers = Arc::new(Semaphore::new(QUERY_CAPACITY));
+        let alerts = Arc::new(Semaphore::new(ALERT_CAPACITY));
+        let previews = preview
+            .clone()
+            .try_acquire_many_owned(PREVIEW_QUERY_CAPACITY as u32)
+            .unwrap();
+        assert!(preview.try_acquire_owned().is_err());
+        let preview_workers = workers
+            .clone()
+            .try_acquire_many_owned(PREVIEW_QUERY_CAPACITY as u32)
+            .unwrap();
+        let browser_workers = workers
+            .try_acquire_many_owned((QUERY_CAPACITY - PREVIEW_QUERY_CAPACITY) as u32)
+            .unwrap();
+        let alerts = alerts
+            .try_acquire_many_owned(ALERT_CAPACITY as u32)
+            .unwrap();
+        drop((alerts, browser_workers, preview_workers, previews));
+    }
+
     #[test]
     fn ingestion_window_bounds_scan_by_delay() {
         const MIN: i64 = 60_000;
diff --git a/src/handlers/http/users/dashboards.rs b/src/handlers/http/users/dashboards.rs
index d7addb905..b773fd8e6 100644
--- a/src/handlers/http/users/dashboards.rs
+++ b/src/handlers/http/users/dashboards.rs
@@ -22,249 +22,416 @@ use crate::{
     handlers::http::rbac::RBACError,
     metastore::MetastoreError,
     storage::ObjectStorageError,
-    users::dashboards::{DASHBOARDS, Dashboard, Tile, validate_dashboard_id},
+    users::{
+        dashboard_patch::{self, DashboardPatchRequest},
+        dashboard_service::{self, DashboardActor, DashboardMutation, DashboardWriteOptions},
+        dashboards::{Dashboard, Tile, validate_dashboard_id},
+    },
     utils::{get_hash, get_tenant_id_from_request, get_user_and_tenant_from_request, is_admin},
 };
-use actix_web::http::StatusCode;
 use actix_web::{
     HttpRequest, HttpResponse, Responder,
-    http::header::ContentType,
+    http::{
+        StatusCode,
+        header::{ContentType, ETAG, IF_MATCH},
+    },
     web::{self, Json, Path},
 };
 use serde_json::Error as SerdeError;
-use serde_json::Value;
+use serde_json::{Value, json};
+
+pub fn actor(req: &HttpRequest) -> Result<(DashboardActor, Option<String>), DashboardError> {
+    let (user_id, tenant) = get_user_and_tenant_from_request(req)?;
+    Ok((
+        DashboardActor {
+            user_id: get_hash(&user_id),
+            is_admin: is_admin(req).map_err(|e| DashboardError::Custom(e.to_string()))?,
+        },
+        tenant,
+    ))
+}
 
-pub async fn list_dashboards(req: HttpRequest) -> Result<impl Responder, DashboardError> {
-    let tenant_id = get_tenant_id_from_request(&req);
-    let query_map = web::Query::<HashMap<String, String>>::from_query(req.query_string())
-        .map_err(|_| DashboardError::InvalidQueryParameter)?;
-    let mut dashboard_limit = 0;
-    if !query_map.is_empty() {
-        if let Some(limit) = query_map.get("limit") {
-            if let Ok(parsed_limit) = limit.parse::<usize>() {
-                dashboard_limit = parsed_limit;
-            } else {
-                return Err(DashboardError::Metadata("Invalid limit value"));
-            }
-        }
+pub fn write_options(req: &HttpRequest) -> Result<DashboardWriteOptions, DashboardError> {
+    let header = |name: &str| -> Result<Option<String>, DashboardError> {
+        req.headers()
+            .get(name)
+            .map(|v| {
+                v.to_str().map(str::to_owned).map_err(|_| {
+                    DashboardError::api(
+                        400,
+                        "INVALID_HEADER",
+                        format!("{name} must be UTF-8"),
+                        json!({}),
+                    )
+                })
+            })
+            .transpose()
+    };
+    Ok(DashboardWriteOptions {
+        expected_revision: header(IF_MATCH.as_str())?,
+        idempotency_key: header("idempotency-key")?,
+        dry_run: false,
+    })
+}
 
-        if let Some(tags) = query_map.get("tags") {
-            let tags: Vec<String> = tags
-                .split(',')
-                .map(|s| s.trim().to_string())
-                .filter(|s| !s.is_empty())
-                .collect();
-            if tags.is_empty() {
-                return Err(DashboardError::Metadata("Tags cannot be empty"));
-            }
-            let dashboard_summaries = list_dashboards_internal(0, Some(tags), &tenant_id).await;
-            return Ok((web::Json(dashboard_summaries), StatusCode::OK));
-        }
+fn document_response(document: Value) -> HttpResponse {
+    let revision = document
+        .get("revision")
+        .and_then(Value::as_str)
+        .unwrap_or("");
+    HttpResponse::Ok()
+        .insert_header((ETAG, format!("\"{revision}\"")))
+        .insert_header(("Cache-Control", "private, no-cache"))
+        .json(document)
+}
+
+pub async fn list_dashboards(req: HttpRequest) -> Result<impl Responder, DashboardError> {
+    let query = web::Query::<HashMap<String, String>>::from_query(req.query_string())
+        .map_err(|_| DashboardError::InvalidQueryParameter)?
+        .into_inner();
+    let limit = query
+        .get("limit")
+        .map(|s| s.parse::<usize>())
+        .transpose()
+        .map_err(|_| DashboardError::Metadata("Invalid limit value"))?
+        .unwrap_or(0);
+    let tags: Option<Vec<String>> = query.get("tags").map(|s| {
+        s.split(',')
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .map(str::to_owned)
+            .collect()
+    });
+    if tags.as_ref().is_some_and(Vec::is_empty) {
+        return Err(DashboardError::Metadata("Tags cannot be empty"));
     }
-    let dashboard_summaries = list_dashboards_internal(dashboard_limit, None, &tenant_id).await;
+    // Legacy tag filtering ignores limit. Cursor pagination explicitly opts in
+    // to ID order and applies its limit after the cursor.
+    let tagged = tags.is_some();
+    let rows = list_dashboards_internal(0, tags, &get_tenant_id_from_request(&req)).await?;
+    Ok(web::Json(filter_listing(rows, &query, tagged, limit)))
+}
 
-    Ok((web::Json(dashboard_summaries), StatusCode::OK))
+fn filter_listing(
+    mut rows: Vec<Value>,
+    query: &HashMap<String, String>,
+    tagged: bool,
+    limit: usize,
+) -> Vec<Value> {
+    if let Some(search) = query.get("query") {
+        let search = search.to_lowercase();
+        rows.retain(|d| {
+            d["title"]
+                .as_str()
+                .is_some_and(|s| s.to_lowercase().contains(&search))
+        });
+    }
+    if let Some(after) = query.get("after") {
+        rows.sort_by(|a, b| a["dashboardId"].as_str().cmp(&b["dashboardId"].as_str()));
+        rows.retain(|d| {
+            d["dashboardId"]
+                .as_str()
+                .is_some_and(|id| id > after.as_str())
+        });
+    }
+    if limit > 0 && (!tagged || query.contains_key("after")) {
+        rows.truncate(limit);
+    }
+    rows
 }
 
 pub async fn list_dashboards_internal(
     limit: usize,
     tags: Option<Vec<String>>,
-    tenant_id: &Option<String>,
-) -> Vec<Value> {
-    let dashboards = if let Some(tags) = tags {
-        DASHBOARDS.list_dashboards_by_tags(tags, tenant_id).await
-    } else {
-        DASHBOARDS.list_dashboards(limit, tenant_id).await
-    };
-    dashboards
-        .iter()
-        .map(|dashboard| Value::Object(dashboard.to_summary()))
-        .collect()
+    tenant: &Option<String>,
+) -> Result<Vec<Value>, DashboardError> {
+    let mut rows = dashboard_service::list_json(tenant).await?;
+    if let Some(tags) = tags {
+        rows.retain(|d| {
+            d["tags"].as_array().is_some_and(|values| {
+                values
+                    .iter()
+                    .any(|v| v.as_str().is_some_and(|v| tags.iter().any(|tag| tag == v)))
+            })
+        });
+    }
+    sort_by_modified(&mut rows);
+    if limit > 0 {
+        rows.truncate(limit);
+    }
+    Ok(rows
+        .into_iter()
+        .map(|d| {
+            let keys = [
+                "dashboardId",
+                "title",
+                "description",
+                "dataset",
+                "author",
+                "created",
+                "modified",
+                "tags",
+                "isFavorite",
+                "revision",
+            ];
+            Value::Object(
+                keys.into_iter()
+                    .filter_map(|k| d.get(k).map(|v| (k.to_owned(), v.clone())))
+                    .collect(),
+            )
+        })
+        .collect())
+}
+
+fn sort_by_modified(rows: &mut [Value]) {
+    rows.sort_by_cached_key(|row| {
+        std::cmp::Reverse(
+            row["modified"]
+                .as_str()
+                .and_then(|value| chrono::DateTime::parse_from_rfc3339(value).ok()),
+        )
+    });
+}
+
+#[derive(Clone, Copy)]
+enum LegacyOperation {
+    Get,
+    Update,
+    Delete,
+    AddTile,
+    Create,
+}
+
+// Keep the original REST error contracts at the compatibility boundary. New
+// PATCH/tool APIs continue to expose the structured service errors.
+fn legacy_error(error: DashboardError, operation: LegacyOperation) -> DashboardError {
+    match &error {
+        DashboardError::Api {
+            code: "dashboard_not_found" | "dashboard_forbidden",
+            ..
+        } => match operation {
+            LegacyOperation::Get => DashboardError::Metadata("Dashboard does not exist"),
+            LegacyOperation::Update => {
+                DashboardError::Metadata("Dashboard does not exist or user is not authorized")
+            }
+            LegacyOperation::Delete => DashboardError::Metadata(
+                "Dashboard does not exist or you do not have permission to access it",
+            ),
+            LegacyOperation::AddTile => DashboardError::Unauthorized,
+            LegacyOperation::Create => error,
+        },
+        DashboardError::Api {
+            code: "title_conflict",
+            ..
+        } => DashboardError::Metadata("Dashboard title must be unique"),
+        DashboardError::Api {
+            code: "tile_conflict",
+            ..
+        } => DashboardError::Metadata("Tile already exists"),
+        _ => error,
+    }
 }
 
 pub async fn get_dashboard(
     req: HttpRequest,
-    dashboard_id: Path<String>,
-) -> Result<impl Responder, DashboardError> {
-    let dashboard_id = validate_dashboard_id(dashboard_id.into_inner())?;
-    let tenant_id = get_tenant_id_from_request(&req);
-    let dashboard = get_dashboard_internal(dashboard_id, &tenant_id).await?;
-
-    Ok((web::Json(dashboard), StatusCode::OK))
+    id: Path<String>,
+) -> Result<HttpResponse, DashboardError> {
+    Ok(document_response(
+        dashboard_service::get_json(
+            validate_dashboard_id(id.into_inner())?,
+            &get_tenant_id_from_request(&req),
+        )
+        .await
+        .map_err(|error| legacy_error(error, LegacyOperation::Get))?,
+    ))
 }
 
 pub async fn get_dashboard_internal(
-    dashboard_id: ulid::Ulid,
-    tenant_id: &Option<String>,
+    id: ulid::Ulid,
+    tenant: &Option<String>,
 ) -> Result<Dashboard, DashboardError> {
-    DASHBOARDS
-        .get_dashboard(dashboard_id, tenant_id)
-        .await
-        .ok_or(DashboardError::Metadata("Dashboard does not exist"))
+    Ok(serde_json::from_value(
+        dashboard_service::get_json(id, tenant).await?,
+    )?)
 }
 
 pub async fn create_dashboard(
     req: HttpRequest,
-    Json(mut dashboard): Json<Dashboard>,
-) -> Result<impl Responder, DashboardError> {
-    if dashboard.title.is_empty() {
+    Json(document): Json<Dashboard>,
+) -> Result<HttpResponse, DashboardError> {
+    if document.title.is_empty() {
         return Err(DashboardError::Metadata("Title must be provided"));
     }
-    let (user_id, tenant_id) = get_user_and_tenant_from_request(&req)?;
-    dashboard.tenant_id.clone_from(&tenant_id);
-    let user_id = get_hash(&user_id);
-
-    DASHBOARDS
-        .create(&user_id, &mut dashboard, &tenant_id)
-        .await?;
-    Ok((web::Json(dashboard), StatusCode::OK))
+    let (actor, tenant) = actor(&req)?;
+    let result =
+        dashboard_service::create_legacy_json(&actor, &tenant, document, &write_options(&req)?)
+            .await
+            .map_err(|error| legacy_error(error, LegacyOperation::Create))?;
+    Ok(document_response(result["dashboard"].clone()))
 }
 
 pub async fn update_dashboard(
     req: HttpRequest,
-    dashboard_id: Path<String>,
-    dashboard: Option<Json<Dashboard>>,
-) -> Result<impl Responder, DashboardError> {
-    let (user_id, tenant_id) = get_user_and_tenant_from_request(&req)?;
-    let user_id = get_hash(&user_id);
-    let dashboard_id = validate_dashboard_id(dashboard_id.into_inner())?;
-    let is_admin = is_admin(&req).map_err(|e| DashboardError::Custom(e.to_string()))?;
-    let mut existing_dashboard = DASHBOARDS
-        .get_dashboard_by_user(dashboard_id, &user_id, is_admin, &tenant_id)
-        .await
-        .ok_or(DashboardError::Metadata(
-            "Dashboard does not exist or user is not authorized",
-        ))?;
-
-    let query_map = web::Query::<HashMap<String, String>>::from_query(req.query_string())
-        .map_err(|_| DashboardError::InvalidQueryParameter)?;
-
-    // Validate: either query params OR body, not both
-    let has_query_params = !query_map.is_empty();
-    let has_body_update = dashboard.is_some();
-
-    if has_query_params && has_body_update {
-        return Err(DashboardError::Metadata(
-            "Cannot use both query parameters and request body for updates",
-        ));
-    }
-
-    let mut final_dashboard = if has_query_params {
-        // Apply partial updates from query parameters
-        if let Some(is_favorite) = query_map.get("isFavorite") {
-            existing_dashboard.is_favorite = Some(is_favorite == "true");
+    id: Path<String>,
+    body: Option<Json<Dashboard>>,
+) -> Result<HttpResponse, DashboardError> {
+    let (actor, tenant) = actor(&req)?;
+    let query = web::Query::<HashMap<String, String>>::from_query(req.query_string())
+        .map_err(|_| DashboardError::InvalidQueryParameter)?
+        .into_inner();
+    let mutation = if !query.is_empty() {
+        if body.is_some() {
+            return Err(DashboardError::Metadata(
+                "Cannot use both query parameters and request body for updates",
+            ));
         }
-        if let Some(tags) = query_map.get("tags") {
-            let parsed_tags: Vec<String> = tags
-                .split(',')
-                .map(|s| s.trim())
-                .filter(|s| !s.is_empty())
-                .map(|s| s.to_string())
-                .collect();
-            existing_dashboard.tags = if parsed_tags.is_empty() {
-                None
-            } else {
-                Some(parsed_tags)
-            };
+        let mut query = query;
+        if let Some(rename) = query.get("renameTo")
+            && rename.trim().is_empty()
+        {
+            return Err(DashboardError::Metadata("Rename to cannot be empty"));
         }
-        if let Some(rename_to) = query_map.get("renameTo") {
-            let trimmed = rename_to.trim();
-            if trimmed.is_empty() {
-                return Err(DashboardError::Metadata("Rename to cannot be empty"));
-            }
-            existing_dashboard.title = trimmed.to_string();
+        if let Some(favorite) = query.get_mut("isFavorite") {
+            *favorite = (*favorite == "true").to_string();
         }
-        existing_dashboard
+        query.retain(|key, _| matches!(key.as_str(), "isFavorite" | "tags" | "renameTo"));
+        DashboardMutation::Metadata(query)
     } else {
-        let dashboard = dashboard
+        let document = body
             .ok_or(DashboardError::Metadata("Request body is required"))?
             .into_inner();
-        if let Some(tiles) = &dashboard.tiles {
-            if tiles.iter().any(|tile| tile.tile_id.is_nil()) {
-                return Err(DashboardError::Metadata("Tile ID must be provided"));
-            }
-
-            // Check if tile_id are unique
-            let unique_tiles: Vec<_> = tiles
-                .iter()
-                .map(|tile| tile.tile_id)
-                .collect::<std::collections::HashSet<_>>()
-                .into_iter()
-                .collect();
-
-            if unique_tiles.len() != tiles.len() {
-                return Err(DashboardError::Metadata("Tile IDs must be unique"));
-            }
-        }
-
-        dashboard
+        validate_legacy_tiles(&document)?;
+        DashboardMutation::Replace(serde_json::to_value(document)?)
     };
+    let result = dashboard_service::mutate_legacy_json(
+        &actor,
+        validate_dashboard_id(id.into_inner())?,
+        &tenant,
+        mutation,
+        &write_options(&req)?,
+    )
+    .await
+    .map_err(|error| legacy_error(error, LegacyOperation::Update))?;
+    Ok(document_response(result["dashboard"].clone()))
+}
 
-    DASHBOARDS
-        .update(&user_id, dashboard_id, &mut final_dashboard, &tenant_id)
-        .await?;
+fn validate_legacy_tiles(document: &Dashboard) -> Result<(), DashboardError> {
+    let mut ids = std::collections::HashSet::new();
+    for tile in document.tiles.iter().flatten() {
+        if tile.tile_id.is_nil() {
+            return Err(DashboardError::Metadata("Tile ID must be provided"));
+        }
+        if !ids.insert(tile.tile_id) {
+            return Err(DashboardError::Metadata("Tile IDs must be unique"));
+        }
+    }
+    Ok(())
+}
 
-    Ok((web::Json(final_dashboard), StatusCode::OK))
+pub async fn patch_dashboard(
+    req: HttpRequest,
+    id: Path<String>,
+    Json(patch): Json<DashboardPatchRequest>,
+) -> Result<HttpResponse, DashboardError> {
+    let (actor, tenant) = actor(&req)?;
+    let mut options = write_options(&req)?;
+    options.dry_run = patch.dry_run;
+    if options.expected_revision.is_none() {
+        options.expected_revision = patch.revision;
+    }
+    let result = dashboard_service::mutate_json(
+        &actor,
+        validate_dashboard_id(id.into_inner())?,
+        &tenant,
+        DashboardMutation::Patch(patch.operations),
+        &options,
+    )
+    .await?;
+    let mut response = HttpResponse::Ok();
+    if let Some(rev) = result["revision"].as_str() {
+        response.insert_header((ETAG, format!("\"{rev}\"")));
+    }
+    Ok(response.json(result))
 }
 
-pub async fn delete_dashboard(
+pub async fn validate_dashboard(
     req: HttpRequest,
-    dashboard_id: Path<String>,
+    Json(document): Json<Value>,
 ) -> Result<HttpResponse, DashboardError> {
-    let (user_id, tenant_id) = get_user_and_tenant_from_request(&req)?;
-    let user_id = get_hash(&user_id);
-    let is_admin = is_admin(&req).map_err(|e| DashboardError::Custom(e.to_string()))?;
+    let _ = actor(&req)?;
+    Ok(HttpResponse::Ok().json(dashboard_patch::validate_dashboard(&document, None)))
+}
 
-    let dashboard_id = validate_dashboard_id(dashboard_id.into_inner())?;
+pub async fn validate_dashboard_changes(
+    req: HttpRequest,
+    id: Path<String>,
+    Json(mut patch): Json<DashboardPatchRequest>,
+) -> Result<HttpResponse, DashboardError> {
+    patch.dry_run = true;
+    patch_dashboard(req, id, Json(patch)).await
+}
 
-    DASHBOARDS
-        .delete_dashboard(&user_id, dashboard_id, is_admin, &tenant_id)
-        .await?;
+pub async fn dashboard_capabilities(req: HttpRequest) -> Result<HttpResponse, DashboardError> {
+    let mut result =
+        crate::users::dashboard_tools::execute(&req, "get_dashboard_capabilities", &json!({}))
+            .await?;
+    result["concurrency"] = json!({"revision":"opaque ETag","requireRevisionForPatch":true,"conflictStatus":412,"atomicBatch":true});
+    Ok(HttpResponse::Ok().json(result))
+}
 
+pub async fn delete_dashboard(
+    req: HttpRequest,
+    id: Path<String>,
+) -> Result<HttpResponse, DashboardError> {
+    let (actor, tenant) = actor(&req)?;
+    dashboard_service::delete_json(
+        &actor,
+        validate_dashboard_id(id.into_inner())?,
+        &tenant,
+        &write_options(&req)?,
+    )
+    .await
+    .map_err(|error| legacy_error(error, LegacyOperation::Delete))?;
     Ok(HttpResponse::Ok().finish())
 }
 
 pub async fn add_tile(
     req: HttpRequest,
-    dashboard_id: Path<String>,
+    id: Path<String>,
     Json(tile): Json<Tile>,
-) -> Result<impl Responder, DashboardError> {
+) -> Result<HttpResponse, DashboardError> {
     if tile.tile_id.is_nil() {
         return Err(DashboardError::Metadata("Tile ID must be provided"));
     }
-
-    let (user_id, tenant_id) = get_user_and_tenant_from_request(&req)?;
-    let user_id = get_hash(&user_id);
-    let dashboard_id = validate_dashboard_id(dashboard_id.into_inner())?;
-    let is_admin = is_admin(&req).map_err(|e| DashboardError::Custom(e.to_string()))?;
-
-    let mut dashboard = DASHBOARDS
-        .get_dashboard_by_user(dashboard_id, &user_id, is_admin, &tenant_id)
-        .await
-        .ok_or(DashboardError::Unauthorized)?;
-
-    let tiles = dashboard.tiles.get_or_insert_with(Vec::new);
-
-    // check if the tile already exists
-    if tiles.iter().any(|t| t.tile_id == tile.tile_id) {
-        return Err(DashboardError::Metadata("Tile already exists"));
-    }
-    tiles.push(tile);
-
-    DASHBOARDS
-        .update(&user_id, dashboard_id, &mut dashboard, &tenant_id)
-        .await?;
-
-    Ok((web::Json(dashboard), StatusCode::OK))
+    let (actor, tenant) = actor(&req)?;
+    let result = dashboard_service::mutate_legacy_json(
+        &actor,
+        validate_dashboard_id(id.into_inner())?,
+        &tenant,
+        DashboardMutation::AddTile(serde_json::to_value(tile)?),
+        &write_options(&req)?,
+    )
+    .await
+    .map_err(|error| legacy_error(error, LegacyOperation::AddTile))?;
+    Ok(document_response(result["dashboard"].clone()))
 }
 
 pub async fn list_tags(req: HttpRequest) -> Result<impl Responder, DashboardError> {
-    let tags = list_tags_internal(&get_tenant_id_from_request(&req)).await;
-    Ok((web::Json(tags), StatusCode::OK))
+    Ok(web::Json(
+        list_tags_internal(&get_tenant_id_from_request(&req)).await?,
+    ))
 }
 
-pub async fn list_tags_internal(tenant_id: &Option<String>) -> Vec<String> {
-    DASHBOARDS.list_tags(tenant_id).await
+pub async fn list_tags_internal(tenant: &Option<String>) -> Result<Vec<String>, DashboardError> {
+    let mut tags = dashboard_service::list_json(tenant)
+        .await?
+        .into_iter()
+        .flat_map(|d| d["tags"].as_array().cloned().unwrap_or_default())
+        .filter_map(|v| v.as_str().map(str::to_owned))
+        .collect::<Vec<_>>();
+    tags.sort();
+    tags.dedup();
+    Ok(tags)
 }
 
 #[derive(Debug, thiserror::Error)]
@@ -285,30 +452,276 @@ pub enum DashboardError {
     InvalidQueryParameter,
     #[error(transparent)]
     MetastoreError(#[from] MetastoreError),
+    #[error("{message}")]
+    Api {
+        status: u16,
+        code: &'static str,
+        message: String,
+        details: Value,
+    },
+}
+impl DashboardError {
+    pub fn api(
+        status: u16,
+        code: &'static str,
+        message: impl Into<String>,
+        details: Value,
+    ) -> Self {
+        Self::Api {
+            status,
+            code,
+            message: message.into(),
+            details,
+        }
+    }
+    pub fn detail(&self) -> Value {
+        match self {
+            Self::Api {
+                code,
+                message,
+                details,
+                ..
+            } => json!({"code":code,"message":message,"details":details}),
+            _ => json!({"code":"DASHBOARD_ERROR","message":self.to_string()}),
+        }
+    }
 }
-
 impl actix_web::ResponseError for DashboardError {
     fn status_code(&self) -> StatusCode {
         match self {
-            Self::ObjectStorage(_) => StatusCode::INTERNAL_SERVER_ERROR,
-            Self::Serde(_) => StatusCode::BAD_REQUEST,
-            Self::Metadata(_) => StatusCode::BAD_REQUEST,
+            Self::ObjectStorage(_) | Self::Custom(_) => StatusCode::INTERNAL_SERVER_ERROR,
+            Self::Serde(_) | Self::Metadata(_) | Self::InvalidQueryParameter => {
+                StatusCode::BAD_REQUEST
+            }
             Self::UserDoesNotExist(_) => StatusCode::NOT_FOUND,
-            Self::Custom(_) => StatusCode::INTERNAL_SERVER_ERROR,
             Self::Unauthorized => StatusCode::UNAUTHORIZED,
-            Self::InvalidQueryParameter => StatusCode::BAD_REQUEST,
             Self::MetastoreError(e) => e.status_code(),
+            Self::Api { status, .. } => {
+                StatusCode::from_u16(*status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR)
+            }
         }
     }
-
-    fn error_response(&self) -> actix_web::HttpResponse<actix_web::body::BoxBody> {
+    fn error_response(&self) -> HttpResponse {
         match self {
-            DashboardError::MetastoreError(e) => {
-                actix_web::HttpResponse::build(self.status_code()).json(e.to_detail())
+            Self::Api { .. } => HttpResponse::build(self.status_code())
+                .json(json!({"error":self.detail(),"message":self.to_string()})),
+            Self::MetastoreError(error) => {
+                HttpResponse::build(self.status_code()).json(error.to_detail())
             }
-            _ => actix_web::HttpResponse::build(self.status_code())
+            _ => HttpResponse::build(self.status_code())
                 .insert_header(ContentType::plaintext())
                 .body(self.to_string()),
         }
     }
 }
+
+#[cfg(test)]
+mod compatibility_tests {
+    use super::*;
+    use actix_web::{ResponseError, body::to_bytes};
+
+    #[test]
+    fn listing_preserves_sort_limit_tags_and_opt_in_cursor_contracts() {
+        let mut rows = (0..600)
+            .map(|index| json!({"dashboardId":format!("{index:03}"),"modified":null}))
+            .collect::<Vec<_>>();
+        rows[0]["modified"] = json!("2026-10-19T10:30:00+02:00");
+        rows[1]["modified"] = json!("2026-10-19T09:00:00Z");
+        sort_by_modified(&mut rows);
+        assert_eq!(rows[0]["dashboardId"], "001");
+        assert_eq!(rows[1]["dashboardId"], "000");
+        assert_eq!(
+            filter_listing(rows.clone(), &HashMap::new(), false, 550).len(),
+            550
+        );
+        assert_eq!(
+            filter_listing(rows.clone(), &HashMap::new(), false, 0).len(),
+            600
+        );
+        assert_eq!(
+            filter_listing(rows.clone(), &HashMap::new(), true, 1).len(),
+            600
+        );
+        let cursor = HashMap::from([("after".to_owned(), "002".to_owned())]);
+        let page = filter_listing(rows, &cursor, true, 2);
+        assert_eq!(
+            page.iter()
+                .map(|row| row["dashboardId"].as_str().unwrap())
+                .collect::<Vec<_>>(),
+            vec!["003", "004"]
+        );
+    }
+
+    #[actix_web::test]
+    async fn empty_tags_are_rejected_before_storage_access() {
+        let request = actix_web::test::TestRequest::get()
+            .uri("/dashboards?tags=%20,%20&limit=5")
+            .to_http_request();
+        let error = match list_dashboards(request).await {
+            Err(error) => error,
+            Ok(_) => panic!("empty tags should fail"),
+        };
+        assert_eq!(error.status_code(), StatusCode::BAD_REQUEST);
+        assert_eq!(
+            error.to_string(),
+            "Cannot perform this operation: Tags cannot be empty"
+        );
+    }
+
+    #[actix_web::test]
+    async fn malformed_legacy_typed_requests_keep_extractor_400_errors() {
+        use actix_web::{App, test};
+        let app = test::init_service(
+            App::new()
+                .route("/dashboards", web::post().to(create_dashboard))
+                .route("/dashboards/{id}/tile", web::post().to(add_tile)),
+        )
+        .await;
+        for document in [
+            json!({}),
+            json!({"title":42}),
+            json!({"title":"Typed","tags":[false]}),
+            json!({"title":"Typed","isFavorite":"yes"}),
+            json!({"title":"Typed","dashboardType":"unknown"}),
+            json!({"title":"Typed","created":"yesterday"}),
+            json!({"title":"Typed","tiles":[{"tile_id":"invalid"}]}),
+            json!({"title":"Typed","tiles":[{}]}),
+        ] {
+            let response = test::call_service(
+                &app,
+                test::TestRequest::post()
+                    .uri("/dashboards")
+                    .set_json(document)
+                    .to_request(),
+            )
+            .await;
+            assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+            let body = test::read_body(response).await;
+            assert!(
+                std::str::from_utf8(&body)
+                    .unwrap()
+                    .contains("Json deserialize error")
+            );
+        }
+        for tile in [
+            json!({}),
+            json!({"tile_id":42}),
+            json!({"tile_id":"invalid"}),
+        ] {
+            let response = test::call_service(
+                &app,
+                test::TestRequest::post()
+                    .uri(&format!("/dashboards/{}/tile", ulid::Ulid::new()))
+                    .set_json(tile)
+                    .to_request(),
+            )
+            .await;
+            assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+            let body = test::read_body(response).await;
+            assert!(
+                std::str::from_utf8(&body)
+                    .unwrap()
+                    .contains("Json deserialize error")
+            );
+        }
+    }
+
+    #[actix_web::test]
+    async fn legacy_put_optional_typed_body_keeps_legacy_extraction_semantics() {
+        use actix_web::{App, test};
+        // Match the original PUT's optional extractor: malformed typed input
+        // becomes no body, which the handler reports as a legacy 400.
+        let app = test::init_service(App::new().route(
+            "/typed",
+            web::put().to(|body: Option<Json<Dashboard>>| async move {
+                match body {
+                    Some(body) => HttpResponse::Ok().json(body.into_inner()),
+                    None => DashboardError::Metadata("Request body is required").error_response(),
+                }
+            }),
+        ))
+        .await;
+        let document = json!({"title":"Legacy","tiles":[{"tile_id":ulid::Ulid::new().to_string(),
+            "tileType":"ai","layout":"arbitrary","future":{"keep":true}}]});
+        let response = test::call_service(
+            &app,
+            test::TestRequest::put()
+                .uri("/typed")
+                .set_json(&document)
+                .to_request(),
+        )
+        .await;
+        assert_eq!(response.status(), StatusCode::OK);
+        let decoded: Value = test::read_body_json(response).await;
+        assert_eq!(decoded["tiles"], document["tiles"]);
+        for document in [
+            json!({"title":42}),
+            json!({"title":"Bad","tags":[42]}),
+            json!({"title":"Bad","tiles":[{}]}),
+        ] {
+            let response = test::call_service(
+                &app,
+                test::TestRequest::put()
+                    .uri("/typed")
+                    .set_json(document)
+                    .to_request(),
+            )
+            .await;
+            assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+            assert_eq!(
+                test::read_body(response).await.as_ref(),
+                b"Cannot perform this operation: Request body is required"
+            );
+        }
+    }
+
+    #[actix_web::test]
+    async fn legacy_errors_keep_plaintext_status_and_body() {
+        for (operation, status, message) in [
+            (
+                LegacyOperation::Get,
+                400,
+                "Cannot perform this operation: Dashboard does not exist",
+            ),
+            (
+                LegacyOperation::Update,
+                400,
+                "Cannot perform this operation: Dashboard does not exist or user is not authorized",
+            ),
+            (
+                LegacyOperation::Delete,
+                400,
+                "Cannot perform this operation: Dashboard does not exist or you do not have permission to access it",
+            ),
+            (
+                LegacyOperation::AddTile,
+                401,
+                "Dashboard does not exist or is not accessible",
+            ),
+        ] {
+            let error = legacy_error(
+                DashboardError::api(
+                    404,
+                    "dashboard_not_found",
+                    "Dashboard does not exist",
+                    json!({}),
+                ),
+                operation,
+            );
+            let response = error.error_response();
+            assert_eq!(response.status().as_u16(), status);
+            assert_eq!(
+                response.headers().get("content-type").unwrap(),
+                "text/plain; charset=utf-8"
+            );
+            assert_eq!(
+                to_bytes(response.into_body()).await.unwrap().as_ref(),
+                message.as_bytes()
+            );
+        }
+        assert_eq!(
+            DashboardError::api(412, "revision_conflict", "changed", json!({})).status_code(),
+            StatusCode::PRECONDITION_FAILED
+        );
+    }
+}
diff --git a/src/metastore/metastore_traits.rs b/src/metastore/metastore_traits.rs
index 4bd6c9415..a2fef1f09 100644
--- a/src/metastore/metastore_traits.rs
+++ b/src/metastore/metastore_traits.rs
@@ -39,6 +39,10 @@ use crate::{
     users::filters::Filter,
 };
 
+pub use crate::storage::object_storage::{
+    ConditionalMetadataError, MetadataVersion, MetadataWriteCondition, VersionedMetadata,
+};
+
 /// A metastore is a logically separated compartment to store metadata for Parseable.
 ///
 /// Before this, the object store (be it S3, local store, azure) was being used as a metastore. With this trait, we do not
@@ -158,7 +162,53 @@ pub trait Metastore: std::fmt::Debug + Send + Sync {
         policy: &AlertTargetPolicyConfig,
     ) -> Result<(), MetastoreError>;
     /// dashboards
+    /// The caller constructs this tenant-prefixed path from trusted server fields.
+    async fn get_dashboard_versioned(
+        &self,
+        _path: &str,
+        _tenant_id: &Option<String>,
+    ) -> Result<Option<VersionedMetadata>, ConditionalMetadataError> {
+        Err(ConditionalMetadataError::Unsupported(
+            "versioned dashboard GET".into(),
+        ))
+    }
+    async fn put_dashboard_conditional(
+        &self,
+        _path: &str,
+        _bytes: Bytes,
+        _condition: MetadataWriteCondition,
+        _tenant_id: &Option<String>,
+    ) -> Result<MetadataVersion, ConditionalMetadataError> {
+        Err(ConditionalMetadataError::Unsupported(
+            "conditional dashboard PUT".into(),
+        ))
+    }
+    async fn delete_dashboard_conditional(
+        &self,
+        _path: &str,
+        _version: MetadataVersion,
+        _tenant_id: &Option<String>,
+    ) -> Result<(), ConditionalMetadataError> {
+        Err(ConditionalMetadataError::Unsupported(
+            "conditional dashboard DELETE".into(),
+        ))
+    }
     async fn get_dashboards(&self) -> Result<HashMap<String, Vec<Bytes>>, MetastoreError>;
+    async fn get_tenant_dashboards(
+        &self,
+        tenant_id: &Option<String>,
+    ) -> Result<Vec<Bytes>, MetastoreError> {
+        Ok(self
+            .get_dashboards()
+            .await?
+            .remove(
+                tenant_id
+                    .as_deref()
+                    .unwrap_or(crate::parseable::DEFAULT_TENANT),
+            )
+            .unwrap_or_default())
+    }
+
     async fn put_dashboard(
         &self,
         obj: &dyn MetastoreObject,
diff --git a/src/metastore/metastores/object_store_metastore.rs b/src/metastore/metastores/object_store_metastore.rs
index 3ebcece96..24276f7d3 100644
--- a/src/metastore/metastores/object_store_metastore.rs
+++ b/src/metastore/metastores/object_store_metastore.rs
@@ -27,7 +27,7 @@ use bytes::Bytes;
 use chrono::{DateTime, Utc};
 use dashmap::DashMap;
 use futures::{StreamExt, TryStreamExt};
-use relative_path::RelativePathBuf;
+use relative_path::{RelativePath, RelativePathBuf};
 use tonic::async_trait;
 use tracing::{info, warn};
 use ulid::Ulid;
@@ -48,7 +48,10 @@ use crate::{
     },
     metastore::{
         MetastoreError,
-        metastore_traits::{Metastore, MetastoreObject},
+        metastore_traits::{
+            ConditionalMetadataError, MetadataVersion, MetadataWriteCondition, Metastore,
+            MetastoreObject, VersionedMetadata,
+        },
     },
     option::Mode,
     parseable::{DEFAULT_TENANT, PARSEABLE},
@@ -688,40 +691,84 @@ impl Metastore for ObjectStoreMetastore {
             .await?)
     }
 
-    /// Fetch all dashboards
+    async fn get_dashboard_versioned(
+        &self,
+        path: &str,
+        tenant_id: &Option<String>,
+    ) -> Result<Option<VersionedMetadata>, ConditionalMetadataError> {
+        self.storage
+            .get_metadata_versioned(RelativePath::new(path), tenant_id)
+            .await
+    }
+
+    async fn put_dashboard_conditional(
+        &self,
+        path: &str,
+        bytes: Bytes,
+        condition: MetadataWriteCondition,
+        tenant_id: &Option<String>,
+    ) -> Result<MetadataVersion, ConditionalMetadataError> {
+        self.storage
+            .put_metadata_conditional(RelativePath::new(path), bytes, condition, tenant_id)
+            .await
+    }
+
+    async fn delete_dashboard_conditional(
+        &self,
+        path: &str,
+        version: MetadataVersion,
+        tenant_id: &Option<String>,
+    ) -> Result<(), ConditionalMetadataError> {
+        self.storage
+            .delete_metadata_conditional(RelativePath::new(path), version, tenant_id)
+            .await
+    }
+
+    /// Fetch all dashboards; hidden service indexes are not dashboard owners.
     async fn get_dashboards(&self) -> Result<HashMap<String, Vec<Bytes>>, MetastoreError> {
-        let mut dashboards: HashMap<String, Vec<Bytes>> = HashMap::new();
-        let base_paths = PARSEABLE.list_tenants().unwrap_or_else(|| vec!["".into()]);
-        for tenant in base_paths {
-            let tenant_id = &Some(tenant.clone());
-            let users_dir = RelativePathBuf::from_iter([&tenant, USERS_ROOT_DIR]);
-            for user in self
+        let mut dashboards = HashMap::new();
+        let tenants = PARSEABLE.list_tenants().unwrap_or_else(|| vec!["".into()]);
+        for tenant in tenants {
+            let tenant_id = if tenant.is_empty() {
+                None
+            } else {
+                Some(tenant.clone())
+            };
+            let bytes = self.get_tenant_dashboards(&tenant_id).await?;
+            dashboards.insert(
+                tenant_id.unwrap_or_else(|| DEFAULT_TENANT.to_string()),
+                bytes,
+            );
+        }
+        Ok(dashboards)
+    }
+
+    async fn get_tenant_dashboards(
+        &self,
+        tenant_id: &Option<String>,
+    ) -> Result<Vec<Bytes>, MetastoreError> {
+        let users =
+            RelativePathBuf::from_iter([tenant_id.as_deref().unwrap_or(""), USERS_ROOT_DIR]);
+        let mut dashboards = Vec::new();
+        for owner in self.storage.list_dirs_relative(&users, tenant_id).await? {
+            if owner.starts_with('.') {
+                continue;
+            }
+            let path = users.join(owner).join("dashboards");
+            match self
                 .storage
-                .list_dirs_relative(&users_dir, tenant_id)
-                .await?
+                .get_objects(
+                    Some(&path),
+                    Box::new(|name| name.ends_with(".json")),
+                    tenant_id,
+                )
+                .await
             {
-                let dashboards_path = users_dir.join(&user).join("dashboards");
-                let dashboard_bytes = self
-                    .storage
-                    .get_objects(
-                        Some(&dashboards_path),
-                        Box::new(|file_name| file_name.ends_with(".json")),
-                        tenant_id,
-                    )
-                    .await?;
-
-                let tenant_key = if tenant.is_empty() {
-                    DEFAULT_TENANT.to_string()
-                } else {
-                    tenant.clone()
-                };
-                dashboards
-                    .entry(tenant_key)
-                    .or_default()
-                    .extend(dashboard_bytes);
+                Ok(bytes) => dashboards.extend(bytes),
+                Err(error) if is_missing_optional_dir(&error) => {}
+                Err(error) => return Err(error.into()),
             }
         }
-
         Ok(dashboards)
     }
 
diff --git a/src/storage/azure_blob.rs b/src/storage/azure_blob.rs
index 6c0bc776b..ae3cfa09b 100644
--- a/src/storage/azure_blob.rs
+++ b/src/storage/azure_blob.rs
@@ -678,6 +678,31 @@ impl ObjectStorage for BlobStore {
         Ok(result?)
     }
 
+    async fn get_metadata_versioned(
+        &self,
+        path: &RelativePath,
+        _tenant_id: &Option<String>,
+    ) -> Result<
+        Option<super::object_storage::VersionedMetadata>,
+        super::object_storage::ConditionalMetadataError,
+    > {
+        super::object_storage::get_cloud_metadata(self.client.as_ref(), path).await
+    }
+
+    async fn put_metadata_conditional(
+        &self,
+        path: &RelativePath,
+        bytes: Bytes,
+        condition: super::object_storage::MetadataWriteCondition,
+        _tenant_id: &Option<String>,
+    ) -> Result<
+        super::object_storage::MetadataVersion,
+        super::object_storage::ConditionalMetadataError,
+    > {
+        super::object_storage::put_cloud_metadata(self.client.as_ref(), path, bytes, condition)
+            .await
+    }
+
     async fn get_object(
         &self,
         path: &RelativePath,
diff --git a/src/storage/gcs.rs b/src/storage/gcs.rs
index 8ac87f763..cc4055037 100644
--- a/src/storage/gcs.rs
+++ b/src/storage/gcs.rs
@@ -660,6 +660,31 @@ impl ObjectStorage for Gcs {
         Ok(result?)
     }
 
+    async fn get_metadata_versioned(
+        &self,
+        path: &RelativePath,
+        _tenant_id: &Option<String>,
+    ) -> Result<
+        Option<super::object_storage::VersionedMetadata>,
+        super::object_storage::ConditionalMetadataError,
+    > {
+        super::object_storage::get_cloud_metadata(self.client.as_ref(), path).await
+    }
+
+    async fn put_metadata_conditional(
+        &self,
+        path: &RelativePath,
+        bytes: Bytes,
+        condition: super::object_storage::MetadataWriteCondition,
+        _tenant_id: &Option<String>,
+    ) -> Result<
+        super::object_storage::MetadataVersion,
+        super::object_storage::ConditionalMetadataError,
+    > {
+        super::object_storage::put_cloud_metadata(self.client.as_ref(), path, bytes, condition)
+            .await
+    }
+
     async fn get_object(
         &self,
         path: &RelativePath,
diff --git a/src/storage/localfs.rs b/src/storage/localfs.rs
index d66714023..357aea800 100644
--- a/src/storage/localfs.rs
+++ b/src/storage/localfs.rs
@@ -46,6 +46,10 @@ use crate::{
     storage::SETTINGS_ROOT_DIRECTORY,
 };
 
+use super::object_storage::{
+    ConditionalMetadataError, MetadataVersion, MetadataWriteCondition, VersionedMetadata,
+};
+
 use super::{
     ALERTS_ROOT_DIRECTORY, ObjectStorage, ObjectStorageError, ObjectStorageProvider,
     PARSEABLE_ROOT_DIRECTORY, STREAM_METADATA_FILE_NAME, STREAM_ROOT_DIRECTORY,
@@ -89,6 +93,20 @@ impl ObjectStorageProvider for FSConfig {
     }
 }
 
+const METADATA_LOCK_DIRECTORY: &str = ".parseable-metadata-locks";
+
+fn is_dashboard_metadata(path: &RelativePath) -> bool {
+    let normalized = path.normalize();
+    let parts = normalized.as_str().split('/').collect::<Vec<_>>();
+    let Some(users) = parts.iter().position(|part| *part == USERS_ROOT_DIR) else {
+        return false;
+    };
+    matches!(
+        parts.get(users + 1),
+        Some(&".dashboard-locations" | &".dashboard-titles")
+    ) || parts.get(users + 2) == Some(&"dashboards")
+}
+
 #[derive(Debug)]
 pub struct LocalFS {
     // absolute path of the data directory
@@ -103,6 +121,94 @@ impl LocalFS {
     pub fn path_in_root(&self, path: &RelativePath) -> PathBuf {
         path.to_path(&self.root)
     }
+
+    fn checked_metadata_path(&self, path: &RelativePath) -> Result<PathBuf, ObjectStorageError> {
+        if path.as_str().starts_with('/')
+            || path
+                .components()
+                .any(|part| matches!(part, relative_path::Component::ParentDir))
+        {
+            return Err(ObjectStorageError::PathTraversal {
+                attempted: self.path_in_root(path),
+                root: self.root.clone(),
+            });
+        }
+        Ok(self.path_in_root(path))
+    }
+
+    pub(crate) fn metadata_lock_path(&self, path: &RelativePath) -> PathBuf {
+        use sha2::{Digest, Sha256};
+        let normalized = path.normalize();
+        self.root.join(METADATA_LOCK_DIRECTORY).join(format!(
+            "{}.lock",
+            hex::encode(Sha256::digest(normalized.as_str().as_bytes()))
+        ))
+    }
+
+    /// Stable private lock files coordinate independent instances/processes.
+    /// Never unlink them: replacing a lock inode permits two writers.
+    async fn metadata_with_lock<T: Send + 'static>(
+        &self,
+        path: &RelativePath,
+        operation: impl FnOnce(&Path, &mut std::fs::File) -> Result<T, ConditionalMetadataError>
+        + Send
+        + 'static,
+    ) -> Result<T, ConditionalMetadataError> {
+        self.metadata_with_lock_mode(path, true, move |path, lock| {
+            operation(path, lock.expect("exclusive metadata lock"))
+        })
+        .await
+    }
+
+    async fn metadata_with_lock_mode<T: Send + 'static>(
+        &self,
+        path: &RelativePath,
+        exclusive: bool,
+        operation: impl FnOnce(&Path, Option<&mut std::fs::File>) -> Result<T, ConditionalMetadataError>
+        + Send
+        + 'static,
+    ) -> Result<T, ConditionalMetadataError> {
+        let lock_path = self.metadata_lock_path(path);
+        let path = self.checked_metadata_path(path)?;
+        tokio::task::spawn_blocking(move || {
+            let parent = path
+                .parent()
+                .ok_or_else(|| ObjectStorageError::Custom("metadata path has no parent".into()))?;
+            if exclusive {
+                std::fs::create_dir_all(parent).map_err(ObjectStorageError::from)?;
+                std::fs::create_dir_all(lock_path.parent().expect("private lock directory"))
+                    .map_err(ObjectStorageError::from)?;
+            }
+            let mut options = std::fs::OpenOptions::new();
+            options.read(true);
+            if exclusive {
+                options.create(true).truncate(false).write(true);
+            }
+            let mut lock = match options.open(&lock_path) {
+                Ok(lock) => lock,
+                Err(error) if !exclusive && error.kind() == std::io::ErrorKind::NotFound => {
+                    return operation(&path, None);
+                }
+                Err(error) => return Err(ObjectStorageError::from(error).into()),
+            };
+            if exclusive {
+                lock.lock().map_err(ObjectStorageError::from)?;
+                if read_metadata_generation(&mut lock)? == [0; 16] {
+                    // Persist both entries BEFORE the first nonzero generation.
+                    // Another opener may have created them without syncing. A
+                    // valid nonzero generation proves this initialization ran.
+                    sync_metadata_parent(&lock_path)?;
+                    sync_metadata_parent(lock_path.parent().expect("private lock directory"))?;
+                }
+            } else {
+                lock.lock_shared().map_err(ObjectStorageError::from)?;
+            }
+            // The lock is released even if operation returns an error or panics.
+            operation(&path, Some(&mut lock))
+        })
+        .await
+        .map_err(ObjectStorageError::from)?
+    }
 }
 
 #[async_trait]
@@ -186,6 +292,69 @@ impl ObjectStorage for LocalFS {
         }
     }
 
+    async fn get_metadata_versioned(
+        &self,
+        path: &RelativePath,
+        _tenant_id: &Option<String>,
+    ) -> Result<Option<VersionedMetadata>, ConditionalMetadataError> {
+        // Reads never create locks. Without one, pin generation zero before
+        // reading content: a concurrent first writer durably rotates away from
+        // zero before mutation, so this read can only cause a false conflict.
+        self.metadata_with_lock_mode(path, false, read_local_metadata)
+            .await
+    }
+
+    async fn put_metadata_conditional(
+        &self,
+        path: &RelativePath,
+        bytes: Bytes,
+        condition: MetadataWriteCondition,
+        _tenant_id: &Option<String>,
+    ) -> Result<MetadataVersion, ConditionalMetadataError> {
+        self.metadata_with_lock(path, move |path, lock| {
+            let current = read_local_metadata(path, Some(lock))?;
+            match condition {
+                MetadataWriteCondition::Create if current.is_some() => {
+                    return Err(ConditionalMetadataError::Conflict);
+                }
+                MetadataWriteCondition::Update(expected)
+                    if current.as_ref().map(|entry| &entry.version) != Some(&expected) =>
+                {
+                    return Err(ConditionalMetadataError::Conflict);
+                }
+                _ => {}
+            }
+            rotate_metadata_generation(lock)?;
+            atomic_metadata_write(path, &bytes)?;
+            Ok(read_local_metadata(path, Some(lock))?
+                .expect("just wrote metadata under exclusive lock")
+                .version)
+        })
+        .await
+    }
+
+    async fn delete_metadata_conditional(
+        &self,
+        path: &RelativePath,
+        version: MetadataVersion,
+        _tenant_id: &Option<String>,
+    ) -> Result<(), ConditionalMetadataError> {
+        self.metadata_with_lock(path, move |path, lock| {
+            if read_local_metadata(path, Some(lock))?
+                .as_ref()
+                .map(|entry| &entry.version)
+                != Some(&version)
+            {
+                return Err(ConditionalMetadataError::Conflict);
+            }
+            rotate_metadata_generation(lock)?;
+            std::fs::remove_file(path).map_err(ObjectStorageError::from)?;
+            sync_metadata_parent(path)?;
+            Ok(())
+        })
+        .await
+    }
+
     async fn get_object(
         &self,
         path: &RelativePath,
@@ -389,13 +558,24 @@ impl ObjectStorage for LocalFS {
         resource: Bytes,
         tenant_id: &Option<String>,
     ) -> Result<(), ObjectStorageError> {
-        let path = self.path_in_root(path);
         let tenant_str = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-        if let Some(parent) = path.parent() {
-            fs::create_dir_all(parent).await?;
-        }
-
-        let res = fs::write(path, resource).await;
+        let res = if is_dashboard_metadata(path) {
+            self.metadata_with_lock(path, move |path, lock| {
+                rotate_metadata_generation(lock)?;
+                atomic_metadata_write(path, &resource)?;
+                Ok(())
+            })
+            .await
+            .map_err(local_metadata_error)
+        } else {
+            let path = self.path_in_root(path);
+            if let Some(parent) = path.parent() {
+                fs::create_dir_all(parent).await?;
+            }
+            fs::write(path, resource)
+                .await
+                .map_err(ObjectStorageError::from)
+        };
         if res.is_ok() {
             // Record single file written successfully
             increment_files_scanned_in_object_store_calls_by_date(
@@ -411,7 +591,7 @@ impl ObjectStorage for LocalFS {
             );
         }
 
-        res.map_err(Into::into)
+        res
     }
 
     async fn delete_prefix(
@@ -449,10 +629,21 @@ impl ObjectStorage for LocalFS {
             });
         }
 
-        let path = self.path_in_root(path);
         let tenant_str = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-
-        let result = tokio::fs::remove_file(path).await;
+        let result = if is_dashboard_metadata(path) {
+            self.metadata_with_lock(path, |path, lock| {
+                rotate_metadata_generation(lock)?;
+                std::fs::remove_file(path).map_err(ObjectStorageError::from)?;
+                sync_metadata_parent(path)?;
+                Ok(())
+            })
+            .await
+            .map_err(local_metadata_error)
+        } else {
+            tokio::fs::remove_file(self.path_in_root(path))
+                .await
+                .map_err(ObjectStorageError::from)
+        };
         if result.is_ok() {
             // Record single file deleted successfully
             increment_files_scanned_in_object_store_calls_by_date(
@@ -528,6 +719,7 @@ impl ObjectStorage for LocalFS {
 
     async fn list_streams(&self) -> Result<HashSet<LogStream>, ObjectStorageError> {
         let ignore_dir = &[
+            METADATA_LOCK_DIRECTORY,
             "lost+found",
             DEFAULT_TENANT,
             PARSEABLE_ROOT_DIRECTORY,
@@ -567,6 +759,7 @@ impl ObjectStorage for LocalFS {
 
     async fn list_old_streams(&self) -> Result<HashSet<LogStream>, ObjectStorageError> {
         let ignore_dir = &[
+            METADATA_LOCK_DIRECTORY,
             "lost+found",
             DEFAULT_TENANT,
             PARSEABLE_ROOT_DIRECTORY,
@@ -897,6 +1090,9 @@ async fn dir_with_stream(
 }
 
 async fn dir_name(entry: DirEntry) -> Result<Option<String>, ObjectStorageError> {
+    if entry.file_name() == METADATA_LOCK_DIRECTORY {
+        return Ok(None);
+    }
     if entry.file_type().await?.is_dir() {
         let dir_name = entry
             .path()
@@ -916,3 +1112,868 @@ impl From<fs_extra::error::Error> for ObjectStorageError {
         ObjectStorageError::UnhandledError(Box::new(e))
     }
 }
+
+fn local_metadata_error(error: ConditionalMetadataError) -> ObjectStorageError {
+    match error {
+        ConditionalMetadataError::Storage(error) => error,
+        error => ObjectStorageError::Custom(error.to_string()),
+    }
+}
+
+// A fixed-size, checksummed record detects partial/torn generation writes. An
+// empty lock is the pre-generation format; all nonempty invalid records fail
+// closed. In particular, never repair corruption by reviving an older version.
+const METADATA_GENERATION_MAGIC: &[u8; 8] = b"PFSVER1\n";
+const METADATA_GENERATION_RECORD_LEN: usize = 8 + 16 + 32;
+
+fn read_metadata_generation(lock: &mut std::fs::File) -> Result<[u8; 16], ObjectStorageError> {
+    use sha2::{Digest, Sha256};
+    use std::io::{Read, Seek, SeekFrom};
+    lock.seek(SeekFrom::Start(0))?;
+    let mut record = Vec::new();
+    lock.take((METADATA_GENERATION_RECORD_LEN + 1) as u64)
+        .read_to_end(&mut record)?;
+    if record.is_empty() {
+        return Ok([0; 16]);
+    }
+    if record.len() != METADATA_GENERATION_RECORD_LEN
+        || &record[..8] != METADATA_GENERATION_MAGIC
+        || Sha256::digest(&record[..24])[..] != record[24..]
+    {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            "invalid LocalFS metadata generation record",
+        )
+        .into());
+    }
+    Ok(record[8..24].try_into().expect("checked generation length"))
+}
+
+fn rotate_metadata_generation(lock: &mut std::fs::File) -> Result<(), ObjectStorageError> {
+    use sha2::{Digest, Sha256};
+    use std::io::{Seek, SeekFrom, Write};
+    // Validate before overwriting, including for unconditional legacy writers.
+    read_metadata_generation(lock)?;
+    let mut record = Vec::with_capacity(METADATA_GENERATION_RECORD_LEN);
+    record.extend_from_slice(METADATA_GENERATION_MAGIC);
+    record.extend_from_slice(uuid::Uuid::new_v4().as_bytes());
+    record.extend_from_slice(&Sha256::digest(&record));
+    lock.seek(SeekFrom::Start(0))?;
+    // Never truncate: a crash must not turn an existing generation back into
+    // the empty legacy format. A partial write fails its checksum on next use.
+    lock.write_all(&record)?;
+    // Persist BEFORE touching the object. A crash in between only causes a
+    // false conflict, never acceptance of a stale precondition.
+    lock.sync_all()?;
+    Ok(())
+}
+
+fn read_local_metadata(
+    path: &Path,
+    lock: Option<&mut std::fs::File>,
+) -> Result<Option<VersionedMetadata>, ConditionalMetadataError> {
+    use sha2::{Digest, Sha256};
+    use std::io::Read;
+    let generation = match lock {
+        Some(lock) => read_metadata_generation(lock)?,
+        None => [0; 16],
+    };
+    let mut file = match std::fs::File::open(path) {
+        Ok(file) => file,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(error) => return Err(ObjectStorageError::from(error).into()),
+    };
+    let metadata = file.metadata().map_err(ObjectStorageError::from)?;
+    let mut bytes = Vec::new();
+    file.read_to_end(&mut bytes)
+        .map_err(ObjectStorageError::from)?;
+    // The durable generation prevents ABA even when bytes, inode and timestamps
+    // all repeat. With an existing lock the caller holds it across both reads;
+    // without one, generation zero cannot match a concurrent first mutation.
+    let mut digest = Sha256::new();
+    digest.update(generation);
+    digest.update(&bytes);
+    digest.update(format!("{:?}{:?}", metadata.modified(), metadata.created()).as_bytes());
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt;
+        digest.update(metadata.dev().to_le_bytes());
+        digest.update(metadata.ino().to_le_bytes());
+        digest.update(metadata.ctime().to_le_bytes());
+        digest.update(metadata.ctime_nsec().to_le_bytes());
+    }
+    Ok(Some(VersionedMetadata {
+        bytes: bytes.into(),
+        version: MetadataVersion {
+            e_tag: Some(hex::encode(digest.finalize())),
+            version: None,
+        },
+    }))
+}
+
+fn sync_metadata_parent(path: &Path) -> Result<(), ObjectStorageError> {
+    #[cfg(unix)]
+    std::fs::File::open(path.parent().expect("metadata parent"))?.sync_all()?;
+    Ok(())
+}
+
+fn atomic_metadata_write(path: &Path, bytes: &[u8]) -> Result<(), ObjectStorageError> {
+    use std::io::Write;
+    let parent = path
+        .parent()
+        .ok_or_else(|| ObjectStorageError::Custom("metadata path has no parent".into()))?;
+    let temporary = parent.join(format!(".metadata-{}.tmp", ulid::Ulid::new()));
+    let result = (|| {
+        let mut file = std::fs::OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&temporary)?;
+        file.write_all(bytes)?;
+        file.sync_all()?;
+        std::fs::rename(&temporary, path)?;
+        sync_metadata_parent(path)?;
+        Ok(())
+    })();
+    if result.is_err() {
+        let _ = std::fs::remove_file(&temporary);
+    }
+    result
+}
+
+#[cfg(test)]
+mod conditional_metadata_tests {
+    use super::*;
+    use crate::metastore::{
+        metastore_traits::Metastore, metastores::object_store_metastore::ObjectStoreMetastore,
+    };
+
+    fn service(root: &Path) -> Arc<ObjectStoreMetastore> {
+        Arc::new(ObjectStoreMetastore {
+            storage: Arc::new(LocalFS::new(root.to_path_buf())),
+        })
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn independent_metastores_have_one_winner_for_create_and_update() {
+        let directory = tempfile::tempdir().unwrap();
+        let first = service(directory.path());
+        let second = service(directory.path());
+        let path = "tenant-a/users/owner/dashboards/shared.json";
+        let tenant = Some("tenant-a".to_string());
+        let (a, b) = tokio::join!(
+            first.put_dashboard_conditional(
+                path,
+                Bytes::from_static(b"original"),
+                MetadataWriteCondition::Create,
+                &tenant
+            ),
+            second.put_dashboard_conditional(
+                path,
+                Bytes::from_static(b"original"),
+                MetadataWriteCondition::Create,
+                &tenant
+            ),
+        );
+        assert_eq!(usize::from(a.is_ok()) + usize::from(b.is_ok()), 1);
+        assert!(matches!(
+            if a.is_err() { a } else { b },
+            Err(ConditionalMetadataError::Conflict)
+        ));
+        let original = first
+            .get_dashboard_versioned(path, &tenant)
+            .await
+            .unwrap()
+            .unwrap();
+        let barrier = Arc::new(tokio::sync::Barrier::new(24));
+        let mut writes = tokio::task::JoinSet::new();
+        for index in 0..24 {
+            let current = if index % 2 == 0 {
+                first.clone()
+            } else {
+                second.clone()
+            };
+            let version = original.version.clone();
+            let barrier = barrier.clone();
+            let tenant = tenant.clone();
+            writes.spawn(async move {
+                barrier.wait().await;
+                current
+                    .put_dashboard_conditional(
+                        path,
+                        Bytes::from(format!("winner-{index}")),
+                        MetadataWriteCondition::Update(version),
+                        &tenant,
+                    )
+                    .await
+            });
+        }
+        let mut winners = 0;
+        while let Some(result) = writes.join_next().await {
+            match result.unwrap() {
+                Ok(_) => winners += 1,
+                Err(ConditionalMetadataError::Conflict) => {}
+                Err(error) => panic!("unexpected storage error: {error}"),
+            }
+        }
+        assert_eq!(winners, 1);
+        let stored = second
+            .get_dashboard_versioned(path, &tenant)
+            .await
+            .unwrap()
+            .unwrap();
+        assert!(stored.bytes.starts_with(b"winner-"));
+        assert_ne!(stored.version, original.version);
+        assert!(
+            first
+                .get_dashboard_versioned(
+                    "tenant-b/users/owner/dashboards/shared.json",
+                    &Some("tenant-b".into())
+                )
+                .await
+                .unwrap()
+                .is_none()
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn unrelated_dashboard_does_not_wait_for_held_object_lock() {
+        let directory = tempfile::tempdir().unwrap();
+        let first = Arc::new(LocalFS::new(directory.path().to_path_buf()));
+        let second = LocalFS::new(directory.path().to_path_buf());
+        let (ready_tx, ready_rx) = tokio::sync::oneshot::channel();
+        let (release_tx, release_rx) = std::sync::mpsc::channel();
+        let held = tokio::spawn(async move {
+            first
+                .metadata_with_lock(RelativePath::new("a.json"), move |_, _| {
+                    ready_tx.send(()).unwrap();
+                    release_rx.recv().unwrap();
+                    Ok(())
+                })
+                .await
+        });
+        ready_rx.await.unwrap();
+        let independent = tokio::time::timeout(
+            std::time::Duration::from_secs(2),
+            second.put_metadata_conditional(
+                RelativePath::new("b.json"),
+                Bytes::from_static(b"different dashboard"),
+                MetadataWriteCondition::Create,
+                &None,
+            ),
+        )
+        .await;
+        release_tx.send(()).unwrap();
+        held.await.unwrap().unwrap();
+        independent
+            .expect("another dashboard was blocked by a global lock")
+            .unwrap();
+    }
+
+    #[tokio::test]
+    async fn stale_delete_and_recreated_identical_content_do_not_reuse_version() {
+        let directory = tempfile::tempdir().unwrap();
+        let first = LocalFS::new(directory.path().to_path_buf());
+        let second = LocalFS::new(directory.path().to_path_buf());
+        let path = RelativePath::new(".users/owner/dashboards/dashboard.json");
+        let bytes = Bytes::from_static(b"same content");
+        let original = first
+            .put_metadata_conditional(path, bytes.clone(), MetadataWriteCondition::Create, &None)
+            .await
+            .unwrap();
+        // Legacy writes share the same lock and atomically replace the file.
+        second
+            .put_object(path, Bytes::from_static(b"legacy update"), &None)
+            .await
+            .unwrap();
+        assert!(matches!(
+            first
+                .delete_metadata_conditional(path, original.clone(), &None)
+                .await,
+            Err(ConditionalMetadataError::Conflict)
+        ));
+        second.delete_object(path, &None).await.unwrap();
+        let recreated = second
+            .put_metadata_conditional(path, bytes, MetadataWriteCondition::Create, &None)
+            .await
+            .unwrap();
+        assert_ne!(original, recreated);
+        assert!(matches!(
+            first
+                .put_metadata_conditional(
+                    path,
+                    Bytes::from_static(b"stale"),
+                    MetadataWriteCondition::Update(original),
+                    &None
+                )
+                .await,
+            Err(ConditionalMetadataError::Conflict)
+        ));
+        second
+            .delete_metadata_conditional(path, recreated, &None)
+            .await
+            .unwrap();
+        assert!(
+            first
+                .get_metadata_versioned(path, &None)
+                .await
+                .unwrap()
+                .is_none()
+        );
+    }
+
+    #[tokio::test]
+    async fn tight_identical_recreates_always_reject_stale_update_and_delete() {
+        let directory = tempfile::tempdir().unwrap();
+        let first = LocalFS::new(directory.path().to_path_buf());
+        let second = LocalFS::new(directory.path().to_path_buf());
+        let path = RelativePath::new(".users/owner/dashboards/tight.json");
+        let bytes = Bytes::from_static(b"identical");
+        let mut versions = HashSet::new();
+        for _ in 0..200 {
+            let old = first
+                .put_metadata_conditional(
+                    path,
+                    bytes.clone(),
+                    MetadataWriteCondition::Create,
+                    &None,
+                )
+                .await
+                .unwrap();
+            assert!(versions.insert(old.e_tag.clone()));
+            first
+                .delete_metadata_conditional(path, old.clone(), &None)
+                .await
+                .unwrap();
+            let new = second
+                .put_metadata_conditional(
+                    path,
+                    bytes.clone(),
+                    MetadataWriteCondition::Create,
+                    &None,
+                )
+                .await
+                .unwrap();
+            assert_ne!(old, new);
+            assert!(versions.insert(new.e_tag.clone()));
+            for _ in 0..2 {
+                let read = first
+                    .get_metadata_versioned(path, &None)
+                    .await
+                    .unwrap()
+                    .unwrap();
+                assert_eq!(read.bytes, bytes);
+                assert_eq!(read.version, new);
+            }
+            assert!(matches!(
+                first
+                    .put_metadata_conditional(
+                        path,
+                        bytes.clone(),
+                        MetadataWriteCondition::Update(old.clone()),
+                        &None
+                    )
+                    .await,
+                Err(ConditionalMetadataError::Conflict)
+            ));
+            assert!(matches!(
+                first.delete_metadata_conditional(path, old, &None).await,
+                Err(ConditionalMetadataError::Conflict)
+            ));
+            second
+                .delete_metadata_conditional(path, new, &None)
+                .await
+                .unwrap();
+        }
+    }
+
+    #[tokio::test]
+    async fn legacy_identical_writes_and_deletes_rotate_generation_without_replacing_lock() {
+        let directory = tempfile::tempdir().unwrap();
+        let storage = LocalFS::new(directory.path().to_path_buf());
+        let path = RelativePath::new(".users/owner/dashboards/legacy.json");
+        let bytes = Bytes::from_static(b"identical");
+        storage
+            .put_object(path, bytes.clone(), &None)
+            .await
+            .unwrap();
+        let lock_path = storage.metadata_lock_path(path);
+        let mut original_lock = std::fs::OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(&lock_path)
+            .unwrap();
+        let old_generation = read_metadata_generation(&mut original_lock).unwrap();
+        let old = storage
+            .get_metadata_versioned(path, &None)
+            .await
+            .unwrap()
+            .unwrap();
+        storage
+            .put_object(path, bytes.clone(), &None)
+            .await
+            .unwrap();
+        assert_ne!(
+            old_generation,
+            read_metadata_generation(&mut original_lock).unwrap()
+        );
+        let updated = storage
+            .get_metadata_versioned(path, &None)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_ne!(old.version, updated.version);
+        storage.delete_object(path, &None).await.unwrap();
+        let deleted_generation = read_metadata_generation(&mut original_lock).unwrap();
+        storage.put_object(path, bytes, &None).await.unwrap();
+        assert_ne!(
+            deleted_generation,
+            read_metadata_generation(&mut original_lock).unwrap()
+        );
+        assert!(matches!(
+            storage
+                .delete_metadata_conditional(path, updated.version, &None)
+                .await,
+            Err(ConditionalMetadataError::Conflict)
+        ));
+    }
+
+    #[tokio::test]
+    async fn reading_unknown_ids_and_titles_creates_no_files_or_directories() {
+        let directory = tempfile::tempdir().unwrap();
+        let paths = [
+            ".users/.dashboard-locations/01ARZ3NDEKTSV4RRFFQ69G5FAV.json",
+            ".users/.dashboard-titles/unknown-title.json",
+            ".users/owner/dashboards/01ARZ3NDEKTSV4RRFFQ69G5FAV.json",
+        ];
+        let root = directory.path().join("absent-root");
+        let storage = LocalFS::new(root.clone());
+        for path in paths {
+            assert!(
+                storage
+                    .get_metadata_versioned(RelativePath::new(path), &None)
+                    .await
+                    .unwrap()
+                    .is_none()
+            );
+        }
+        assert!(!root.exists());
+        std::fs::create_dir(&root).unwrap();
+        for path in paths {
+            assert!(
+                storage
+                    .get_metadata_versioned(RelativePath::new(path), &None)
+                    .await
+                    .unwrap()
+                    .is_none()
+            );
+        }
+        assert_eq!(std::fs::read_dir(&root).unwrap().count(), 0);
+        let locks = root.join(METADATA_LOCK_DIRECTORY);
+        std::fs::create_dir(&locks).unwrap();
+        for path in paths {
+            assert!(
+                storage
+                    .get_metadata_versioned(RelativePath::new(path), &None)
+                    .await
+                    .unwrap()
+                    .is_none()
+            );
+        }
+        assert_eq!(std::fs::read_dir(&root).unwrap().count(), 1);
+        assert_eq!(std::fs::read_dir(&locks).unwrap().count(), 0);
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn preexisting_readonly_metadata_and_locks_have_stable_versions() {
+        use std::os::unix::fs::PermissionsExt;
+        let directory = tempfile::tempdir().unwrap();
+        let storage = LocalFS::new(directory.path().to_path_buf());
+        let path = RelativePath::new(".users/owner/dashboards/readonly.json");
+        let object_path = storage.path_in_root(path);
+        std::fs::create_dir_all(object_path.parent().unwrap()).unwrap();
+        std::fs::write(&object_path, b"existing").unwrap();
+        std::fs::set_permissions(&object_path, std::fs::Permissions::from_mode(0o444)).unwrap();
+        let lock_path = storage.metadata_lock_path(path);
+        // Exercise no lock, an empty legacy lock, and a durable generation.
+        for format in 0..3 {
+            if format != 0 {
+                std::fs::create_dir_all(lock_path.parent().unwrap()).unwrap();
+                let mut lock = std::fs::OpenOptions::new()
+                    .create(true)
+                    .truncate(false)
+                    .read(true)
+                    .write(true)
+                    .open(&lock_path)
+                    .unwrap();
+                if format == 2 {
+                    rotate_metadata_generation(&mut lock).unwrap();
+                }
+                std::fs::set_permissions(&lock_path, std::fs::Permissions::from_mode(0o444))
+                    .unwrap();
+                std::fs::set_permissions(
+                    lock_path.parent().unwrap(),
+                    std::fs::Permissions::from_mode(0o555),
+                )
+                .unwrap();
+            }
+            std::fs::set_permissions(directory.path(), std::fs::Permissions::from_mode(0o555))
+                .unwrap();
+            let first = storage.get_metadata_versioned(path, &None).await;
+            let second = storage.get_metadata_versioned(path, &None).await;
+            // Restore directory permissions before assertions/TempDir cleanup.
+            std::fs::set_permissions(directory.path(), std::fs::Permissions::from_mode(0o755))
+                .unwrap();
+            if format != 0 {
+                std::fs::set_permissions(
+                    lock_path.parent().unwrap(),
+                    std::fs::Permissions::from_mode(0o755),
+                )
+                .unwrap();
+                std::fs::set_permissions(&lock_path, std::fs::Permissions::from_mode(0o644))
+                    .unwrap();
+            }
+            let first = first.unwrap().unwrap();
+            let second = second.unwrap().unwrap();
+            assert_eq!(first.bytes, b"existing"[..]);
+            assert_eq!(first.version, second.version);
+            assert_eq!(lock_path.exists(), format != 0);
+        }
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn read_without_lock_rejects_stale_version_after_concurrent_first_writer() {
+        let directory = tempfile::tempdir().unwrap();
+        let reader = LocalFS::new(directory.path().to_path_buf());
+        let writer = LocalFS::new(directory.path().to_path_buf());
+        let path = RelativePath::new(".users/owner/dashboards/first-writer.json");
+        let (ready_tx, ready_rx) = tokio::sync::oneshot::channel();
+        let (release_tx, release_rx) = std::sync::mpsc::channel();
+        let reading = tokio::spawn(async move {
+            reader
+                .metadata_with_lock_mode(path, false, move |path, lock| {
+                    assert!(lock.is_none());
+                    ready_tx.send(()).unwrap();
+                    release_rx.recv().unwrap();
+                    // Force content from the first writer to pair with zero,
+                    // never its new generation, after observing no lock.
+                    read_local_metadata(path, lock)
+                })
+                .await
+        });
+        ready_rx.await.unwrap();
+        let written = writer
+            .put_metadata_conditional(
+                path,
+                Bytes::from_static(b"first content"),
+                MetadataWriteCondition::Create,
+                &None,
+            )
+            .await;
+        release_tx.send(()).unwrap();
+        let stale = reading.await.unwrap().unwrap().unwrap();
+        let written = written.unwrap();
+        assert_eq!(stale.bytes, b"first content"[..]);
+        assert_ne!(stale.version, written);
+        assert!(matches!(
+            writer
+                .put_metadata_conditional(
+                    path,
+                    Bytes::from_static(b"stale update"),
+                    MetadataWriteCondition::Update(stale.version.clone()),
+                    &None,
+                )
+                .await,
+            Err(ConditionalMetadataError::Conflict)
+        ));
+        assert!(matches!(
+            writer
+                .delete_metadata_conditional(path, stale.version, &None)
+                .await,
+            Err(ConditionalMetadataError::Conflict)
+        ));
+        let current = writer
+            .get_metadata_versioned(path, &None)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(current.version, written);
+        assert_eq!(current.bytes, stale.bytes);
+    }
+
+    #[tokio::test]
+    async fn empty_legacy_lock_migrates_and_interrupted_mutation_only_invalidates_version() {
+        let directory = tempfile::tempdir().unwrap();
+        let storage = LocalFS::new(directory.path().to_path_buf());
+        let path = RelativePath::new(".users/owner/dashboards/migration.json");
+        let object_path = storage.path_in_root(path);
+        std::fs::create_dir_all(object_path.parent().unwrap()).unwrap();
+        std::fs::write(&object_path, b"old content").unwrap();
+        // An existing empty lock must still exclude the first mutation.
+        let lock_path = storage.metadata_lock_path(path);
+        std::fs::create_dir_all(lock_path.parent().unwrap()).unwrap();
+        std::fs::File::create(&lock_path).unwrap();
+        storage
+            .metadata_with_lock_mode(path, false, move |_, lock| {
+                let lock = lock.expect("existing empty lock");
+                let contender = std::fs::OpenOptions::new()
+                    .read(true)
+                    .write(true)
+                    .open(lock_path)
+                    .unwrap();
+                assert!(matches!(
+                    contender.try_lock(),
+                    Err(std::fs::TryLockError::WouldBlock)
+                ));
+                assert_eq!(read_metadata_generation(lock)?, [0; 16]);
+                Ok(())
+            })
+            .await
+            .unwrap();
+        let old = storage
+            .get_metadata_versioned(path, &None)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(
+            std::fs::metadata(storage.metadata_lock_path(path))
+                .unwrap()
+                .len(),
+            0
+        );
+        assert_eq!(
+            old.version,
+            storage
+                .get_metadata_versioned(path, &None)
+                .await
+                .unwrap()
+                .unwrap()
+                .version
+        );
+        // Model a crash after the generation fsync but before object mutation.
+        storage
+            .metadata_with_lock(path, |_, lock| {
+                rotate_metadata_generation(lock)?;
+                Ok(())
+            })
+            .await
+            .unwrap();
+        let current = storage
+            .get_metadata_versioned(path, &None)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(old.bytes, current.bytes);
+        assert_ne!(old.version, current.version);
+        assert!(matches!(
+            storage
+                .put_metadata_conditional(
+                    path,
+                    Bytes::from_static(b"stale"),
+                    MetadataWriteCondition::Update(old.version),
+                    &None
+                )
+                .await,
+            Err(ConditionalMetadataError::Conflict)
+        ));
+        storage
+            .put_metadata_conditional(
+                path,
+                Bytes::from_static(b"new content"),
+                MetadataWriteCondition::Update(current.version),
+                &None,
+            )
+            .await
+            .unwrap();
+    }
+
+    #[tokio::test]
+    async fn partial_or_corrupt_generation_fails_closed_for_read_and_all_writers() {
+        let directory = tempfile::tempdir().unwrap();
+        let storage = LocalFS::new(directory.path().to_path_buf());
+        let path = RelativePath::new(".users/owner/dashboards/corrupt.json");
+        let old = storage
+            .put_metadata_conditional(
+                path,
+                Bytes::from_static(b"original"),
+                MetadataWriteCondition::Create,
+                &None,
+            )
+            .await
+            .unwrap();
+        let lock_path = storage.metadata_lock_path(path);
+        let valid = std::fs::read(&lock_path).unwrap();
+        let mut corrupt = valid.clone();
+        corrupt[8] ^= 1;
+        let mut oversized = valid.clone();
+        oversized.push(0);
+        for record in [
+            valid[..1].to_vec(),
+            valid[..24].to_vec(),
+            corrupt,
+            oversized,
+        ] {
+            // Deliberately inject an interrupted/corrupt record with no live operations.
+            std::fs::write(&lock_path, &record).unwrap();
+            assert!(matches!(
+                storage.get_metadata_versioned(path, &None).await,
+                Err(ConditionalMetadataError::Storage(_))
+            ));
+            for condition in [
+                MetadataWriteCondition::Create,
+                MetadataWriteCondition::Update(old.clone()),
+            ] {
+                assert!(matches!(
+                    storage
+                        .put_metadata_conditional(
+                            path,
+                            Bytes::from_static(b"unsafe"),
+                            condition,
+                            &None
+                        )
+                        .await,
+                    Err(ConditionalMetadataError::Storage(_))
+                ));
+            }
+            assert!(matches!(
+                storage
+                    .delete_metadata_conditional(path, old.clone(), &None)
+                    .await,
+                Err(ConditionalMetadataError::Storage(_))
+            ));
+            assert!(
+                storage
+                    .put_object(path, Bytes::from_static(b"unsafe legacy"), &None)
+                    .await
+                    .is_err()
+            );
+            assert!(storage.delete_object(path, &None).await.is_err());
+            assert_eq!(
+                std::fs::read(storage.path_in_root(path)).unwrap(),
+                b"original"
+            );
+            assert_eq!(std::fs::read(&lock_path).unwrap(), record);
+        }
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn versioned_read_holds_shared_lock_across_generation_and_content() {
+        let directory = tempfile::tempdir().unwrap();
+        let storage = LocalFS::new(directory.path().to_path_buf());
+        let path = RelativePath::new(".users/owner/dashboards/read.json");
+        let old = storage
+            .put_metadata_conditional(
+                path,
+                Bytes::from_static(b"old"),
+                MetadataWriteCondition::Create,
+                &None,
+            )
+            .await
+            .unwrap();
+        let lock_path = storage.metadata_lock_path(path);
+        let expected = storage
+            .metadata_with_lock_mode(path, false, move |path, lock| {
+                // Independent writers cannot rotate the generation between these reads.
+                let lock = lock.expect("existing generation lock");
+                let contender = std::fs::OpenOptions::new()
+                    .read(true)
+                    .write(true)
+                    .open(lock_path)
+                    .unwrap();
+                assert!(matches!(
+                    contender.try_lock(),
+                    Err(std::fs::TryLockError::WouldBlock)
+                ));
+                let generation = read_metadata_generation(lock)?;
+                let read = read_local_metadata(path, Some(lock))?.unwrap();
+                assert_eq!(read_metadata_generation(lock)?, generation);
+                Ok(read)
+            })
+            .await
+            .unwrap();
+        assert_eq!(expected.version, old);
+        let actual = storage
+            .get_metadata_versioned(path, &None)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(actual.version, expected.version);
+        assert_eq!(actual.bytes, expected.bytes);
+    }
+
+    #[tokio::test]
+    async fn ordinary_objects_avoid_metadata_lock_overhead_and_listing_filters_see_only_content() {
+        let directory = tempfile::tempdir().unwrap();
+        let storage = LocalFS::new(directory.path().to_path_buf());
+        for path in [
+            "stream/date=2026-10-17/data.parquet",
+            ".schema.json",
+            ".ingestor-node.json",
+        ] {
+            storage
+                .put_object(RelativePath::new(path), Bytes::from_static(b"{}"), &None)
+                .await
+                .unwrap();
+        }
+        assert!(!directory.path().join(METADATA_LOCK_DIRECTORY).exists());
+        let dashboard = RelativePath::new(".users/owner/dashboards/test.json");
+        storage
+            .put_object(
+                dashboard,
+                Bytes::from_static(b"{\"title\":\"Example\"}"),
+                &None,
+            )
+            .await
+            .unwrap();
+        let locks = directory.path().join(METADATA_LOCK_DIRECTORY);
+        assert!(locks.is_dir());
+        assert!(storage.metadata_lock_path(dashboard).is_file());
+        assert_eq!(
+            storage.metadata_lock_path(dashboard),
+            storage.metadata_lock_path(RelativePath::new("./.users/owner/dashboards/test.json"))
+        );
+        assert!(
+            !directory
+                .path()
+                .join(".users/owner/dashboards/test.json.metadata.lock")
+                .exists()
+        );
+        for needle in [".schema", ".ingestor"] {
+            let needle = needle.to_owned();
+            let objects = storage
+                .get_objects(None, Box::new(move |name| name.contains(&needle)), &None)
+                .await
+                .unwrap();
+            assert_eq!(objects.len(), 1);
+            assert_eq!(objects[0], Bytes::from_static(b"{}"));
+        }
+        let dashboards = storage
+            .get_objects(
+                Some(RelativePath::new(".users/owner/dashboards")),
+                Box::new(|name| name.ends_with(".json")),
+                &None,
+            )
+            .await
+            .unwrap();
+        assert_eq!(dashboards.len(), 1);
+        assert!(!dashboards[0].is_empty());
+        assert!(
+            !storage
+                .list_dirs(&None)
+                .await
+                .unwrap()
+                .iter()
+                .any(|name| name == METADATA_LOCK_DIRECTORY)
+        );
+        storage.delete_object(dashboard, &None).await.unwrap();
+        assert!(storage.metadata_lock_path(dashboard).is_file());
+        storage
+            .delete_object(
+                RelativePath::new("stream/date=2026-10-17/data.parquet"),
+                &None,
+            )
+            .await
+            .unwrap();
+        assert_eq!(std::fs::read_dir(locks).unwrap().count(), 1);
+    }
+}
diff --git a/src/storage/object_storage.rs b/src/storage/object_storage.rs
index 368326a67..025cfec0d 100644
--- a/src/storage/object_storage.rs
+++ b/src/storage/object_storage.rs
@@ -330,8 +330,158 @@ pub trait ObjectStorageProvider: std::fmt::Debug + Send + Sync {
     fn name(&self) -> &'static str;
 }
 
+/// Opaque storage precondition. Preserve both fields when returning it to storage.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MetadataVersion {
+    pub e_tag: Option<String>,
+    pub version: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct VersionedMetadata {
+    pub bytes: Bytes,
+    pub version: MetadataVersion,
+}
+
+#[derive(Debug, Clone)]
+pub enum MetadataWriteCondition {
+    Create,
+    Update(MetadataVersion),
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum ConditionalMetadataError {
+    #[error("metadata changed or already exists")]
+    Conflict,
+    #[error("conditional metadata operation unsupported: {0}")]
+    Unsupported(String),
+    #[error(transparent)]
+    Storage(#[from] ObjectStorageError),
+}
+
+impl From<object_store::Error> for ConditionalMetadataError {
+    fn from(error: object_store::Error) -> Self {
+        match error {
+            object_store::Error::AlreadyExists { .. }
+            | object_store::Error::Precondition { .. }
+            | object_store::Error::NotModified { .. } => Self::Conflict,
+            object_store::Error::NotImplemented { .. }
+            | object_store::Error::NotSupported { .. } => Self::Unsupported(error.to_string()),
+            error => Self::Storage(error.into()),
+        }
+    }
+}
+
+/// A single GET binds the returned bytes to their actual storage version.
+pub(crate) async fn get_cloud_metadata(
+    store: &dyn object_store::ObjectStore,
+    path: &RelativePath,
+) -> Result<Option<VersionedMetadata>, ConditionalMetadataError> {
+    use object_store::ObjectStoreExt;
+    let result = match store.get(&super::to_object_store_path(path)).await {
+        Ok(result) => result,
+        Err(object_store::Error::NotFound { .. }) => return Ok(None),
+        Err(error) => return Err(error.into()),
+    };
+    let version = MetadataVersion {
+        e_tag: result.meta.e_tag.clone(),
+        version: result.meta.version.clone(),
+    };
+    if version.e_tag.is_none() && version.version.is_none() {
+        return Err(ConditionalMetadataError::Unsupported(
+            "storage did not return an object version".into(),
+        ));
+    }
+    Ok(Some(VersionedMetadata {
+        bytes: result
+            .bytes()
+            .await
+            .map_err(ConditionalMetadataError::from)?,
+        version,
+    }))
+}
+
+pub(crate) async fn put_cloud_metadata(
+    store: &dyn object_store::ObjectStore,
+    path: &RelativePath,
+    bytes: Bytes,
+    condition: MetadataWriteCondition,
+) -> Result<MetadataVersion, ConditionalMetadataError> {
+    let mode = match condition {
+        MetadataWriteCondition::Create => object_store::PutMode::Create,
+        MetadataWriteCondition::Update(version) => {
+            if version.e_tag.is_none() && version.version.is_none() {
+                return Err(ConditionalMetadataError::Unsupported(
+                    "empty update version".into(),
+                ));
+            }
+            object_store::PutMode::Update(object_store::UpdateVersion {
+                e_tag: version.e_tag,
+                version: version.version,
+            })
+        }
+    };
+    // Never retry with an unconditional PUT if the provider rejects preconditions.
+    let result = store
+        .put_opts(
+            &super::to_object_store_path(path),
+            bytes.into(),
+            mode.into(),
+        )
+        .await
+        .map_err(|error| match error {
+            object_store::Error::NotFound { .. } => ConditionalMetadataError::Conflict,
+            error => error.into(),
+        })?;
+    if result.e_tag.is_none() && result.version.is_none() {
+        return Err(ConditionalMetadataError::Unsupported(
+            "committed write did not return an object version".into(),
+        ));
+    }
+    Ok(MetadataVersion {
+        e_tag: result.e_tag,
+        version: result.version,
+    })
+}
+
 #[async_trait]
 pub trait ObjectStorage: Debug + Send + Sync + 'static {
+    /// Paths already contain the trusted tenant prefix; tenant_id is metrics context.
+    async fn get_metadata_versioned(
+        &self,
+        _path: &RelativePath,
+        _tenant_id: &Option<String>,
+    ) -> Result<Option<VersionedMetadata>, ConditionalMetadataError> {
+        Err(ConditionalMetadataError::Unsupported(
+            "versioned GET".into(),
+        ))
+    }
+
+    async fn put_metadata_conditional(
+        &self,
+        _path: &RelativePath,
+        _bytes: Bytes,
+        _condition: MetadataWriteCondition,
+        _tenant_id: &Option<String>,
+    ) -> Result<MetadataVersion, ConditionalMetadataError> {
+        Err(ConditionalMetadataError::Unsupported(
+            "conditional PUT".into(),
+        ))
+    }
+
+    /// object_store 0.13 has no conditional DELETE. Use a conditional tombstone
+    /// PUT on cloud stores rather than an unsafe check-then-delete sequence.
+    async fn delete_metadata_conditional(
+        &self,
+        _path: &RelativePath,
+        _version: MetadataVersion,
+        _tenant_id: &Option<String>,
+    ) -> Result<(), ConditionalMetadataError> {
+        Err(ConditionalMetadataError::Unsupported(
+            "conditional DELETE; use a conditional tombstone PUT".into(),
+        ))
+    }
+
     async fn get_buffered_reader(
         &self,
         path: &RelativePath,
@@ -1841,3 +1991,70 @@ mod manifest_ownership_tests {
         ));
     }
 }
+
+#[cfg(test)]
+mod conditional_cloud_metadata_tests {
+    use super::*;
+    use crate::storage::metrics_layer::MetricLayer;
+    use object_store::{limit::LimitStore, memory::InMemory};
+
+    #[tokio::test]
+    async fn cloud_adapter_preserves_preconditions_through_storage_wrappers() {
+        let store = MetricLayer::new(LimitStore::new(InMemory::new(), 8), "s3");
+        let path = RelativePath::new("tenant/users/owner/dashboards/test.json");
+        assert!(get_cloud_metadata(&store, path).await.unwrap().is_none());
+        let initial = put_cloud_metadata(
+            &store,
+            path,
+            Bytes::from_static(b"initial"),
+            MetadataWriteCondition::Create,
+        )
+        .await
+        .unwrap();
+        assert!(matches!(
+            put_cloud_metadata(
+                &store,
+                path,
+                Bytes::from_static(b"duplicate"),
+                MetadataWriteCondition::Create
+            )
+            .await,
+            Err(ConditionalMetadataError::Conflict)
+        ));
+        let read = get_cloud_metadata(&store, path).await.unwrap().unwrap();
+        assert_eq!(read.bytes, Bytes::from_static(b"initial"));
+        assert_eq!(read.version, initial);
+        let (first, second) = tokio::join!(
+            put_cloud_metadata(
+                &store,
+                path,
+                Bytes::from_static(b"first"),
+                MetadataWriteCondition::Update(initial.clone())
+            ),
+            put_cloud_metadata(
+                &store,
+                path,
+                Bytes::from_static(b"second"),
+                MetadataWriteCondition::Update(initial)
+            ),
+        );
+        assert_eq!(usize::from(first.is_ok()) + usize::from(second.is_ok()), 1);
+        assert!(matches!(
+            if first.is_err() { first } else { second },
+            Err(ConditionalMetadataError::Conflict)
+        ));
+        assert!(matches!(
+            put_cloud_metadata(
+                &store,
+                path,
+                Bytes::from_static(b"unguarded"),
+                MetadataWriteCondition::Update(MetadataVersion {
+                    e_tag: None,
+                    version: None
+                })
+            )
+            .await,
+            Err(ConditionalMetadataError::Unsupported(_))
+        ));
+    }
+}
diff --git a/src/storage/s3.rs b/src/storage/s3.rs
index a92923172..7ef6802dd 100644
--- a/src/storage/s3.rs
+++ b/src/storage/s3.rs
@@ -899,6 +899,31 @@ impl ObjectStorage for S3 {
         self._parallel_download(path, tenant_id, write_path).await
     }
 
+    async fn get_metadata_versioned(
+        &self,
+        path: &RelativePath,
+        _tenant_id: &Option<String>,
+    ) -> Result<
+        Option<super::object_storage::VersionedMetadata>,
+        super::object_storage::ConditionalMetadataError,
+    > {
+        super::object_storage::get_cloud_metadata(self.client.as_ref(), path).await
+    }
+
+    async fn put_metadata_conditional(
+        &self,
+        path: &RelativePath,
+        bytes: Bytes,
+        condition: super::object_storage::MetadataWriteCondition,
+        _tenant_id: &Option<String>,
+    ) -> Result<
+        super::object_storage::MetadataVersion,
+        super::object_storage::ConditionalMetadataError,
+    > {
+        super::object_storage::put_cloud_metadata(self.client.as_ref(), path, bytes, condition)
+            .await
+    }
+
     async fn get_object(
         &self,
         path: &RelativePath,
diff --git a/src/tool_catalog.rs b/src/tool_catalog.rs
index 079d163cc..1ec3625aa 100644
--- a/src/tool_catalog.rs
+++ b/src/tool_catalog.rs
@@ -80,7 +80,7 @@ pub struct ToolSpec {
 }
 
 impl ToolSpec {
-    fn new(
+    pub(crate) fn new(
         name: &'static str,
         title: &'static str,
         description: &'static str,
@@ -100,6 +100,7 @@ impl ToolSpec {
             | "sample_events"
             | "get_log_context"
             | "query_sql"
+            | "run_dashboard_queries"
             | "get_cluster_metrics"
             | "explain_query"
             | "discover_datasets"
@@ -135,7 +136,21 @@ pub fn validate_tool_arguments(schema: &Value, arguments: &Value) -> Result<(),
 
 fn validate_schema_value(schema: &Value, value: &Value, path: &str) -> Result<(), String> {
     if let Some(result) = validate_any_of(schema, value, path) {
-        return result;
+        result?;
+    }
+    if let Some(variants) = schema.get("oneOf").and_then(Value::as_array) {
+        let matches = variants
+            .iter()
+            .filter(|variant| validate_schema_value(variant, value, path).is_ok())
+            .count();
+        if matches != 1 {
+            return Err(format!("{path} must match exactly one allowed schema"));
+        }
+    }
+    if let Some(expected) = schema.get("const")
+        && expected != value
+    {
+        return Err(format!("{path} must equal {expected}"));
     }
 
     validate_enum(schema, value, path)?;
@@ -246,6 +261,12 @@ fn validate_string(schema: &Value, value: &Value, path: &str) -> Result<(), Stri
     {
         return Err(format!("{path} must contain at least {minimum} characters"));
     }
+    if let Some(string) = value.as_str()
+        && let Some(maximum) = schema.get("maxLength").and_then(Value::as_u64)
+        && string.chars().count() > maximum as usize
+    {
+        return Err(format!("{path} must contain at most {maximum} characters"));
+    }
     Ok(())
 }
 
@@ -307,7 +328,7 @@ fn target_schema() -> Value {
 /// Read-only tools implemented by Parseable OSS and safe for generic external
 /// invocation without a confirmation flow.
 pub fn oss_read_tool_specs() -> Vec<ToolSpec> {
-    vec![
+    let mut tools = vec![
         ToolSpec::new(
             "list_datasets",
             "List datasets",
@@ -632,19 +653,22 @@ pub fn oss_read_tool_specs() -> Vec<ToolSpec> {
             object_schema(
                 json!({
                     "query": { "type": "string" },
+                    "after": { "type": "string", "description": "Opaque dashboard ID cursor returned by the previous page." },
                     "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }
                 }),
                 &[],
             ),
         ),
-    ]
+    ];
+    tools.extend(crate::users::dashboard_tools::read_specs());
+    tools
 }
 
 /// Effectful OSS tools retained in the canonical registry for internal agents.
 /// Generic external invocation must not use this catalog until confirmation is
 /// server-verifiable.
 pub fn oss_action_tool_specs() -> Vec<ToolSpec> {
-    vec![
+    let mut tools = vec![
         ToolSpec::new(
             "enable_alert",
             "Enable alert",
@@ -733,58 +757,9 @@ pub fn oss_action_tool_specs() -> Vec<ToolSpec> {
                 &["targetId", "idempotencyKey"],
             ),
         ),
-        ToolSpec::new(
-            "save_tile",
-            "Save tile",
-            "Persist a validated tile in an existing dashboard after confirmation.",
-            object_schema(
-                json!({
-                    "dashboardId": string_property("Dashboard ID."),
-                    "tile": { "type": "object", "additionalProperties": true },
-                    "idempotencyKey": string_property("Server-scoped idempotency key.")
-                }),
-                &["dashboardId", "tile", "idempotencyKey"],
-            ),
-        ),
-        ToolSpec::new(
-            "create_dashboard",
-            "Create dashboard",
-            "Persist a validated dashboard after confirmation.",
-            object_schema(
-                json!({
-                    "dashboard": { "type": "object", "additionalProperties": true },
-                    "idempotencyKey": string_property("Server-scoped idempotency key.")
-                }),
-                &["dashboard", "idempotencyKey"],
-            ),
-        ),
-        ToolSpec::new(
-            "update_dashboard",
-            "Update dashboard",
-            "Update a dashboard using an explicit patch or validated replacement after confirmation.",
-            object_schema(
-                json!({
-                    "dashboardId": string_property("Dashboard ID."),
-                    "patch": { "type": "object", "additionalProperties": true },
-                    "replacement": { "type": "object", "additionalProperties": true },
-                    "idempotencyKey": string_property("Server-scoped idempotency key.")
-                }),
-                &["dashboardId", "idempotencyKey"],
-            ),
-        ),
-        ToolSpec::new(
-            "delete_dashboard",
-            "Delete dashboard",
-            "Delete one dashboard after explicit confirmation.",
-            object_schema(
-                json!({
-                    "dashboardId": string_property("Dashboard ID."),
-                    "idempotencyKey": string_property("Server-scoped idempotency key.")
-                }),
-                &["dashboardId", "idempotencyKey"],
-            ),
-        ),
-    ]
+    ];
+    tools.extend(crate::users::dashboard_tools::write_specs());
+    tools
 }
 
 /// Canonical OSS catalog used by internal agents and imported by Enterprise.
@@ -826,17 +801,29 @@ pub fn registry_http_response(request: &HttpRequest, tools: Vec<Value>) -> HttpR
         .body(body)
 }
 
+/// Immutable schemas are shared across concurrent calls so rich dashboard
+/// operation schemas are built once rather than allocated for every mutation.
+pub fn external_tool_specs(writes_enabled: bool) -> impl Iterator<Item = &'static ToolSpec> {
+    static READ: std::sync::LazyLock<Vec<ToolSpec>> = std::sync::LazyLock::new(oss_read_tool_specs);
+    static WRITES: std::sync::LazyLock<Vec<ToolSpec>> =
+        std::sync::LazyLock::new(crate::users::dashboard_tools::write_specs);
+    READ.iter()
+        .chain(WRITES.iter().filter(move |_| writes_enabled))
+}
+
 /// `GET /api/prism/v1/llm/tools/list`
 pub async fn list_tool_registry(request: HttpRequest) -> HttpResponse {
-    let tools = oss_read_tool_specs()
-        .into_iter()
+    let tools = external_tool_specs(crate::users::dashboard_tools::writes_enabled(&request))
         .map(|tool| {
-            json!({
+            let mut value = json!({
                 "name": tool.name,
                 "title": tool.title,
                 "description": tool.description,
                 "inputSchema": tool.input_schema,
-            })
+                "annotations": { "readOnlyHint": matches!(tool.effect(), ToolEffect::ReadOnly | ToolEffect::ExpensiveRead), "destructiveHint": tool.name == "delete_dashboard", "idempotentHint": crate::users::dashboard_tools::is_write(tool.name), "openWorldHint": false },
+            });
+            if let Some(schema) = crate::users::dashboard_tools::output_schema(tool.name) { value["outputSchema"] = schema; }
+            value
         })
         .collect::<Vec<_>>();
 
@@ -845,6 +832,7 @@ pub async fn list_tool_registry(request: HttpRequest) -> HttpResponse {
 
 #[cfg(test)]
 mod tests {
+    use super::validate_tool_arguments;
     use std::collections::HashSet;
 
     use actix_web::{App, http::header, test, web};
@@ -860,7 +848,7 @@ mod tests {
         let tools = oss_tool_specs();
         let names = tools.iter().map(|tool| tool.name).collect::<HashSet<_>>();
 
-        assert_eq!(tools.len(), 49);
+        assert_eq!(tools.len(), 53);
         assert_eq!(tools.len(), names.len());
     }
 
@@ -899,7 +887,7 @@ mod tests {
         let read_tools = oss_read_tool_specs();
         let action_tools = oss_action_tool_specs();
 
-        assert_eq!(read_tools.len(), 36);
+        assert_eq!(read_tools.len(), 40);
         assert_eq!(action_tools.len(), 13);
         assert!(read_tools.iter().all(|tool| matches!(
             tool.effect(),
@@ -1042,6 +1030,43 @@ mod tests {
         }
     }
 
+    #[actix_web::test]
+    async fn schema_combinators_enforce_branches_and_sibling_constraints() {
+        let schema = serde_json::json!({
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {"op": {"type": "string"}, "value": {}},
+            "oneOf": [
+                {"required": ["op", "value"], "properties": {"op": {"const": "add"}}},
+                {"required": ["op"], "properties": {"op": {"const": "remove"}}}
+            ]
+        });
+        for value in [
+            serde_json::json!({"op":"add","value":1}),
+            serde_json::json!({"op":"remove"}),
+        ] {
+            assert!(validate_tool_arguments(&schema, &value).is_ok());
+        }
+        for value in [
+            serde_json::json!({"op":"add"}),
+            serde_json::json!({"op":"unknown"}),
+            serde_json::json!({"op":"remove","extra":1}),
+        ] {
+            assert!(validate_tool_arguments(&schema, &value).is_err());
+        }
+        assert!(
+            validate_tool_arguments(&serde_json::json!({"oneOf":[{},{}]}), &serde_json::json!(1))
+                .is_err()
+        );
+        assert!(
+            validate_tool_arguments(
+                &serde_json::json!({"anyOf":[{"type":"string"}],"maxLength":2}),
+                &serde_json::json!("long")
+            )
+            .is_err()
+        );
+    }
+
     #[actix_web::test]
     async fn tool_results_use_mcp_call_tool_result_shape() {
         let result = serde_json::to_value(ToolCallResult::success(serde_json::json!({
diff --git a/src/tool_executor.rs b/src/tool_executor.rs
index 5c81a497a..772acac3d 100644
--- a/src/tool_executor.rs
+++ b/src/tool_executor.rs
@@ -15,7 +15,7 @@ use crate::{
     parseable::PARSEABLE,
     prism::logstream::get_prism_logstream_info,
     rbac::{Response, Users, map::SessionKey, role::Action},
-    tool_catalog::{ToolCallRequest, ToolCallResult, oss_read_tool_specs},
+    tool_catalog::{ToolCallRequest, ToolCallResult},
     utils::{
         actix::extract_session_key_from_req,
         get_tenant_id_from_request,
@@ -53,12 +53,12 @@ fn bounded_select(query: &str) -> Result<String, String> {
     if query.contains(';') {
         return Err("exactly one SQL statement is required".to_owned());
     }
-    let normalized = query.to_ascii_lowercase();
-    if !(normalized.starts_with("select ") || normalized.starts_with("with ")) {
+    let first_word = query.split_whitespace().next().unwrap_or("");
+    if !(first_word.eq_ignore_ascii_case("select") || first_word.eq_ignore_ascii_case("with")) {
         return Err("only SQL SELECT queries are allowed".to_owned());
     }
     Ok(format!(
-        "SELECT * FROM ({query}) AS __parseable_tool_query LIMIT 500"
+        "SELECT * FROM (\n{query}\n) AS __parseable_tool_query LIMIT 500"
     ))
 }
 
@@ -988,8 +988,12 @@ async fn execute_saved_object_tool(
         }
         "list_dashboard_tags" => {
             authorize(context.session_key, Action::ListDashboard, None, None)?;
-            serde_json::to_value(dashboards::list_tags_internal(context.tenant_id).await)
-                .map_err(|error| error.to_string())
+            serde_json::to_value(
+                dashboards::list_tags_internal(context.tenant_id)
+                    .await
+                    .map_err(|e| e.to_string())?,
+            )
+            .map_err(|error| error.to_string())
         }
         "get_dashboard" => {
             authorize(context.session_key, Action::GetDashboard, None, None)?;
@@ -1008,6 +1012,7 @@ async fn execute_saved_object_tool(
             Ok(
                 dashboards::list_dashboards_internal(limit, None, context.tenant_id)
                     .await
+                    .map_err(|e| e.to_string())?
                     .into(),
             )
         }
@@ -1086,16 +1091,42 @@ pub async fn call_tool_registry(
             "Your session has expired or is no longer valid. Please re-authenticate to access this resource.",
         ));
     }
-    let Some(spec) = oss_read_tool_specs()
-        .into_iter()
-        .find(|tool| tool.name == call.name)
-    else {
+    let Some(spec) = crate::tool_catalog::external_tool_specs(
+        crate::users::dashboard_tools::writes_enabled(&req),
+    )
+    .find(|tool| tool.name == call.name) else {
         return HttpResponse::NotFound().json(ToolCallResult::error("unknown tool"));
     };
     if let Err(error) = spec.validate_arguments(&call.arguments) {
         return HttpResponse::BadRequest().json(ToolCallResult::error(error));
     }
     let tenant_id = get_tenant_id_from_request(&req);
+    if crate::users::dashboard_tools::is_dashboard_tool(spec.name) {
+        return match crate::users::dashboard_tools::execute(&req, spec.name, &call.arguments).await
+        {
+            Ok(result) => HttpResponse::Ok().json(ToolCallResult::success(result)),
+            Err(error) => {
+                let mut result = ToolCallResult::error(error.to_string());
+                result.structured_content =
+                    json!({"error":crate::users::dashboard_tools::tool_error(&error)});
+                HttpResponse::Ok().json(result)
+            }
+        };
+    }
+    // Multiplexed transport authentication is separate from per-tool policy.
+    // Preserve the existing query gate for non-dashboard tools, including
+    // tenant suspension checks, without requiring query access to edit config.
+    if let crate::rbac::Response::Suspended(message) =
+        crate::handlers::http::middleware::check_suspension_for_tenant(
+            tenant_id.as_deref(),
+            Action::Query,
+        )
+    {
+        return HttpResponse::Forbidden().json(ToolCallResult::error(message));
+    }
+    if let Err(message) = authorize(&session_key, Action::Query, None, None) {
+        return HttpResponse::Forbidden().json(ToolCallResult::error(message));
+    }
     match execute_oss_tool_inner(
         spec.name,
         &call.arguments,
@@ -1112,6 +1143,27 @@ pub async fn call_tool_registry(
 
 #[cfg(test)]
 mod tests {
+    #[actix_web::test]
+    async fn bounded_tool_sql_preserves_multiline_queries_and_trailing_comments() {
+        use datafusion::sql::sqlparser::{dialect::GenericDialect, parser::Parser};
+        for source in [
+            "SELECT\n1 AS value",
+            "WITH\nx AS (SELECT 1) SELECT * FROM x",
+            "SELECT 1 -- trailing comment",
+        ] {
+            let bounded = super::bounded_select(source).unwrap();
+            assert_eq!(
+                Parser::parse_sql(&GenericDialect {}, &bounded)
+                    .unwrap()
+                    .len(),
+                1
+            );
+            assert!(bounded.ends_with("LIMIT 500"));
+        }
+        assert!(super::bounded_select("DELETE FROM logs").is_err());
+        assert!(super::bounded_select("SELECT 1; SELECT 2").is_err());
+    }
+
     use actix_web::{App, http::StatusCode, test, web};
     use chrono::{DateTime, Duration, Utc};
     use serde_json::{Value, json};
diff --git a/src/users/dashboard_patch.rs b/src/users/dashboard_patch.rs
new file mode 100644
index 000000000..87e9ffd69
--- /dev/null
+++ b/src/users/dashboard_patch.rs
@@ -0,0 +1,5061 @@
+/*
+ * Parseable Server (C) 2022 - 2025 Parseable, Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+//! Pure, ID-addressed dashboard patching and structural configuration validation.
+//!
+//! Nothing here performs I/O, executes queries or probes datasets. Patches operate on the
+//! stored wire document (`serde_json::Value`) so unknown and legacy fields survive untouched.
+//! Layout semantics mirror `frontend/src/features/dashboards/layout.ts` and `sections.ts`.
+
+use std::collections::{HashMap, HashSet};
+
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_json::{Map, Value, json};
+use ulid::Ulid;
+
+use super::dashboards::Dashboard;
+
+pub const MAX_OPERATIONS: usize = 256;
+pub const MAX_DOCUMENT_BYTES: usize = 2 * 1024 * 1024;
+pub const MAX_TILES: usize = 500;
+pub const MAX_SECTIONS: usize = 100;
+pub const MAX_VARIABLES: usize = 100;
+pub const MAX_POINTER_TOKENS: usize = 32;
+pub const MAX_ID_BYTES: usize = 128;
+pub const GRID_COLUMNS: i64 = 12;
+pub const MAX_TILE_ROW: i64 = 100_000;
+/// Editor/renderer bound for new or changed heights; taller legacy heights are grandfathered and
+/// still occupy their full stored height during collision handling.
+pub const MAX_TILE_HEIGHT: i64 = 24;
+/// Server-internal storage metadata. It is never patchable and must be hidden from clients.
+pub const INTERNAL_METADATA_KEY: &str = "_parseableDashboard";
+
+const DEFAULT_TILE_W: i64 = 6;
+const DEFAULT_TILE_H: i64 = 4;
+/// Stands in for the frontend's `Infinity` height bound while keeping sums overflow-free.
+const UNBOUNDED: i64 = i64::MAX / 4;
+
+const SERVER_OWNED: &[&str] = &[
+    "dashboardId",
+    "author",
+    "created",
+    "modified",
+    "version",
+    "tenantId",
+    "revision",
+    INTERNAL_METADATA_KEY,
+];
+const ENTITY_COLLECTIONS: &[&str] = &["tiles", "sections", "variables"];
+const TILE_TYPES: &[&str] = &["code", "builder", "promql"];
+const CHART_TYPES: &[&str] = &[
+    "timeseries",
+    "line",
+    "area",
+    "bar",
+    "table",
+    "query-value",
+    "pie",
+    "donut",
+    "gauge",
+    "bubble",
+];
+const SERIES_STYLES: &[&str] = &["line", "bar", "area"];
+const COLOUR_SCHEMES: &[&str] = &[
+    "classic",
+    "agentObservability",
+    "parseableBlue",
+    "blue",
+    "teal",
+    "green",
+    "purple",
+    "red",
+    "orange",
+    "yellow",
+    "gray",
+    "greenYellowRed",
+    "redYellowGreen",
+];
+const LEGEND_POSITIONS: &[&str] = &["top", "bottom", "left", "right"];
+const BAR_ORIENTATIONS: &[&str] = &["vertical", "horizontal"];
+const QUERY_VALUE_THEMES: &[&str] = &[
+    "blue", "brown", "emerald", "fuchsia", "grey", "orange", "pink", "purple", "red", "yellow",
+];
+const PERCENT_FILLS: &[&str] = &["horizontal", "vertical", "diagonal", "none"];
+const QUERY_MODES: &[&str] = &["range", "instant", "both"];
+const VARIABLE_TYPES: &[&str] = &["promql", "promql_query", "sql", "list", "text", "dataset"];
+const LABEL_FILTER_OPERATORS: &[&str] = &["=", "!=", "=~", "!~"];
+const TIME_RANGE_PRESETS: &[&str] = &["10m", "30m", "1h", "5h", "1d", "3d"];
+const TIME_RANGE_TYPES: &[&str] = &["fixed", "custom"];
+const REFRESH_INTERVALS: &[u64] = &[0, 15_000, 30_000, 60_000, 300_000];
+const DASHBOARD_TYPES: &[&str] = &["Dashboard", "Report"];
+/// Variable fields whose `$name` tokens are rewritten by `renameVariable`.
+const VARIABLE_SOURCES: &[&str] = &["sqlQuery", "promqlQuery", "promqlQueryDataset", "dataset"];
+
+/// Body of a dashboard PATCH request.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct DashboardPatchRequest {
+    pub operations: Vec<DashboardOperation>,
+    #[serde(default)]
+    pub dry_run: bool,
+    /// Expected stored revision. Opaque to the engine; the service compares it.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub revision: Option<String>,
+}
+
+/// The entity a generic operation addresses. Paths are relative to the selected object.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "camelCase", deny_unknown_fields)]
+pub enum PatchTarget {
+    Dashboard,
+    Tile { id: String },
+    Section { id: String },
+    Variable { name: String },
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(
+    tag = "op",
+    rename_all = "camelCase",
+    rename_all_fields = "camelCase",
+    deny_unknown_fields
+)]
+pub enum DashboardOperation {
+    /// RFC 6902 `add` at an RFC 6901 pointer relative to `target`; an empty path adds the entity.
+    Add {
+        target: PatchTarget,
+        #[serde(default)]
+        path: String,
+        value: Value,
+    },
+    /// RFC 6902 `replace`; the location must exist. An empty path replaces an entity's content
+    /// while keeping its identity (and its layout when the value has none).
+    Replace {
+        target: PatchTarget,
+        #[serde(default)]
+        path: String,
+        value: Value,
+    },
+    /// RFC 6902 `remove`; the location must exist. An empty path removes the entity.
+    Remove {
+        target: PatchTarget,
+        #[serde(default)]
+        path: String,
+    },
+    /// Move and/or resize a tile with the frontend's collision and compaction rules.
+    /// `sectionId`: absent keeps the section, `null` or `""` unsections, a string moves.
+    PlaceTile {
+        tile_id: String,
+        #[serde(
+            default,
+            deserialize_with = "double_option",
+            skip_serializing_if = "Option::is_none"
+        )]
+        section_id: Option<Option<String>>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        layout: Option<LayoutEdits>,
+    },
+    /// Rename a variable and rewrite `$from`/`${from}` references.
+    RenameVariable { from: String, to: String },
+    /// An exact permutation of the dashboard's addressable section ids.
+    ReorderSections { section_ids: Vec<String> },
+    /// Remove a section with an explicit disposition for its tiles.
+    RemoveSection {
+        section_id: String,
+        tiles: TileDisposition,
+    },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LayoutEdits {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub x: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub y: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub w: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub h: Option<i64>,
+}
+
+impl LayoutEdits {
+    fn is_empty(&self) -> bool {
+        self.x.is_none() && self.y.is_none() && self.w.is_none() && self.h.is_none()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(
+    tag = "mode",
+    rename_all = "camelCase",
+    rename_all_fields = "camelCase",
+    deny_unknown_fields
+)]
+pub enum TileDisposition {
+    /// Append the tiles below the unsectioned grid.
+    Unsection,
+    /// Delete the section's tiles.
+    Delete,
+    /// Append the tiles below another existing section's tiles.
+    Move { section_id: String },
+}
+
+fn double_option<'de, D: Deserializer<'de>>(
+    deserializer: D,
+) -> Result<Option<Option<String>>, D::Error> {
+    Option::<String>::deserialize(deserializer).map(Some)
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PatchErrorCode {
+    TooManyOperations,
+    InvalidBase,
+    InvalidTarget,
+    TargetNotFound,
+    AmbiguousTarget,
+    TargetExists,
+    InvalidPointer,
+    PathNotFound,
+    ProtectedPath,
+    InvalidValue,
+    InvalidOperation,
+    NameConflict,
+    LimitExceeded,
+    DocumentTooLarge,
+}
+
+/// A rejected operation. No part of the batch applies.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PatchError {
+    pub code: PatchErrorCode,
+    pub message: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub operation_index: Option<usize>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub target: Option<PatchTarget>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub path: Option<String>,
+}
+
+impl PatchError {
+    fn new(code: PatchErrorCode, message: impl Into<String>) -> Self {
+        Self {
+            code,
+            message: message.into(),
+            operation_index: None,
+            target: None,
+            path: None,
+        }
+    }
+
+    fn target(mut self, target: PatchTarget) -> Self {
+        self.target = Some(target);
+        self
+    }
+
+    fn path(mut self, path: impl Into<String>) -> Self {
+        self.path = Some(path.into());
+        self
+    }
+
+    fn locate(mut self, index: usize, operation: &DashboardOperation) -> Self {
+        self.operation_index = Some(index);
+        if self.target.is_none() {
+            self.target = Some(operation_target(operation));
+        }
+        if self.path.is_none()
+            && let DashboardOperation::Add { path, .. }
+            | DashboardOperation::Replace { path, .. }
+            | DashboardOperation::Remove { path, .. } = operation
+        {
+            self.path = Some(path.clone());
+        }
+        self
+    }
+}
+
+impl std::fmt::Display for PatchError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self.operation_index {
+            Some(index) => write!(f, "operation {index}: {}", self.message),
+            None => f.write_str(&self.message),
+        }
+    }
+}
+
+impl std::error::Error for PatchError {}
+
+fn operation_target(operation: &DashboardOperation) -> PatchTarget {
+    match operation {
+        DashboardOperation::Add { target, .. }
+        | DashboardOperation::Replace { target, .. }
+        | DashboardOperation::Remove { target, .. } => target.clone(),
+        DashboardOperation::PlaceTile { tile_id, .. } => PatchTarget::Tile {
+            id: tile_id.clone(),
+        },
+        DashboardOperation::RenameVariable { from, .. } => {
+            PatchTarget::Variable { name: from.clone() }
+        }
+        DashboardOperation::ReorderSections { .. } => PatchTarget::Dashboard,
+        DashboardOperation::RemoveSection { section_id, .. } => PatchTarget::Section {
+            id: section_id.clone(),
+        },
+    }
+}
+
+/// A fresh tile id for tool layers that want the server to mint one. Never called while
+/// applying a patch, so dry runs and applies of the same batch are identical.
+pub fn generate_tile_id() -> String {
+    Ulid::new().to_string()
+}
+
+/// Remove server-internal storage metadata before a document leaves the server.
+pub fn strip_internal_metadata(document: &mut Value) {
+    if let Some(root) = document.as_object_mut() {
+        root.remove(INTERNAL_METADATA_KEY);
+    }
+}
+
+/// Apply every operation to a copy of `base`, or none of them. Final-state validation is
+/// separate: callers must run [`validate_dashboard`] on the result before persisting it.
+pub fn apply_patch(base: &Value, operations: &[DashboardOperation]) -> Result<Value, PatchError> {
+    if operations.len() > MAX_OPERATIONS {
+        return Err(PatchError::new(
+            PatchErrorCode::TooManyOperations,
+            format!("a patch may contain at most {MAX_OPERATIONS} operations"),
+        ));
+    }
+    if !base.is_object() {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidBase,
+            "the stored dashboard is not a JSON object",
+        ));
+    }
+    let mut document = base.clone();
+    for (index, operation) in operations.iter().enumerate() {
+        apply_operation(&mut document, operation)
+            .map_err(|error| error.locate(index, operation))?;
+    }
+    check_growth(base, &document)?;
+    Ok(document)
+}
+
+fn check_growth(base: &Value, candidate: &Value) -> Result<(), PatchError> {
+    let count = |document: &Value, key: &str| {
+        document
+            .get(key)
+            .and_then(Value::as_array)
+            .map_or(0, Vec::len)
+    };
+    for (key, limit) in [
+        ("tiles", MAX_TILES),
+        ("sections", MAX_SECTIONS),
+        ("variables", MAX_VARIABLES),
+    ] {
+        let after = count(candidate, key);
+        if after > limit && after > count(base, key) {
+            return Err(PatchError::new(
+                PatchErrorCode::LimitExceeded,
+                format!("a dashboard may contain at most {limit} {key}"),
+            )
+            .target(PatchTarget::Dashboard)
+            .path(format!("/{key}")));
+        }
+    }
+    let size = json_len(candidate);
+    if size > MAX_DOCUMENT_BYTES && size > json_len(base) {
+        return Err(PatchError::new(
+            PatchErrorCode::DocumentTooLarge,
+            format!("the patched dashboard would exceed {MAX_DOCUMENT_BYTES} bytes"),
+        )
+        .target(PatchTarget::Dashboard));
+    }
+    Ok(())
+}
+
+fn json_len(value: &Value) -> usize {
+    struct Counter(usize);
+    impl std::io::Write for Counter {
+        fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
+            self.0 += bytes.len();
+            Ok(bytes.len())
+        }
+        fn flush(&mut self) -> std::io::Result<()> {
+            Ok(())
+        }
+    }
+    let mut counter = Counter(0);
+    // Serializing a Value into an infallible writer cannot fail.
+    let _ = serde_json::to_writer(&mut counter, value);
+    counter.0
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Edit {
+    Add,
+    Replace,
+    Remove,
+}
+
+fn apply_operation(document: &mut Value, operation: &DashboardOperation) -> Result<(), PatchError> {
+    match operation {
+        DashboardOperation::Add {
+            target,
+            path,
+            value,
+        } => apply_generic(document, Edit::Add, target, path, Some(value)),
+        DashboardOperation::Replace {
+            target,
+            path,
+            value,
+        } => apply_generic(document, Edit::Replace, target, path, Some(value)),
+        DashboardOperation::Remove { target, path } => {
+            apply_generic(document, Edit::Remove, target, path, None)
+        }
+        DashboardOperation::PlaceTile {
+            tile_id,
+            section_id,
+            layout,
+        } => place_tile(document, tile_id, section_id.as_ref(), layout.as_ref()),
+        DashboardOperation::RenameVariable { from, to } => rename_variable(document, from, to),
+        DashboardOperation::ReorderSections { section_ids } => {
+            reorder_sections(document, section_ids)
+        }
+        DashboardOperation::RemoveSection { section_id, tiles } => {
+            remove_section(document, section_id, tiles)
+        }
+    }
+}
+
+fn root_mut(document: &mut Value) -> Result<&mut Map<String, Value>, PatchError> {
+    document.as_object_mut().ok_or_else(|| {
+        PatchError::new(
+            PatchErrorCode::InvalidBase,
+            "the stored dashboard is not a JSON object",
+        )
+    })
+}
+
+// ---------------------------------------------------------------------------------------------
+// JSON Pointer
+// ---------------------------------------------------------------------------------------------
+
+fn parse_pointer(path: &str) -> Result<Vec<String>, PatchError> {
+    if path.is_empty() {
+        return Ok(Vec::new());
+    }
+    let Some(rest) = path.strip_prefix('/') else {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidPointer,
+            "a path must be empty or a JSON Pointer starting with '/'",
+        ));
+    };
+    let mut tokens = Vec::new();
+    for raw in rest.split('/') {
+        if tokens.len() == MAX_POINTER_TOKENS {
+            return Err(PatchError::new(
+                PatchErrorCode::InvalidPointer,
+                format!("a path may have at most {MAX_POINTER_TOKENS} segments"),
+            ));
+        }
+        let mut token = String::with_capacity(raw.len());
+        let mut chars = raw.chars();
+        while let Some(c) = chars.next() {
+            if c != '~' {
+                token.push(c);
+                continue;
+            }
+            match chars.next() {
+                Some('0') => token.push('~'),
+                Some('1') => token.push('/'),
+                _ => {
+                    return Err(PatchError::new(
+                        PatchErrorCode::InvalidPointer,
+                        "'~' in a JSON Pointer must be followed by '0' or '1'",
+                    ));
+                }
+            }
+        }
+        tokens.push(token);
+    }
+    Ok(tokens)
+}
+
+fn escape_token(token: &str) -> String {
+    token.replace('~', "~0").replace('/', "~1")
+}
+
+fn join(prefix: &str, key: &str) -> String {
+    format!("{prefix}/{}", escape_token(key))
+}
+
+/// Case-, underscore- and hyphen-insensitive key, so `tenant_id` or `TileId` cannot slip past
+/// a protected name.
+fn fold(key: &str) -> String {
+    key.chars()
+        .filter(|c| *c != '_' && *c != '-')
+        .flat_map(char::to_lowercase)
+        .collect()
+}
+
+fn array_index(token: &str) -> Option<usize> {
+    let valid = !token.is_empty()
+        && token.bytes().all(|b| b.is_ascii_digit())
+        && (token == "0" || !token.starts_with('0'));
+    if valid { token.parse().ok() } else { None }
+}
+
+fn path_not_found(message: impl Into<String>) -> PatchError {
+    PatchError::new(PatchErrorCode::PathNotFound, message)
+}
+
+fn apply_pointer(
+    root: &mut Value,
+    tokens: &[String],
+    edit: Edit,
+    value: Option<&Value>,
+) -> Result<(), PatchError> {
+    let Some((last, parents)) = tokens.split_last() else {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidPointer,
+            "an empty path is not valid here",
+        ));
+    };
+    let mut current = root;
+    for token in parents {
+        current = match current {
+            Value::Object(map) => map.get_mut(token.as_str()),
+            Value::Array(items) => array_index(token).and_then(|index| items.get_mut(index)),
+            _ => None,
+        }
+        .ok_or_else(|| path_not_found(format!("`{token}` does not exist")))?;
+    }
+    let value = || value.cloned().unwrap_or(Value::Null);
+    match current {
+        Value::Object(map) => match edit {
+            Edit::Add => {
+                map.insert(last.clone(), value());
+            }
+            Edit::Replace => match map.get_mut(last.as_str()) {
+                Some(slot) => *slot = value(),
+                None => return Err(path_not_found(format!("`{last}` does not exist"))),
+            },
+            Edit::Remove => {
+                if map.remove(last.as_str()).is_none() {
+                    return Err(path_not_found(format!("`{last}` does not exist")));
+                }
+            }
+        },
+        Value::Array(items) => {
+            let len = items.len();
+            let index = if edit == Edit::Add && last == "-" {
+                Some(len)
+            } else {
+                array_index(last)
+                    .filter(|index| *index < len || (edit == Edit::Add && *index == len))
+            };
+            let Some(index) = index else {
+                return Err(path_not_found(format!(
+                    "array index `{last}` is out of bounds"
+                )));
+            };
+            match edit {
+                Edit::Add => items.insert(index, value()),
+                Edit::Replace => items[index] = value(),
+                Edit::Remove => {
+                    items.remove(index);
+                }
+            }
+        }
+        _ => {
+            return Err(path_not_found(
+                "the parent of the final path segment is not an object or array",
+            ));
+        }
+    }
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------------------------
+// Entity lookup
+// ---------------------------------------------------------------------------------------------
+
+#[derive(Clone, Copy)]
+enum Slot {
+    Absent,
+    Null,
+    Present,
+}
+
+fn take_array(root: &mut Map<String, Value>, key: &str) -> Result<(Vec<Value>, Slot), PatchError> {
+    match root.get_mut(key) {
+        None => Ok((Vec::new(), Slot::Absent)),
+        Some(Value::Null) => Ok((Vec::new(), Slot::Null)),
+        Some(Value::Array(items)) => Ok((std::mem::take(items), Slot::Present)),
+        Some(_) => Err(PatchError::new(
+            PatchErrorCode::InvalidBase,
+            format!("`{key}` is not an array"),
+        )
+        .target(PatchTarget::Dashboard)
+        .path(format!("/{key}"))),
+    }
+}
+
+fn restore_array(root: &mut Map<String, Value>, key: &str, items: Vec<Value>, slot: Slot) {
+    match slot {
+        Slot::Present => {
+            if let Some(stored) = root.get_mut(key) {
+                *stored = Value::Array(items);
+            }
+        }
+        Slot::Null | Slot::Absent if !items.is_empty() => {
+            root.insert(key.to_owned(), Value::Array(items));
+        }
+        Slot::Null | Slot::Absent => {}
+    }
+}
+
+/// Runs `f` with the tiles taken out of the document and the sections borrowed from it.
+fn with_tiles<R>(
+    root: &mut Map<String, Value>,
+    f: impl FnOnce(&mut Vec<Value>, &[Value]) -> Result<R, PatchError>,
+) -> Result<R, PatchError> {
+    let (mut tiles, slot) = take_array(root, "tiles")?;
+    let sections: &[Value] = root
+        .get("sections")
+        .and_then(Value::as_array)
+        .map(Vec::as_slice)
+        .unwrap_or(&[]);
+    let result = f(&mut tiles, sections);
+    restore_array(root, "tiles", tiles, slot);
+    result
+}
+
+fn array_mut<'a>(
+    root: &'a mut Map<String, Value>,
+    key: &str,
+) -> Result<&'a mut Vec<Value>, PatchError> {
+    match root.get_mut(key) {
+        Some(Value::Array(items)) => Ok(items),
+        _ => Err(PatchError::new(
+            PatchErrorCode::TargetNotFound,
+            format!("the dashboard has no {key}"),
+        )),
+    }
+}
+
+fn unique_position(
+    mut positions: impl Iterator<Item = usize>,
+    describe: impl FnOnce() -> String,
+) -> Result<Option<usize>, PatchError> {
+    let first = positions.next();
+    if first.is_some() && positions.next().is_some() {
+        return Err(PatchError::new(
+            PatchErrorCode::AmbiguousTarget,
+            format!("{} matches more than one stored entry", describe()),
+        ));
+    }
+    Ok(first)
+}
+
+fn tile_ulid(tile: &Value) -> Option<Ulid> {
+    tile.get("tile_id")?
+        .as_str()
+        .and_then(|id| Ulid::from_string(id).ok())
+}
+
+fn tile_target(id: &str) -> Result<Ulid, PatchError> {
+    let ulid = Ulid::from_string(id).map_err(|_| {
+        PatchError::new(
+            PatchErrorCode::InvalidTarget,
+            format!("tile id `{id}` is not a valid ULID"),
+        )
+    })?;
+    if ulid.is_nil() {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidTarget,
+            "the nil ULID cannot identify a tile",
+        ));
+    }
+    Ok(ulid)
+}
+
+fn find_tile(tiles: &[Value], id: Ulid) -> Result<Option<usize>, PatchError> {
+    unique_position(
+        tiles
+            .iter()
+            .enumerate()
+            .filter(|(_, tile)| tile_ulid(tile) == Some(id))
+            .map(|(index, _)| index),
+        || format!("tile `{id}`"),
+    )
+}
+
+fn require_tile(tiles: &[Value], id: Ulid) -> Result<usize, PatchError> {
+    find_tile(tiles, id)?.ok_or_else(|| {
+        PatchError::new(
+            PatchErrorCode::TargetNotFound,
+            format!("tile `{id}` does not exist"),
+        )
+    })
+}
+
+fn section_id(section: &Value) -> Option<&str> {
+    section
+        .get("sectionId")
+        .and_then(Value::as_str)
+        .filter(|id| !id.is_empty())
+}
+
+fn section_target(id: &str) -> Result<(), PatchError> {
+    if id.is_empty() || id.len() > MAX_ID_BYTES {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidTarget,
+            format!("a section id must be 1 to {MAX_ID_BYTES} bytes"),
+        ));
+    }
+    Ok(())
+}
+
+fn find_section(sections: &[Value], id: &str) -> Result<Option<usize>, PatchError> {
+    unique_position(
+        sections
+            .iter()
+            .enumerate()
+            .filter(|(_, section)| section_id(section) == Some(id))
+            .map(|(index, _)| index),
+        || format!("section `{id}`"),
+    )
+}
+
+fn has_section(sections: &[Value], id: &str) -> bool {
+    sections
+        .iter()
+        .any(|section| section_id(section) == Some(id))
+}
+
+fn is_variable_name(name: &str) -> bool {
+    !name.is_empty()
+        && name.len() <= MAX_ID_BYTES
+        && name.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_')
+}
+
+fn variable_name(variable: &Value) -> Option<&str> {
+    variable.get("name").and_then(Value::as_str)
+}
+
+fn variable_target(name: &str) -> Result<(), PatchError> {
+    if !is_variable_name(name) {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidTarget,
+            format!("variable name `{name}` must match ^\\w+$ (at most {MAX_ID_BYTES} bytes)"),
+        ));
+    }
+    Ok(())
+}
+
+fn find_variable(variables: &[Value], name: &str) -> Result<Option<usize>, PatchError> {
+    unique_position(
+        variables
+            .iter()
+            .enumerate()
+            .filter(|(_, variable)| variable_name(variable) == Some(name))
+            .map(|(index, _)| index),
+        || format!("variable `{name}`"),
+    )
+}
+
+fn protected(message: impl Into<String>) -> PatchError {
+    PatchError::new(PatchErrorCode::ProtectedPath, message)
+}
+
+fn guard_identity(token: &str, identity: &str) -> Result<(), PatchError> {
+    if fold(token) == fold(identity) {
+        return Err(protected(format!(
+            "`{identity}` identifies the entity and cannot be patched"
+        )));
+    }
+    Ok(())
+}
+
+/// An added or replacing entity value: an object whose identity, if present, matches the target.
+fn entity_value(
+    value: Option<&Value>,
+    identity: &str,
+    matches: impl Fn(&Value) -> bool,
+    canonical: &str,
+) -> Result<Map<String, Value>, PatchError> {
+    let Some(Value::Object(map)) = value else {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidValue,
+            "an entity value must be a JSON object",
+        ));
+    };
+    for (key, field) in map {
+        if fold(key) == fold(identity) && (key != identity || !matches(field)) {
+            return Err(PatchError::new(
+                PatchErrorCode::InvalidValue,
+                format!("`{key}` in the value conflicts with the target identity"),
+            ));
+        }
+    }
+    let mut map = map.clone();
+    map.insert(identity.to_owned(), Value::String(canonical.to_owned()));
+    Ok(map)
+}
+
+fn not_found(what: String) -> PatchError {
+    PatchError::new(
+        PatchErrorCode::TargetNotFound,
+        format!("{what} does not exist"),
+    )
+}
+
+fn exists(what: String) -> PatchError {
+    PatchError::new(
+        PatchErrorCode::TargetExists,
+        format!("{what} already exists"),
+    )
+}
+
+// ---------------------------------------------------------------------------------------------
+// Generic add / replace / remove
+// ---------------------------------------------------------------------------------------------
+
+fn apply_generic(
+    document: &mut Value,
+    edit: Edit,
+    target: &PatchTarget,
+    path: &str,
+    value: Option<&Value>,
+) -> Result<(), PatchError> {
+    let tokens = parse_pointer(path)?;
+    match target {
+        PatchTarget::Dashboard => {
+            let Some(first) = tokens.first() else {
+                return Err(protected(
+                    "the dashboard root cannot be added, replaced or removed; address fields or entities",
+                ));
+            };
+            let folded = fold(first);
+            if SERVER_OWNED.iter().any(|key| fold(key) == folded) {
+                return Err(protected(format!("`{first}` is server-owned")));
+            }
+            if ENTITY_COLLECTIONS.iter().any(|key| fold(key) == folded) {
+                return Err(protected(format!(
+                    "`{first}` entries must be addressed with tile, section or variable targets"
+                )));
+            }
+            apply_pointer(document, &tokens, edit, value)
+        }
+        PatchTarget::Tile { id } => {
+            let id = tile_target(id)?;
+            let root = root_mut(document)?;
+            if tokens.is_empty() {
+                return tile_entity(root, edit, id, value);
+            }
+            guard_identity(&tokens[0], "tile_id")?;
+            let tiles = array_mut(root, "tiles")?;
+            let index = require_tile(tiles, id)?;
+            apply_pointer(&mut tiles[index], &tokens, edit, value)
+        }
+        PatchTarget::Section { id } => {
+            section_target(id)?;
+            let root = root_mut(document)?;
+            if tokens.is_empty() {
+                return section_entity(root, edit, id, value);
+            }
+            guard_identity(&tokens[0], "sectionId")?;
+            let sections = array_mut(root, "sections")?;
+            let index =
+                find_section(sections, id)?.ok_or_else(|| not_found(format!("section `{id}`")))?;
+            apply_pointer(&mut sections[index], &tokens, edit, value)
+        }
+        PatchTarget::Variable { name } => {
+            variable_target(name)?;
+            let root = root_mut(document)?;
+            if tokens.is_empty() {
+                return variable_entity(root, edit, name, value);
+            }
+            guard_identity(&tokens[0], "name")?;
+            let variables = array_mut(root, "variables")?;
+            let index = find_variable(variables, name)?
+                .ok_or_else(|| not_found(format!("variable `{name}`")))?;
+            apply_pointer(&mut variables[index], &tokens, edit, value)
+        }
+    }
+}
+
+/// Tile add/remove follow the frontend's applyTile/removeTile: the affected section compacts.
+fn tile_entity(
+    root: &mut Map<String, Value>,
+    edit: Edit,
+    id: Ulid,
+    value: Option<&Value>,
+) -> Result<(), PatchError> {
+    let canonical = id.to_string();
+    let matches =
+        |field: &Value| field.as_str().and_then(|s| Ulid::from_string(s).ok()) == Some(id);
+    with_tiles(root, |tiles, sections| {
+        let found = find_tile(tiles, id)?;
+        match edit {
+            Edit::Add => {
+                if found.is_some() {
+                    return Err(exists(format!("tile `{id}`")));
+                }
+                let mut tile = Value::Object(entity_value(value, "tile_id", matches, &canonical)?);
+                fill_new_layout(tiles, sections, &mut tile);
+                tiles.push(tile);
+                let added = tiles.len() - 1;
+                compact_section(tiles, sections, added);
+            }
+            Edit::Replace => {
+                let index = found.ok_or_else(|| not_found(format!("tile `{id}`")))?;
+                let mut tile = entity_value(value, "tile_id", matches, &canonical)?;
+                if !tile.contains_key("layout")
+                    && let Some(layout) = tiles[index].get("layout")
+                {
+                    tile.insert("layout".to_owned(), layout.clone());
+                }
+                tiles[index] = Value::Object(tile);
+            }
+            Edit::Remove => {
+                let index = found.ok_or_else(|| not_found(format!("tile `{id}`")))?;
+                let groups = section_groups(tiles, sections);
+                let neighbour = members_of(&groups, index)
+                    .iter()
+                    .copied()
+                    .find(|member| *member != index);
+                tiles.remove(index);
+                if let Some(neighbour) = neighbour {
+                    let neighbour = if neighbour > index {
+                        neighbour - 1
+                    } else {
+                        neighbour
+                    };
+                    compact_section(tiles, sections, neighbour);
+                }
+            }
+        }
+        Ok(())
+    })
+}
+
+/// Missing layout fields get the frontend's newTile/appendLayout defaults.
+fn fill_new_layout(tiles: &[Value], sections: &[Value], tile: &mut Value) {
+    let section = tile
+        .get("sectionId")
+        .and_then(Value::as_str)
+        .unwrap_or("")
+        .to_owned();
+    let Some(tile) = tile.as_object_mut() else {
+        return;
+    };
+    let layout = tile
+        .entry("layout")
+        .or_insert_with(|| Value::Object(Map::new()));
+    let Value::Object(layout) = layout else {
+        return;
+    };
+    let missing =
+        |layout: &Map<String, Value>, key: &str| layout.get(key).is_none_or(Value::is_null);
+    if missing(layout, "w") {
+        layout.insert("w".to_owned(), DEFAULT_TILE_W.into());
+    }
+    if missing(layout, "h") {
+        layout.insert("h".to_owned(), DEFAULT_TILE_H.into());
+    }
+    if missing(layout, "x") {
+        layout.insert("x".to_owned(), 0.into());
+    }
+    if missing(layout, "y") {
+        let groups = section_groups(tiles, sections);
+        let peers = &group_for(&groups, &section).members;
+        layout.insert("y".to_owned(), append_y(tiles, peers).into());
+    }
+}
+
+fn section_entity(
+    root: &mut Map<String, Value>,
+    edit: Edit,
+    id: &str,
+    value: Option<&Value>,
+) -> Result<(), PatchError> {
+    if edit == Edit::Remove {
+        let referenced = root
+            .get("tiles")
+            .and_then(Value::as_array)
+            .map_or(0, |tiles| {
+                tiles
+                    .iter()
+                    .filter(|tile| tile.get("sectionId").and_then(Value::as_str) == Some(id))
+                    .count()
+            });
+        if referenced > 0 {
+            return Err(PatchError::new(
+                PatchErrorCode::InvalidOperation,
+                format!(
+                    "section `{id}` contains {referenced} tiles; use removeSection with an explicit tile disposition"
+                ),
+            ));
+        }
+    }
+    let (mut sections, slot) = take_array(root, "sections")?;
+    let result = (|| {
+        let found = find_section(&sections, id)?;
+        let matches = |field: &Value| field.as_str() == Some(id);
+        match edit {
+            Edit::Add => {
+                if found.is_some() {
+                    return Err(exists(format!("section `{id}`")));
+                }
+                sections.push(Value::Object(entity_value(
+                    value,
+                    "sectionId",
+                    matches,
+                    id,
+                )?));
+            }
+            Edit::Replace => {
+                let index = found.ok_or_else(|| not_found(format!("section `{id}`")))?;
+                sections[index] = Value::Object(entity_value(value, "sectionId", matches, id)?);
+            }
+            Edit::Remove => {
+                let index = found.ok_or_else(|| not_found(format!("section `{id}`")))?;
+                sections.remove(index);
+            }
+        }
+        Ok(())
+    })();
+    restore_array(root, "sections", sections, slot);
+    result
+}
+
+fn variable_entity(
+    root: &mut Map<String, Value>,
+    edit: Edit,
+    name: &str,
+    value: Option<&Value>,
+) -> Result<(), PatchError> {
+    let (mut variables, slot) = take_array(root, "variables")?;
+    let result = (|| {
+        let found = find_variable(&variables, name)?;
+        let matches = |field: &Value| field.as_str() == Some(name);
+        match edit {
+            Edit::Add => {
+                if found.is_some() {
+                    return Err(exists(format!("variable `{name}`")));
+                }
+                variables.push(Value::Object(entity_value(value, "name", matches, name)?));
+            }
+            Edit::Replace => {
+                let index = found.ok_or_else(|| not_found(format!("variable `{name}`")))?;
+                variables[index] = Value::Object(entity_value(value, "name", matches, name)?);
+            }
+            Edit::Remove => {
+                let index = found.ok_or_else(|| not_found(format!("variable `{name}`")))?;
+                variables.remove(index);
+            }
+        }
+        Ok(())
+    })();
+    restore_array(root, "variables", variables, slot);
+    result
+}
+
+// ---------------------------------------------------------------------------------------------
+// Layout (ports of frontend layout.ts; positions are indices into the tiles array)
+// ---------------------------------------------------------------------------------------------
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct Rect {
+    x: i64,
+    y: i64,
+    w: i64,
+    h: i64,
+}
+
+impl Rect {
+    fn overlaps(&self, other: &Rect) -> bool {
+        self.x < other.x + other.w
+            && self.x + self.w > other.x
+            && self.y < other.y + other.h
+            && self.y + self.h > other.y
+    }
+}
+
+#[derive(Debug, Clone, Copy, Default)]
+struct RawLayout {
+    x: Option<f64>,
+    y: Option<f64>,
+    w: Option<f64>,
+    h: Option<f64>,
+}
+
+impl RawLayout {
+    fn of(tile: &Value) -> Self {
+        let number = |key: &str| layout_number(tile, key);
+        Self {
+            x: number("x"),
+            y: number("y"),
+            w: number("w"),
+            h: number("h"),
+        }
+    }
+
+    fn from_rect(rect: Rect) -> Self {
+        Self {
+            x: Some(rect.x as f64),
+            y: Some(rect.y as f64),
+            w: Some(rect.w as f64),
+            h: Some(rect.h as f64),
+        }
+    }
+}
+
+fn layout_number(tile: &Value, key: &str) -> Option<f64> {
+    tile.get("layout")?.get(key)?.as_f64()
+}
+
+/// The frontend's `integer`: floor, then clamp; non-numbers take the fallback.
+fn clamp_int(value: Option<f64>, fallback: i64, min: i64, max: i64) -> i64 {
+    match value {
+        Some(value) => value.floor().max(min as f64).min(max as f64) as i64,
+        None => fallback,
+    }
+}
+
+fn resolved(items: &[(usize, RawLayout)]) -> Vec<(usize, Rect)> {
+    let mut bottom = items
+        .iter()
+        .filter_map(|(_, layout)| {
+            layout.y.map(|y| {
+                clamp_int(Some(y), 0, 0, MAX_TILE_ROW).saturating_add(clamp_int(
+                    layout.h,
+                    DEFAULT_TILE_H,
+                    1,
+                    UNBOUNDED,
+                ))
+            })
+        })
+        .fold(0, i64::max);
+    let mut rows: Vec<(usize, Rect)> = items
+        .iter()
+        .map(|&(index, layout)| {
+            let w = clamp_int(layout.w, DEFAULT_TILE_W, 1, GRID_COLUMNS);
+            let h = clamp_int(layout.h, DEFAULT_TILE_H, 1, UNBOUNDED);
+            let y = match layout.y {
+                Some(y) => clamp_int(Some(y), 0, 0, MAX_TILE_ROW),
+                None => {
+                    let y = bottom;
+                    bottom = bottom.saturating_add(h);
+                    y
+                }
+            };
+            let x = clamp_int(layout.x, 0, 0, GRID_COLUMNS - w);
+            (index, Rect { x, y, w, h })
+        })
+        .collect();
+    rows.sort_by_key(|(_, rect)| (rect.y, rect.x));
+    rows
+}
+
+/// RGL vertical compaction: push collisions down in reading order, then raise each item until
+/// it touches a blocker.
+fn compact(items: &[(usize, RawLayout)]) -> Vec<(usize, Rect)> {
+    let mut placed: Vec<(usize, Rect)> = Vec::with_capacity(items.len());
+    for (index, mut rect) in resolved(items) {
+        while let Some(&(_, blocker)) = placed.iter().find(|(_, other)| rect.overlaps(other)) {
+            rect.y = blocker.y + blocker.h;
+        }
+        rect.y = placed.iter().fold(0, |y, (_, other)| {
+            if other.y + other.h <= rect.y
+                && rect.x < other.x + other.w
+                && rect.x + rect.w > other.x
+            {
+                y.max(other.y + other.h)
+            } else {
+                y
+            }
+        });
+        placed.push((index, rect));
+    }
+    placed.sort_by_key(|(_, rect)| (rect.y, rect.x));
+    placed
+}
+
+struct Group {
+    id: String,
+    members: Vec<usize>,
+}
+
+/// Classic grouping: the unsectioned grid (id "") first, then each first-seen section id;
+/// tiles naming an unknown section join the unsectioned grid.
+fn section_groups(tiles: &[Value], sections: &[Value]) -> Vec<Group> {
+    let mut groups = vec![Group {
+        id: String::new(),
+        members: Vec::new(),
+    }];
+    let mut by_id: HashMap<&str, usize> = HashMap::new();
+    for id in sections.iter().filter_map(section_id) {
+        if !by_id.contains_key(id) {
+            by_id.insert(id, groups.len());
+            groups.push(Group {
+                id: id.to_owned(),
+                members: Vec::new(),
+            });
+        }
+    }
+    for (index, tile) in tiles.iter().enumerate() {
+        let group = tile
+            .get("sectionId")
+            .and_then(Value::as_str)
+            .and_then(|id| by_id.get(id).copied())
+            .unwrap_or(0);
+        groups[group].members.push(index);
+    }
+    groups
+}
+
+fn members_of(groups: &[Group], index: usize) -> &[usize] {
+    groups
+        .iter()
+        .find(|group| group.members.contains(&index))
+        .map_or(&[], |group| group.members.as_slice())
+}
+
+fn group_for<'a>(groups: &'a [Group], id: &str) -> &'a Group {
+    groups
+        .iter()
+        .skip(1)
+        .find(|group| group.id == id)
+        .unwrap_or(&groups[0])
+}
+
+fn layout_items(tiles: &[Value], members: &[usize]) -> Vec<(usize, RawLayout)> {
+    members
+        .iter()
+        .map(|&index| (index, RawLayout::of(&tiles[index])))
+        .collect()
+}
+
+fn append_y(tiles: &[Value], members: &[usize]) -> i64 {
+    resolved(&layout_items(tiles, members))
+        .iter()
+        .map(|(_, rect)| rect.y.saturating_add(rect.h))
+        .max()
+        .unwrap_or(0)
+}
+
+fn set_layout(tile: &mut Value, fields: impl IntoIterator<Item = (&'static str, Value)>) {
+    let Some(tile) = tile.as_object_mut() else {
+        return;
+    };
+    let layout = tile.entry("layout").or_insert(Value::Null);
+    if !layout.is_object() {
+        *layout = Value::Object(Map::new());
+    }
+    if let Value::Object(layout) = layout {
+        for (key, value) in fields {
+            layout.insert(key.to_owned(), value);
+        }
+    }
+}
+
+fn set_section_id(tile: &mut Value, section: Option<&str>) {
+    if let Some(tile) = tile.as_object_mut() {
+        match section {
+            Some(id) => {
+                tile.insert("sectionId".to_owned(), Value::String(id.to_owned()));
+            }
+            None => {
+                tile.remove("sectionId");
+            }
+        }
+    }
+}
+
+/// Compaction changes rows only; untouched columns, sizes and extras are never normalized.
+fn write_positions(tiles: &mut [Value], positions: &[(usize, Rect)]) {
+    for &(index, rect) in positions {
+        if layout_number(&tiles[index], "y") != Some(rect.y as f64) {
+            set_layout(&mut tiles[index], [("y", Value::from(rect.y))]);
+        }
+    }
+}
+
+fn compact_section(tiles: &mut [Value], sections: &[Value], index: usize) {
+    let groups = section_groups(tiles, sections);
+    let positions = compact(&layout_items(tiles, members_of(&groups, index)));
+    write_positions(tiles, &positions);
+}
+
+fn check_range(key: &str, value: Option<i64>, min: i64, max: i64) -> Result<(), PatchError> {
+    match value {
+        Some(value) if value < min || value > max => Err(PatchError::new(
+            PatchErrorCode::InvalidValue,
+            format!("layout `{key}` must be between {min} and {max}"),
+        )
+        .path(format!("/layout/{key}"))),
+        _ => Ok(()),
+    }
+}
+
+/// Port of updateTileLayout within the tile's section: the edited tile takes priority at its
+/// destination, collisions move down and the result compacts.
+fn update_tile_layout(
+    tiles: &mut [Value],
+    sections: &[Value],
+    index: usize,
+    edits: &LayoutEdits,
+) -> Result<(), PatchError> {
+    let groups = section_groups(tiles, sections);
+    let members = members_of(&groups, index).to_vec();
+    let items = layout_items(tiles, &members);
+    let active = compact(&items)
+        .into_iter()
+        .find(|(member, _)| *member == index)
+        .map(|(_, rect)| rect)
+        .unwrap_or(Rect {
+            x: 0,
+            y: 0,
+            w: DEFAULT_TILE_W,
+            h: DEFAULT_TILE_H,
+        });
+    check_range("w", edits.w, 1, GRID_COLUMNS)?;
+    check_range("h", edits.h, 1, MAX_TILE_HEIGHT)?;
+    check_range("y", edits.y, 0, MAX_TILE_ROW)?;
+    let w = edits.w.unwrap_or(active.w);
+    check_range("x", edits.x, 0, GRID_COLUMNS - w)?;
+    let target = Rect {
+        x: edits.x.unwrap_or(active.x.min(GRID_COLUMNS - w)),
+        y: edits.y.unwrap_or(active.y),
+        w,
+        h: edits.h.unwrap_or(active.h),
+    };
+    let differs = |edit: Option<i64>, current: i64| matches!(edit, Some(value) if value != current);
+    // A zero-distance gesture must not normalize the document.
+    if !(differs(edits.x, active.x)
+        || differs(edits.y, active.y)
+        || differs(edits.w, active.w)
+        || differs(edits.h, active.h))
+    {
+        return Ok(());
+    }
+    let mut placed = vec![(index, target)];
+    let others: Vec<(usize, RawLayout)> = items
+        .iter()
+        .copied()
+        .filter(|(member, _)| *member != index)
+        .collect();
+    for (member, mut rect) in compact(&others) {
+        while let Some(&(_, blocker)) = placed.iter().find(|(_, other)| rect.overlaps(other)) {
+            rect.y = blocker.y + blocker.h;
+        }
+        placed.push((member, rect));
+    }
+    let normalized: HashMap<usize, Rect> = compact(
+        &placed
+            .iter()
+            .map(|&(member, rect)| (member, RawLayout::from_rect(rect)))
+            .collect::<Vec<_>>(),
+    )
+    .into_iter()
+    .collect();
+    for &member in &members {
+        let rect = normalized[&member];
+        if member != index {
+            if layout_number(&tiles[member], "y") != Some(rect.y as f64) {
+                set_layout(&mut tiles[member], [("y", Value::from(rect.y))]);
+            }
+            continue;
+        }
+        let mut patch = vec![("y", Value::from(rect.y))];
+        if edits.x.is_some() || (edits.w.is_some() && target.x != active.x) {
+            patch.push(("x", Value::from(rect.x)));
+        }
+        if edits.w.is_some() {
+            patch.push(("w", Value::from(rect.w)));
+        }
+        if edits.h.is_some() {
+            patch.push(("h", Value::from(rect.h)));
+        }
+        set_layout(&mut tiles[member], patch);
+    }
+    Ok(())
+}
+
+/// Port of relocateTile plus applyTile's compaction of the section the tile left.
+fn relocate_tile(tiles: &mut [Value], sections: &[Value], index: usize, destination: Option<&str>) {
+    let neighbour = {
+        let groups = section_groups(tiles, sections);
+        members_of(&groups, index)
+            .iter()
+            .copied()
+            .find(|member| *member != index)
+    };
+    set_section_id(&mut tiles[index], destination);
+    let groups = section_groups(tiles, sections);
+    let peers: Vec<usize> = group_for(&groups, destination.unwrap_or(""))
+        .members
+        .iter()
+        .copied()
+        .filter(|member| *member != index)
+        .collect();
+    let y = append_y(tiles, &peers);
+    let stored = |key: &str, fallback: i64| {
+        tiles[index]
+            .get("layout")
+            .and_then(|layout| layout.get(key))
+            .filter(|value| !value.is_null())
+            .cloned()
+            .unwrap_or_else(|| fallback.into())
+    };
+    let (w, h) = (stored("w", DEFAULT_TILE_W), stored("h", DEFAULT_TILE_H));
+    set_layout(
+        &mut tiles[index],
+        [
+            ("x", Value::from(0)),
+            ("y", Value::from(y)),
+            ("w", w),
+            ("h", h),
+        ],
+    );
+    compact_section(tiles, sections, index);
+    if let Some(neighbour) = neighbour {
+        compact_section(tiles, sections, neighbour);
+    }
+}
+
+fn place_tile(
+    document: &mut Value,
+    tile_id: &str,
+    section: Option<&Option<String>>,
+    edits: Option<&LayoutEdits>,
+) -> Result<(), PatchError> {
+    let id = tile_target(tile_id)?;
+    let root = root_mut(document)?;
+    with_tiles(root, |tiles, sections| {
+        let index = require_tile(tiles, id)?;
+        let mut relocated = false;
+        if let Some(section) = section {
+            let destination = section.as_deref().filter(|id| !id.is_empty());
+            if let Some(destination) = destination
+                && !has_section(sections, destination)
+            {
+                return Err(not_found(format!("section `{destination}`")).target(
+                    PatchTarget::Section {
+                        id: destination.to_owned(),
+                    },
+                ));
+            }
+            let current = tiles[index]
+                .get("sectionId")
+                .and_then(Value::as_str)
+                .unwrap_or("");
+            if current != destination.unwrap_or("") {
+                relocate_tile(tiles, sections, index, destination);
+                relocated = true;
+            }
+        }
+        match edits.filter(|edits| !edits.is_empty()) {
+            Some(edits) => update_tile_layout(tiles, sections, index, edits)?,
+            None if !relocated => compact_section(tiles, sections, index),
+            None => {}
+        }
+        Ok(())
+    })
+}
+
+// ---------------------------------------------------------------------------------------------
+// Sections and variables
+// ---------------------------------------------------------------------------------------------
+
+fn reorder_sections(document: &mut Value, ids: &[String]) -> Result<(), PatchError> {
+    let root = root_mut(document)?;
+    let sections = match root.get_mut("sections") {
+        Some(Value::Array(sections)) => sections,
+        None | Some(Value::Null) if ids.is_empty() => return Ok(()),
+        _ => return Err(not_found("a sections array".to_owned()).target(PatchTarget::Dashboard)),
+    };
+    // Later duplicates and malformed entries are not addressable and keep their slots.
+    let mut seen = HashSet::new();
+    let mut slots = Vec::new();
+    for (index, section) in sections.iter().enumerate() {
+        if let Some(id) = section_id(section)
+            && seen.insert(id.to_owned())
+        {
+            slots.push(index);
+        }
+    }
+    let mut requested = HashSet::new();
+    for id in ids {
+        if !seen.contains(id) {
+            return Err(not_found(format!("section `{id}`"))
+                .target(PatchTarget::Section { id: id.clone() }));
+        }
+        if !requested.insert(id) {
+            return Err(PatchError::new(
+                PatchErrorCode::InvalidOperation,
+                format!("section `{id}` is listed more than once"),
+            ));
+        }
+    }
+    if ids.len() != slots.len() {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidOperation,
+            format!(
+                "sectionIds must list all {} sections exactly once; got {}",
+                slots.len(),
+                ids.len()
+            ),
+        ));
+    }
+    let mut by_id: HashMap<String, Value> = slots
+        .iter()
+        .map(|&slot| {
+            let section = std::mem::take(&mut sections[slot]);
+            (section_id(&section).unwrap_or_default().to_owned(), section)
+        })
+        .collect();
+    for (&slot, id) in slots.iter().zip(ids) {
+        sections[slot] = by_id.remove(id).unwrap_or_default();
+    }
+    Ok(())
+}
+
+/// Port of sections.ts removeSection, plus explicit delete and move dispositions.
+fn remove_section(
+    document: &mut Value,
+    id: &str,
+    disposition: &TileDisposition,
+) -> Result<(), PatchError> {
+    section_target(id)?;
+    let root = root_mut(document)?;
+    let sections: &[Value] = root
+        .get("sections")
+        .and_then(Value::as_array)
+        .map(Vec::as_slice)
+        .unwrap_or(&[]);
+    if !has_section(sections, id) {
+        return Err(not_found(format!("section `{id}`")));
+    }
+    let destination = match disposition {
+        TileDisposition::Move { section_id } => {
+            if section_id == id {
+                return Err(PatchError::new(
+                    PatchErrorCode::InvalidOperation,
+                    "tiles cannot move into the section being removed",
+                ));
+            }
+            if !has_section(sections, section_id) {
+                return Err(not_found(format!("section `{section_id}`")).target(
+                    PatchTarget::Section {
+                        id: section_id.clone(),
+                    },
+                ));
+            }
+            Some(section_id.as_str())
+        }
+        _ => None,
+    };
+    with_tiles(root, |tiles, sections| {
+        let in_section = |tile: &Value| tile.get("sectionId").and_then(Value::as_str) == Some(id);
+        if *disposition == TileDisposition::Delete {
+            tiles.retain(|tile| !in_section(tile));
+            return Ok(());
+        }
+        let groups = section_groups(tiles, sections);
+        let mut members = group_for(&groups, destination.unwrap_or(""))
+            .members
+            .clone();
+        for index in 0..tiles.len() {
+            if !in_section(&tiles[index]) {
+                continue;
+            }
+            let size = |key: &str, fallback: i64| {
+                tiles[index]
+                    .get("layout")
+                    .and_then(|layout| layout.get(key))
+                    .filter(|value| value.is_number())
+                    .cloned()
+                    .unwrap_or_else(|| fallback.into())
+            };
+            let (w, h) = (size("w", DEFAULT_TILE_W), size("h", DEFAULT_TILE_H));
+            let y = append_y(tiles, &members);
+            set_section_id(&mut tiles[index], destination);
+            set_layout(
+                &mut tiles[index],
+                [
+                    ("x", Value::from(0)),
+                    ("y", Value::from(y)),
+                    ("w", w),
+                    ("h", h),
+                ],
+            );
+            members.push(index);
+        }
+        Ok(())
+    })?;
+    if let Some(Value::Array(sections)) = root.get_mut("sections") {
+        sections.retain(|section| section_id(section) != Some(id));
+    }
+    Ok(())
+}
+
+/// Byte ranges of the names in `$name` and `${name}` tokens (JS `\$\{?(\w+)\}?`).
+fn token_spans(text: &str) -> Vec<(usize, usize)> {
+    let bytes = text.as_bytes();
+    let mut spans = Vec::new();
+    let mut i = 0;
+    while i < bytes.len() {
+        if bytes[i] == b'$' {
+            let start = if bytes.get(i + 1) == Some(&b'{') {
+                i + 2
+            } else {
+                i + 1
+            };
+            let mut end = start;
+            while end < bytes.len() && (bytes[end].is_ascii_alphanumeric() || bytes[end] == b'_') {
+                end += 1;
+            }
+            if end > start {
+                spans.push((start, end));
+                i = end;
+                continue;
+            }
+        }
+        i += 1;
+    }
+    spans
+}
+
+fn referenced_names(text: &str) -> impl Iterator<Item = &str> {
+    token_spans(text)
+        .into_iter()
+        .map(move |(start, end)| &text[start..end])
+}
+
+fn rename_tokens(text: &str, from: &str, to: &str) -> Option<String> {
+    let spans: Vec<_> = token_spans(text)
+        .into_iter()
+        .filter(|&(start, end)| &text[start..end] == from)
+        .collect();
+    if spans.is_empty() {
+        return None;
+    }
+    let mut renamed = String::with_capacity(text.len() + spans.len() * to.len());
+    let mut last = 0;
+    for (start, end) in spans {
+        renamed.push_str(&text[last..start]);
+        renamed.push_str(to);
+        last = end;
+    }
+    renamed.push_str(&text[last..]);
+    Some(renamed)
+}
+
+fn rename_value(value: &mut Value, from: &str, to: &str) {
+    match value {
+        Value::String(text) => {
+            if let Some(renamed) = rename_tokens(text, from, to) {
+                *text = renamed;
+            }
+        }
+        Value::Array(items) => items
+            .iter_mut()
+            .for_each(|item| rename_value(item, from, to)),
+        Value::Object(map) => map
+            .values_mut()
+            .for_each(|item| rename_value(item, from, to)),
+        _ => {}
+    }
+}
+
+fn rename_variable(document: &mut Value, from: &str, to: &str) -> Result<(), PatchError> {
+    variable_target(from)?;
+    if !is_variable_name(to) {
+        return Err(PatchError::new(
+            PatchErrorCode::InvalidValue,
+            format!("variable name `{to}` must match ^\\w+$ (at most {MAX_ID_BYTES} bytes)"),
+        ));
+    }
+    let root = root_mut(document)?;
+    {
+        let variables =
+            array_mut(root, "variables").map_err(|_| not_found(format!("variable `{from}`")))?;
+        let index = find_variable(variables, from)?
+            .ok_or_else(|| not_found(format!("variable `{from}`")))?;
+        if from == to {
+            return Ok(());
+        }
+        if variables
+            .iter()
+            .any(|variable| variable_name(variable) == Some(to))
+        {
+            return Err(PatchError::new(
+                PatchErrorCode::NameConflict,
+                format!("a variable named `{to}` already exists"),
+            )
+            .target(PatchTarget::Variable {
+                name: to.to_owned(),
+            }));
+        }
+        for (position, variable) in variables.iter_mut().enumerate() {
+            let Some(variable) = variable.as_object_mut() else {
+                continue;
+            };
+            if position == index {
+                variable.insert("name".to_owned(), Value::String(to.to_owned()));
+                continue;
+            }
+            for key in VARIABLE_SOURCES {
+                if let Some(Value::String(text)) = variable.get_mut(*key)
+                    && let Some(renamed) = rename_tokens(text, from, to)
+                {
+                    *text = renamed;
+                }
+            }
+            if let Some(Value::Array(filters)) = variable.get_mut("labelFilters") {
+                for filter in filters {
+                    if let Some(Value::String(text)) = filter.get_mut("value")
+                        && let Some(renamed) = rename_tokens(text, from, to)
+                    {
+                        *text = renamed;
+                    }
+                }
+            }
+        }
+    }
+    if let Some(Value::Array(tiles)) = root.get_mut("tiles") {
+        for tile in tiles.iter_mut().filter_map(Value::as_object_mut) {
+            for key in ["chartQuery", "dbName"] {
+                if let Some(value) = tile.get_mut(key) {
+                    rename_value(value, from, to);
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------------------------
+
+/// One structural problem in a dashboard document. `path` is relative to `target`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ValidationIssue {
+    pub code: String,
+    pub message: String,
+    pub target: PatchTarget,
+    pub path: String,
+    /// The same defect, at the same value, was already present in the base document.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub legacy: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ValidationReport {
+    pub valid: bool,
+    pub errors: Vec<ValidationIssue>,
+    pub warnings: Vec<ValidationIssue>,
+}
+
+struct Finding {
+    issue: ValidationIssue,
+    /// Advisory findings are always warnings.
+    advisory: bool,
+    /// The offending value(s); a legacy defect matches only when this is unchanged.
+    detail: String,
+}
+
+type FindingKey = (String, PatchTarget, String, String);
+
+impl Finding {
+    fn key(&self) -> FindingKey {
+        (
+            self.issue.code.clone(),
+            self.issue.target.clone(),
+            self.issue.path.clone(),
+            self.detail.clone(),
+        )
+    }
+}
+
+/// Structural validation of a final candidate. Executes no queries and probes no datasets.
+///
+/// With a `base`, a defect already present in the base at the same target, path and value is
+/// reported as a legacy warning, so untouched legacy content never blocks unrelated edits while
+/// new or changed defects are errors. Unknown fields are preserved and not validated.
+pub fn validate_dashboard(candidate: &Value, base: Option<&Value>) -> ValidationReport {
+    // Growth past the limits is rejected before any per-entity work, bounding validation cost.
+    let mut limits = Checker::default();
+    check_limits(&mut limits, candidate, base);
+    if !limits.findings.is_empty() {
+        let errors: Vec<ValidationIssue> = limits
+            .findings
+            .into_iter()
+            .map(|finding| finding.issue)
+            .collect();
+        return ValidationReport {
+            valid: false,
+            errors,
+            warnings: Vec::new(),
+        };
+    }
+    let mut findings = check_document(candidate);
+    if let Some(base) = base {
+        // A multiset: each base occurrence grandfathers one candidate occurrence, so adding
+        // another copy of a legacy defect (such as a third duplicate id) is still an error.
+        let mut legacy: HashMap<FindingKey, usize> = HashMap::new();
+        for finding in check_document(base)
+            .iter()
+            .filter(|finding| !finding.advisory)
+        {
+            *legacy.entry(finding.key()).or_default() += 1;
+        }
+        for finding in findings.iter_mut().filter(|finding| !finding.advisory) {
+            if let Some(remaining) = legacy.get_mut(&finding.key()).filter(|count| **count > 0) {
+                *remaining -= 1;
+                finding.issue.legacy = true;
+            }
+        }
+    }
+    let mut checker = Checker { findings };
+    check_reserved(&mut checker, candidate, base);
+    if let Some(base) = base {
+        check_removed_variables(&mut checker, candidate, base);
+    }
+    let mut report = ValidationReport::default();
+    for finding in checker.findings {
+        if finding.advisory || finding.issue.legacy {
+            report.warnings.push(finding.issue);
+        } else {
+            report.errors.push(finding.issue);
+        }
+    }
+    report.valid = report.errors.is_empty();
+    report
+}
+
+#[derive(Clone, Copy)]
+enum Shape {
+    String,
+    Bool,
+    Number,
+    PositiveNumber,
+    Strings,
+    StringOrStrings,
+}
+
+impl Shape {
+    fn accepts(self, value: &Value) -> bool {
+        match self {
+            Shape::String => value.is_string(),
+            Shape::Bool => value.is_boolean(),
+            Shape::Number => value.is_number(),
+            Shape::PositiveNumber => value.as_f64().is_some_and(|number| number > 0.0),
+            Shape::Strings => value
+                .as_array()
+                .is_some_and(|items| items.iter().all(Value::is_string)),
+            Shape::StringOrStrings => value.is_string() || Shape::Strings.accepts(value),
+        }
+    }
+
+    fn describe(self) -> &'static str {
+        match self {
+            Shape::String => "a string",
+            Shape::Bool => "a boolean",
+            Shape::Number => "a number",
+            Shape::PositiveNumber => "a positive number",
+            Shape::Strings => "an array of strings",
+            Shape::StringOrStrings => "a string or an array of strings",
+        }
+    }
+}
+
+fn detail(value: Option<&Value>) -> String {
+    value.map(Value::to_string).unwrap_or_default()
+}
+
+fn present(map: &Map<String, Value>, key: &str) -> Option<Value> {
+    map.get(key).filter(|value| !value.is_null()).cloned()
+}
+
+#[derive(Default)]
+struct Checker {
+    findings: Vec<Finding>,
+}
+
+impl Checker {
+    fn report(
+        &mut self,
+        advisory: bool,
+        code: &str,
+        target: &PatchTarget,
+        path: impl Into<String>,
+        detail: String,
+        message: impl Into<String>,
+    ) {
+        self.findings.push(Finding {
+            issue: ValidationIssue {
+                code: code.to_owned(),
+                message: message.into(),
+                target: target.clone(),
+                path: path.into(),
+                legacy: false,
+            },
+            advisory,
+            detail,
+        });
+    }
+
+    fn error(
+        &mut self,
+        code: &str,
+        target: &PatchTarget,
+        path: impl Into<String>,
+        detail: String,
+        message: impl Into<String>,
+    ) {
+        self.report(false, code, target, path, detail, message);
+    }
+
+    fn advise(
+        &mut self,
+        code: &str,
+        target: &PatchTarget,
+        path: impl Into<String>,
+        detail: String,
+        message: impl Into<String>,
+    ) {
+        self.report(true, code, target, path, detail, message);
+    }
+
+    /// Null and absent are always accepted for optional fields.
+    fn field(
+        &mut self,
+        target: &PatchTarget,
+        prefix: &str,
+        map: &Map<String, Value>,
+        key: &str,
+        shape: Shape,
+    ) {
+        if let Some(value) = map.get(key).filter(|value| !value.is_null())
+            && !shape.accepts(value)
+        {
+            self.error(
+                "invalid_field_type",
+                target,
+                join(prefix, key),
+                value.to_string(),
+                format!("`{key}` must be {}", shape.describe()),
+            );
+        }
+    }
+
+    fn one_of(
+        &mut self,
+        code: &str,
+        target: &PatchTarget,
+        prefix: &str,
+        map: &Map<String, Value>,
+        key: &str,
+        allowed: &[&str],
+    ) {
+        if let Some(value) = map.get(key).filter(|value| !value.is_null())
+            && !value.as_str().is_some_and(|value| allowed.contains(&value))
+        {
+            self.error(
+                code,
+                target,
+                join(prefix, key),
+                value.to_string(),
+                format!("`{key}` must be one of: {}", allowed.join(", ")),
+            );
+        }
+    }
+
+    fn object<'a>(
+        &mut self,
+        target: &PatchTarget,
+        prefix: &str,
+        map: &'a Map<String, Value>,
+        key: &str,
+    ) -> Option<&'a Map<String, Value>> {
+        match map.get(key) {
+            None | Some(Value::Null) => None,
+            Some(Value::Object(object)) => Some(object),
+            Some(other) => {
+                self.error(
+                    "invalid_field_type",
+                    target,
+                    join(prefix, key),
+                    other.to_string(),
+                    format!("`{key}` must be an object"),
+                );
+                None
+            }
+        }
+    }
+}
+
+fn check_document(document: &Value) -> Vec<Finding> {
+    let mut c = Checker::default();
+    let d = PatchTarget::Dashboard;
+    let Some(root) = document.as_object() else {
+        c.error(
+            "invalid_document",
+            &d,
+            "",
+            String::new(),
+            "a dashboard must be a JSON object",
+        );
+        return c.findings;
+    };
+    if let Err(error) = Dashboard::deserialize(document) {
+        c.error(
+            "incompatible_document",
+            &d,
+            "",
+            String::new(),
+            format!("the document does not match the stored dashboard shape: {error}"),
+        );
+    }
+    match root.get("title") {
+        Some(Value::String(title)) if !title.trim().is_empty() => {}
+        Some(Value::String(_)) => c.error(
+            "empty_title",
+            &d,
+            "/title",
+            String::new(),
+            "`title` must not be blank",
+        ),
+        other => c.error(
+            "invalid_field_type",
+            &d,
+            "/title",
+            detail(other),
+            "`title` must be a string",
+        ),
+    }
+    c.field(&d, "", root, "tags", Shape::Strings);
+    c.field(&d, "", root, "isFavorite", Shape::Bool);
+    c.field(&d, "", root, "description", Shape::String);
+    c.field(&d, "", root, "dataset", Shape::String);
+    c.one_of(
+        "invalid_field_value",
+        &d,
+        "",
+        root,
+        "dashboardType",
+        DASHBOARD_TYPES,
+    );
+    check_time_range(&mut c, root);
+    if let Some(value) = root.get("refreshInterval").filter(|value| !value.is_null())
+        && !value
+            .as_u64()
+            .is_some_and(|ms| REFRESH_INTERVALS.contains(&ms))
+    {
+        c.error(
+            "invalid_refresh_interval",
+            &d,
+            "/refreshInterval",
+            value.to_string(),
+            "`refreshInterval` must be one of 0, 15000, 30000, 60000 or 300000 milliseconds",
+        );
+    }
+    let sections = collection(&mut c, root, "sections");
+    let variables = collection(&mut c, root, "variables");
+    let tiles = collection(&mut c, root, "tiles");
+    let section_ids = check_sections(&mut c, sections);
+    check_variables(&mut c, variables);
+    check_tiles(&mut c, tiles, &section_ids);
+    c.findings
+}
+
+/// Over-limit documents may shrink or stay the same size, but never grow (also for full PUTs).
+fn check_limits(c: &mut Checker, candidate: &Value, base: Option<&Value>) {
+    let count = |document: Option<&Value>, key: &str| {
+        document
+            .and_then(|document| document.get(key))
+            .and_then(Value::as_array)
+            .map_or(0, Vec::len)
+    };
+    for (key, limit) in [
+        ("tiles", MAX_TILES),
+        ("sections", MAX_SECTIONS),
+        ("variables", MAX_VARIABLES),
+    ] {
+        let after = count(Some(candidate), key);
+        if after > limit && after > count(base, key) {
+            c.error(
+                "limit_exceeded",
+                &PatchTarget::Dashboard,
+                join("", key),
+                after.to_string(),
+                format!("a dashboard may contain at most {limit} {key}"),
+            );
+        }
+    }
+    let size = json_len(candidate);
+    if size > MAX_DOCUMENT_BYTES && base.is_none_or(|base| size > json_len(base)) {
+        c.error(
+            "document_too_large",
+            &PatchTarget::Dashboard,
+            "",
+            size.to_string(),
+            format!("a dashboard may be at most {MAX_DOCUMENT_BYTES} bytes of JSON"),
+        );
+    }
+}
+
+fn collection<'a>(c: &mut Checker, root: &'a Map<String, Value>, key: &str) -> &'a [Value] {
+    match root.get(key) {
+        None | Some(Value::Null) => &[],
+        // Size limits depend on the base and are checked by `check_limits`.
+        Some(Value::Array(items)) => items,
+        Some(other) => {
+            c.error(
+                "invalid_collection",
+                &PatchTarget::Dashboard,
+                join("", key),
+                other.to_string(),
+                format!("`{key}` must be an array"),
+            );
+            &[]
+        }
+    }
+}
+
+fn check_time_range(c: &mut Checker, root: &Map<String, Value>) {
+    let d = PatchTarget::Dashboard;
+    let Some(range) = c.object(&d, "", root, "timeRange") else {
+        return;
+    };
+    let p = "/timeRange";
+    for key in ["startTime", "endTime"] {
+        if !range.get(key).is_some_and(Value::is_string) {
+            c.error(
+                "invalid_time_range",
+                &d,
+                join(p, key),
+                detail(range.get(key)),
+                format!("`timeRange.{key}` must be a string"),
+            );
+        }
+    }
+    c.field(&d, p, range, "label", Shape::String);
+    c.field(&d, p, range, "interval", Shape::Number);
+    c.field(&d, p, range, "shiftInterval", Shape::Number);
+    c.one_of("invalid_time_range", &d, p, range, "type", TIME_RANGE_TYPES);
+    let start = range.get("startTime").and_then(Value::as_str);
+    match range.get("type").and_then(Value::as_str) {
+        Some("fixed") => {
+            if start.is_some_and(|start| !TIME_RANGE_PRESETS.contains(&start)) {
+                c.advise(
+                    "unknown_time_preset",
+                    &d,
+                    join(p, "startTime"),
+                    detail(range.get("startTime")),
+                    format!(
+                        "fixed ranges the dashboard UI offers are: {}",
+                        TIME_RANGE_PRESETS.join(", ")
+                    ),
+                );
+            }
+        }
+        Some("custom") => {
+            // The frontend resolves only endTime "now"; anything else unparseable silently
+            // falls back to the last hour, so concrete bounds must parse and be ordered.
+            let bound = |key: &str| {
+                let text = range.get(key).and_then(Value::as_str)?;
+                if key == "endTime" && text == "now" {
+                    return Some(None);
+                }
+                chrono::DateTime::parse_from_rfc3339(text).ok().map(Some)
+            };
+            let (start, end) = (bound("startTime"), bound("endTime"));
+            for (key, parsed) in [("startTime", start), ("endTime", end)] {
+                if range.get(key).is_some_and(Value::is_string) && parsed.is_none() {
+                    c.error(
+                        "invalid_time_range",
+                        &d,
+                        join(p, key),
+                        detail(range.get(key)),
+                        if key == "endTime" {
+                            "custom `timeRange.endTime` must be an RFC 3339 timestamp or \"now\""
+                        } else {
+                            "custom `timeRange.startTime` must be an RFC 3339 timestamp"
+                        },
+                    );
+                }
+            }
+            if let (Some(Some(start)), Some(Some(end))) = (start, end)
+                && start >= end
+            {
+                c.error(
+                    "invalid_time_range",
+                    &d,
+                    join(p, "startTime"),
+                    json!([range.get("startTime"), range.get("endTime")]).to_string(),
+                    "custom `timeRange.startTime` must be before `endTime`",
+                );
+            }
+        }
+        _ => {}
+    }
+}
+
+fn check_sections<'a>(c: &mut Checker, sections: &'a [Value]) -> HashSet<&'a str> {
+    let mut ids = HashSet::new();
+    for (index, section) in sections.iter().enumerate() {
+        let at = format!("/sections/{index}");
+        let Some(map) = section.as_object() else {
+            c.error(
+                "invalid_section",
+                &PatchTarget::Dashboard,
+                at,
+                section.to_string(),
+                "a section must be an object",
+            );
+            continue;
+        };
+        let id = match map.get("sectionId") {
+            Some(Value::String(id)) if !id.is_empty() && id.len() <= MAX_ID_BYTES => id.as_str(),
+            other => {
+                c.error(
+                    "invalid_section_id",
+                    &PatchTarget::Dashboard,
+                    join(&at, "sectionId"),
+                    detail(other),
+                    format!(
+                        "`sectionId` must be a non-empty string of at most {MAX_ID_BYTES} bytes"
+                    ),
+                );
+                continue;
+            }
+        };
+        let target = PatchTarget::Section { id: id.to_owned() };
+        if !ids.insert(id) {
+            c.error(
+                "duplicate_section_id",
+                &target,
+                "/sectionId",
+                id.to_owned(),
+                format!("section id `{id}` is used more than once"),
+            );
+        }
+        c.field(&target, "", map, "title", Shape::String);
+        c.field(&target, "", map, "collapsed", Shape::Bool);
+        c.field(&target, "", map, "isExpanded", Shape::Bool);
+    }
+    ids
+}
+
+/// The text the option loader interpolates, by variable type (variables.ts variableSource).
+fn variable_source(variable: &Map<String, Value>) -> String {
+    let text = |key: &str| variable.get(key).and_then(Value::as_str).unwrap_or("");
+    match variable.get("type").and_then(Value::as_str) {
+        Some("sql") => text("sqlQuery").to_owned(),
+        Some("promql_query") => format!("{} {}", text("promqlQuery"), text("promqlQueryDataset")),
+        Some("promql") => {
+            let mut source = text("dataset").to_owned();
+            if let Some(filters) = variable.get("labelFilters").and_then(Value::as_array) {
+                for value in filters
+                    .iter()
+                    .filter_map(|filter| filter.get("value")?.as_str())
+                {
+                    source.push(' ');
+                    source.push_str(value);
+                }
+            }
+            source
+        }
+        _ => String::new(),
+    }
+}
+
+fn check_variables(c: &mut Checker, variables: &[Value]) {
+    let mut names = HashSet::new();
+    let mut readable: Vec<(&str, &Map<String, Value>)> = Vec::new();
+    for (index, variable) in variables.iter().enumerate() {
+        let at = format!("/variables/{index}");
+        let Some(map) = variable.as_object() else {
+            c.error(
+                "invalid_variable",
+                &PatchTarget::Dashboard,
+                at,
+                variable.to_string(),
+                "a variable must be an object",
+            );
+            continue;
+        };
+        let name = match map.get("name") {
+            Some(Value::String(name)) if is_variable_name(name) => name.as_str(),
+            other => {
+                c.error(
+                    "invalid_variable_name",
+                    &PatchTarget::Dashboard,
+                    join(&at, "name"),
+                    detail(other),
+                    "variable `name` must match ^\\w+$",
+                );
+                continue;
+            }
+        };
+        let target = PatchTarget::Variable {
+            name: name.to_owned(),
+        };
+        if !names.insert(name) {
+            c.error(
+                "duplicate_variable_name",
+                &target,
+                "/name",
+                name.to_owned(),
+                format!("variable name `{name}` is used more than once"),
+            );
+        }
+        if !map.get("label").is_some_and(Value::is_string) {
+            c.error(
+                "invalid_field_type",
+                &target,
+                "/label",
+                detail(map.get("label")),
+                "variable `label` must be a string",
+            );
+        }
+        let kind = map.get("type").and_then(Value::as_str);
+        let Some(kind) = kind.filter(|kind| VARIABLE_TYPES.contains(kind)) else {
+            c.error(
+                "unsupported_variable_type",
+                &target,
+                "/type",
+                detail(map.get("type")),
+                format!(
+                    "variable `type` must be one of: {}",
+                    VARIABLE_TYPES.join(", ")
+                ),
+            );
+            continue;
+        };
+        for key in [
+            "dataset",
+            "labelName",
+            "metric",
+            "sqlQuery",
+            "promqlQuery",
+            "promqlQueryDataset",
+            "promqlQueryLabel",
+            "defaultValue",
+        ] {
+            c.field(&target, "", map, key, Shape::String);
+        }
+        c.field(&target, "", map, "options", Shape::Strings);
+        c.field(&target, "", map, "includeAll", Shape::Bool);
+        if let Some(filters) = map.get("labelFilters").filter(|value| !value.is_null()) {
+            let valid = filters.as_array().is_some_and(|filters| {
+                filters.iter().all(|filter| {
+                    filter.get("label").is_some_and(Value::is_string)
+                        && filter.get("value").is_some_and(Value::is_string)
+                        && filter
+                            .get("operator")
+                            .and_then(Value::as_str)
+                            .is_some_and(|op| LABEL_FILTER_OPERATORS.contains(&op))
+                })
+            });
+            if !valid {
+                c.error(
+                    "invalid_label_filter",
+                    &target,
+                    "/labelFilters",
+                    filters.to_string(),
+                    "`labelFilters` must be an array of {label, operator, value} with operator =, !=, =~ or !~",
+                );
+            }
+        }
+        let required: &[&str] = match kind {
+            "promql" => &["dataset", "labelName"],
+            "promql_query" => &["promqlQuery", "promqlQueryDataset"],
+            "sql" => &["sqlQuery"],
+            _ => &[],
+        };
+        for key in required {
+            if map
+                .get(*key)
+                .and_then(Value::as_str)
+                .is_none_or(|text| text.trim().is_empty())
+            {
+                c.error(
+                    "incomplete_variable",
+                    &target,
+                    join("", key),
+                    detail(map.get(*key)),
+                    format!("a `{kind}` variable requires a non-blank `{key}`"),
+                );
+            }
+        }
+        if kind == "list" {
+            let options = map.get("options").and_then(Value::as_array);
+            if options.is_none_or(Vec::is_empty) {
+                c.error(
+                    "incomplete_variable",
+                    &target,
+                    "/options",
+                    detail(map.get("options")),
+                    "a `list` variable requires at least one option",
+                );
+            } else if let (Some(default), Some(options)) = (map.get("defaultValue"), options)
+                && default.is_string()
+                && !options.contains(default)
+            {
+                c.advise(
+                    "default_not_in_options",
+                    &target,
+                    "/defaultValue",
+                    default.to_string(),
+                    "`defaultValue` is not one of the options; the first option is selected",
+                );
+            }
+        }
+        readable.push((name, map));
+    }
+    check_variable_cycles(c, &readable);
+}
+
+fn check_variable_cycles(c: &mut Checker, readable: &[(&str, &Map<String, Value>)]) {
+    let index: HashMap<&str, usize> = readable
+        .iter()
+        .enumerate()
+        .map(|(position, (name, _))| (*name, position))
+        .collect();
+    let dependencies: Vec<Vec<usize>> = readable
+        .iter()
+        .map(|(_, variable)| {
+            let source = variable_source(variable);
+            let mut found: Vec<usize> = referenced_names(&source)
+                .filter_map(|name| index.get(name).copied())
+                .collect();
+            found.sort_unstable();
+            found.dedup();
+            found
+        })
+        .collect();
+    // Iterative DFS: stored documents can hold arbitrarily long dependency chains.
+    // 0 = unvisited, 1 = on the current path, 2 = done.
+    let mut state = vec![0u8; readable.len()];
+    let mut stack: Vec<(usize, usize)> = Vec::new();
+    for start in 0..readable.len() {
+        if state[start] != 0 {
+            continue;
+        }
+        state[start] = 1;
+        stack.push((start, 0));
+        while let Some(top) = stack.last_mut() {
+            let (node, cursor) = *top;
+            let Some(&next) = dependencies[node].get(cursor) else {
+                state[node] = 2;
+                stack.pop();
+                continue;
+            };
+            top.1 += 1;
+            match state[next] {
+                0 => {
+                    state[next] = 1;
+                    stack.push((next, 0));
+                }
+                1 => {
+                    let name = readable[next].0;
+                    c.error(
+                        "variable_cycle",
+                        &PatchTarget::Variable {
+                            name: name.to_owned(),
+                        },
+                        "",
+                        name.to_owned(),
+                        format!("variable dependencies contain a cycle at `{name}`"),
+                    );
+                    // Report each cycle once; the rest of this path is abandoned.
+                    for (node, _) in stack.drain(..) {
+                        state[node] = 2;
+                    }
+                }
+                _ => {}
+            }
+        }
+    }
+}
+
+fn check_tiles(c: &mut Checker, tiles: &[Value], section_ids: &HashSet<&str>) {
+    let mut ids = HashSet::new();
+    let mut groups: HashMap<&str, Vec<(PatchTarget, Rect)>> = HashMap::new();
+    for (index, tile) in tiles.iter().enumerate() {
+        let at = format!("/tiles/{index}");
+        let Some(map) = tile.as_object() else {
+            c.error(
+                "invalid_tile",
+                &PatchTarget::Dashboard,
+                at,
+                tile.to_string(),
+                "a tile must be an object",
+            );
+            continue;
+        };
+        let raw = map.get("tile_id");
+        let target = match raw.and_then(Value::as_str).map(Ulid::from_string) {
+            Some(Ok(ulid)) if !ulid.is_nil() => {
+                let target = PatchTarget::Tile {
+                    id: ulid.to_string(),
+                };
+                if !ids.insert(ulid) {
+                    c.error(
+                        "duplicate_tile_id",
+                        &target,
+                        "/tile_id",
+                        ulid.to_string(),
+                        format!("tile id `{ulid}` is used more than once"),
+                    );
+                }
+                target
+            }
+            Some(Ok(_)) => {
+                let target = PatchTarget::Tile {
+                    id: detail(raw).trim_matches('"').to_owned(),
+                };
+                c.error(
+                    "nil_tile_id",
+                    &target,
+                    "/tile_id",
+                    detail(raw),
+                    "tile ids must not be the nil ULID",
+                );
+                target
+            }
+            _ => {
+                c.error(
+                    "invalid_tile_id",
+                    &PatchTarget::Dashboard,
+                    join(&at, "tile_id"),
+                    detail(raw),
+                    "`tile_id` must be a ULID string",
+                );
+                continue;
+            }
+        };
+        let section = check_tile(c, &target, map, section_ids);
+        if let Some(rect) = check_layout(c, &target, map) {
+            groups.entry(section).or_default().push((target, rect));
+        }
+    }
+    // Overlap advice is quadratic; documents over the tile limit are already rejected on growth.
+    for members in groups.values().filter(|members| members.len() <= MAX_TILES) {
+        for (position, (target, rect)) in members.iter().enumerate() {
+            if let Some((other, _)) = members
+                .iter()
+                .enumerate()
+                .find(|(other, (_, candidate))| *other != position && rect.overlaps(candidate))
+                .map(|(_, member)| member)
+            {
+                let other = match other {
+                    PatchTarget::Tile { id } => id.clone(),
+                    _ => String::new(),
+                };
+                c.advise(
+                    "layout_overlap",
+                    target,
+                    "/layout",
+                    other.clone(),
+                    format!(
+                        "overlaps tile `{other}`; the dashboard compacts it downward when shown"
+                    ),
+                );
+            }
+        }
+    }
+}
+
+/// Returns the tile's effective section group id.
+fn check_tile<'a>(
+    c: &mut Checker,
+    target: &PatchTarget,
+    tile: &'a Map<String, Value>,
+    section_ids: &HashSet<&str>,
+) -> &'a str {
+    c.field(target, "", tile, "title", Shape::String);
+    let section = match tile.get("sectionId") {
+        None | Some(Value::Null) => "",
+        Some(Value::String(id)) if id.is_empty() || section_ids.contains(id.as_str()) => {
+            id.as_str()
+        }
+        Some(Value::String(id)) => {
+            c.error(
+                "unknown_section",
+                target,
+                "/sectionId",
+                id.clone(),
+                format!("section `{id}` does not exist"),
+            );
+            ""
+        }
+        Some(other) => {
+            c.error(
+                "invalid_field_type",
+                target,
+                "/sectionId",
+                other.to_string(),
+                "`sectionId` must be a string",
+            );
+            ""
+        }
+    };
+    let tile_type = match tile.get("tileType") {
+        None | Some(Value::Null) => Some("builder"),
+        Some(Value::String(kind)) if TILE_TYPES.contains(&kind.as_str()) => Some(kind.as_str()),
+        other => {
+            c.error(
+                "unsupported_tile_type",
+                target,
+                "/tileType",
+                detail(other),
+                format!("`tileType` must be one of: {}", TILE_TYPES.join(", ")),
+            );
+            None
+        }
+    };
+    let chart = match tile.get("chartType") {
+        None => Some("timeseries"),
+        Some(Value::String(kind)) if CHART_TYPES.contains(&kind.as_str()) => Some(kind.as_str()),
+        other => {
+            c.error(
+                "unsupported_chart_type",
+                target,
+                "/chartType",
+                detail(other),
+                format!("`chartType` must be one of: {}", CHART_TYPES.join(", ")),
+            );
+            None
+        }
+    };
+    if let Some(tile_type) = tile_type {
+        check_query(c, target, tile, tile_type, chart);
+    }
+    check_config(c, target, tile, tile_type, chart);
+    section
+}
+
+fn check_query(
+    c: &mut Checker,
+    target: &PatchTarget,
+    tile: &Map<String, Value>,
+    tile_type: &str,
+    chart: Option<&str>,
+) {
+    let query = tile.get("chartQuery");
+    let blank = |text: &str| text.trim().is_empty();
+    if tile_type != "promql" {
+        match query {
+            // {query} / {sql} objects are read as plain SQL by the frontend.
+            Some(Value::Object(object))
+                if object.get("query").is_some_and(Value::is_string)
+                    || object.get("sql").is_some_and(Value::is_string) => {}
+            Some(Value::Object(object)) if tile_type == "builder" => {
+                check_builder_query(c, target, tile, object, chart);
+            }
+            None | Some(Value::Null) => c.advise(
+                "empty_query",
+                target,
+                "/chartQuery",
+                String::new(),
+                "the tile has no SQL query",
+            ),
+            Some(Value::String(sql)) if blank(sql) => c.advise(
+                "empty_query",
+                target,
+                "/chartQuery",
+                String::new(),
+                "the tile has no SQL query",
+            ),
+            Some(Value::String(_)) => {}
+            Some(Value::Object(_)) => c.error(
+                "legacy_query_shape",
+                target,
+                "/chartQuery",
+                detail(query),
+                "code tiles store SQL as a string; builder objects need tileType `builder`",
+            ),
+            Some(other) => c.error(
+                "invalid_query_shape",
+                target,
+                "/chartQuery",
+                other.to_string(),
+                "SQL tiles need `chartQuery` as a string",
+            ),
+        }
+        c.field(target, "", tile, "dbName", Shape::StringOrStrings);
+        for key in ["promqlQueryType", "promqlStep"] {
+            if let Some(value) = present(tile, key) {
+                c.advise(
+                    "ignored_field",
+                    target,
+                    join("", key),
+                    value.to_string(),
+                    format!("`{key}` only applies to PromQL tiles"),
+                );
+            }
+        }
+        return;
+    }
+    let count = match query {
+        Some(Value::String(promql)) => {
+            if blank(promql) {
+                c.advise(
+                    "empty_query",
+                    target,
+                    "/chartQuery",
+                    String::new(),
+                    "the PromQL query is blank",
+                );
+            }
+            1
+        }
+        Some(Value::Array(items)) if !items.is_empty() && items.iter().all(Value::is_string) => {
+            if items.iter().filter_map(Value::as_str).any(blank) {
+                c.advise(
+                    "empty_query",
+                    target,
+                    "/chartQuery",
+                    String::new(),
+                    "a PromQL query is blank",
+                );
+            }
+            items.len()
+        }
+        Some(Value::Object(_)) => {
+            c.error(
+                "legacy_query_shape",
+                target,
+                "/chartQuery",
+                detail(query),
+                "object `chartQuery` is a legacy shape; use a string or an array of strings",
+            );
+            0
+        }
+        other => {
+            c.error(
+                "invalid_query_shape",
+                target,
+                "/chartQuery",
+                detail(other),
+                "PromQL tiles need `chartQuery` as a string or a non-empty array of strings",
+            );
+            0
+        }
+    };
+    let mode = |value: &Value| {
+        value
+            .as_str()
+            .is_some_and(|mode| QUERY_MODES.contains(&mode))
+    };
+    match tile.get("promqlQueryType") {
+        None | Some(Value::Null) => {}
+        Some(value) if mode(value) => {}
+        Some(Value::Array(modes)) if modes.iter().all(mode) => {
+            if count > 0 && modes.len() != count {
+                c.error(
+                    "invalid_query_mode",
+                    target,
+                    "/promqlQueryType",
+                    json!([modes, count]).to_string(),
+                    format!(
+                        "`promqlQueryType` lists {} modes for {count} queries",
+                        modes.len()
+                    ),
+                );
+            }
+        }
+        Some(other) => c.error(
+            "invalid_query_mode",
+            target,
+            "/promqlQueryType",
+            other.to_string(),
+            "`promqlQueryType` must be range, instant, both, or an array of those",
+        ),
+    }
+    if let Some(step) = present(tile, "promqlStep") {
+        let valid = match &step {
+            Value::String(text) => is_duration(text),
+            Value::Number(number) => number.as_f64().is_some_and(|seconds| seconds > 0.0),
+            _ => false,
+        };
+        if !valid {
+            c.error(
+                "invalid_step",
+                target,
+                "/promqlStep",
+                step.to_string(),
+                "`promqlStep` must be a duration such as 30s or 5m, or positive seconds",
+            );
+        }
+    }
+    let datasets = match tile.get("dbName") {
+        Some(Value::String(name)) if !blank(name) => Some(1),
+        Some(Value::Array(names))
+            if !names.is_empty()
+                && names
+                    .iter()
+                    .all(|name| name.as_str().is_some_and(|name| !blank(name))) =>
+        {
+            Some(names.len())
+        }
+        _ => None,
+    };
+    match datasets {
+        None => c.error(
+            "missing_dataset",
+            target,
+            "/dbName",
+            detail(tile.get("dbName")),
+            "PromQL tiles need `dbName` naming the metrics dataset",
+        ),
+        Some(count) if count > 1 => c.advise(
+            "extra_datasets",
+            target,
+            "/dbName",
+            detail(tile.get("dbName")),
+            "only the first dataset is queried by PromQL tiles",
+        ),
+        Some(_) => {}
+    }
+}
+
+const BUILDER_AGGREGATES: &[&str] = &["COUNT", "SUM", "AVG", "MIN", "MAX", "COUNT(DISTINCT)"];
+const BUILDER_OPERATORS: &[&str] = &[
+    "=",
+    "!=",
+    "<>",
+    "<",
+    ">",
+    "<=",
+    ">=",
+    "is null",
+    "is not null",
+];
+const BUILDER_GRAINS: &[&str] = &[
+    "second", "minute", "hour", "day", "week", "month", "quarter", "year",
+];
+const BUILDER_STAR: &[&str] = &["*", "All rows (*)"];
+
+fn builder_fields(axis: Option<&Map<String, Value>>) -> Vec<&Value> {
+    axis.and_then(|axis| axis.get("fields"))
+        .and_then(Value::as_array)
+        .map(|fields| fields.iter().collect())
+        .unwrap_or_default()
+}
+
+/// Structural checks for the visual builder's object `chartQuery` ({x, y, filters}), matching
+/// what frontend legacySql.ts compiles and builder.ts edits. Extra keys are preserved unchecked.
+fn check_builder_query(
+    c: &mut Checker,
+    target: &PatchTarget,
+    tile: &Map<String, Value>,
+    query: &Map<String, Value>,
+    chart: Option<&str>,
+) {
+    let p = "/chartQuery";
+    let fail = |c: &mut Checker, path: String, value: Option<&Value>, message: &str| {
+        c.error(
+            "invalid_builder_query",
+            target,
+            path,
+            detail(value),
+            message,
+        );
+    };
+    let stat = matches!(chart, Some("query-value" | "gauge"));
+    let mut axes: [Option<&Map<String, Value>>; 2] = [None, None];
+    for (slot, axis) in ["x", "y"].into_iter().enumerate() {
+        let at = join(p, axis);
+        match query.get(axis) {
+            None | Some(Value::Null) => {}
+            Some(Value::Object(map)) => axes[slot] = Some(map),
+            other => fail(c, at, other, "builder axes must be objects"),
+        }
+    }
+    let [x, y] = axes;
+    let fields = builder_fields;
+    for (name, axis) in [("x", x), ("y", y)] {
+        let Some(axis) = axis else { continue };
+        let at = join(p, name);
+        match axis.get("fields") {
+            None | Some(Value::Null) if name == "x" => {}
+            Some(Value::Array(_)) => {}
+            other => fail(
+                c,
+                join(&at, "fields"),
+                other,
+                "builder `fields` must be an array",
+            ),
+        }
+        if let Some(group) = axis.get("groupBy").filter(|value| !value.is_null())
+            && !Shape::Strings.accepts(group)
+        {
+            fail(
+                c,
+                join(&at, "groupBy"),
+                Some(group),
+                "builder `groupBy` must be an array of column names",
+            );
+        }
+        if let Some(sort) = axis.get("sortBy").filter(|value| !value.is_null()) {
+            let field = sort
+                .get("field")
+                .and_then(Value::as_str)
+                .filter(|field| !field.is_empty());
+            let direction = sort.get("direction").and_then(Value::as_str);
+            if field.is_none() || !matches!(direction, Some("ASC" | "DESC")) {
+                fail(
+                    c,
+                    join(&at, "sortBy"),
+                    Some(sort),
+                    "builder `sortBy` must be {field, direction: ASC|DESC}",
+                );
+            }
+        }
+    }
+    if y.is_none() {
+        fail(
+            c,
+            join(p, "y"),
+            query.get("y"),
+            "builder queries need a `y` axis with aggregate fields",
+        );
+    }
+    for (index, field) in fields(x).into_iter().enumerate() {
+        if field
+            .get("name")
+            .and_then(Value::as_str)
+            .is_none_or(|name| name.is_empty())
+        {
+            fail(
+                c,
+                format!("{p}/x/fields/{index}"),
+                Some(field),
+                "builder dimensions need a column `name`",
+            );
+        }
+    }
+    for (index, field) in fields(y).into_iter().enumerate() {
+        let at = format!("{p}/y/fields/{index}");
+        let name = field
+            .get("name")
+            .and_then(Value::as_str)
+            .filter(|name| !name.is_empty());
+        let aggregate = field
+            .get("aggregate")
+            .and_then(Value::as_str)
+            .map(str::to_uppercase);
+        match (name, aggregate.as_deref()) {
+            (Some(name), Some(aggregate)) if BUILDER_AGGREGATES.contains(&aggregate) => {
+                if BUILDER_STAR.contains(&name) && aggregate != "COUNT" {
+                    fail(c, at, Some(field), "only COUNT can aggregate all rows (*)");
+                }
+            }
+            _ => fail(
+                c,
+                at,
+                Some(field),
+                "builder measures need a `name` and an aggregate: COUNT, SUM, AVG, MIN, MAX or COUNT(DISTINCT)",
+            ),
+        }
+    }
+    if let Some(grain) = x
+        .and_then(|x| x.get("granularity"))
+        .filter(|value| !value.is_null())
+        && !grain
+            .as_str()
+            .is_some_and(|grain| BUILDER_GRAINS.contains(&grain))
+    {
+        fail(
+            c,
+            join(p, "x") + "/granularity",
+            Some(grain),
+            "unsupported time granularity",
+        );
+    }
+    if chart == Some("timeseries") && fields(x).is_empty() {
+        fail(
+            c,
+            format!("{p}/x/fields"),
+            x.and_then(|x| x.get("fields")),
+            "timeseries builder queries need a time field first",
+        );
+    }
+    if y.is_some() && fields(y).is_empty() && (stat || fields(x).is_empty()) {
+        fail(
+            c,
+            format!("{p}/y/fields"),
+            y.and_then(|y| y.get("fields")),
+            if stat {
+                "query-value and gauge builder queries need an aggregate measure"
+            } else {
+                "the builder query selects nothing"
+            },
+        );
+    }
+    if !stat
+        && let Some(limit) = y
+            .and_then(|y| y.get("limit"))
+            .filter(|value| !value.is_null())
+        && limit.as_u64().is_none_or(|limit| limit < 1)
+    {
+        fail(
+            c,
+            format!("{p}/y/limit"),
+            Some(limit),
+            "builder `limit` must be a whole number of at least 1",
+        );
+    }
+    match query.get("filters") {
+        None | Some(Value::Null) => {}
+        Some(Value::Array(filters)) => {
+            for (index, filter) in filters.iter().enumerate() {
+                let column = filter
+                    .get("column")
+                    .and_then(Value::as_str)
+                    .filter(|column| !column.is_empty());
+                let operator = filter
+                    .get("operator")
+                    .and_then(Value::as_str)
+                    .map(|op| op.trim().to_lowercase());
+                let list = filter
+                    .get("type")
+                    .and_then(Value::as_str)
+                    .is_some_and(|kind| kind.starts_with("list"));
+                let scalar =
+                    |value: &Value| value.is_string() || value.is_number() || value.is_boolean();
+                let value_ok = operator.as_deref().is_some_and(|op| op.contains("null"))
+                    || match filter.get("value") {
+                        Some(Value::Array(values)) => {
+                            !values.is_empty() && values.iter().all(scalar)
+                        }
+                        Some(value) => scalar(value),
+                        None => false,
+                    };
+                if column.is_none()
+                    || !operator
+                        .as_deref()
+                        .is_some_and(|op| BUILDER_OPERATORS.contains(&op))
+                    || list
+                    || !value_ok
+                {
+                    fail(
+                        c,
+                        format!("{p}/filters/{index}"),
+                        Some(filter),
+                        "builder filters need {column, operator, value} with a comparison or is (not) null operator",
+                    );
+                }
+            }
+        }
+        other => fail(
+            c,
+            join(p, "filters"),
+            other,
+            "builder `filters` must be an array",
+        ),
+    }
+    let dataset = match tile.get("dbName") {
+        Some(Value::String(name)) => !name.trim().is_empty(),
+        Some(Value::Array(names)) => names
+            .first()
+            .and_then(Value::as_str)
+            .is_some_and(|name| !name.trim().is_empty()),
+        _ => false,
+    };
+    if !dataset {
+        c.error(
+            "missing_dataset",
+            target,
+            "/dbName",
+            detail(tile.get("dbName")),
+            "builder queries need `dbName` naming the dataset",
+        );
+    }
+}
+
+fn is_duration(text: &str) -> bool {
+    let mut rest = text;
+    let mut any = false;
+    while !rest.is_empty() {
+        let digits = rest.bytes().take_while(u8::is_ascii_digit).count();
+        if digits == 0 {
+            return false;
+        }
+        rest = &rest[digits..];
+        let unit = ["ms", "s", "m", "h", "d", "w", "y"]
+            .into_iter()
+            .find(|unit| rest.starts_with(unit));
+        let Some(unit) = unit else {
+            return false;
+        };
+        rest = &rest[unit.len()..];
+        any = true;
+    }
+    any && !text.bytes().all(|b| b == b'0' || !b.is_ascii_digit())
+}
+
+fn check_config(
+    c: &mut Checker,
+    target: &PatchTarget,
+    tile: &Map<String, Value>,
+    tile_type: Option<&str>,
+    chart: Option<&str>,
+) {
+    let Some(config) = c.object(target, "", tile, "config") else {
+        return;
+    };
+    let p = "/config";
+    let config_type = config.get("type").and_then(Value::as_str);
+    c.field(target, p, config, "type", Shape::String);
+    if let (Some(config_type), Some(chart)) = (config_type, chart) {
+        let consistent = if chart == "timeseries" {
+            config_type == "timeseries" || SERIES_STYLES.contains(&config_type)
+        } else {
+            config_type == chart
+        };
+        if !consistent {
+            c.advise(
+                "config_type_mismatch",
+                target,
+                "/config/type",
+                config_type.to_owned(),
+                "`config.type` is ignored unless it is the chart type, or a series style (line, bar, area) for timeseries",
+            );
+        }
+    }
+    c.one_of(
+        "unknown_colour_scheme",
+        target,
+        p,
+        config,
+        "colourScheme",
+        COLOUR_SCHEMES,
+    );
+    c.field(target, p, config, "maxDataPoints", Shape::PositiveNumber);
+    let layout = c.object(target, p, config, "layout");
+    let stacked = chart == Some("timeseries")
+        && config_type == Some("bar")
+        && layout.and_then(|layout| layout.get("stacked")) == Some(&Value::Bool(true));
+    if let Some(layout) = layout {
+        check_chart_layout(c, target, layout, chart);
+    }
+    if let Some(axes) = c.object(target, p, config, "axes") {
+        check_axes(c, target, axes, tile_type, chart, stacked);
+    }
+    if let Some(advanced) = c.object(target, p, config, "advanced") {
+        let p = "/config/advanced";
+        if let Some(labels) = c.object(target, p, advanced, "dataLabels") {
+            c.field(
+                target,
+                "/config/advanced/dataLabels",
+                labels,
+                "enabled",
+                Shape::Bool,
+            );
+        }
+        if let Some(tooltip) = c.object(target, p, advanced, "tooltip") {
+            let p = "/config/advanced/tooltip";
+            c.field(target, p, tooltip, "enabled", Shape::Bool);
+            c.field(target, p, tooltip, "mode", Shape::String);
+            c.field(target, p, tooltip, "intersect", Shape::Bool);
+        }
+    }
+}
+
+/// Display, threshold and conditional colour settings (config.layout).
+fn check_chart_layout(
+    c: &mut Checker,
+    target: &PatchTarget,
+    layout: &Map<String, Value>,
+    chart: Option<&str>,
+) {
+    let p = "/config/layout";
+    c.one_of(
+        "invalid_field_value",
+        target,
+        p,
+        layout,
+        "legendPosition",
+        LEGEND_POSITIONS,
+    );
+    if let Some(position @ ("left" | "right")) =
+        layout.get("legendPosition").and_then(Value::as_str)
+        && !matches!(chart, Some("pie" | "donut"))
+    {
+        c.advise(
+            "side_legend",
+            target,
+            "/config/layout/legendPosition",
+            position.to_owned(),
+            "the editor offers left/right legends only for pie and donut charts",
+        );
+    }
+    for key in ["label", "stacked", "sparkline", "humanize"] {
+        c.field(target, p, layout, key, Shape::Bool);
+    }
+    c.one_of(
+        "invalid_field_value",
+        target,
+        p,
+        layout,
+        "barOrientation",
+        BAR_ORIENTATIONS,
+    );
+    c.one_of(
+        "invalid_field_value",
+        target,
+        p,
+        layout,
+        "queryValueTheme",
+        QUERY_VALUE_THEMES,
+    );
+    c.one_of(
+        "invalid_field_value",
+        target,
+        p,
+        layout,
+        "percentFill",
+        PERCENT_FILLS,
+    );
+    c.field(target, p, layout, "unit", Shape::String);
+    c.field(target, p, layout, "rangeFrom", Shape::Number);
+    c.field(target, p, layout, "rangeTo", Shape::Number);
+    c.field(target, p, layout, "maxDataPoints", Shape::PositiveNumber);
+    if let Some(precision) = present(layout, "precision")
+        && !precision
+            .as_i64()
+            .is_some_and(|value| (-1..=20).contains(&value))
+    {
+        c.error(
+            "invalid_field_value",
+            target,
+            "/config/layout/precision",
+            precision.to_string(),
+            "`precision` must be an integer from -1 (precise) to 20",
+        );
+    }
+    let segments = present(layout, "segments");
+    let thresholds = segments.as_ref().and_then(|segments| {
+        let values = segments.get("value")?.as_array()?;
+        let numbers: Option<Vec<f64>> = values.iter().map(Value::as_f64).collect();
+        let percent = segments
+            .get("isPercent")
+            .map_or(Some(false), Value::as_bool)?;
+        Some((numbers?, percent))
+    });
+    if segments.is_some() && thresholds.is_none() {
+        c.error(
+            "invalid_segments",
+            target,
+            "/config/layout/segments",
+            detail(segments.as_ref()),
+            "`segments` must be {value: number[], isPercent: boolean}",
+        );
+    }
+    if chart != Some("gauge") {
+        return;
+    }
+    let number =
+        |key: &str, fallback: f64| layout.get(key).and_then(Value::as_f64).unwrap_or(fallback);
+    let (from, to) = (number("rangeFrom", 0.0), number("rangeTo", 100.0));
+    let gauge = json!([layout.get("rangeFrom"), layout.get("rangeTo"), segments]).to_string();
+    if from >= to {
+        c.error(
+            "invalid_gauge_range",
+            target,
+            "/config/layout/rangeFrom",
+            gauge.clone(),
+            "gauge `rangeFrom` must be below `rangeTo`",
+        );
+    }
+    let Some((values, percent)) = thresholds else {
+        return;
+    };
+    if values.windows(2).any(|pair| pair[1] <= pair[0]) {
+        c.error(
+            "invalid_segments",
+            target,
+            "/config/layout/segments",
+            gauge.clone(),
+            "gauge thresholds must increase",
+        );
+    }
+    let (low, high) = if percent { (0.0, 100.0) } else { (from, to) };
+    if values.iter().any(|value| *value < low || *value > high) {
+        c.error(
+            "invalid_segments",
+            target,
+            "/config/layout/segments",
+            gauge.clone(),
+            if percent {
+                "percent thresholds must be between 0 and 100"
+            } else {
+                "absolute thresholds must be within the gauge range"
+            },
+        );
+    }
+    if values.len() > 2 {
+        c.advise(
+            "extra_thresholds",
+            target,
+            "/config/layout/segments",
+            gauge,
+            "gauges colour green/yellow/red with at most two thresholds; more renders a neutral colour",
+        );
+    }
+}
+
+fn field_count(axis: Option<&Map<String, Value>>) -> usize {
+    match axis.and_then(|axis| axis.get("field")) {
+        Some(Value::String(field)) if !field.is_empty() => 1,
+        Some(Value::Array(fields)) => fields.iter().filter(|field| field.is_string()).count(),
+        _ => 0,
+    }
+}
+
+fn check_axes(
+    c: &mut Checker,
+    target: &PatchTarget,
+    axes: &Map<String, Value>,
+    tile_type: Option<&str>,
+    chart: Option<&str>,
+    stacked: bool,
+) {
+    let mut bound = HashMap::new();
+    for axis in ["x", "y", "size", "groupBy"] {
+        let Some(map) = c.object(target, "/config/axes", axes, axis) else {
+            continue;
+        };
+        let p = format!("/config/axes/{axis}");
+        c.field(target, &p, map, "field", Shape::StringOrStrings);
+        c.field(target, &p, map, "title", Shape::String);
+        c.field(target, &p, map, "display", Shape::Bool);
+        c.field(target, &p, map, "beginAtZero", Shape::Bool);
+        bound.insert(axis, map);
+    }
+    if tile_type == Some("promql") {
+        return;
+    }
+    let count = |axis: &str| field_count(bound.get(axis).copied());
+    let detail_of = |axis: &str| detail(bound.get(axis).and_then(|map| map.get("field")));
+    let mut limit = |axis: &str, max: usize, message: &str| {
+        if count(axis) > max {
+            c.error(
+                "invalid_binding",
+                target,
+                format!("/config/axes/{axis}/field"),
+                detail_of(axis),
+                message,
+            );
+        }
+    };
+    if stacked {
+        limit(
+            "y",
+            1,
+            "stacked bar supports one Y column; use groupBy to split series",
+        );
+    }
+    if chart == Some("bubble") {
+        limit("y", 1, "bubble charts take one Y column");
+        limit("x", 1, "bubble charts take one X column");
+        limit("size", 1, "bubble charts take one size column");
+        limit("groupBy", 1, "bubble charts support one groupBy column");
+    }
+    if matches!(chart, Some("pie" | "donut" | "gauge" | "query-value")) {
+        limit("y", 1, "this chart reads one value or category column");
+    }
+    limit("groupBy", 2, "at most two groupBy columns are supported");
+}
+
+fn check_layout(c: &mut Checker, target: &PatchTarget, tile: &Map<String, Value>) -> Option<Rect> {
+    let layout = match tile.get("layout") {
+        None | Some(Value::Null) => {
+            c.advise(
+                "missing_layout",
+                target,
+                "/layout",
+                String::new(),
+                "the tile has no layout and is appended below the grid when shown",
+            );
+            return None;
+        }
+        Some(Value::Object(layout)) => layout,
+        Some(other) => {
+            c.error(
+                "invalid_layout",
+                target,
+                "/layout",
+                other.to_string(),
+                "`layout` must be an object {x, y, w, h}",
+            );
+            return None;
+        }
+    };
+    let integer = |key: &str| {
+        layout.get(key).and_then(|value| {
+            value.as_i64().or_else(|| {
+                value
+                    .as_f64()
+                    .filter(|f| f.fract() == 0.0 && f.abs() < 1e15)
+                    .map(|f| f as i64)
+            })
+        })
+    };
+    let (x, y, w, h) = (integer("x"), integer("y"), integer("w"), integer("h"));
+    let mut valid = true;
+    let mut fail = |key: &str, detail: String, message: String| {
+        valid = false;
+        c.error(
+            "invalid_layout",
+            target,
+            join("/layout", key),
+            detail,
+            message,
+        );
+    };
+    if !w.is_some_and(|w| (1..=GRID_COLUMNS).contains(&w)) {
+        fail(
+            "w",
+            detail(layout.get("w")),
+            format!("`w` must be an integer from 1 to {GRID_COLUMNS}"),
+        );
+    }
+    if !h.is_some_and(|h| (1..=MAX_TILE_HEIGHT).contains(&h)) {
+        fail(
+            "h",
+            detail(layout.get("h")),
+            format!("`h` must be an integer from 1 to {MAX_TILE_HEIGHT}"),
+        );
+    }
+    if !y.is_some_and(|y| (0..=MAX_TILE_ROW).contains(&y)) {
+        fail(
+            "y",
+            detail(layout.get("y")),
+            format!("`y` must be an integer from 0 to {MAX_TILE_ROW}"),
+        );
+    }
+    let span = w.unwrap_or(1).clamp(1, GRID_COLUMNS);
+    if !x.is_some_and(|x| (0..=GRID_COLUMNS - span).contains(&x)) {
+        fail(
+            "x",
+            json!([layout.get("x"), layout.get("w")]).to_string(),
+            format!("`x` must be an integer with x + w <= {GRID_COLUMNS}"),
+        );
+    }
+    if !valid {
+        // Overlap advice only considers layouts that are already valid.
+        return None;
+    }
+    Some(Rect {
+        x: x?,
+        y: y?,
+        w: w?,
+        h: h?,
+    })
+}
+
+fn check_reserved(c: &mut Checker, candidate: &Value, base: Option<&Value>) {
+    let stored = base.and_then(|base| base.get(INTERNAL_METADATA_KEY));
+    if candidate.get(INTERNAL_METADATA_KEY) != stored {
+        c.error(
+            "reserved_field",
+            &PatchTarget::Dashboard,
+            join("", INTERNAL_METADATA_KEY),
+            String::new(),
+            format!("`{INTERNAL_METADATA_KEY}` is server-internal and cannot be set or changed"),
+        );
+    }
+}
+
+fn string_leaves<'a>(value: &'a Value, out: &mut Vec<&'a str>) {
+    match value {
+        Value::String(text) => out.push(text),
+        Value::Array(items) => items.iter().for_each(|item| string_leaves(item, out)),
+        Value::Object(map) => map.values().for_each(|item| string_leaves(item, out)),
+        _ => {}
+    }
+}
+
+fn variable_names(document: &Value) -> HashSet<&str> {
+    document
+        .get("variables")
+        .and_then(Value::as_array)
+        .map(|variables| variables.iter().filter_map(variable_name).collect())
+        .unwrap_or_default()
+}
+
+/// A reference to a variable that existed in the base but was removed is a new defect.
+fn check_removed_variables(c: &mut Checker, candidate: &Value, base: &Value) {
+    let remaining = variable_names(candidate);
+    let removed: HashSet<&str> = variable_names(base)
+        .into_iter()
+        .filter(|name| !remaining.contains(name))
+        .collect();
+    if removed.is_empty() {
+        return;
+    }
+    let report = |c: &mut Checker, target: PatchTarget, path: String, value: &Value| {
+        let mut texts = Vec::new();
+        string_leaves(value, &mut texts);
+        let mut names: Vec<&str> = texts
+            .iter()
+            .flat_map(|text| referenced_names(text))
+            .filter(|name| removed.contains(name))
+            .collect();
+        names.sort_unstable();
+        names.dedup();
+        for name in names {
+            c.error(
+                "dangling_variable_reference",
+                &target,
+                path.clone(),
+                name.to_owned(),
+                format!("references `${name}`, which this change removes"),
+            );
+        }
+    };
+    for tile in candidate
+        .get("tiles")
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+    {
+        let Some(id) = tile_ulid(tile) else {
+            continue;
+        };
+        for key in ["chartQuery", "dbName"] {
+            if let Some(value) = tile.get(key) {
+                report(
+                    c,
+                    PatchTarget::Tile { id: id.to_string() },
+                    join("", key),
+                    value,
+                );
+            }
+        }
+    }
+    for variable in candidate
+        .get("variables")
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+    {
+        let (Some(name), Some(map)) = (variable_name(variable), variable.as_object()) else {
+            continue;
+        };
+        let source = Value::String(variable_source(map));
+        report(
+            c,
+            PatchTarget::Variable {
+                name: name.to_owned(),
+            },
+            String::new(),
+            &source,
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Capabilities and schema
+// ---------------------------------------------------------------------------------------------
+
+/// Discoverable patch contract, limits, enumerations and JSON Schemas. `operationSchema` is the
+/// self-contained JSON Schema of a patch request body; `operationItemSchema` is one operation.
+pub fn capabilities() -> Value {
+    json!({
+        "version": 1,
+        "patch": patch_capabilities(),
+        "operationSchema": operation_schema(),
+        "operationItemSchema": operation_item_schema(),
+        "limits": {
+            "maxOperations": MAX_OPERATIONS,
+            "maxDocumentBytes": MAX_DOCUMENT_BYTES,
+            "maxTiles": MAX_TILES,
+            "maxSections": MAX_SECTIONS,
+            "maxVariables": MAX_VARIABLES,
+            "maxPointerSegments": MAX_POINTER_TOKENS,
+            "maxIdBytes": MAX_ID_BYTES,
+            "growth": "limits reject growth; documents already over a limit may shrink or stay the same",
+        },
+        "layout": {
+            "columns": GRID_COLUMNS,
+            "maxRow": MAX_TILE_ROW,
+            "maxTileHeight": MAX_TILE_HEIGHT,
+            "defaultTileSize": { "w": DEFAULT_TILE_W, "h": DEFAULT_TILE_H },
+            "rules": layout_rules(),
+        },
+        "enums": enums(),
+        "validation": {
+            "structuralOnly": true,
+            "executesQueries": false,
+            "checksQuerySyntax": false,
+            "probesDatasets": false,
+            "legacyPolicy": "a defect already present in the stored document at the same target, path and value is a legacy warning; new or changed defects are errors",
+            "unknownFields": "unknown and extension fields are preserved verbatim and are not validated",
+        },
+        "schema": dashboard_schema(),
+    })
+}
+
+fn patch_capabilities() -> Value {
+    json!({
+        "atomic": true,
+        "finalStateValidation": true,
+        "dryRun": "dryRun: true returns the candidate and validation report without saving",
+        "pointer": "RFC 6901 JSON Pointer relative to the target object, with RFC 6902 add/replace/remove semantics; '-' appends to arrays",
+        "entityPaths": "an empty path adds, replaces (identity kept; tile layout kept when omitted) or removes the target entity",
+        "ids": "ids of added entities are supplied by the client: tile ids are non-nil ULIDs, section ids opaque strings, variable names ^\\w+$",
+        "operations": ["add", "replace", "remove", "placeTile", "renameVariable", "reorderSections", "removeSection"],
+        "targets": ["dashboard", "tile", "section", "variable"],
+        "protectedPaths": {
+            "dashboard": SERVER_OWNED,
+            "dashboardCollections": ENTITY_COLLECTIONS,
+            "dashboardRoot": "the empty path on the dashboard target is rejected",
+            "tile": ["tile_id"],
+            "section": ["sectionId"],
+            "variable": ["name"],
+            "matching": "case-, underscore- and hyphen-insensitive after pointer unescaping",
+        },
+        "errorCodes": [
+            "too_many_operations", "invalid_base", "invalid_target", "target_not_found",
+            "ambiguous_target", "target_exists", "invalid_pointer", "path_not_found",
+            "protected_path", "invalid_value", "invalid_operation", "name_conflict",
+            "limit_exceeded", "document_too_large",
+        ],
+    })
+}
+
+fn layout_rules() -> Value {
+    json!({
+        "addTile": "missing layout fields default to x 0, w 6, h 4 and y below the tile's section; the section then compacts",
+        "removeTile": "the section the tile left compacts",
+        "fieldEdits": "generic edits under /layout or /sectionId are literal; use placeTile for moves and resizes",
+        "placeTile": "the edited tile takes its destination, colliding tiles move down and the section compacts vertically; only y is written to other tiles",
+        "removeSection": "unsection and move append tiles at x 0 below the destination grid, keeping their sizes",
+        "legacy": "stored sizes beyond the editor bounds are never normalized and keep their full height for collisions",
+    })
+}
+
+fn enums() -> Value {
+    json!({
+        "tileTypes": TILE_TYPES,
+        "chartTypes": CHART_TYPES,
+        "stackedBar": "chartType timeseries with config.type bar and config.layout.stacked true",
+        "seriesStyles": SERIES_STYLES,
+        "colourSchemes": COLOUR_SCHEMES,
+        "legendPositions": LEGEND_POSITIONS,
+        "barOrientations": BAR_ORIENTATIONS,
+        "queryValueThemes": QUERY_VALUE_THEMES,
+        "percentFills": PERCENT_FILLS,
+        "promqlQueryModes": QUERY_MODES,
+        "variableTypes": VARIABLE_TYPES,
+        "labelFilterOperators": LABEL_FILTER_OPERATORS,
+        "timeRangePresets": TIME_RANGE_PRESETS,
+        "timeRangeTypes": TIME_RANGE_TYPES,
+        "refreshIntervalsMs": REFRESH_INTERVALS,
+        "dashboardTypes": DASHBOARD_TYPES,
+    })
+}
+
+/// JSON Schema of the patch request body. Self-contained (no `$ref`), with the operation union
+/// from [`operation_item_schema`] inlined as `operations.items`.
+fn operation_schema() -> Value {
+    json!({
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "DashboardPatchRequest",
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["operations"],
+        "properties": {
+            "operations": {
+                "type": "array",
+                "maxItems": MAX_OPERATIONS,
+                "items": operation_item_schema(),
+            },
+            "dryRun": { "type": "boolean", "default": false },
+            "revision": { "type": "string", "description": "expected current revision" },
+        },
+    })
+}
+
+/// JSON Schema of one [`DashboardOperation`], fully inline (no `$ref`), so tools can embed it as
+/// the `items` of an operations array.
+pub fn operation_item_schema() -> Value {
+    let pointer = json!({
+        "type": "string",
+        "default": "",
+        "description": "JSON Pointer relative to the target; empty addresses the entity",
+    });
+    let [place, rename, reorder, remove] = semantic_operation_schemas();
+    json!({ "oneOf": [
+        {
+            "type": "object", "additionalProperties": false,
+            "required": ["op", "target", "value"],
+            "properties": {
+                "op": { "enum": ["add", "replace"] },
+                "target": target_schema(),
+                "path": pointer,
+                "value": {},
+            },
+        },
+        {
+            "type": "object", "additionalProperties": false,
+            "required": ["op", "target"],
+            "properties": {
+                "op": { "const": "remove" },
+                "target": target_schema(),
+                "path": pointer,
+            },
+        },
+        place,
+        rename,
+        reorder,
+        remove,
+    ]})
+}
+
+fn layout_edits_schema() -> Value {
+    json!({
+        "type": "object",
+        "additionalProperties": false,
+        "description": "omitted fields keep the tile's current value; x + w must not exceed 12",
+        "properties": {
+            "x": { "type": "integer", "minimum": 0, "maximum": GRID_COLUMNS - 1 },
+            "y": { "type": "integer", "minimum": 0, "maximum": MAX_TILE_ROW },
+            "w": { "type": "integer", "minimum": 1, "maximum": GRID_COLUMNS },
+            "h": { "type": "integer", "minimum": 1, "maximum": MAX_TILE_HEIGHT },
+        },
+    })
+}
+
+fn target_schema() -> Value {
+    json!({ "oneOf": [
+        {
+            "type": "object", "additionalProperties": false, "required": ["type"],
+            "properties": { "type": { "const": "dashboard" } },
+        },
+        {
+            "type": "object", "additionalProperties": false, "required": ["type", "id"],
+            "properties": {
+                "type": { "const": "tile" },
+                "id": { "type": "string", "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$" },
+            },
+        },
+        {
+            "type": "object", "additionalProperties": false, "required": ["type", "id"],
+            "properties": {
+                "type": { "const": "section" },
+                "id": { "type": "string", "minLength": 1, "maxLength": MAX_ID_BYTES },
+            },
+        },
+        {
+            "type": "object", "additionalProperties": false, "required": ["type", "name"],
+            "properties": {
+                "type": { "const": "variable" },
+                "name": { "type": "string", "pattern": "^\\w+$" },
+            },
+        },
+    ]})
+}
+
+fn semantic_operation_schemas() -> [Value; 4] {
+    [
+        json!({
+            "type": "object", "additionalProperties": false, "required": ["op", "tileId"],
+            "properties": {
+                "op": { "const": "placeTile" },
+                "tileId": { "type": "string" },
+                "sectionId": {
+                    "type": ["string", "null"],
+                    "description": "absent keeps the section; null or empty unsections; a string moves into that section",
+                },
+                "layout": layout_edits_schema(),
+            },
+        }),
+        json!({
+            "type": "object", "additionalProperties": false, "required": ["op", "from", "to"],
+            "properties": {
+                "op": { "const": "renameVariable" },
+                "from": { "type": "string", "pattern": "^\\w+$" },
+                "to": { "type": "string", "pattern": "^\\w+$" },
+            },
+        }),
+        json!({
+            "type": "object", "additionalProperties": false, "required": ["op", "sectionIds"],
+            "properties": {
+                "op": { "const": "reorderSections" },
+                "sectionIds": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+            },
+        }),
+        json!({
+            "type": "object", "additionalProperties": false, "required": ["op", "sectionId", "tiles"],
+            "properties": {
+                "op": { "const": "removeSection" },
+                "sectionId": { "type": "string" },
+                "tiles": { "oneOf": [
+                    {
+                        "type": "object", "additionalProperties": false, "required": ["mode"],
+                        "properties": { "mode": { "enum": ["unsection", "delete"] } },
+                    },
+                    {
+                        "type": "object", "additionalProperties": false, "required": ["mode", "sectionId"],
+                        "properties": { "mode": { "const": "move" }, "sectionId": { "type": "string" } },
+                    },
+                ]},
+            },
+        }),
+    ]
+}
+
+fn read_only(kind: &str) -> Value {
+    json!({ "type": [kind, "null"], "readOnly": true })
+}
+
+fn dashboard_schema() -> Value {
+    let mut properties = json!({
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "tags": { "type": ["array", "null"], "items": { "type": "string" } },
+        "isFavorite": { "type": ["boolean", "null"] },
+        "dashboardType": { "enum": ["Dashboard", "Report", null] },
+        "dataset": { "type": ["string", "null"], "description": "default dataset for new tiles" },
+        "timeRange": { "$ref": "#/$defs/timeRange" },
+        "refreshInterval": { "enum": REFRESH_INTERVALS, "description": "saved auto-refresh default in milliseconds; 0 is off" },
+        "variables": { "type": "array", "maxItems": MAX_VARIABLES, "items": { "$ref": "#/$defs/variable" } },
+        "sections": { "type": "array", "maxItems": MAX_SECTIONS, "items": { "$ref": "#/$defs/section" } },
+        "tiles": { "type": "array", "maxItems": MAX_TILES, "items": { "$ref": "#/$defs/tile" } },
+    });
+    if let Some(properties) = properties.as_object_mut() {
+        for key in [
+            "dashboardId",
+            "author",
+            "created",
+            "modified",
+            "version",
+            "tenantId",
+            "revision",
+        ] {
+            properties.insert(key.to_owned(), read_only("string"));
+        }
+    }
+    json!({
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$ref": "#/$defs/dashboard",
+        "$defs": {
+            "dashboard": {
+                "type": "object",
+                "required": ["title"],
+                "additionalProperties": true,
+                "properties": properties,
+            },
+            "timeRange": time_range_schema(),
+            "section": {
+                "type": "object",
+                "required": ["sectionId"],
+                "additionalProperties": true,
+                "properties": {
+                    "sectionId": { "type": "string", "minLength": 1, "maxLength": MAX_ID_BYTES },
+                    "title": { "type": "string" },
+                    "collapsed": { "type": "boolean" },
+                },
+            },
+            "variable": variable_schema(),
+            "tile": tile_schema(),
+            "tileLayout": {
+                "type": "object",
+                "required": ["x", "y", "w", "h"],
+                "additionalProperties": true,
+                "properties": {
+                    "x": { "type": "integer", "minimum": 0, "description": "x + w <= 12" },
+                    "y": { "type": "integer", "minimum": 0, "maximum": MAX_TILE_ROW },
+                    "w": { "type": "integer", "minimum": 1, "maximum": GRID_COLUMNS },
+                    "h": { "type": "integer", "minimum": 1, "maximum": MAX_TILE_HEIGHT },
+                },
+            },
+            "tileConfig": tile_config_schema(),
+            "chartLayout": chart_layout_schema(),
+            "axis": {
+                "type": "object",
+                "additionalProperties": true,
+                "properties": {
+                    "field": { "type": ["string", "array"], "items": { "type": "string" } },
+                    "title": { "type": "string" },
+                    "display": { "type": "boolean" },
+                    "beginAtZero": { "type": "boolean" },
+                },
+            },
+        },
+    })
+}
+
+fn time_range_schema() -> Value {
+    json!({
+        "type": ["object", "null"],
+        "required": ["startTime", "endTime"],
+        "additionalProperties": true,
+        "properties": {
+            "startTime": { "type": "string", "description": "a preset (10m, 30m, 1h, 5h, 1d, 3d) for fixed ranges, RFC 3339 for custom" },
+            "endTime": { "type": "string", "description": "'now' for fixed ranges, RFC 3339 for custom" },
+            "type": { "enum": TIME_RANGE_TYPES },
+            "label": { "type": "string" },
+            "interval": { "type": "number", "description": "range length in milliseconds" },
+            "shiftInterval": { "type": "number" },
+        },
+    })
+}
+
+fn variable_schema() -> Value {
+    json!({
+        "type": "object",
+        "required": ["name", "label", "type"],
+        "additionalProperties": true,
+        "description": "promql needs dataset and labelName; promql_query needs promqlQuery and promqlQueryDataset; sql needs sqlQuery; list needs options. Reference variables as $name or ${name}.",
+        "properties": {
+            "name": { "type": "string", "pattern": "^\\w+$" },
+            "label": { "type": "string" },
+            "type": { "enum": VARIABLE_TYPES },
+            "dataset": { "type": "string" },
+            "labelName": { "type": "string" },
+            "metric": { "type": "string" },
+            "labelFilters": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": ["label", "operator", "value"],
+                    "properties": {
+                        "label": { "type": "string" },
+                        "operator": { "enum": LABEL_FILTER_OPERATORS },
+                        "value": { "type": "string" },
+                    },
+                },
+            },
+            "options": { "type": "array", "items": { "type": "string" } },
+            "sqlQuery": { "type": "string" },
+            "promqlQuery": { "type": "string" },
+            "promqlQueryDataset": { "type": "string" },
+            "promqlQueryLabel": { "type": "string" },
+            "includeAll": { "type": "boolean" },
+            "defaultValue": { "type": "string" },
+        },
+    })
+}
+
+fn tile_schema() -> Value {
+    json!({
+        "type": "object",
+        "required": ["tile_id"],
+        "additionalProperties": true,
+        "description": "code tiles store chartQuery as one SQL string; builder tiles store an SQL string or the visual builder object {x: {fields, groupBy, granularity}, y: {fields: [{name, aggregate}], groupBy, limit, sortBy}, filters: [{column, operator, value}]}; promql tiles store one query string or an array with promqlQueryType per query.",
+        "properties": {
+            "tile_id": { "type": "string", "description": "non-nil ULID" },
+            "title": { "type": "string" },
+            "authorMode": { "type": "string" },
+            "tileType": { "enum": TILE_TYPES, "default": "builder" },
+            "chartType": { "enum": CHART_TYPES, "default": "timeseries" },
+            "chartQuery": { "type": ["string", "array", "object"], "items": { "type": "string" } },
+            "promqlQueryType": { "oneOf": [
+                { "enum": QUERY_MODES },
+                { "type": "array", "items": { "enum": QUERY_MODES } },
+            ]},
+            "promqlStep": { "type": ["string", "number"], "description": "duration such as 30s, or seconds" },
+            "dbName": { "type": ["string", "array"], "items": { "type": "string" } },
+            "sectionId": { "type": ["string", "null"] },
+            "layout": { "$ref": "#/$defs/tileLayout" },
+            "config": { "$ref": "#/$defs/tileConfig" },
+        },
+    })
+}
+
+fn tile_config_schema() -> Value {
+    json!({
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+            "type": { "type": "string", "description": "series style (line, bar, area) for timeseries; otherwise the chart type" },
+            "colourScheme": { "enum": COLOUR_SCHEMES },
+            "maxDataPoints": { "type": "number", "exclusiveMinimum": 0 },
+            "layout": { "$ref": "#/$defs/chartLayout" },
+            "axes": {
+                "type": "object",
+                "additionalProperties": true,
+                "properties": {
+                    "x": { "$ref": "#/$defs/axis" },
+                    "y": { "$ref": "#/$defs/axis" },
+                    "size": { "$ref": "#/$defs/axis" },
+                    "groupBy": { "$ref": "#/$defs/axis" },
+                },
+            },
+            "advanced": {
+                "type": "object",
+                "additionalProperties": true,
+                "properties": {
+                    "dataLabels": { "type": "object", "properties": { "enabled": { "type": "boolean" } } },
+                    "tooltip": {
+                        "type": "object",
+                        "properties": {
+                            "enabled": { "type": "boolean" },
+                            "mode": { "type": "string" },
+                            "intersect": { "type": "boolean" },
+                        },
+                    },
+                },
+            },
+        },
+    })
+}
+
+fn chart_layout_schema() -> Value {
+    json!({
+        "type": "object",
+        "additionalProperties": true,
+        "description": "Display and conditional styling. Gauges colour green/yellow/red by up to two increasing segment thresholds (percent of range, or absolute within rangeFrom..rangeTo).",
+        "properties": {
+            "legendPosition": { "enum": LEGEND_POSITIONS },
+            "label": { "type": "boolean" },
+            "stacked": { "type": "boolean" },
+            "barOrientation": { "enum": BAR_ORIENTATIONS },
+            "sparkline": { "type": "boolean" },
+            "queryValueTheme": { "enum": QUERY_VALUE_THEMES },
+            "percentFill": { "enum": PERCENT_FILLS },
+            "unit": { "type": "string" },
+            "precision": { "type": "integer", "minimum": -1, "maximum": 20 },
+            "humanize": { "type": "boolean" },
+            "rangeFrom": { "type": "number" },
+            "rangeTo": { "type": "number" },
+            "segments": {
+                "type": "object",
+                "properties": {
+                    "value": { "type": "array", "items": { "type": "number" } },
+                    "isPercent": { "type": "boolean" },
+                },
+            },
+        },
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    const CLASSIC: &str =
+        include_str!("../../frontend/src/features/dashboards/__fixtures__/classic.json");
+    const HOST_LOAD: &str = "01JZ8Y5R7B2K9WQ0X4F6M1T3HD";
+    const ERRORS: &str = "01JZ8Y4A0C7H3GQ5P2W9D8S6VF";
+    const AI: &str = "01JZ8Y4A0C7H3GQ5P2W9D8S6VG";
+
+    fn classic() -> Value {
+        serde_json::from_str(CLASSIC).unwrap()
+    }
+
+    fn ops(value: Value) -> Vec<DashboardOperation> {
+        serde_json::from_value(value).unwrap()
+    }
+
+    fn apply(base: &Value, operations: Value) -> Value {
+        apply_patch(base, &ops(operations)).unwrap()
+    }
+
+    fn apply_err(base: &Value, operations: Value) -> PatchError {
+        apply_patch(base, &ops(operations)).unwrap_err()
+    }
+
+    fn id(n: u32) -> String {
+        format!("01JZ8Y5R7B2K9WQ0X4F6M{n:05}")
+    }
+
+    fn tile(n: u32, x: i64, y: i64, w: i64, h: i64) -> Value {
+        json!({ "tile_id": id(n), "layout": { "x": x, "y": y, "w": w, "h": h, "future": true } })
+    }
+
+    fn doc(tiles: Vec<Value>) -> Value {
+        json!({ "title": "Layout", "tiles": tiles })
+    }
+
+    fn tile_ref(id: &str) -> Value {
+        json!({ "type": "tile", "id": id })
+    }
+
+    fn ys(document: &Value) -> Vec<i64> {
+        document["tiles"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|tile| tile["layout"]["y"].as_i64().unwrap())
+            .collect()
+    }
+
+    /// Reading order of the stored layouts.
+    fn order(document: &Value) -> Vec<String> {
+        let mut tiles: Vec<&Value> = document["tiles"].as_array().unwrap().iter().collect();
+        tiles.sort_by_key(|tile| (tile["layout"]["y"].as_i64(), tile["layout"]["x"].as_i64()));
+        tiles
+            .iter()
+            .map(|tile| tile["tile_id"].as_str().unwrap().to_owned())
+            .collect()
+    }
+
+    fn codes(issues: &[ValidationIssue]) -> Vec<&str> {
+        issues.iter().map(|issue| issue.code.as_str()).collect()
+    }
+
+    #[test]
+    fn request_wire_shape_round_trips_and_rejects_unknown_fields() {
+        let request: DashboardPatchRequest = serde_json::from_value(json!({
+            "dryRun": true,
+            "revision": "abc",
+            "operations": [
+                { "op": "add", "target": tile_ref(&id(1)), "value": { "title": "t" } },
+                { "op": "replace", "target": { "type": "dashboard" }, "path": "/title", "value": "x" },
+                { "op": "remove", "target": { "type": "variable", "name": "host" }, "path": "/label" },
+                { "op": "placeTile", "tileId": id(1), "sectionId": null, "layout": { "w": 12 } },
+                { "op": "renameVariable", "from": "a", "to": "b" },
+                { "op": "reorderSections", "sectionIds": ["a", "b"] },
+                { "op": "removeSection", "sectionId": "a", "tiles": { "mode": "move", "sectionId": "b" } },
+            ],
+        }))
+        .unwrap();
+        assert!(request.dry_run);
+        assert_eq!(request.revision.as_deref(), Some("abc"));
+        assert_eq!(
+            request.operations[0],
+            DashboardOperation::Add {
+                target: PatchTarget::Tile { id: id(1) },
+                path: String::new(),
+                value: json!({ "title": "t" }),
+            }
+        );
+        assert_eq!(
+            request.operations[3],
+            DashboardOperation::PlaceTile {
+                tile_id: id(1),
+                section_id: Some(None),
+                layout: Some(LayoutEdits {
+                    w: Some(12),
+                    ..LayoutEdits::default()
+                }),
+            }
+        );
+        let again: DashboardPatchRequest =
+            serde_json::from_value(serde_json::to_value(&request).unwrap()).unwrap();
+        assert_eq!(again, request);
+        for invalid in [
+            json!({ "operations": [], "dryrun": true }),
+            json!({ "operations": [{ "op": "removeSection", "sectionId": "a" }] }),
+            json!({ "operations": [{ "op": "add", "target": { "type": "dashboard" }, "path": "/a" }] }),
+            json!({ "operations": [{ "op": "placeTile", "tileId": id(1), "layout": { "x": 1.5 } }] }),
+            json!({ "operations": [{ "op": "merge", "target": { "type": "dashboard" } }] }),
+        ] {
+            assert!(
+                serde_json::from_value::<DashboardPatchRequest>(invalid.clone()).is_err(),
+                "{invalid}"
+            );
+        }
+    }
+
+    #[test]
+    fn generic_edits_preserve_unknown_fields() {
+        let base = classic();
+        let candidate = apply(
+            &base,
+            json!([
+                { "op": "replace", "target": tile_ref(HOST_LOAD), "path": "/title", "value": "CPU load" },
+                { "op": "add", "target": tile_ref(HOST_LOAD), "path": "/config/layout/unit", "value": "%" },
+                { "op": "add", "target": { "type": "dashboard" }, "path": "/refreshInterval", "value": 60000 },
+                { "op": "add", "target": { "type": "section", "id": "classic-section" }, "path": "/title", "value": "Hosts" },
+            ]),
+        );
+        let mut expected = base.clone();
+        expected["tiles"][0]["title"] = json!("CPU load");
+        expected["tiles"][0]["config"]["layout"]["unit"] = json!("%");
+        expected["refreshInterval"] = json!(60000);
+        expected["sections"][0]["title"] = json!("Hosts");
+        assert_eq!(candidate, expected);
+        let report = validate_dashboard(&candidate, Some(&base));
+        assert!(report.valid, "{report:?}");
+    }
+
+    #[test]
+    fn missing_locations_fail_with_operation_context() {
+        let base = classic();
+        let error = apply_err(
+            &base,
+            json!([
+                { "op": "replace", "target": { "type": "dashboard" }, "path": "/title", "value": "Renamed" },
+                { "op": "replace", "target": tile_ref(ERRORS), "path": "/config/missing/key", "value": 1 },
+            ]),
+        );
+        assert_eq!(error.code, PatchErrorCode::PathNotFound);
+        assert_eq!(error.operation_index, Some(1));
+        assert_eq!(
+            error.target,
+            Some(PatchTarget::Tile {
+                id: ERRORS.to_owned()
+            })
+        );
+        assert_eq!(error.path.as_deref(), Some("/config/missing/key"));
+        for (operations, code) in [
+            (
+                json!([{ "op": "remove", "target": tile_ref(ERRORS), "path": "/nope" }]),
+                PatchErrorCode::PathNotFound,
+            ),
+            (
+                json!([{ "op": "replace", "target": tile_ref(ERRORS), "path": "/dbName/5", "value": "x" }]),
+                PatchErrorCode::PathNotFound,
+            ),
+            (
+                json!([{ "op": "remove", "target": tile_ref(&id(77)) }]),
+                PatchErrorCode::TargetNotFound,
+            ),
+            (
+                json!([{ "op": "replace", "target": { "type": "variable", "name": "nope" }, "path": "/label", "value": "x" }]),
+                PatchErrorCode::TargetNotFound,
+            ),
+        ] {
+            assert_eq!(apply_err(&base, operations).code, code);
+        }
+    }
+
+    #[test]
+    fn failed_batches_are_atomic_and_invalid_final_states_are_reported() {
+        let base = classic();
+        let before = base.clone();
+        let error = apply_err(
+            &base,
+            json!([
+                { "op": "replace", "target": { "type": "dashboard" }, "path": "/title", "value": "Renamed" },
+                { "op": "remove", "target": { "type": "section", "id": "classic-section" } },
+            ]),
+        );
+        assert_eq!(error.code, PatchErrorCode::InvalidOperation);
+        assert_eq!(error.operation_index, Some(1));
+        assert_eq!(base, before);
+
+        let candidate = apply(
+            &base,
+            json!([
+                { "op": "replace", "target": { "type": "dashboard" }, "path": "/title", "value": "Renamed" },
+                { "op": "replace", "target": tile_ref(ERRORS), "path": "/chartType", "value": "sparkle" },
+            ]),
+        );
+        let report = validate_dashboard(&candidate, Some(&base));
+        assert!(!report.valid);
+        assert_eq!(codes(&report.errors), ["unsupported_chart_type"]);
+        assert_eq!(
+            report.errors[0].target,
+            PatchTarget::Tile {
+                id: ERRORS.to_owned()
+            }
+        );
+        assert_eq!(report.errors[0].path, "/chartType");
+    }
+
+    #[test]
+    fn sql_tile_converts_to_multi_query_promql_in_one_batch() {
+        let base = classic();
+        let operations = ops(json!([
+            { "op": "replace", "target": tile_ref(ERRORS), "path": "/chartQuery", "value": ["sum(rate(http_requests_total[5m]))", "up"] },
+            { "op": "add", "target": tile_ref(ERRORS), "path": "/promqlQueryType", "value": ["range", "instant"] },
+            { "op": "replace", "target": tile_ref(ERRORS), "path": "/tileType", "value": "promql" },
+            { "op": "replace", "target": tile_ref(ERRORS), "path": "/dbName", "value": ["otel-metrics"] },
+            { "op": "replace", "target": tile_ref(ERRORS), "path": "/chartType", "value": "timeseries" },
+        ]));
+        let partial = apply_patch(&base, &operations[..1]).unwrap();
+        let report = validate_dashboard(&partial, Some(&base));
+        assert!(
+            codes(&report.errors).contains(&"invalid_query_shape"),
+            "{report:?}"
+        );
+
+        let candidate = apply_patch(&base, &operations).unwrap();
+        let report = validate_dashboard(&candidate, Some(&base));
+        assert!(report.valid, "{report:?}");
+        assert_eq!(candidate["tiles"][1]["config"], base["tiles"][1]["config"]);
+
+        let mismatched = apply(
+            &candidate,
+            json!([{ "op": "replace", "target": tile_ref(ERRORS), "path": "/promqlQueryType", "value": ["range"] }]),
+        );
+        let report = validate_dashboard(&mismatched, Some(&candidate));
+        assert_eq!(codes(&report.errors), ["invalid_query_mode"]);
+    }
+
+    #[test]
+    fn server_owned_identity_and_internal_paths_are_protected() {
+        let mut base = classic();
+        base[INTERNAL_METADATA_KEY] = json!({ "version": 3 });
+        let dashboard = json!({ "type": "dashboard" });
+        let section = json!({ "type": "section", "id": "classic-section" });
+        let variable = json!({ "type": "variable", "name": "host" });
+        for (target, path) in [
+            (&dashboard, ""),
+            (&dashboard, "/dashboardId"),
+            (&dashboard, "/dashboard_id"),
+            (&dashboard, "/Author"),
+            (&dashboard, "/tenant-id"),
+            (&dashboard, "/revision"),
+            (&dashboard, "/created"),
+            (&dashboard, "/_parseableDashboard"),
+            (&dashboard, "/_PARSEABLE_dashboard/version"),
+            (&dashboard, "/tiles/0/title"),
+            (&dashboard, "/Variables"),
+            (&tile_ref(HOST_LOAD), "/tile_id"),
+            (&tile_ref(HOST_LOAD), "/tileId"),
+            (&section, "/sectionId"),
+            (&variable, "/name"),
+        ] {
+            for op in ["add", "replace", "remove"] {
+                let mut operation = json!({ "op": op, "target": target, "path": path });
+                if op != "remove" {
+                    operation["value"] = json!("x");
+                }
+                let error = apply_err(&base, json!([operation]));
+                assert_eq!(error.code, PatchErrorCode::ProtectedPath, "{op} {path}");
+            }
+        }
+        for path in ["/tile~2id", "title", "/a~"] {
+            let error = apply_err(
+                &base,
+                json!([{ "op": "add", "target": tile_ref(HOST_LOAD), "path": path, "value": 1 }]),
+            );
+            assert_eq!(error.code, PatchErrorCode::InvalidPointer, "{path}");
+        }
+        for value in [
+            json!({ "tile_id": id(8) }),
+            json!({ "tileId": id(9) }),
+            json!("tile"),
+        ] {
+            let error = apply_err(
+                &base,
+                json!([{ "op": "add", "target": tile_ref(&id(9)), "value": value }]),
+            );
+            assert_eq!(error.code, PatchErrorCode::InvalidValue);
+        }
+
+        let replaced = apply(
+            &base,
+            json!([{ "op": "replace", "target": tile_ref(HOST_LOAD), "value": { "title": "New", "tileType": "code", "chartQuery": "SELECT 1" } }]),
+        );
+        assert_eq!(replaced["tiles"][0]["tile_id"], HOST_LOAD);
+        assert_eq!(replaced["tiles"][0]["layout"], base["tiles"][0]["layout"]);
+        assert_eq!(replaced[INTERNAL_METADATA_KEY], base[INTERNAL_METADATA_KEY]);
+        assert!(validate_dashboard(&replaced, Some(&base)).valid);
+
+        let mut tampered = replaced.clone();
+        tampered[INTERNAL_METADATA_KEY] = json!({ "version": 4 });
+        let report = validate_dashboard(&tampered, Some(&base));
+        assert_eq!(codes(&report.errors), ["reserved_field"]);
+        assert!(codes(&validate_dashboard(&base, None).errors).contains(&"reserved_field"));
+        strip_internal_metadata(&mut tampered);
+        assert!(tampered.get(INTERNAL_METADATA_KEY).is_none());
+    }
+
+    #[test]
+    fn rename_variable_rewrites_references_and_rejects_collisions() {
+        let base = classic();
+        let candidate = apply(
+            &base,
+            json!([{ "op": "renameVariable", "from": "metrics_dataset", "to": "metrics" }]),
+        );
+        assert_eq!(candidate["variables"][0]["name"], "metrics");
+        assert_eq!(candidate["variables"][0]["customVariable"], true);
+        assert_eq!(candidate["variables"][1]["dataset"], "$metrics");
+        assert_eq!(candidate["variables"][2]["promqlQueryDataset"], "$metrics");
+        assert_eq!(candidate["tiles"][0]["dbName"], "$metrics");
+        assert!(validate_dashboard(&candidate, Some(&base)).valid);
+
+        let renamed = apply(
+            &base,
+            json!([{ "op": "renameVariable", "from": "host", "to": "server" }]),
+        );
+        assert_eq!(
+            renamed["tiles"][0]["chartQuery"][0],
+            "avg by (host) ({__name__=\"system.cpu.load_average.15m\",host=~\"$server\"})"
+        );
+
+        let error = apply_err(
+            &base,
+            json!([{ "op": "renameVariable", "from": "host", "to": "result" }]),
+        );
+        assert_eq!(error.code, PatchErrorCode::NameConflict);
+        assert_eq!(
+            error.target,
+            Some(PatchTarget::Variable {
+                name: "result".to_owned()
+            })
+        );
+        let error = apply_err(
+            &base,
+            json!([{ "op": "renameVariable", "from": "nope", "to": "x" }]),
+        );
+        assert_eq!(error.code, PatchErrorCode::TargetNotFound);
+        assert_eq!(
+            rename_tokens("${host} $hostname $$host x$host", "host", "h").as_deref(),
+            Some("${h} $hostname $$h x$h")
+        );
+
+        let removed = apply(
+            &base,
+            json!([{ "op": "remove", "target": { "type": "variable", "name": "host" } }]),
+        );
+        let report = validate_dashboard(&removed, Some(&base));
+        assert_eq!(codes(&report.errors), ["dangling_variable_reference"]);
+        assert_eq!(
+            report.errors[0].target,
+            PatchTarget::Tile {
+                id: HOST_LOAD.to_owned()
+            }
+        );
+    }
+
+    fn mixed() -> Value {
+        doc(vec![
+            tile(1, 0, 0, 6, 8),
+            tile(2, 6, 0, 6, 4),
+            tile(3, 6, 4, 6, 4),
+            tile(4, 0, 8, 12, 4),
+        ])
+    }
+
+    fn place(n: u32, layout: Value) -> Value {
+        json!([{ "op": "placeTile", "tileId": id(n), "layout": layout }])
+    }
+
+    #[test]
+    fn layout_matches_frontend_resize_remove_and_drag() {
+        let base = mixed();
+        assert_eq!(
+            ys(&apply(&base, place(2, json!({ "h": 8 })))),
+            [0, 0, 8, 12]
+        );
+        let removed = apply(
+            &base,
+            json!([{ "op": "remove", "target": tile_ref(&id(2)) }]),
+        );
+        assert_eq!(ys(&removed), [0, 0, 8]);
+
+        let widened = apply(&base, place(2, json!({ "x": 4, "w": 8 })));
+        let rects: Vec<Rect> = widened["tiles"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|tile| {
+                let n = |key: &str| tile["layout"][key].as_i64().unwrap();
+                Rect {
+                    x: n("x"),
+                    y: n("y"),
+                    w: n("w"),
+                    h: n("h"),
+                }
+            })
+            .collect();
+        for (i, a) in rects.iter().enumerate() {
+            for b in &rects[i + 1..] {
+                assert!(!a.overlaps(b), "{a:?} {b:?}");
+            }
+        }
+
+        let source = doc(vec![
+            tile(1, 0, 0, 12, 4),
+            tile(2, 0, 4, 12, 4),
+            tile(3, 0, 8, 12, 4),
+        ]);
+        assert_eq!(
+            order(&apply(&source, place(1, json!({ "x": 0, "y": 4 })))),
+            [id(2), id(1), id(3)]
+        );
+        assert_eq!(
+            order(&apply(&source, place(3, json!({ "x": 0, "y": 0 })))),
+            [id(3), id(1), id(2)]
+        );
+        assert_eq!(
+            source["tiles"][0]["layout"],
+            json!({ "x": 0, "y": 0, "w": 12, "h": 4, "future": true })
+        );
+    }
+
+    #[test]
+    fn resize_preserves_opaque_and_legacy_layout_fields() {
+        let mut first = tile(1, 8, 0, 4, 4);
+        first["custom"] = json!({ "untouched": true });
+        let second = json!({ "tile_id": id(2), "layout": { "x": -7, "y": 0, "w": 8, "h": 30, "future": true } });
+        let base = doc(vec![first, second]);
+        let candidate = apply(&base, place(1, json!({ "w": 12, "h": 6 })));
+        assert_eq!(
+            candidate["tiles"][0],
+            json!({ "tile_id": id(1), "custom": { "untouched": true }, "layout": { "x": 0, "y": 0, "w": 12, "h": 6, "future": true } })
+        );
+        assert_eq!(
+            candidate["tiles"][1]["layout"],
+            json!({ "x": -7, "y": 6, "w": 8, "h": 30, "future": true })
+        );
+        let report = validate_dashboard(&candidate, Some(&base));
+        assert!(report.valid, "{report:?}");
+        let legacy: Vec<&str> = report
+            .warnings
+            .iter()
+            .filter(|issue| issue.legacy)
+            .map(|issue| issue.path.as_str())
+            .collect();
+        assert!(
+            legacy.contains(&"/layout/x") && legacy.contains(&"/layout/h"),
+            "{legacy:?}"
+        );
+
+        for (edits, path) in [
+            (json!({ "w": 99 }), "/layout/w"),
+            (json!({ "h": 25 }), "/layout/h"),
+            (json!({ "x": 9, "w": 6 }), "/layout/x"),
+            (json!({ "y": -1 }), "/layout/y"),
+        ] {
+            let error = apply_err(&base, place(1, edits));
+            assert_eq!(error.code, PatchErrorCode::InvalidValue);
+            assert_eq!(error.path.as_deref(), Some(path));
+        }
+
+        let untouched = doc(vec![
+            json!({ "tile_id": id(1), "layout": { "x": -2, "y": 12, "w": 6, "h": 4 } }),
+        ]);
+        assert_eq!(
+            apply(&untouched, place(1, json!({ "x": 0, "y": 0 }))),
+            untouched
+        );
+    }
+
+    #[test]
+    fn huge_layout_coordinates_are_rejected_without_overflow() {
+        for x in [json!(i64::MAX), json!(u64::MAX), json!(-1), json!(7)] {
+            let document = doc(vec![
+                json!({ "tile_id": id(1), "layout": { "x": x, "y": 0, "w": 6, "h": 4 } }),
+            ]);
+            let report = validate_dashboard(&document, None);
+            assert_eq!(codes(&report.errors), ["invalid_layout"], "{x}");
+            assert_eq!(report.errors[0].path, "/layout/x");
+        }
+    }
+
+    fn sectioned() -> Value {
+        json!({
+            "title": "Sections",
+            "extra": { "preserved": true },
+            "sections": [
+                { "sectionId": "a", "title": "Alpha", "future": 9 },
+                { "opaque": true },
+                { "sectionId": "b", "title": "Beta" },
+            ],
+            "tiles": [
+                { "tile_id": id(1), "layout": { "x": 0, "y": 0, "w": 12, "h": 4 } },
+                { "tile_id": id(2), "sectionId": "a", "layout": { "x": 0, "y": 0, "w": 6, "h": 4, "future": true } },
+                { "tile_id": id(3), "sectionId": "b", "layout": { "x": 0, "y": 0, "w": 6, "h": 4 } },
+            ],
+        })
+    }
+
+    #[test]
+    fn sections_move_remove_and_reorder_like_the_frontend() {
+        let base = sectioned();
+        let moved = apply(
+            &base,
+            json!([{ "op": "placeTile", "tileId": id(2), "sectionId": "b" }]),
+        );
+        assert_eq!(
+            moved["tiles"][1],
+            json!({ "tile_id": id(2), "sectionId": "b", "layout": { "x": 0, "y": 4, "w": 6, "h": 4, "future": true } })
+        );
+        assert_eq!(moved["tiles"][0], base["tiles"][0]);
+        assert_eq!(moved["tiles"][2], base["tiles"][2]);
+
+        let remove =
+            |tiles: Value| json!([{ "op": "removeSection", "sectionId": "a", "tiles": tiles }]);
+        let unsectioned = apply(&base, remove(json!({ "mode": "unsection" })));
+        assert_eq!(
+            unsectioned["sections"],
+            json!([{ "opaque": true }, { "sectionId": "b", "title": "Beta" }])
+        );
+        assert_eq!(
+            unsectioned["tiles"][1],
+            json!({ "tile_id": id(2), "layout": { "x": 0, "y": 4, "w": 6, "h": 4, "future": true } })
+        );
+        assert_eq!(unsectioned["tiles"][2], base["tiles"][2]);
+        assert_eq!(unsectioned["extra"], base["extra"]);
+
+        let mut tall = base.clone();
+        tall["tiles"][0]["layout"]["h"] = json!(50);
+        assert_eq!(
+            apply(&tall, remove(json!({ "mode": "unsection" })))["tiles"][1]["layout"]["y"],
+            50
+        );
+
+        let relocated = apply(&base, remove(json!({ "mode": "move", "sectionId": "b" })));
+        assert_eq!(relocated["tiles"][1]["sectionId"], "b");
+        assert_eq!(relocated["tiles"][1]["layout"]["y"], 4);
+        let deleted = apply(&base, remove(json!({ "mode": "delete" })));
+        assert_eq!(order(&deleted), [id(1), id(3)]);
+        assert_eq!(
+            apply_err(&base, remove(json!({ "mode": "move", "sectionId": "a" }))).code,
+            PatchErrorCode::InvalidOperation
+        );
+        assert_eq!(
+            apply_err(&base, remove(json!({ "mode": "move", "sectionId": "zzz" }))).code,
+            PatchErrorCode::TargetNotFound
+        );
+
+        let reordered = apply(
+            &base,
+            json!([{ "op": "reorderSections", "sectionIds": ["b", "a"] }]),
+        );
+        assert_eq!(
+            reordered["sections"],
+            json!([{ "sectionId": "b", "title": "Beta" }, { "opaque": true }, { "sectionId": "a", "title": "Alpha", "future": 9 }])
+        );
+        assert_eq!(
+            apply_err(
+                &base,
+                json!([{ "op": "reorderSections", "sectionIds": ["b"] }])
+            )
+            .code,
+            PatchErrorCode::InvalidOperation
+        );
+        assert_eq!(
+            apply_err(
+                &base,
+                json!([{ "op": "reorderSections", "sectionIds": ["b", "zzz"] }])
+            )
+            .code,
+            PatchErrorCode::TargetNotFound
+        );
+        assert_eq!(
+            apply_err(
+                &base,
+                json!([{ "op": "placeTile", "tileId": id(1), "sectionId": "zzz" }])
+            )
+            .code,
+            PatchErrorCode::TargetNotFound
+        );
+    }
+
+    #[test]
+    fn added_entities_get_ids_defaults_and_compaction() {
+        let base = doc(vec![tile(1, 0, 0, 6, 4), tile(2, 6, 0, 6, 8)]);
+        let candidate = apply(
+            &base,
+            json!([
+                { "op": "add", "target": tile_ref(&id(3)), "value": { "title": "Rows", "tileType": "code", "chartType": "table", "chartQuery": "SELECT 1", "dbName": ["app-logs"] } },
+                { "op": "add", "target": { "type": "section", "id": "ops" }, "value": { "title": "Ops" } },
+                { "op": "add", "target": { "type": "variable", "name": "env" }, "value": { "label": "Env", "type": "list", "options": ["prod"] } },
+            ]),
+        );
+        assert_eq!(candidate["tiles"][2]["tile_id"], id(3));
+        assert_eq!(
+            candidate["tiles"][2]["layout"],
+            json!({ "x": 0, "y": 4, "w": 6, "h": 4 })
+        );
+        assert_eq!(
+            candidate["sections"],
+            json!([{ "sectionId": "ops", "title": "Ops" }])
+        );
+        assert_eq!(candidate["variables"][0]["name"], "env");
+        let report = validate_dashboard(&candidate, Some(&base));
+        assert!(report.valid, "{report:?}");
+
+        let add = |target: &str| json!([{ "op": "add", "target": tile_ref(target), "value": {} }]);
+        assert_eq!(
+            apply_err(&base, add(&id(1))).code,
+            PatchErrorCode::TargetExists
+        );
+        assert_eq!(
+            apply_err(&base, add("00000000000000000000000000")).code,
+            PatchErrorCode::InvalidTarget
+        );
+        assert_eq!(
+            apply_err(&base, add("not-a-ulid")).code,
+            PatchErrorCode::InvalidTarget
+        );
+    }
+
+    #[test]
+    fn untouched_legacy_defects_warn_while_new_ones_fail() {
+        let base = classic();
+        let fresh = validate_dashboard(&base, None);
+        assert_eq!(codes(&fresh.errors), ["unsupported_tile_type"]);
+        let unchanged = validate_dashboard(&base, Some(&base));
+        assert!(unchanged.valid);
+        assert!(
+            unchanged
+                .warnings
+                .iter()
+                .any(|issue| issue.legacy && issue.code == "unsupported_tile_type")
+        );
+
+        let retitled = apply(
+            &base,
+            json!([{ "op": "replace", "target": tile_ref(AI), "path": "/title", "value": "Summary" }]),
+        );
+        assert!(validate_dashboard(&retitled, Some(&base)).valid);
+        let changed = apply(
+            &base,
+            json!([{ "op": "replace", "target": tile_ref(AI), "path": "/tileType", "value": "ai2" }]),
+        );
+        assert!(!validate_dashboard(&changed, Some(&base)).valid);
+    }
+
+    #[test]
+    fn legacy_duplicates_are_grandfathered_by_count() {
+        let titled = |title: &str| {
+            let mut tile = tile(1, 0, 0, 6, 4);
+            tile["title"] = json!(title);
+            tile
+        };
+        let base = doc(vec![titled("a"), titled("b")]);
+        assert!(validate_dashboard(&base, Some(&base)).valid);
+        assert_eq!(
+            apply_err(&base, json!([{ "op": "replace", "target": tile_ref(&id(1)), "path": "/title", "value": "c" }])).code,
+            PatchErrorCode::AmbiguousTarget
+        );
+        let grown = doc(vec![titled("a"), titled("b"), titled("c")]);
+        let report = validate_dashboard(&grown, Some(&base));
+        assert_eq!(codes(&report.errors), ["duplicate_tile_id"]);
+        assert_eq!(
+            report
+                .warnings
+                .iter()
+                .filter(|issue| issue.code == "duplicate_tile_id")
+                .count(),
+            1
+        );
+    }
+
+    #[test]
+    fn limits_reject_growth_but_allow_legacy_shrinking() {
+        let replace = json!({ "op": "replace", "target": { "type": "dashboard" }, "path": "/title", "value": "x" });
+        let error = apply_err(
+            &doc(vec![]),
+            Value::Array(vec![replace; MAX_OPERATIONS + 1]),
+        );
+        assert_eq!(error.code, PatchErrorCode::TooManyOperations);
+
+        let many = |count: u32| {
+            doc((0..count)
+                .map(|n| tile(n, 0, i64::from(n) * 4, 12, 4))
+                .collect())
+        };
+        let base = many(501);
+        assert_eq!(
+            codes(&validate_dashboard(&many(502), Some(&base)).errors),
+            ["limit_exceeded"]
+        );
+        assert_eq!(
+            codes(&validate_dashboard(&many(1000), Some(&base)).errors),
+            ["limit_exceeded"]
+        );
+        assert!(validate_dashboard(&many(501), Some(&base)).valid);
+        assert!(validate_dashboard(&many(400), Some(&base)).valid);
+        assert_eq!(
+            codes(&validate_dashboard(&many(501), None).errors),
+            ["limit_exceeded"]
+        );
+        let error = apply_err(
+            &base,
+            json!([{ "op": "add", "target": tile_ref(&id(900)), "value": {} }]),
+        );
+        assert_eq!(error.code, PatchErrorCode::LimitExceeded);
+
+        let small = doc(vec![]);
+        let huge = json!([{ "op": "add", "target": tile_ref(&id(1)), "value": { "title": "x".repeat(MAX_DOCUMENT_BYTES) } }]);
+        assert_eq!(
+            apply_err(&small, huge).code,
+            PatchErrorCode::DocumentTooLarge
+        );
+        let mut oversized = small.clone();
+        oversized["description"] = json!("x".repeat(MAX_DOCUMENT_BYTES));
+        assert_eq!(
+            codes(&validate_dashboard(&oversized, Some(&small)).errors),
+            ["document_too_large"]
+        );
+        assert!(validate_dashboard(&oversized, Some(&oversized)).valid);
+    }
+
+    #[test]
+    fn long_variable_chains_validate_without_recursion() {
+        let chain = |cycle: bool| {
+            let count = 20_000;
+            let variables: Vec<Value> = (0..count)
+                .map(|i| {
+                    let next = if cycle && i + 1 == count { 0 } else { i + 1 };
+                    json!({ "name": format!("v{i}"), "label": "v", "type": "sql", "sqlQuery": format!("SELECT $v{next}") })
+                })
+                .collect();
+            json!({ "title": "Chain", "variables": variables })
+        };
+        let cycles = |document: &Value| {
+            check_document(document)
+                .iter()
+                .filter(|finding| finding.issue.code == "variable_cycle")
+                .count()
+        };
+        assert_eq!(cycles(&chain(false)), 0);
+        assert_eq!(cycles(&chain(true)), 1);
+        let legacy = chain(true);
+        assert!(validate_dashboard(&legacy, Some(&legacy)).valid);
+        assert_eq!(
+            codes(&validate_dashboard(&legacy, None).errors),
+            ["limit_exceeded"]
+        );
+
+        let small = json!({ "title": "Cycle", "variables": [
+            { "name": "a", "label": "a", "type": "sql", "sqlQuery": "SELECT $b" },
+            { "name": "b", "label": "b", "type": "sql", "sqlQuery": "SELECT ${a}" },
+        ]});
+        assert_eq!(
+            codes(&validate_dashboard(&small, None).errors),
+            ["variable_cycle"]
+        );
+    }
+
+    fn gauge(layout: Value) -> Value {
+        json!({ "title": "Gauge", "tiles": [{
+            "tile_id": id(1), "tileType": "code", "chartType": "gauge", "chartQuery": "SELECT 1",
+            "dbName": ["logs"], "layout": { "x": 0, "y": 0, "w": 6, "h": 4 },
+            "config": { "type": "gauge", "colourScheme": "classic", "layout": layout },
+        }]})
+    }
+
+    #[test]
+    fn styling_thresholds_and_enums_are_validated() {
+        let valid = gauge(
+            json!({ "rangeFrom": 0, "rangeTo": 200, "segments": { "value": [50, 150], "isPercent": false }, "unit": "ms", "precision": 2 }),
+        );
+        assert!(
+            validate_dashboard(&valid, None).valid,
+            "{:?}",
+            validate_dashboard(&valid, None)
+        );
+        for (layout, code) in [
+            (
+                json!({ "segments": { "value": [150, 50], "isPercent": false }, "rangeTo": 200 }),
+                "invalid_segments",
+            ),
+            (
+                json!({ "segments": { "value": [10, 120], "isPercent": true } }),
+                "invalid_segments",
+            ),
+            (
+                json!({ "segments": { "value": "high" } }),
+                "invalid_segments",
+            ),
+            (
+                json!({ "rangeFrom": 10, "rangeTo": 10 }),
+                "invalid_gauge_range",
+            ),
+            (json!({ "queryValueTheme": "neon" }), "invalid_field_value"),
+            (json!({ "percentFill": "radial" }), "invalid_field_value"),
+            (json!({ "precision": 40 }), "invalid_field_value"),
+        ] {
+            let report = validate_dashboard(&gauge(layout.clone()), None);
+            assert!(codes(&report.errors).contains(&code), "{layout} {report:?}");
+        }
+        let mut scheme = valid.clone();
+        scheme["tiles"][0]["config"]["colourScheme"] = json!("rainbow");
+        assert_eq!(
+            codes(&validate_dashboard(&scheme, None).errors),
+            ["unknown_colour_scheme"]
+        );
+    }
+
+    #[test]
+    fn time_range_refresh_and_variables_are_validated() {
+        let time = |range: Value| json!({ "title": "Time", "timeRange": range });
+        assert!(validate_dashboard(&time(json!({ "startTime": "2026-10-01T00:00:00Z", "endTime": "now", "type": "custom" })), None).valid);
+        assert!(
+            validate_dashboard(
+                &time(json!({ "startTime": "1h", "endTime": "now", "type": "fixed" })),
+                None
+            )
+            .valid
+        );
+        for range in [
+            json!({ "startTime": "now", "endTime": "2026-10-01T00:00:00Z", "type": "custom" }),
+            json!({ "startTime": "2026-10-02T00:00:00Z", "endTime": "2026-10-01T00:00:00Z", "type": "custom" }),
+            json!({ "startTime": "yesterday", "endTime": "now", "type": "custom" }),
+            json!({ "startTime": "1h", "type": "fixed" }),
+        ] {
+            assert_eq!(
+                codes(&validate_dashboard(&time(range.clone()), None).errors),
+                ["invalid_time_range"],
+                "{range}"
+            );
+        }
+        let unusual = validate_dashboard(
+            &time(json!({ "startTime": "2w", "endTime": "now", "type": "fixed" })),
+            None,
+        );
+        assert!(unusual.valid && codes(&unusual.warnings).contains(&"unknown_time_preset"));
+
+        assert!(validate_dashboard(&json!({ "title": "R", "refreshInterval": 60000 }), None).valid);
+        assert_eq!(
+            codes(
+                &validate_dashboard(&json!({ "title": "R", "refreshInterval": 1234 }), None).errors
+            ),
+            ["invalid_refresh_interval"]
+        );
+        let variables = json!({ "title": "V", "variables": [
+            { "name": "a", "label": "A", "type": "promql", "dataset": "metrics" },
+            { "name": "b", "label": "B", "type": "radio" },
+            { "name": "c", "label": "C", "type": "promql", "dataset": "m", "labelName": "host", "labelFilters": [{ "label": "x", "operator": "~", "value": "y" }] },
+        ]});
+        assert_eq!(
+            codes(&validate_dashboard(&variables, None).errors),
+            [
+                "incomplete_variable",
+                "unsupported_variable_type",
+                "invalid_label_filter"
+            ]
+        );
+    }
+
+    #[test]
+    fn builder_object_queries_are_supported() {
+        let builder = |chart: &str, query: Value| {
+            json!({ "title": "Builder", "tiles": [{
+                "tile_id": id(1), "tileType": "builder", "chartType": chart, "chartQuery": query,
+                "dbName": ["app-logs"], "layout": { "x": 0, "y": 0, "w": 6, "h": 4 },
+            }]})
+        };
+        // frontend newBuilderQuery('timeseries'), plus a filter, sort and an unknown extension
+        let query = json!({
+            "x": { "fields": [{ "name": "p_timestamp" }], "groupBy": [], "granularity": "hour" },
+            "y": { "fields": [{ "name": "*", "aggregate": "COUNT" }, { "name": "latency", "aggregate": "avg" }], "groupBy": ["level"], "limit": 100, "sortBy": { "field": "latency", "direction": "DESC" } },
+            "filters": [{ "column": "level", "operator": "=", "value": "error" }, { "column": "host", "operator": "is not null" }],
+            "future": { "kept": true },
+        });
+        let report = validate_dashboard(&builder("timeseries", query.clone()), None);
+        assert!(report.valid, "{report:?}");
+        let stat = json!({ "x": { "fields": [], "groupBy": [] }, "y": { "fields": [{ "name": "*", "aggregate": "COUNT" }], "groupBy": [], "limit": 100 }, "filters": [] });
+        assert!(validate_dashboard(&builder("query-value", stat), None).valid);
+
+        for (chart, broken) in [
+            (
+                "bar",
+                json!({ "x": { "fields": [] }, "y": { "fields": [{ "name": "latency", "aggregate": "MEDIAN" }] } }),
+            ),
+            (
+                "bar",
+                json!({ "y": { "fields": [{ "name": "*", "aggregate": "SUM" }] } }),
+            ),
+            (
+                "bar",
+                json!({ "y": { "fields": [{ "name": "*", "aggregate": "COUNT" }] }, "filters": [{ "column": "a", "operator": "like", "value": "x" }] }),
+            ),
+            (
+                "bar",
+                json!({ "y": { "fields": [{ "name": "*", "aggregate": "COUNT" }], "limit": 0 } }),
+            ),
+            (
+                "timeseries",
+                json!({ "x": { "fields": [] }, "y": { "fields": [{ "name": "*", "aggregate": "COUNT" }] } }),
+            ),
+            (
+                "gauge",
+                json!({ "x": { "fields": [{ "name": "a" }] }, "y": { "fields": [] } }),
+            ),
+            ("bar", json!({ "x": { "fields": [] } })),
+        ] {
+            let report = validate_dashboard(&builder(chart, broken.clone()), None);
+            assert_eq!(
+                codes(&report.errors),
+                ["invalid_builder_query"],
+                "{broken} {report:?}"
+            );
+        }
+        let mut no_dataset = builder("bar", query.clone());
+        no_dataset["tiles"][0]["dbName"] = json!([]);
+        assert_eq!(
+            codes(&validate_dashboard(&no_dataset, None).errors),
+            ["missing_dataset"]
+        );
+        let mut code_tile = builder("bar", query);
+        code_tile["tiles"][0]["tileType"] = json!("code");
+        assert_eq!(
+            codes(&validate_dashboard(&code_tile, None).errors),
+            ["legacy_query_shape"]
+        );
+    }
+
+    #[test]
+    fn capabilities_publish_inline_schemas_and_enums() {
+        let caps = capabilities();
+        let operations = caps["patch"]["operations"].as_array().unwrap();
+        for op in [
+            "add",
+            "replace",
+            "remove",
+            "placeTile",
+            "renameVariable",
+            "reorderSections",
+            "removeSection",
+        ] {
+            assert!(operations.contains(&json!(op)), "{op}");
+        }
+        assert_eq!(
+            caps["enums"]["chartTypes"].as_array().unwrap().len(),
+            CHART_TYPES.len()
+        );
+        let properties = &caps["schema"]["$defs"]["dashboard"]["properties"];
+        for key in [
+            "title",
+            "timeRange",
+            "refreshInterval",
+            "variables",
+            "sections",
+            "tiles",
+            "dashboardId",
+        ] {
+            assert!(properties.get(key).is_some(), "{key}");
+        }
+        assert!(!caps["operationItemSchema"].to_string().contains("$ref"));
+        assert!(!caps["operationSchema"].to_string().contains("$ref"));
+        assert_eq!(
+            caps["operationSchema"]["properties"]["operations"]["maxItems"],
+            MAX_OPERATIONS
+        );
+        assert_eq!(
+            caps["operationItemSchema"]["oneOf"]
+                .as_array()
+                .unwrap()
+                .len(),
+            6
+        );
+    }
+}
diff --git a/src/users/dashboard_runtime.rs b/src/users/dashboard_runtime.rs
new file mode 100644
index 000000000..3e0632c6f
--- /dev/null
+++ b/src/users/dashboard_runtime.rs
@@ -0,0 +1,1498 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//! Explicit, read-only dashboard execution. Configuration validation never calls this module.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use actix_web::{HttpRequest, HttpResponse, web::Json};
+use chrono::DateTime;
+use futures_util::{StreamExt, stream};
+use once_cell::sync::Lazy;
+use regex::{Captures, Regex};
+use serde::Deserialize;
+use serde_json::{Value, json};
+use tokio::sync::Semaphore;
+
+use crate::handlers::http::{
+    promql,
+    query::{self, Query},
+    users::dashboards::DashboardError,
+};
+use crate::users::{
+    dashboard_patch::{self, DashboardOperation},
+    dashboard_service,
+    dashboards::validate_dashboard_id,
+};
+use crate::utils::{
+    actix::extract_session_key_from_req, arrow::record_batches_to_json, get_tenant_id_from_request,
+};
+use crate::{
+    handlers::http::middleware,
+    rbac::{Response, Users, role::Action},
+};
+
+const MAX_BYTES: usize = 1024 * 1024;
+const MAX_TILES: usize = 32;
+const MAX_QUERY_BYTES: usize = 16 * 1024;
+const MAX_RANGE_MS: i64 = 31 * 86400 * 1000;
+static PREVIEW_SLOTS: Lazy<Arc<Semaphore>> = Lazy::new(|| Arc::new(Semaphore::new(16)));
+static SQL_SLOTS: Lazy<Arc<Semaphore>> = Lazy::new(|| Arc::new(Semaphore::new(8)));
+static TOKENS: Lazy<Regex> = Lazy::new(|| Regex::new(r"\$\{?([A-Za-z0-9_]+)\}?").unwrap());
+static SQL_TOKENS: Lazy<Regex> = Lazy::new(|| {
+    Regex::new(r#"--[^\n]*|/\*[\s\S]*?\*/|'(?:''|[^'])*'|"(\$\{?([A-Za-z0-9_]+)\}?)"|\$\{?([A-Za-z0-9_]+)\}?"#).unwrap()
+});
+static ALL_MATCHER: Lazy<Regex> = Lazy::new(|| Regex::new(r#"(^|[^!=<>])=\s*"\.\*""#).unwrap());
+type Values = BTreeMap<String, Value>;
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct PreviewRequest {
+    dashboard_id: Option<String>,
+    document: Option<Value>,
+    #[serde(default)]
+    operations: Vec<DashboardOperation>,
+    revision: Option<String>,
+    tile_ids: Option<Vec<String>>,
+    start_time: String,
+    end_time: String,
+    #[serde(default)]
+    variables: Values,
+    row_limit: Option<usize>,
+}
+
+fn bad(message: impl Into<String>) -> DashboardError {
+    DashboardError::api(400, "INVALID_PREVIEW", message, json!({}))
+}
+fn text(value: &Value) -> &str {
+    value.as_str().unwrap_or("")
+}
+fn id(value: &str) -> String {
+    format!("\"{}\"", value.replace('"', "\"\""))
+}
+fn literal(value: &str) -> String {
+    format!("'{}'", value.replace('\'', "''"))
+}
+fn array(value: &Value) -> &[Value] {
+    value.as_array().map(Vec::as_slice).unwrap_or(&[])
+}
+fn selection(value: &Value) -> Vec<&str> {
+    match value {
+        Value::String(value) => vec![value],
+        Value::Array(values) => values.iter().filter_map(Value::as_str).collect(),
+        _ => vec![],
+    }
+}
+fn first(value: &Value) -> Option<&str> {
+    selection(value).into_iter().next()
+}
+fn number_string(number: &serde_json::Number) -> Result<String, String> {
+    let value = number.as_f64().ok_or("Unsupported numeric filter")?;
+    if value.abs() > 9_007_199_254_740_991.0 {
+        return Err(
+            "Numeric builder filters outside JavaScript's safe range are unsupported".into(),
+        );
+    }
+    Ok(if value == 0.0 {
+        "0".into()
+    } else if value.fract() == 0.0 {
+        format!("{value:.0}")
+    } else {
+        value.to_string()
+    })
+}
+fn integer(value: &Value) -> Option<u64> {
+    value
+        .as_f64()
+        .filter(|v| *v >= 0.0 && *v <= 9_007_199_254_740_991.0 && v.fract() == 0.0)
+        .map(|v| v as u64)
+}
+fn token_name(value: &str) -> Option<&str> {
+    let capture = TOKENS.captures(value)?;
+    (capture.get(0)?.as_str() == value).then(|| capture.get(1).unwrap().as_str())
+}
+fn dataset_names(definitions: &[Value]) -> BTreeSet<&str> {
+    definitions
+        .iter()
+        .filter(|v| v["type"] == "dataset")
+        .filter_map(|v| v["name"].as_str())
+        .collect()
+}
+fn interpolate_sql(source: &str, values: &Values, definitions: &[Value]) -> String {
+    let datasets = dataset_names(definitions);
+    let dataset = |name: &str| {
+        values
+            .get(name)
+            .and_then(first)
+            .filter(|s| !s.is_empty())
+            .map(id)
+    };
+    SQL_TOKENS
+        .replace_all(source, |caps: &Captures<'_>| {
+            let token = &caps[0];
+            if token.starts_with("--") || token.starts_with("/*") {
+                return token.to_owned();
+            }
+            if token.starts_with('\'') {
+                let contents = &token[1..token.len() - 1];
+                if let Some(name) = token_name(contents).filter(|name| !datasets.contains(name)) {
+                    if let Some(value) = values.get(name) {
+                        let selected = selection(value);
+                        if !selected.is_empty() {
+                            return selected
+                                .into_iter()
+                                .map(literal)
+                                .collect::<Vec<_>>()
+                                .join(",");
+                        }
+                    }
+                    return token.to_owned();
+                }
+                return format!(
+                    "'{}'",
+                    TOKENS.replace_all(contents, |part: &Captures<'_>| {
+                        let name = &part[1];
+                        let value = if datasets.contains(name) {
+                            dataset(name)
+                        } else {
+                            values.get(name).and_then(first).map(str::to_owned)
+                        };
+                        value
+                            .map(|v| v.replace('\'', "''"))
+                            .unwrap_or_else(|| part[0].to_owned())
+                    })
+                );
+            }
+            let name = caps.get(3).or_else(|| caps.get(2)).unwrap().as_str();
+            if datasets.contains(name) {
+                return dataset(name).unwrap_or_else(|| token.to_owned());
+            }
+            let Some(value) = values.get(name) else {
+                return token.to_owned();
+            };
+            let selected = selection(value);
+            if selected.is_empty() {
+                return token.to_owned();
+            }
+            if caps.get(2).is_some() {
+                selected.into_iter().map(id).collect::<Vec<_>>().join(",")
+            } else {
+                selected.join(",")
+            }
+        })
+        .into_owned()
+}
+fn prom_escape(value: &str) -> String {
+    value
+        .replace('\\', "\\\\")
+        .replace('"', "\\\"")
+        .replace('\n', "\\n")
+        .replace('\r', "\\r")
+        .replace('\t', "\\t")
+}
+fn regex_escape(value: &str) -> String {
+    value
+        .chars()
+        .flat_map(|c| {
+            if ".*+?^${}()|[]\\".contains(c) {
+                vec!['\\', c]
+            } else {
+                vec![c]
+            }
+        })
+        .collect()
+}
+fn interpolate_promql(source: &str, values: &Values) -> String {
+    let result = TOKENS.replace_all(source, |caps: &Captures<'_>| match values.get(&caps[1]) {
+        Some(Value::String(value)) => prom_escape(value),
+        Some(Value::Array(items)) if !items.is_empty() => format!(
+            "({})",
+            items
+                .iter()
+                .filter_map(Value::as_str)
+                .map(|s| prom_escape(&regex_escape(s)))
+                .collect::<Vec<_>>()
+                .join("|")
+        ),
+        _ => caps[0].to_owned(),
+    });
+    ALL_MATCHER
+        .replace_all(&result, "${1}=~\".*\"")
+        .into_owned()
+}
+fn resolve_dataset(source: &str, values: &Values) -> String {
+    let result = TOKENS
+        .replace_all(source, |caps: &Captures<'_>| match values.get(&caps[1]) {
+            Some(Value::String(s)) => s.clone(),
+            Some(Value::Array(items)) if !items.is_empty() => format!(
+                "({})",
+                items
+                    .iter()
+                    .filter_map(Value::as_str)
+                    .collect::<Vec<_>>()
+                    .join("|")
+            ),
+            _ => caps[0].to_owned(),
+        })
+        .into_owned();
+    if token_name(&result).is_some() {
+        String::new()
+    } else {
+        result
+    }
+}
+fn tile_dataset(tile: &Value) -> &str {
+    tile["dbName"]
+        .as_str()
+        .or_else(|| tile["dbName"].get(0).and_then(Value::as_str))
+        .unwrap_or("")
+}
+
+/// Frontend legacySql.ts conversion, with explicit errors for unsupported legacy shapes.
+fn sql_query(tile: &Value) -> Result<String, String> {
+    let query = &tile["chartQuery"];
+    if let Some(sql) = query
+        .as_str()
+        .or_else(|| query["query"].as_str())
+        .or_else(|| query["sql"].as_str())
+    {
+        return Ok(sql.to_owned());
+    }
+    if !query.is_object() {
+        return Err("This tile has no SQL query".into());
+    }
+    legacy_sql(tile, query)
+}
+fn legacy_sql(tile: &Value, query: &Value) -> Result<String, String> {
+    let unsupported = |part: &str| {
+        format!(
+            "This legacy {part} cannot be converted faithfully to SQL. Open it in the classic UI."
+        )
+    };
+    let dataset = tile_dataset(tile);
+    if dataset.is_empty() {
+        return Err(unsupported("query with no dataset"));
+    }
+    let x = &query["x"];
+    let y = &query["y"];
+    for axis in [x, y] {
+        if !axis["fields"].is_null() && !axis["fields"].is_array() {
+            return Err(unsupported("fields"));
+        }
+        if !axis["groupBy"].is_null()
+            && (!axis["groupBy"].is_array()
+                || array(&axis["groupBy"]).iter().any(|v| !v.is_string()))
+        {
+            return Err(unsupported("grouping"));
+        }
+    }
+    let xs = array(&x["fields"]);
+    let ys = array(&y["fields"]);
+    let stat = ["query-value", "gauge"].contains(&text(&tile["chartType"]));
+    let timeseries = tile["chartType"] == "timeseries";
+    if stat && ys.first().is_none_or(|v| text(&v["aggregate"]).is_empty()) {
+        return Err(unsupported("aggregate"));
+    }
+    // Ordered maps reproduce JavaScript Map insertion/overwrite behavior.
+    let mut expressions: Vec<(String, String)> = vec![];
+    let mut groups: Vec<String> = vec![];
+    let mut aliases = BTreeMap::new();
+    fn set(rows: &mut Vec<(String, String)>, key: String, value: String) {
+        if let Some(row) = rows.iter_mut().find(|row| row.0 == key) {
+            row.1 = value;
+        } else {
+            rows.push((key, value));
+        }
+    }
+    fn group(groups: &mut Vec<String>, value: &str) {
+        if !groups.iter().any(|v| v == value) {
+            groups.push(value.into());
+        }
+    }
+    if timeseries && xs.first().is_some_and(|v| !text(&v["name"]).is_empty()) {
+        let grain = x["granularity"]
+            .as_str()
+            .filter(|s| !s.is_empty())
+            .unwrap_or("minute");
+        if ![
+            "second", "minute", "hour", "day", "week", "month", "quarter", "year",
+        ]
+        .contains(&grain)
+        {
+            return Err(unsupported("granularity"));
+        }
+        set(
+            &mut expressions,
+            "time_bucket".into(),
+            format!(
+                "DATE_TRUNC({}, {}) AS {}",
+                literal(grain),
+                id(text(&xs[0]["name"])),
+                id("time_bucket")
+            ),
+        );
+        group(&mut groups, "time_bucket");
+    }
+    if !stat {
+        for field in xs {
+            let name = text(&field["name"]);
+            if name.is_empty() {
+                return Err(unsupported("field"));
+            }
+            if timeseries
+                && name == text(&xs[0]["name"])
+                && field["aggregate"].as_str().is_none_or(str::is_empty)
+            {
+                continue;
+            }
+            set(
+                &mut expressions,
+                name.into(),
+                format!("{} AS {}", id(name), id(name)),
+            );
+            group(&mut groups, name);
+        }
+    }
+    let group_by: Vec<&str> = array(&x["groupBy"])
+        .iter()
+        .chain(array(&y["groupBy"]))
+        .filter_map(Value::as_str)
+        .collect();
+    if stat {
+        for name in &group_by {
+            set(
+                &mut expressions,
+                (*name).into(),
+                format!("{} AS {}", id(name), id(name)),
+            );
+        }
+    }
+    for field in ys.iter().take(if stat { 1 } else { ys.len() }) {
+        let name = text(&field["name"]);
+        let aggregate = text(&field["aggregate"]).to_uppercase();
+        if aggregate.is_empty() {
+            continue;
+        }
+        if name.is_empty()
+            || !["COUNT", "SUM", "AVG", "MIN", "MAX", "COUNT(DISTINCT)"]
+                .contains(&aggregate.as_str())
+        {
+            return Err(unsupported("aggregate"));
+        }
+        let star = aggregate == "COUNT" && ["All rows (*)", "*"].contains(&name);
+        let alias = if star {
+            "COUNT_STAR".into()
+        } else {
+            format!("{aggregate}_{name}")
+        };
+        let value = if star { "*".into() } else { id(name) };
+        let expression = if aggregate == "COUNT(DISTINCT)" {
+            format!("COUNT(DISTINCT {value})")
+        } else {
+            format!("{aggregate}({value})")
+        };
+        set(
+            &mut expressions,
+            alias.clone(),
+            format!("{expression} AS {}", id(&alias)),
+        );
+        aliases.insert(name, alias);
+    }
+    for name in group_by {
+        if !expressions.iter().any(|v| v.0 == name) {
+            set(
+                &mut expressions,
+                name.into(),
+                format!("{} AS {}", id(name), id(name)),
+            );
+        }
+        group(&mut groups, name);
+    }
+    let mut order = vec![];
+    let sort = if !y["sortBy"].is_null() {
+        &y["sortBy"]
+    } else {
+        &x["sortBy"]
+    };
+    if !stat && sort.as_object().is_some_and(|v| !v.is_empty()) {
+        let field = text(&sort["field"]);
+        let direction = text(&sort["direction"]);
+        if field.is_empty() || !["ASC", "DESC"].contains(&direction) {
+            return Err(unsupported("sort"));
+        }
+        let alias = aliases.get(field).map(String::as_str).unwrap_or(field);
+        if !expressions.iter().any(|v| v.0 == alias) {
+            set(
+                &mut expressions,
+                alias.into(),
+                format!("{} AS {}", id(field), id(alias)),
+            );
+        }
+        order.push(format!("{} {direction}", id(alias)));
+    } else if timeseries && !stat {
+        order.push(format!("{} DESC", id("time_bucket")));
+    }
+    let mut filters = vec![];
+    if !query["filters"].is_null() && !query["filters"].is_array() {
+        return Err(unsupported("filter"));
+    }
+    for filter in array(&query["filters"]) {
+        let column = text(&filter["column"]);
+        let operator = text(&filter["operator"]).trim().to_lowercase();
+        if column.is_empty()
+            || ![
+                "=",
+                "!=",
+                "<>",
+                "<",
+                ">",
+                "<=",
+                ">=",
+                "is null",
+                "is not null",
+            ]
+            .contains(&operator.as_str())
+            || text(&filter["type"]).starts_with("list")
+        {
+            return Err(unsupported("filter"));
+        }
+        let values = if operator.contains("null") {
+            vec![Value::Null]
+        } else {
+            filter["value"]
+                .as_array()
+                .cloned()
+                .unwrap_or_else(|| vec![filter["value"].clone()])
+        };
+        let mut seen = BTreeSet::new();
+        let mut predicates = vec![];
+        for value in values {
+            let key = if let Some(s) = value.as_str() {
+                s.to_owned()
+            } else if let Some(number) = value.as_number() {
+                number_string(number)?
+            } else {
+                value.to_string()
+            };
+            if !seen.insert(key) {
+                continue;
+            }
+            let name = id(&column.replace('`', ""));
+            if value.is_null() {
+                // Missing values are not explicit SQL NULL in the frontend converter.
+                if !operator.contains("null") && filter.get("value").is_none() {
+                    return Err(unsupported("filter"));
+                }
+                predicates.push(format!(
+                    "{name} IS {}NULL",
+                    if ["!=", "<>", "is not null"].contains(&operator.as_str()) {
+                        "NOT "
+                    } else {
+                        ""
+                    }
+                ));
+            } else {
+                let value = match value {
+                    Value::String(s) => literal(&s),
+                    Value::Number(n) => number_string(&n)?,
+                    Value::Bool(b) => b.to_string(),
+                    _ => return Err(unsupported("filter")),
+                };
+                predicates.push(format!("{name} {} {value}", operator.to_uppercase()));
+            }
+        }
+        if !predicates.is_empty() {
+            filters.push(if predicates.len() > 1 {
+                format!("({})", predicates.join(" OR "))
+            } else {
+                predicates.remove(0)
+            });
+        }
+    }
+    if expressions.is_empty() {
+        return Err(unsupported("query"));
+    }
+    if !stat && !y["limit"].is_null() && integer(&y["limit"]).is_none_or(|v| v < 1) {
+        return Err(unsupported("limit"));
+    }
+    let mut sql = format!(
+        "SELECT {} FROM {}",
+        expressions
+            .into_iter()
+            .map(|v| v.1)
+            .collect::<Vec<_>>()
+            .join(", "),
+        id(dataset)
+    );
+    if !filters.is_empty() {
+        sql.push_str(&format!(" WHERE {}", filters.join(" AND ")));
+    }
+    if !groups.is_empty() {
+        sql.push_str(&format!(
+            " GROUP BY {}",
+            groups.iter().map(|v| id(v)).collect::<Vec<_>>().join(", ")
+        ));
+    }
+    if !order.is_empty() {
+        sql.push_str(&format!(" ORDER BY {}", order.join(", ")));
+    }
+    if !stat && let Some(limit) = integer(&y["limit"]) {
+        sql.push_str(&format!(" LIMIT {limit}"));
+    }
+    Ok(sql)
+}
+
+fn promql_queries(tile: &Value) -> Vec<(String, String)> {
+    let chart = &tile["chartQuery"];
+    let legacy = &tile["promqlQuery"];
+    let queries = if let Some(query) = chart.as_str() {
+        vec![query.to_owned()]
+    } else if let Some(queries) = chart.as_array().filter(|v| v.iter().all(Value::is_string)) {
+        queries.iter().map(|v| text(v).to_owned()).collect()
+    } else {
+        legacy["query"]
+            .as_str()
+            .or_else(|| chart["query"].as_str())
+            .map(|q| vec![q.to_owned()])
+            .unwrap_or_default()
+    };
+    queries
+        .into_iter()
+        .enumerate()
+        .map(|(index, query)| {
+            let mode = if tile["promqlQueryType"].is_array() {
+                text(&tile["promqlQueryType"][index])
+            } else {
+                let value = tile
+                    .get("promqlQueryType")
+                    .filter(|v| !v.is_null())
+                    .or_else(|| legacy.get("type").or_else(|| chart.get("type")));
+                value.and_then(Value::as_str).unwrap_or("")
+            };
+            (
+                query,
+                if ["instant", "both"].contains(&mode) {
+                    mode
+                } else {
+                    "range"
+                }
+                .into(),
+            )
+        })
+        .collect()
+}
+fn query_modes(tile: &Value, index: usize, mode: &str) -> (bool, bool) {
+    let stat = ["query-value", "gauge", "pie", "donut"].contains(&text(&tile["chartType"]));
+    let spark = index == 0
+        && tile["chartType"] == "query-value"
+        && tile.pointer("/config/layout/sparkline") == Some(&Value::Bool(true));
+    (
+        spark || (!stat && mode != "instant"),
+        stat || mode != "range",
+    )
+}
+fn query_bounds(
+    start: &str,
+    end: &str,
+    row_limit: Option<usize>,
+) -> Result<(i64, i64, usize), String> {
+    let start = DateTime::parse_from_rfc3339(start)
+        .map_err(|_| "startTime must be RFC3339")?
+        .timestamp_millis();
+    let end = DateTime::parse_from_rfc3339(end)
+        .map_err(|_| "endTime must be RFC3339")?
+        .timestamp_millis();
+    if start < 0 || end < start || end - start > MAX_RANGE_MS {
+        return Err("Preview range must be ordered and at most 31 days".into());
+    }
+    let limit = row_limit.unwrap_or(100);
+    if !(1..=500).contains(&limit) {
+        return Err("rowLimit must be between 1 and 500".into());
+    }
+    Ok((start, end, limit))
+}
+fn parse_duration(source: &str) -> Option<f64> {
+    let source = source.trim();
+    if let Ok(value) = source.parse::<f64>() {
+        return value.is_finite().then_some(value);
+    }
+    let pattern = Regex::new(r"([0-9]+)(ms|[ywdhms])").unwrap();
+    let mut total = 0.0;
+    let mut previous = f64::INFINITY;
+    let mut offset = 0;
+    for cap in pattern.captures_iter(source) {
+        let m = cap.get(0)?;
+        if m.start() != offset {
+            return None;
+        }
+        let scale = match &cap[2] {
+            "y" => 31536000.,
+            "w" => 604800.,
+            "d" => 86400.,
+            "h" => 3600.,
+            "m" => 60.,
+            "s" => 1.,
+            "ms" => 0.001,
+            _ => return None,
+        };
+        if scale >= previous {
+            return None;
+        }
+        previous = scale;
+        total += cap[1].parse::<f64>().ok()? * scale;
+        offset = m.end();
+    }
+    (offset == source.len() && offset > 0 && total.is_finite()).then_some(total)
+}
+fn tile_step(tile: &Value, start: i64, end: i64, query: &str) -> Result<i64, String> {
+    let stored = tile
+        .get("promqlStep")
+        .filter(|v| !v.is_null())
+        .or_else(|| tile["promqlQuery"].get("step"))
+        .filter(|v| !v.is_null())
+        .or_else(|| tile["chartQuery"].get("step"));
+    if let Some(value) = stored {
+        let seconds = value
+            .as_f64()
+            .or_else(|| value.as_str().and_then(parse_duration));
+        if let Some(seconds) = seconds.filter(|v| *v > 0. && v.is_finite()) {
+            let ms = (seconds * 1000.).floor();
+            if ms < 1. || ms > MAX_RANGE_MS as f64 {
+                return Err("Step must be between 1ms and 31d".into());
+            }
+            return Ok(ms as i64);
+        }
+    }
+    let max_dp = tile
+        .pointer("/config/maxDataPoints")
+        .or_else(|| tile.pointer("/config/layout/maxDataPoints"))
+        .and_then(|v| {
+            v.as_f64()
+                .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
+        })
+        .filter(|v| *v > 0. && v.is_finite())
+        .unwrap_or(500.);
+    let range = ((end - start) as f64 / 1000.).max(1.);
+    let mut window = f64::INFINITY;
+    let mut code = String::new();
+    let mut quote = None;
+    let mut comment = false;
+    let mut escaped = false;
+    for c in query.chars() {
+        if comment {
+            code.push(' ');
+            if c == '\n' {
+                comment = false;
+            }
+        } else if let Some(q) = quote {
+            code.push(' ');
+            if escaped {
+                escaped = false;
+            } else if c == '\\' && q != '`' {
+                escaped = true;
+            } else if c == q {
+                quote = None;
+            }
+        } else if ['"', '\'', '`'].contains(&c) {
+            quote = Some(c);
+            code.push(' ');
+        } else if c == '#' {
+            comment = true;
+            code.push(' ');
+        } else {
+            code.push(c);
+        }
+    }
+    let windows = Regex::new(r"\[([^\[\]]+)\]").unwrap();
+    for cap in windows.captures_iter(&code) {
+        if let Some(duration) = parse_duration(&cap[1]).filter(|v| *v > 0.) {
+            window = window.min((duration / 4.).floor());
+        }
+    }
+    let steps = [
+        1., 2., 5., 10., 15., 30., 60., 120., 300., 600., 900., 1800., 3600., 7200., 14400.,
+        21600., 43200., 86400.,
+    ];
+    let snap = |s: f64| {
+        steps
+            .iter()
+            .copied()
+            .find(|v| *v >= s)
+            .unwrap_or_else(|| (s / 86400.).ceil() * 86400.)
+    };
+    let mut step = snap(((range / max_dp).ceil().max(15.)).min(window).max(1.));
+    if range / step > 3000. {
+        step = snap((range / 3000.).ceil());
+    }
+    Ok((step * 1000.) as i64)
+}
+
+fn bounded_sql(sql: &str, limit: usize) -> String {
+    // A trailing SQL line comment must end before the wrapper's closing syntax.
+    format!(
+        "SELECT * FROM (\n{}\n) AS {} LIMIT {limit}",
+        sql.trim().trim_end_matches(';'),
+        id("__dashboard_preview")
+    )
+}
+
+async fn sql_rows(
+    req: &HttpRequest,
+    sql: &str,
+    start: &str,
+    end: &str,
+    limit: usize,
+) -> Result<Vec<serde_json::Map<String, Value>>, String> {
+    let _permit = SQL_SLOTS
+        .clone()
+        .acquire_owned()
+        .await
+        .map_err(|_| "SQL preview service unavailable")?;
+    if sql.len() > MAX_QUERY_BYTES {
+        return Err("SQL query exceeds 16 KiB".into());
+    }
+    if sql.trim().is_empty() {
+        return Err("This tile has no SQL query".into());
+    }
+    let creds = extract_session_key_from_req(req).map_err(|e| e.to_string())?;
+    let tenant = get_tenant_id_from_request(req);
+    let query = Query {
+        query: bounded_sql(sql, limit),
+        start_time: start.into(),
+        end_time: end.into(),
+        send_null: true,
+        fields: false,
+        streaming: false,
+        filter_tags: None,
+    };
+    // This path resolves referenced datasets and calls user_auth_for_datasets
+    // using the caller's real session; it never uses the authorized-query bypass.
+    let (records, _) = query::get_records_and_fields(&query, &creds, &tenant)
+        .await
+        .map_err(|e| e.to_string())?;
+    let rows = record_batches_to_json(&records.unwrap_or_default()).map_err(|e| e.to_string())?;
+    if rows.len() > limit {
+        return Err("Query engine exceeded preview row bound".into());
+    }
+    if serde_json::to_vec(&rows).map_err(|e| e.to_string())?.len() > MAX_BYTES {
+        return Err("Preview rows exceed 1 MiB; narrow the query".into());
+    }
+    Ok(rows)
+}
+fn dependencies(source: &str, definitions: &[Value]) -> BTreeSet<String> {
+    let names: BTreeSet<&str> = definitions
+        .iter()
+        .filter_map(|v| v["name"].as_str())
+        .collect();
+    TOKENS
+        .captures_iter(source)
+        .map(|v| v[1].to_owned())
+        .filter(|n| names.contains(n.as_str()))
+        .collect()
+}
+fn variable_source(variable: &Value) -> String {
+    match text(&variable["type"]) {
+        "sql" => text(&variable["sqlQuery"]).into(),
+        "promql_query" => format!(
+            "{} {}",
+            text(&variable["promqlQuery"]),
+            text(&variable["promqlQueryDataset"])
+        ),
+        "promql" => format!(
+            "{} {}",
+            text(&variable["dataset"]),
+            variable["labelFilters"]
+        ),
+        _ => String::new(),
+    }
+}
+fn select_variable_default(variable: &Value, options: &[String]) -> Result<String, String> {
+    if options.iter().any(|value| value.len() > 4096)
+        || text(&variable["defaultValue"]).len() > 4096
+    {
+        return Err(
+            "Resolved variable selection exceeds 4096 bytes; provide a bounded explicit selection"
+                .into(),
+        );
+    }
+    let default = text(&variable["defaultValue"]);
+    if !default.is_empty() {
+        if options.iter().any(|value| value == default) {
+            return Ok(default.to_owned());
+        }
+        if matches!(text(&variable["type"]), "sql" | "promql_query") {
+            return Err("Saved variable default was not found in bounded query options; provide an explicit selection".into());
+        }
+    }
+    Ok(options.first().cloned().unwrap_or_default())
+}
+
+async fn resolve_variables(
+    req: &HttpRequest,
+    definitions: &[Value],
+    mut needed: BTreeSet<String>,
+    values: &mut Values,
+    start: &str,
+    end: &str,
+    end_ms: i64,
+) -> BTreeMap<String, String> {
+    loop {
+        let mut added = false;
+        for variable in definitions {
+            if needed.contains(text(&variable["name"]))
+                && !values.contains_key(text(&variable["name"]))
+            {
+                for dependency in dependencies(&variable_source(variable), definitions) {
+                    added |= needed.insert(dependency);
+                }
+            }
+        }
+        if !added {
+            break;
+        }
+    }
+    let mut pending: Vec<&Value> = definitions
+        .iter()
+        .filter(|v| needed.contains(text(&v["name"])) && !values.contains_key(text(&v["name"])))
+        .collect();
+    let mut errors = BTreeMap::new();
+    while !pending.is_empty() {
+        let mut progressed = false;
+        let mut next = vec![];
+        for variable in pending {
+            let name = text(&variable["name"]);
+            if dependencies(&variable_source(variable), definitions)
+                .iter()
+                .any(|dep| !values.contains_key(dep))
+            {
+                next.push(variable);
+                continue;
+            }
+            progressed = true;
+            let kind = text(&variable["type"]);
+            let mut options: Vec<String> = vec![];
+            let result: Result<(), String> = match kind {
+                "text" => {
+                    values.insert(
+                        name.into(),
+                        json!(variable["defaultValue"].as_str().unwrap_or("")),
+                    );
+                    Ok(())
+                }
+                "list" => {
+                    options = array(&variable["options"])
+                        .iter()
+                        .filter_map(Value::as_str)
+                        .map(str::to_owned)
+                        .collect();
+                    Ok(())
+                }
+                "sql" => {
+                    let sql = interpolate_sql(text(&variable["sqlQuery"]), values, definitions);
+                    match sql_rows(req, &sql, start, end, 500).await {
+                        Ok(rows) => {
+                            options = rows
+                                .into_iter()
+                                .filter_map(|row| row.into_iter().next().map(|(_, v)| v))
+                                .filter(|v| !v.is_null())
+                                .map(|v| {
+                                    v.as_str()
+                                        .map(str::to_owned)
+                                        .unwrap_or_else(|| v.to_string())
+                                })
+                                .collect();
+                            Ok(())
+                        }
+                        Err(e) => Err(e),
+                    }
+                }
+                "promql_query" => {
+                    let stream = resolve_dataset(text(&variable["promqlQueryDataset"]), values);
+                    let query = interpolate_promql(text(&variable["promqlQuery"]), values);
+                    match promql::dashboard_query(req, &stream, &query, end_ms, end_ms, None).await
+                    {
+                        Ok(result) => {
+                            let label = text(&variable["promqlQueryLabel"]);
+                            options = match text(&result["resultType"]) {
+                                "vector" => array(&result["result"])
+                                    .iter()
+                                    .filter_map(|row| {
+                                        if label.is_empty() {
+                                            row["value"].get(1).and_then(Value::as_str)
+                                        } else {
+                                            row["metric"].get(label).and_then(Value::as_str)
+                                        }
+                                    })
+                                    .map(str::to_owned)
+                                    .collect(),
+                                "matrix" => array(&result["result"])
+                                    .iter()
+                                    .filter_map(|row| {
+                                        if label.is_empty() {
+                                            array(&row["values"])
+                                                .last()
+                                                .and_then(|v| v.get(1))
+                                                .and_then(Value::as_str)
+                                        } else {
+                                            row["metric"].get(label).and_then(Value::as_str)
+                                        }
+                                    })
+                                    .map(str::to_owned)
+                                    .collect(),
+                                _ => result["result"]
+                                    .get(1)
+                                    .and_then(Value::as_str)
+                                    .map(|v| vec![v.to_owned()])
+                                    .unwrap_or_default(),
+                            };
+                            Ok(())
+                        }
+                        Err(e) => Err(e.to_string()),
+                    }
+                }
+                "dataset" | "promql" => Err(format!(
+                    "Variable {name} requires an explicit selection in preview; dataset-list and label metadata discovery are not executed"
+                )),
+                _ => Err(format!("Unsupported variable type for {name}")),
+            };
+            if let Err(error) = result {
+                errors.insert(name.into(), error);
+                continue;
+            }
+            if kind == "text" {
+                continue;
+            }
+            let mut seen = BTreeSet::new();
+            options.retain(|v| seen.insert(v.clone()));
+            if variable["includeAll"] == true {
+                options.insert(0, if kind == "promql_query" { ".*" } else { "*" }.into());
+            }
+            let selected = match select_variable_default(variable, &options) {
+                Ok(selected) => selected,
+                Err(error) => {
+                    errors.insert(name.into(), error);
+                    continue;
+                }
+            };
+            values.insert(name.into(), json!(selected));
+        }
+        if !progressed {
+            for variable in next {
+                errors
+                    .entry(text(&variable["name"]).into())
+                    .or_insert_with(|| {
+                        "Variable dependencies contain a cycle or an unresolved dependency".into()
+                    });
+            }
+            break;
+        }
+        pending = next;
+    }
+    errors
+}
+fn trim_promql(result: &mut Value, limit: usize) -> bool {
+    let mut truncated = false;
+    if let Some(series) = result["result"].as_array_mut() {
+        // Scalars are a [timestamp,string] pair, not a series list.
+        if series.first().is_some_and(Value::is_object) {
+            if series.len() > limit {
+                series.truncate(limit);
+                truncated = true;
+            }
+            for row in series {
+                if let Some(points) = row["values"].as_array_mut()
+                    && points.len() > limit
+                {
+                    let keep = points.len() - limit;
+                    points.drain(..keep);
+                    truncated = true;
+                }
+            }
+        }
+    }
+    truncated
+}
+#[allow(clippy::too_many_arguments)]
+async fn execute_tile(
+    req: &HttpRequest,
+    tile: &Value,
+    definitions: &[Value],
+    values: &Values,
+    start: &str,
+    end: &str,
+    start_ms: i64,
+    end_ms: i64,
+    limit: usize,
+) -> Result<Value, String> {
+    let source = format!(
+        "{} {} {}",
+        tile["chartQuery"], tile["promqlQuery"], tile["dbName"]
+    );
+    for name in dependencies(&source, definitions) {
+        if values.get(&name).is_none_or(|v| selection(v).is_empty()) {
+            return Err(format!("Select values for query variable {name}"));
+        }
+    }
+    let kind = text(&tile["tileType"]);
+    if !["", "builder", "code", "promql"].contains(&kind) {
+        return Err("Unsupported tile type".into());
+    }
+    if kind != "promql" {
+        let sql = interpolate_sql(&sql_query(tile)?, values, definitions);
+        return Ok(json!({"rows":sql_rows(req,&sql,start,end,limit).await?}));
+    }
+    let dataset = resolve_dataset(tile_dataset(tile), values);
+    if dataset.is_empty() {
+        return Err("Select a dataset for this tile".into());
+    }
+    let queries = promql_queries(tile);
+    if queries.is_empty() {
+        return Err("This tile has no PromQL query".into());
+    }
+    if queries.len() > 8
+        || queries
+            .iter()
+            .enumerate()
+            .map(|(i, (_, mode))| {
+                let (r, n) = query_modes(tile, i, mode);
+                r as usize + n as usize
+            })
+            .sum::<usize>()
+            > 8
+    {
+        return Err("At most 8 executed queries per tile are allowed".into());
+    }
+    let mut results = vec![];
+    for (index, (template, mode)) in queries.into_iter().enumerate() {
+        let query = interpolate_promql(&template, values);
+        let (range, instant) = query_modes(tile, index, &mode);
+        let mut item =
+            json!({"id":char::from(b'A'+index as u8).to_string(),"pending":0,"errors":[]});
+        let mut truncated = false;
+        if range {
+            let step = tile_step(tile, start_ms, end_ms, &query)?;
+            let mut data =
+                promql::dashboard_query(req, &dataset, &query, start_ms, end_ms, Some(step))
+                    .await
+                    .map_err(|e| e.to_string())?;
+            truncated |= trim_promql(&mut data, limit);
+            item["range"] = data;
+        }
+        if instant {
+            let mut data = promql::dashboard_query(req, &dataset, &query, end_ms, end_ms, None)
+                .await
+                .map_err(|e| e.to_string())?;
+            truncated |= trim_promql(&mut data, limit);
+            item["instant"] = data;
+        }
+        if truncated {
+            item["truncated"] = json!(true);
+        }
+        results.push(item);
+    }
+    Ok(json!({"promql":results}))
+}
+
+pub async fn preview(
+    req: HttpRequest,
+    Json(request): Json<Value>,
+) -> Result<HttpResponse, DashboardError> {
+    Ok(HttpResponse::Ok().json(preview_value(&req, request).await?))
+}
+
+pub async fn preview_value(req: &HttpRequest, request: Value) -> Result<Value, DashboardError> {
+    authorize_runtime(req, Action::Query)?;
+    let _permit = PREVIEW_SLOTS.clone().try_acquire_owned().map_err(|_| {
+        DashboardError::api(
+            429,
+            "PREVIEW_BUSY",
+            "Dashboard preview request queue is full",
+            json!({}),
+        )
+    })?;
+    tokio::time::timeout(Duration::from_secs(30), preview_inner(req, request))
+        .await
+        .map_err(|_| {
+            DashboardError::api(
+                504,
+                "PREVIEW_TIMEOUT",
+                "Dashboard preview exceeded 30 seconds",
+                json!({}),
+            )
+        })?
+}
+
+fn authorize_runtime(req: &HttpRequest, action: Action) -> Result<(), DashboardError> {
+    let key = extract_session_key_from_req(req).map_err(|_| {
+        DashboardError::api(
+            401,
+            "UNAUTHENTICATED",
+            "Valid authentication is required",
+            json!({}),
+        )
+    })?;
+    let tenant = get_tenant_id_from_request(req);
+    if let Response::Suspended(message) =
+        middleware::check_suspension_for_tenant(tenant.as_deref(), action)
+    {
+        return Err(DashboardError::api(403, "SUSPENDED", message, json!({})));
+    }
+    if Users.authorize(key, action, None, None) != Response::Authorized {
+        return Err(DashboardError::api(
+            403,
+            "FORBIDDEN",
+            "Dashboard preview permission denied",
+            json!({"action":format!("{action:?}")}),
+        ));
+    }
+    Ok(())
+}
+
+async fn preview_inner(req: &HttpRequest, request: Value) -> Result<Value, DashboardError> {
+    if serde_json::to_vec(&request)?.len() > 2 * MAX_BYTES {
+        return Err(bad("Preview request exceeds 2 MiB"));
+    }
+    let request: PreviewRequest =
+        serde_json::from_value(request).map_err(|e| bad(e.to_string()))?;
+    let (start_ms, end_ms, limit) =
+        query_bounds(&request.start_time, &request.end_time, request.row_limit).map_err(bad)?;
+    if request.variables.len() > 100
+        || request.variables.iter().any(|(k, v)| {
+            k.len() > 128
+                || selection(v).len() > 100
+                || match v {
+                    Value::String(s) => s.len() > 4096,
+                    Value::Array(a) => a.iter().any(|v| v.as_str().is_none_or(|s| s.len() > 4096)),
+                    _ => true,
+                }
+        })
+    {
+        return Err(bad(
+            "variables must contain at most 100 string or string-array selections",
+        ));
+    }
+    let mut document = match (request.dashboard_id, request.document) {
+        (Some(id), None) => {
+            authorize_runtime(req, Action::GetDashboard)?;
+            dashboard_service::get_json(
+                validate_dashboard_id(id)?,
+                &get_tenant_id_from_request(req),
+            )
+            .await?
+        }
+        (None, Some(document)) if document.is_object() => document,
+        _ => return Err(bad("Provide exactly one of dashboardId or document")),
+    };
+    if let Some(revision) = request.revision
+        && document["revision"].as_str() != Some(revision.trim_matches('"'))
+    {
+        return Err(DashboardError::api(
+            412,
+            "REVISION_CONFLICT",
+            "Dashboard changed before preview",
+            json!({"revision":document["revision"]}),
+        ));
+    }
+    if !request.operations.is_empty() {
+        document = dashboard_patch::apply_patch(&document, &request.operations)
+            .map_err(|e| DashboardError::api(400, "INVALID_PATCH", e.to_string(), json!({})))?;
+    }
+    let tiles = document
+        .get("tiles")
+        .and_then(Value::as_array)
+        .ok_or_else(|| bad("document.tiles must be an array"))?;
+    let selected: Vec<&Value> = if let Some(ids) = request.tile_ids {
+        if ids.len() > MAX_TILES {
+            return Err(bad("At most 32 tiles can be previewed"));
+        }
+        let mut seen = BTreeSet::new();
+        let mut selected = vec![];
+        for id in ids {
+            if !seen.insert(id.clone()) {
+                return Err(bad("tileIds must be unique"));
+            }
+            selected.push(
+                tiles
+                    .iter()
+                    .find(|tile| tile["tile_id"].as_str() == Some(&id))
+                    .ok_or_else(|| bad(format!("Unknown tileId: {id}")))?,
+            );
+        }
+        selected
+    } else {
+        if tiles.len() > MAX_TILES {
+            return Err(bad("Select at most 32 tileIds for preview"));
+        }
+        tiles.iter().collect()
+    };
+    let definitions = array(&document["variables"]);
+    if definitions.len() > 100 {
+        return Err(bad("At most 100 variable definitions are supported"));
+    }
+    let needed = selected
+        .iter()
+        .flat_map(|tile| {
+            dependencies(
+                &format!(
+                    "{} {} {}",
+                    tile["chartQuery"], tile["promqlQuery"], tile["dbName"]
+                ),
+                definitions,
+            )
+        })
+        .collect();
+    let mut values = request.variables;
+    let work = async {
+        let variable_errors = resolve_variables(
+            req,
+            definitions,
+            needed,
+            &mut values,
+            &request.start_time,
+            &request.end_time,
+            end_ms,
+        )
+        .await;
+        let results:Vec<Value>=stream::iter(selected.into_iter().map(|tile|{
+            let values=&values;let start=&request.start_time;let end=&request.end_time;
+            async move{
+                let began=Instant::now();
+                let result=execute_tile(req,tile,definitions,values,start,end,start_ms,end_ms,limit).await;
+                let mut response=json!({"tileId":tile["tile_id"],"durationMs":began.elapsed().as_millis() as u64});
+                match result{Ok(data)=>{response["status"]=json!("success");if let Some(data)=data.as_object(){for(k,v)in data{response[k]=v.clone();}}},Err(error)=>{response["status"]=json!("error");response["error"]=json!(error);}}
+                response
+            }
+        })).buffered(4).collect().await;
+        Ok::<_, DashboardError>(
+            json!({"results":results,"variables":values,"variableErrors":variable_errors,"revision":document["revision"],"limits":{"rowLimit":limit,"timeoutMs":30000,"maxConcurrentTiles":4},"notice":"Runtime results describe this explicit execution only; configuration validation does not guarantee successful execution."}),
+        )
+    };
+    let mut response = work.await?;
+    // Keep a single oversized tile from defeating the aggregate wire-size bound.
+    if serde_json::to_vec(&response)?.len() > MAX_BYTES
+        && let Some(results) = response["results"].as_array_mut()
+    {
+        for index in (0..results.len()).rev() {
+            let tile_id = results[index]["tileId"].clone();
+            results[index] = json!({"tileId":tile_id,"status":"error","error":"Preview response exceeds 1 MiB; narrow the selection"});
+            if serde_json::to_vec(results)?.len() < MAX_BYTES / 2 {
+                break;
+            }
+        }
+    }
+    if serde_json::to_vec(&response)?.len() > MAX_BYTES {
+        return Err(bad("Preview response exceeds 1 MiB"));
+    }
+    Ok(response)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn values(value: Value) -> Values {
+        serde_json::from_value(value).unwrap()
+    }
+
+    #[test]
+    fn bounded_sql_preserves_trailing_comments_and_enforces_the_outer_limit() {
+        use datafusion::sql::sqlparser::{dialect::GenericDialect, parser::Parser};
+        for source in [
+            "SELECT 1 AS count -- trailing comment",
+            "-- leading comment\nSELECT 1 AS count -- trailing comment",
+            "SELECT '-- inside literal' AS message;",
+        ] {
+            let wrapped = bounded_sql(source, 17);
+            let statements = Parser::parse_sql(&GenericDialect {}, &wrapped).unwrap();
+            assert_eq!(statements.len(), 1);
+            assert!(statements[0].to_string().ends_with("LIMIT 17"));
+        }
+        // The pre-fix wrapper comments out its own closing parenthesis.
+        assert!(
+            Parser::parse_sql(
+                &GenericDialect {},
+                "SELECT * FROM (SELECT 1 -- trailing comment) AS preview LIMIT 17"
+            )
+            .is_err()
+        );
+    }
+
+    #[test]
+    fn sql_interpolation_matches_frontend_lexical_escape_and_never_reinterprets_inserted_tokens() {
+        let definitions = vec![json!({"name":"ds","type":"dataset"})];
+        let inputs = values(
+            json!({"ds":"a\"b","host":["a'b","c"],"word":"x'y","v":"$other","other":"injected"}),
+        );
+        assert_eq!(
+            interpolate_sql(
+                "SELECT * FROM \"$ds\" WHERE host IN ('$host') AND message='prefix ${word}'",
+                &inputs,
+                &definitions
+            ),
+            "SELECT * FROM \"a\"\"b\" WHERE host IN ('a''b','c') AND message='prefix x''y'"
+        );
+        assert_eq!(
+            interpolate_sql("SELECT \"$host\" FROM ${ds}", &inputs, &definitions),
+            "SELECT \"a'b\",\"c\" FROM \"a\"\"b\""
+        );
+        assert_eq!(
+            interpolate_sql("SELECT '$v'", &inputs, &definitions),
+            "SELECT '$other'"
+        );
+        let comments = values(json!({"v":"O'Brien","ds":"x'y"}));
+        assert_eq!(
+            interpolate_sql(
+                "-- user's filter\nSELECT * FROM logs WHERE name='$v'",
+                &comments,
+                &definitions
+            ),
+            "-- user's filter\nSELECT * FROM logs WHERE name='O''Brien'"
+        );
+        assert_eq!(
+            interpolate_sql(
+                "/* user's\n filter */ SELECT * FROM logs WHERE name='$v' /* '$v */",
+                &comments,
+                &definitions
+            ),
+            "/* user's\n filter */ SELECT * FROM logs WHERE name='O''Brien' /* '$v */"
+        );
+        assert_eq!(
+            interpolate_sql(
+                "SELECT '--', '/*' FROM $ds WHERE name='$v' -- $v",
+                &comments,
+                &definitions
+            ),
+            "SELECT '--', '/*' FROM \"x'y\" WHERE name='O''Brien' -- $v"
+        );
+        let attack = values(json!({"v":"x'); DROP TABLE logs; -- $other","other":"expanded"}));
+        assert_eq!(
+            interpolate_sql("SELECT '$v'", &attack, &[]),
+            "SELECT 'x''); DROP TABLE logs; -- $other'"
+        );
+    }
+    #[test]
+    fn promql_interpolation_matches_frontend_string_regex_arrays_and_all() {
+        assert_eq!(
+            interpolate_promql("up{host=\"$v\"}", &values(json!({"v":"a\"\n\r\t\\"}))),
+            "up{host=\"a\\\"\\n\\r\\t\\\\\"}"
+        );
+        assert_eq!(
+            interpolate_promql("up{host=~\"${v}\"}", &values(json!({"v":["a.b","c|d"]}))),
+            "up{host=~\"(a\\\\.b|c\\\\|d)\"}"
+        );
+        assert_eq!(
+            interpolate_promql("up{host=\"$v\",region!=\"$v\"}", &values(json!({"v":".*"}))),
+            "up{host=~\".*\",region!=\".*\"}"
+        );
+        assert_eq!(
+            interpolate_promql(
+                "up{host=\"$v\"}",
+                &values(json!({"v":"$other","other":"expanded"}))
+            ),
+            "up{host=\"$other\"}"
+        );
+        assert_eq!(
+            resolve_dataset("$ds", &values(json!({"ds":"metrics"}))),
+            "metrics"
+        );
+    }
+    #[test]
+    fn compiler_matches_frontend_builder_golden_queries() {
+        let tile = json!({"dbName":["logs"],"chartType":"timeseries","chartQuery":{"x":{"fields":[{"name":"p_timestamp"}]},"y":{"fields":[{"name":"*","aggregate":"count"}]}}});
+        assert_eq!(
+            sql_query(&tile).unwrap(),
+            "SELECT DATE_TRUNC('minute', \"p_timestamp\") AS \"time_bucket\", COUNT(*) AS \"COUNT_STAR\" FROM \"logs\" GROUP BY \"time_bucket\" ORDER BY \"time_bucket\" DESC"
+        );
+        let tile = json!({"dbName":["demodata"],"chartType":"bar","chartQuery":{"x":{"fields":[{"name":"service"}]},"y":{"fields":[{"name":"All rows (*)","aggregate":"count"}],"sortBy":{"field":"All rows (*)","direction":"DESC"},"limit":20.0},"filters":[{"column":"severity","operator":"=","value":[1.0,"1",2],"type":"number"},{"column":"host","operator":"!=","value":null,"type":"text"}]}});
+        assert_eq!(
+            sql_query(&tile).unwrap(),
+            "SELECT \"service\" AS \"service\", COUNT(*) AS \"COUNT_STAR\" FROM \"demodata\" WHERE (\"severity\" = 1 OR \"severity\" = 2) AND \"host\" IS NOT NULL GROUP BY \"service\" ORDER BY \"COUNT_STAR\" DESC LIMIT 20"
+        );
+        let mut bad = tile.clone();
+        bad["chartQuery"]["filters"][0]["type"] = json!("list-number");
+        assert!(
+            sql_query(&bad)
+                .unwrap_err()
+                .contains("cannot be converted faithfully")
+        );
+    }
+    #[test]
+    fn compiler_quotes_identifier_and_literal_injection_as_data() {
+        let tile = json!({"dbName":"logs\"; DROP TABLE other; --","chartType":"table","chartQuery":{"x":{"fields":[{"name":"host\" FROM secret --"}]},"y":{"fields":[{"name":"*","aggregate":"COUNT"}]},"filters":[{"column":"message","operator":"=","value":"x' OR 1=1 --"}]}});
+        let sql = sql_query(&tile).unwrap();
+        assert!(sql.contains("FROM \"logs\"\"; DROP TABLE other; --\""));
+        assert!(sql.contains("\"message\" = 'x'' OR 1=1 --'"));
+    }
+    #[test]
+    fn mixed_promql_modes_stat_and_sparkline_match_frontend() {
+        let tile = json!({"chartType":"timeseries","chartQuery":["up","rate(up[5m])","up+1"],"promqlQueryType":["instant","range","both"]});
+        assert_eq!(
+            promql_queries(&tile),
+            vec![
+                ("up".into(), "instant".into()),
+                ("rate(up[5m])".into(), "range".into()),
+                ("up+1".into(), "both".into())
+            ]
+        );
+        assert_eq!(query_modes(&tile, 0, "instant"), (false, true));
+        assert_eq!(query_modes(&tile, 1, "range"), (true, false));
+        assert_eq!(query_modes(&tile, 2, "both"), (true, true));
+        for chart in ["query-value", "gauge", "pie", "donut"] {
+            let mut stat = tile.clone();
+            stat["chartType"] = json!(chart);
+            assert_eq!(query_modes(&stat, 0, "range"), (false, true));
+        }
+        let mut stat = tile.clone();
+        stat["chartType"] = json!("query-value");
+        stat["config"] = json!({"layout":{"sparkline":true}});
+        assert_eq!(query_modes(&stat, 0, "range"), (true, true));
+        assert_eq!(query_modes(&stat, 1, "range"), (false, true));
+        assert_eq!(tile_step(&tile, 0, 3600_000, "up").unwrap(), 15000);
+        assert_eq!(tile_step(&tile, 0, 3600_000, "rate(up[5s])").unwrap(), 2000);
+        let null_fallback = json!({"promqlStep":null,"promqlQuery":{"step":"5m"}});
+        assert_eq!(
+            tile_step(&null_fallback, 0, 3600_000, "up").unwrap(),
+            300000
+        );
+    }
+    #[test]
+    fn bounds_reject_invalid_ranges_and_rows_before_execution() {
+        let start = "2026-10-01T00:00:00Z";
+        assert_eq!(
+            query_bounds(start, "2026-10-02T00:00:00Z", Some(500))
+                .unwrap()
+                .2,
+            500
+        );
+        for end in ["bad", "2026-09-30T23:59:59Z", "2026-11-02T00:00:00Z"] {
+            assert!(query_bounds(start, end, None).is_err());
+        }
+        for limit in [0, 501, usize::MAX] {
+            assert!(query_bounds(start, start, Some(limit)).is_err());
+        }
+        assert!(query_bounds("1969-12-31T23:00:00Z", start, None).is_err());
+    }
+    #[test]
+    fn bounded_variable_options_never_silently_replace_saved_dynamic_default() {
+        let variable = json!({"name":"host","type":"sql","defaultValue":"z"});
+        assert!(
+            select_variable_default(&variable, &["a".into()])
+                .unwrap_err()
+                .contains("explicit selection")
+        );
+        assert_eq!(
+            select_variable_default(&variable, &["a".into(), "z".into()]).unwrap(),
+            "z"
+        );
+        assert!(select_variable_default(&json!({"type":"sql"}), &["x".repeat(4097)]).is_err());
+        assert_eq!(
+            select_variable_default(&json!({"type":"list"}), &["a".into()]).unwrap(),
+            "a"
+        );
+    }
+    #[actix_web::test]
+    async fn unauthenticated_proposed_document_cannot_reach_query_execution() {
+        let req = actix_web::test::TestRequest::default().to_http_request();
+        let error=preview_value(&req,json!({"document":{"tiles":[]},"startTime":"2026-10-10T00:00:00Z","endTime":"2026-10-10T01:00:00Z"})).await.unwrap_err();
+        assert!(matches!(error, DashboardError::Api { status: 401, .. }));
+    }
+}
diff --git a/src/users/dashboard_service.rs b/src/users/dashboard_service.rs
new file mode 100644
index 000000000..811c49fc8
--- /dev/null
+++ b/src/users/dashboard_service.rs
@@ -0,0 +1,4333 @@
+/*
+ * Parseable Server (C) 2022 - 2026 Parseable, Inc.
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+//! Authoritative dashboard reads and atomic, conditional mutations shared by
+//! HTTP, tools and compatibility entry points. No cache lock spans storage I/O.
+
+use std::{collections::HashMap, sync::Arc};
+
+use bytes::Bytes;
+use chrono::Utc;
+use dashmap::DashMap;
+use once_cell::sync::Lazy;
+use serde_json::{Value, json};
+use sha2::{Digest, Sha256};
+use ulid::Ulid;
+
+use crate::{
+    handlers::http::users::{DASHBOARDS_DIR, USERS_ROOT_DIR, dashboards::DashboardError},
+    metastore::metastore_traits::{
+        ConditionalMetadataError, MetadataVersion, MetadataWriteCondition, Metastore,
+        VersionedMetadata,
+    },
+    parseable::PARSEABLE,
+};
+
+use super::{
+    dashboard_patch::{DashboardOperation, apply_patch, validate_dashboard},
+    dashboards::{CURRENT_DASHBOARD_VERSION, Dashboard},
+};
+
+const INTERNAL: &str = "_parseableDashboard";
+const RECEIPT_LIMIT: usize = 64;
+
+#[derive(Debug, Clone)]
+pub struct DashboardActor {
+    /// Already hashed using the same identity mapping as existing dashboards.
+    pub user_id: String,
+    pub is_admin: bool,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct DashboardWriteOptions {
+    pub expected_revision: Option<String>,
+    pub idempotency_key: Option<String>,
+    pub dry_run: bool,
+}
+
+#[derive(Debug)]
+pub enum DashboardMutation {
+    Replace(Value),
+    Metadata(HashMap<String, String>),
+    AddTile(Value),
+    Patch(Vec<DashboardOperation>),
+}
+
+// Only the legacy REST adapter selects this mode. Tools and PATCH always use
+// strict final-state validation, including when routed through the adapter.
+#[derive(Clone, Copy)]
+enum ValidationMode {
+    Strict,
+    LegacyRest,
+}
+
+#[derive(Debug, Clone)]
+pub struct DashboardService {
+    metastore: Arc<dyn Metastore>,
+    /// Immutable owner locators can safely be cached across revisions/deletion.
+    owners: Arc<DashMap<(String, Ulid), String>>,
+    legacy: Arc<DashMap<String, Arc<LegacyTenant>>>,
+}
+
+#[derive(Debug, Default)]
+struct LegacyTenant {
+    initialized: tokio::sync::OnceCell<()>,
+    titles: DashMap<String, Ulid>,
+}
+
+static SERVICE: Lazy<DashboardService> =
+    Lazy::new(|| DashboardService::new(PARSEABLE.metastore.clone()));
+
+pub async fn create_json(
+    actor: &DashboardActor,
+    tenant: &Option<String>,
+    document: Value,
+    options: &DashboardWriteOptions,
+) -> Result<Value, DashboardError> {
+    SERVICE.create_json(actor, tenant, document, options).await
+}
+pub async fn create_legacy_json(
+    actor: &DashboardActor,
+    tenant: &Option<String>,
+    document: Dashboard,
+    options: &DashboardWriteOptions,
+) -> Result<Value, DashboardError> {
+    SERVICE
+        .create_legacy_json(actor, tenant, document, options)
+        .await
+}
+pub async fn mutate_json(
+    actor: &DashboardActor,
+    id: Ulid,
+    tenant: &Option<String>,
+    mutation: DashboardMutation,
+    options: &DashboardWriteOptions,
+) -> Result<Value, DashboardError> {
+    SERVICE
+        .mutate_json(actor, id, tenant, mutation, options)
+        .await
+}
+pub async fn mutate_legacy_json(
+    actor: &DashboardActor,
+    id: Ulid,
+    tenant: &Option<String>,
+    mutation: DashboardMutation,
+    options: &DashboardWriteOptions,
+) -> Result<Value, DashboardError> {
+    SERVICE
+        .mutate_legacy_json(actor, id, tenant, mutation, options)
+        .await
+}
+pub async fn get_json(id: Ulid, tenant: &Option<String>) -> Result<Value, DashboardError> {
+    SERVICE.get_json(id, tenant).await
+}
+pub async fn delete_json(
+    actor: &DashboardActor,
+    id: Ulid,
+    tenant: &Option<String>,
+    options: &DashboardWriteOptions,
+) -> Result<(), DashboardError> {
+    SERVICE.delete_json(actor, id, tenant, options).await
+}
+pub async fn list_json(tenant: &Option<String>) -> Result<Vec<Value>, DashboardError> {
+    SERVICE.list_json(tenant).await
+}
+
+pub(crate) fn forget_tenant(tenant: &str) {
+    SERVICE.owners.retain(|(key, _), _| key != tenant);
+    SERVICE.legacy.remove(tenant);
+}
+
+struct StoredDashboard {
+    path: String,
+    document: Value,
+    version: MetadataVersion,
+    revision: String,
+}
+
+struct TitleClaim {
+    path: String,
+    version: MetadataVersion,
+    document: Value,
+    /// Only the operation that acquired a pending claim may roll it back.
+    acquired: bool,
+}
+
+impl DashboardService {
+    pub fn new(metastore: Arc<dyn Metastore>) -> Self {
+        Self {
+            metastore,
+            owners: Arc::new(DashMap::new()),
+            legacy: Arc::new(DashMap::new()),
+        }
+    }
+
+    async fn read(
+        &self,
+        path: &str,
+        tenant: &Option<String>,
+    ) -> Result<Option<(Value, MetadataVersion)>, DashboardError> {
+        self.metastore
+            .get_dashboard_versioned(path, tenant)
+            .await
+            .map_err(storage_error)?
+            .map(|VersionedMetadata { bytes, version }| {
+                Ok((serde_json::from_slice(&bytes)?, version))
+            })
+            .transpose()
+    }
+
+    async fn write(
+        &self,
+        path: &str,
+        document: &Value,
+        condition: MetadataWriteCondition,
+        tenant: &Option<String>,
+    ) -> Result<MetadataVersion, DashboardError> {
+        self.metastore
+            .put_dashboard_conditional(
+                path,
+                Bytes::from(serde_json::to_vec(document)?),
+                condition,
+                tenant,
+            )
+            .await
+            .map_err(storage_error)
+    }
+
+    /// Confirm the commit nonce after EVERY conditional-write error: provider
+    /// transport retries can report a precondition failure after committing.
+    async fn commit_document(
+        &self,
+        path: &str,
+        document: &Value,
+        condition: MetadataWriteCondition,
+        tenant: &Option<String>,
+        fence_create: bool,
+    ) -> Result<(), DashboardError> {
+        let nonce = document
+            .pointer("/_parseableDashboard/revision")
+            .and_then(Value::as_str)
+            .ok_or_else(|| corrupt("commit nonce"))?;
+        let error = match self.write(path, document, condition.clone(), tenant).await {
+            Ok(_) => return Ok(()),
+            Err(error) => error,
+        };
+        let current = self.read(path, tenant).await?;
+        if current
+            .as_ref()
+            .is_some_and(|(current, _)| has_nonce(current, nonce))
+        {
+            return Ok(());
+        }
+        let fence = match (&condition, current.as_ref()) {
+            (MetadataWriteCondition::Create, None) if fence_create => {
+                let mut fence = compact_tombstone(document);
+                // An unaccepted unkeyed create gets no applied receipt.
+                fence[INTERNAL] = json!({"revision":Ulid::new().to_string(),"tombstone":true,"createReceipt":null,"receipts":[]});
+                Some((fence, MetadataWriteCondition::Create))
+            }
+            (MetadataWriteCondition::Update(source), Some((current, version)))
+                if source == version =>
+            {
+                let mut fence = current.clone();
+                advance_nonce(&mut fence);
+                Some((fence, MetadataWriteCondition::Update(version.clone())))
+            }
+            _ => None,
+        };
+        if let Some((fence, condition)) = fence {
+            // Conditional fencing either prevents the original from landing,
+            // or loses to it. Reread even when the fencing request also errors.
+            let _ = self.write(path, &fence, condition, tenant).await;
+            if self
+                .read(path, tenant)
+                .await?
+                .as_ref()
+                .is_some_and(|(current, _)| has_nonce(current, nonce))
+            {
+                return Ok(());
+            }
+        }
+        Err(error)
+    }
+
+    async fn settle_failed_claim(&self, claim: &TitleClaim, tenant: &Option<String>) {
+        let Some(id) = claim
+            .document
+            .get("dashboardId")
+            .and_then(Value::as_str)
+            .and_then(|id| Ulid::from_string(id).ok())
+        else {
+            return;
+        };
+        let current = match self.stored(id, tenant).await {
+            Ok(stored) => Some(stored),
+            Err(error) if is_not_found(&error) => None,
+            Err(error) => {
+                tracing::warn!(%error,"Could not reconcile dashboard title after uncertain write");
+                return;
+            }
+        };
+        if current.as_ref().is_some_and(|stored| {
+            !deleted(&stored.document)
+                && stored.document.get("title") == claim.document.get("title")
+        }) {
+            // Another edit may already have advanced our commit nonce. Its
+            // current live title remains reserved regardless of nonce mismatch.
+            self.activate_claim(
+                TitleClaim {
+                    path: claim.path.clone(),
+                    version: claim.version.clone(),
+                    document: claim.document.clone(),
+                    acquired: false,
+                },
+                tenant,
+            )
+            .await;
+        } else if pending_source_obsolete(&claim.document, current.as_ref()) {
+            self.release_owned_title(
+                TitleClaim {
+                    path: claim.path.clone(),
+                    version: claim.version.clone(),
+                    document: claim.document.clone(),
+                    acquired: false,
+                },
+                tenant,
+            )
+            .await;
+        }
+    }
+
+    async fn bootstrap_legacy(
+        &self,
+        tenant: &Option<String>,
+    ) -> Result<Arc<LegacyTenant>, DashboardError> {
+        let state = self
+            .legacy
+            .entry(tenant.as_deref().unwrap_or("").to_owned())
+            .or_default()
+            .clone();
+        state
+            .initialized
+            .get_or_try_init(|| async {
+                for bytes in self.metastore.get_tenant_dashboards(tenant).await? {
+                    let Ok(document) = serde_json::from_slice::<Value>(&bytes) else {
+                        continue;
+                    };
+                    let Some(id) = document
+                        .get("dashboardId")
+                        .and_then(Value::as_str)
+                        .and_then(|id| Ulid::from_string(id).ok())
+                    else {
+                        continue;
+                    };
+                    let Some(owner) = document.get("author").and_then(Value::as_str) else {
+                        continue;
+                    };
+                    validate_scope(tenant, Some(owner))?;
+                    self.owners
+                        .entry((tenant.as_deref().unwrap_or("").to_owned(), id))
+                        .or_insert_with(|| owner.to_owned());
+                    if !deleted(&document)
+                        && let Some(title) = document.get("title").and_then(Value::as_str)
+                    {
+                        state.titles.entry(title.to_owned()).or_insert(id);
+                    }
+                }
+                Ok::<(), DashboardError>(())
+            })
+            .await?;
+        Ok(state)
+    }
+
+    async fn legacy_title(
+        &self,
+        title: &str,
+        tenant: &Option<String>,
+    ) -> Result<Option<Ulid>, DashboardError> {
+        let state = self.bootstrap_legacy(tenant).await?;
+        let Some(id) = state.titles.get(title).map(|entry| *entry.value()) else {
+            return Ok(None);
+        };
+        // The bootstrap is a candidate index, never authority: another node
+        // may have renamed or deleted this legacy document since initialization.
+        match self.stored(id, tenant).await {
+            Ok(stored)
+                if !deleted(&stored.document)
+                    && stored.document.get("title").and_then(Value::as_str) == Some(title) =>
+            {
+                Ok(Some(id))
+            }
+            Ok(_) => {
+                state.titles.remove_if(title, |_, existing| *existing == id);
+                Ok(None)
+            }
+            Err(error) if is_not_found(&error) => {
+                state.titles.remove_if(title, |_, existing| *existing == id);
+                Ok(None)
+            }
+            Err(error) => Err(error),
+        }
+    }
+
+    async fn owner(&self, id: Ulid, tenant: &Option<String>) -> Result<String, DashboardError> {
+        validate_scope(tenant, None)?;
+        let key = (tenant.as_deref().unwrap_or("").to_owned(), id);
+        if let Some(owner) = self.owners.get(&key) {
+            return Ok(owner.clone());
+        }
+        let locator_path = locator_path(tenant, id);
+        if let Some((locator, _)) = self.read(&locator_path, tenant).await? {
+            let owner = locator
+                .get("owner")
+                .and_then(Value::as_str)
+                .ok_or_else(|| corrupt("dashboard owner locator"))?
+                .to_owned();
+            validate_scope(tenant, Some(&owner))?;
+            if locator.get("dashboardId").and_then(Value::as_str) != Some(id.to_string().as_str()) {
+                return Err(corrupt("dashboard owner locator ID"));
+            }
+            self.owners.insert(key, owner.clone());
+            return Ok(owner);
+        }
+        // A negative result only skips repeated legacy scans. Every uncached
+        // ID still checks its canonical locator above, so new remote creations
+        // remain visible after this tenant's one-time bootstrap.
+        self.bootstrap_legacy(tenant).await?;
+        if let Some(owner) = self.owners.get(&key) {
+            return Ok(owner.clone());
+        }
+        Err(not_found())
+    }
+
+    async fn install_locator(
+        &self,
+        id: Ulid,
+        owner: &str,
+        tenant: &Option<String>,
+    ) -> Result<String, DashboardError> {
+        let path = locator_path(tenant, id);
+        let locator = json!({"dashboardId":id.to_string(),"owner":owner});
+        match self
+            .write(&path, &locator, MetadataWriteCondition::Create, tenant)
+            .await
+        {
+            Ok(_) => {}
+            Err(error) if is_conflict(&error) => {
+                let (existing, _) = self
+                    .read(&path, tenant)
+                    .await?
+                    .ok_or_else(|| corrupt("missing dashboard locator after conflict"))?;
+                if existing != locator {
+                    return Err(api(
+                        409,
+                        "dashboard_id_conflict",
+                        "Dashboard ID belongs to another owner",
+                        json!({}),
+                    ));
+                }
+            }
+            Err(error) => return Err(error),
+        }
+        self.owners.insert(
+            (tenant.as_deref().unwrap_or("").to_owned(), id),
+            owner.to_owned(),
+        );
+        Ok(owner.to_owned())
+    }
+
+    async fn stored(
+        &self,
+        id: Ulid,
+        tenant: &Option<String>,
+    ) -> Result<StoredDashboard, DashboardError> {
+        let owner = self.owner(id, tenant).await?;
+        let path = dashboard_path(tenant, &owner, id);
+        let (mut document, version) = self.read(&path, tenant).await?.ok_or_else(not_found)?;
+        if !document.is_object() {
+            return Err(corrupt("dashboard document"));
+        }
+        // A caller never controls storage identity via fields in an update body.
+        document["author"] = json!(owner);
+        document["dashboardId"] = json!(id.to_string());
+        document["tenantId"] = json!(tenant);
+        let revision = revision(&document);
+        Ok(StoredDashboard {
+            path,
+            document,
+            version,
+            revision,
+        })
+    }
+
+    pub async fn get_json(
+        &self,
+        id: Ulid,
+        tenant: &Option<String>,
+    ) -> Result<Value, DashboardError> {
+        let stored = self.stored(id, tenant).await?;
+        if deleted(&stored.document) {
+            return Err(not_found());
+        }
+        Ok(public_document(&stored.document, &stored.revision))
+    }
+
+    pub async fn list_json(&self, tenant: &Option<String>) -> Result<Vec<Value>, DashboardError> {
+        validate_scope(tenant, None)?;
+        let mut documents = Vec::new();
+        for bytes in self.metastore.get_tenant_dashboards(tenant).await? {
+            let Ok(mut document) = serde_json::from_slice::<Value>(&bytes) else {
+                tracing::warn!("Skipping malformed dashboard JSON in listing");
+                continue;
+            };
+            if deleted(&document) {
+                continue;
+            }
+            // Listings need no extra per-object GET for new service documents.
+            // Legacy documents are fetched once to expose an authoritative token.
+            let current_revision = document
+                .pointer("/_parseableDashboard/revision")
+                .and_then(Value::as_str)
+                .map(|_| {
+                    let mut normalized = document.clone();
+                    normalized["tenantId"] = json!(tenant);
+                    revision(&normalized)
+                });
+            if let Some(current_revision) = current_revision {
+                document["tenantId"] = json!(tenant);
+                documents.push(public_document(&document, &current_revision));
+            } else if let Some(id) = document
+                .get("dashboardId")
+                .and_then(Value::as_str)
+                .and_then(|id| Ulid::from_string(id).ok())
+            {
+                match self.get_json(id, tenant).await {
+                    Ok(document) => documents.push(document),
+                    Err(error) if is_not_found(&error) => {}
+                    Err(error) => return Err(error),
+                }
+            }
+        }
+        documents.sort_by(|a, b| {
+            b.get("modified")
+                .and_then(Value::as_str)
+                .cmp(&a.get("modified").and_then(Value::as_str))
+        });
+        Ok(documents)
+    }
+
+    pub async fn create_json(
+        &self,
+        actor: &DashboardActor,
+        tenant: &Option<String>,
+        document: Value,
+        options: &DashboardWriteOptions,
+    ) -> Result<Value, DashboardError> {
+        self.create_with_validation(actor, tenant, document, options, ValidationMode::Strict)
+            .await
+    }
+
+    pub(crate) async fn create_legacy_json(
+        &self,
+        actor: &DashboardActor,
+        tenant: &Option<String>,
+        document: Dashboard,
+        options: &DashboardWriteOptions,
+    ) -> Result<Value, DashboardError> {
+        if document.title.is_empty() {
+            return Err(DashboardError::Metadata("Title must be provided"));
+        }
+        self.create_with_validation(
+            actor,
+            tenant,
+            serde_json::to_value(document)?,
+            options,
+            ValidationMode::LegacyRest,
+        )
+        .await
+    }
+
+    async fn create_with_validation(
+        &self,
+        actor: &DashboardActor,
+        tenant: &Option<String>,
+        document: Value,
+        options: &DashboardWriteOptions,
+        validation_mode: ValidationMode,
+    ) -> Result<Value, DashboardError> {
+        if options.dry_run {
+            return self
+                .create_json_inner(actor, tenant, document, options, validation_mode)
+                .await;
+        }
+        // Dropping a request's JoinHandle detaches its commit task. Once a
+        // title is reserved, routine HTTP cancellation cannot strand it.
+        let service = self.clone();
+        let actor = actor.clone();
+        let tenant = tenant.clone();
+        let options = options.clone();
+        tokio::spawn(async move {
+            service
+                .create_json_inner(&actor, &tenant, document, &options, validation_mode)
+                .await
+        })
+        .await
+        .map_err(|error| {
+            api(
+                500,
+                "dashboard_commit_failed",
+                &format!("Dashboard commit task failed: {error}"),
+                json!({}),
+            )
+        })?
+    }
+
+    async fn create_json_inner(
+        &self,
+        actor: &DashboardActor,
+        tenant: &Option<String>,
+        mut document: Value,
+        options: &DashboardWriteOptions,
+        validation_mode: ValidationMode,
+    ) -> Result<Value, DashboardError> {
+        validate_scope(tenant, Some(&actor.user_id))?;
+        validate_options(options)?;
+        require_object(&document)?;
+        reject_internal(&document)?;
+        let request_hash =
+            validation_mode.request_hash(&json!({"operation":"create","document":document}));
+        let id = if let Some(key) = &options.idempotency_key {
+            let digest = Sha256::digest(serde_json::to_vec(&json!([tenant, actor.user_id, key]))?);
+            Ulid::from_bytes(digest[..16].try_into().expect("SHA256 prefix"))
+        } else {
+            Ulid::new()
+        };
+        let path = dashboard_path(tenant, &actor.user_id, id);
+        if options.idempotency_key.is_some()
+            && let Some((existing, _version)) = self.read(&path, tenant).await?
+        {
+            let revision = revision(&existing);
+            if let Some(result) =
+                replay(&existing, &revision, actor, options, &request_hash, false)?
+            {
+                return Ok(result);
+            }
+            return Err(api(
+                409,
+                "idempotency_conflict",
+                "Create idempotency key is already used",
+                json!({"dashboardId":id.to_string()}),
+            ));
+        }
+        let now = Utc::now().to_rfc3339();
+        document["dashboardId"] = json!(id.to_string());
+        document["author"] = json!(actor.user_id);
+        document["tenantId"] = json!(tenant);
+        document["created"] = json!(now);
+        document["modified"] = json!(now);
+        document["version"] = json!(CURRENT_DASHBOARD_VERSION);
+        let object = document.as_object_mut().expect("object checked");
+        object.remove("revision");
+        for (key, default) in [
+            ("tiles", json!([])),
+            ("dashboardType", json!("Dashboard")),
+            ("isFavorite", json!(false)),
+        ] {
+            if object.get(key).is_none_or(Value::is_null) {
+                object.insert(key.to_owned(), default);
+            }
+        }
+        let validation = validation_mode.validate(&document, None)?;
+        let next_revision = Ulid::new().to_string();
+        let diff = document_diff(&json!({}), &document);
+        let title = title(&document)?.to_owned();
+        if options.dry_run {
+            self.check_title_available(&title, id, tenant).await?;
+            let next_revision = revision_with_nonce(&document, Some(&next_revision));
+            return Ok(
+                json!({"dashboard":public_document(&document,&next_revision),"revision":next_revision,"validation":validation,"diff":diff,"dryRun":true,"titleAvailability":{"checked":true,"reserved":false,"mayConflictAtCommit":true}}),
+            );
+        }
+        let claim = self
+            .claim_title(&title, id, None, actor, options, &request_hash, tenant)
+            .await?;
+        if let Err(error) = self.install_locator(id, &actor.user_id, tenant).await {
+            self.release_claim(&claim, tenant).await;
+            return Err(error);
+        }
+        stamp(
+            &mut document,
+            &next_revision,
+            false,
+            actor,
+            options,
+            &request_hash,
+            true,
+        );
+        let next_revision = revision(&document);
+        match self
+            .commit_document(
+                &path,
+                &document,
+                MetadataWriteCondition::Create,
+                tenant,
+                options.idempotency_key.is_none(),
+            )
+            .await
+        {
+            Ok(_) => {
+                self.activate_claim(claim, tenant).await;
+            }
+            Err(error) => {
+                self.settle_failed_claim(&claim, tenant).await;
+                if is_conflict(&error)
+                    && let Some((existing, _version)) = self.read(&path, tenant).await?
+                {
+                    let revision = revision(&existing);
+                    if let Some(result) =
+                        replay(&existing, &revision, actor, options, &request_hash, false)?
+                    {
+                        return Ok(result);
+                    }
+                }
+                return Err(error);
+            }
+        }
+        Ok(
+            json!({"dashboard":public_document(&document,&next_revision),"revision":next_revision,"validation":validation,"diff":diff}),
+        )
+    }
+
+    /// Legacy PUT may omit a revision. Capture a source version once and use
+    /// the normal CAS path; never retry a full replacement against newer data.
+    /// PATCH/tools retain their explicit revision requirement.
+    pub async fn mutate_legacy_json(
+        &self,
+        actor: &DashboardActor,
+        id: Ulid,
+        tenant: &Option<String>,
+        mutation: DashboardMutation,
+        options: &DashboardWriteOptions,
+    ) -> Result<Value, DashboardError> {
+        let mut options = options.clone();
+        if let DashboardMutation::Replace(document) = &mutation
+            && options.expected_revision.is_none()
+            && document.get("revision").and_then(Value::as_str).is_none()
+            && options.idempotency_key.is_none()
+        {
+            let base = self.stored(id, tenant).await?;
+            authorize(actor, &base.document)?;
+            if deleted(&base.document) {
+                return Err(not_found());
+            }
+            options.expected_revision = Some(base.revision);
+        }
+        let validation_mode = if matches!(&mutation, DashboardMutation::Patch(_)) {
+            ValidationMode::Strict
+        } else {
+            ValidationMode::LegacyRest
+        };
+        self.mutate_with_validation(actor, id, tenant, mutation, &options, validation_mode)
+            .await
+    }
+
+    pub async fn mutate_json(
+        &self,
+        actor: &DashboardActor,
+        id: Ulid,
+        tenant: &Option<String>,
+        mutation: DashboardMutation,
+        options: &DashboardWriteOptions,
+    ) -> Result<Value, DashboardError> {
+        self.mutate_with_validation(actor, id, tenant, mutation, options, ValidationMode::Strict)
+            .await
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    async fn mutate_with_validation(
+        &self,
+        actor: &DashboardActor,
+        id: Ulid,
+        tenant: &Option<String>,
+        mutation: DashboardMutation,
+        options: &DashboardWriteOptions,
+        validation_mode: ValidationMode,
+    ) -> Result<Value, DashboardError> {
+        if options.dry_run {
+            return self
+                .mutate_json_inner(actor, id, tenant, mutation, options, validation_mode)
+                .await;
+        }
+        // Dropping a request's JoinHandle detaches its commit task. Once a
+        // title is reserved, routine HTTP cancellation cannot strand it.
+        let service = self.clone();
+        let actor = actor.clone();
+        let tenant = tenant.clone();
+        let options = options.clone();
+        tokio::spawn(async move {
+            service
+                .mutate_json_inner(&actor, id, &tenant, mutation, &options, validation_mode)
+                .await
+        })
+        .await
+        .map_err(|error| {
+            api(
+                500,
+                "dashboard_commit_failed",
+                &format!("Dashboard commit task failed: {error}"),
+                json!({}),
+            )
+        })?
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    async fn mutate_json_inner(
+        &self,
+        actor: &DashboardActor,
+        id: Ulid,
+        tenant: &Option<String>,
+        mutation: DashboardMutation,
+        options: &DashboardWriteOptions,
+        validation_mode: ValidationMode,
+    ) -> Result<Value, DashboardError> {
+        let retry_delta = options.expected_revision.is_none()
+            && options.idempotency_key.is_none()
+            && matches!(
+                &mutation,
+                DashboardMutation::Metadata(_) | DashboardMutation::AddTile(_)
+            );
+        for attempt in 0..8 {
+            let result = self
+                .mutate_once(actor, id, tenant, &mutation, options, validation_mode)
+                .await;
+            if retry_delta
+                && attempt < 7
+                && matches!(
+                    &result,
+                    Err(DashboardError::Api {
+                        code: "revision_conflict" | "title_reservation_pending",
+                        ..
+                    })
+                )
+            {
+                tokio::task::yield_now().await;
+                continue;
+            }
+            return result;
+        }
+        unreachable!("bounded mutation retry always returns")
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    async fn mutate_once(
+        &self,
+        actor: &DashboardActor,
+        id: Ulid,
+        tenant: &Option<String>,
+        mutation: &DashboardMutation,
+        options: &DashboardWriteOptions,
+        validation_mode: ValidationMode,
+    ) -> Result<Value, DashboardError> {
+        let mut effective_options = options.clone();
+        if let DashboardMutation::Replace(document) = mutation
+            && effective_options.expected_revision.is_none()
+        {
+            effective_options.expected_revision = document
+                .get("revision")
+                .and_then(Value::as_str)
+                .map(str::to_owned);
+        }
+        let options = &effective_options;
+        validate_scope(tenant, Some(&actor.user_id))?;
+        validate_options(options)?;
+        let base = self.stored(id, tenant).await?;
+        authorize(actor, &base.document)?;
+        let request_hash = validation_mode.request_hash(&mutation_request(mutation)?);
+        if let Some(result) = replay(
+            &base.document,
+            &base.revision,
+            actor,
+            options,
+            &request_hash,
+            false,
+        )? {
+            return Ok(result);
+        }
+        if deleted(&base.document) {
+            return Err(not_found());
+        }
+        if (matches!(
+            mutation,
+            DashboardMutation::Patch(_) | DashboardMutation::Replace(_)
+        ) || options.idempotency_key.is_some())
+            && options.expected_revision.is_none()
+        {
+            return Err(api(
+                428,
+                "revision_required",
+                "Dashboard replacements, patches and keyed mutations require an expected revision",
+                json!({"currentRevision":base.revision}),
+            ));
+        }
+        check_revision(options, &base.revision)?;
+        let mut candidate = match &mutation {
+            DashboardMutation::Replace(document) => {
+                require_object(document)?;
+                reject_internal(document)?;
+                document.clone()
+            }
+            DashboardMutation::Metadata(metadata) => apply_metadata(&base.document, metadata)?,
+            DashboardMutation::AddTile(tile) => add_tile(&base.document, tile)?,
+            DashboardMutation::Patch(operations) => {
+                apply_patch_candidate(&base.document, operations)?
+            }
+        };
+        require_object(&candidate)?;
+        // Metadata is restored from the authoritative object, including owner
+        // when an administrator changes someone else's dashboard.
+        for field in ["author", "dashboardId", "tenantId", "created", "version"] {
+            if let Some(value) = base.document.get(field) {
+                candidate[field] = value.clone();
+            }
+        }
+        candidate
+            .as_object_mut()
+            .expect("object checked")
+            .remove("revision");
+        if let Some(internal) = base.document.get(INTERNAL) {
+            candidate[INTERNAL] = internal.clone();
+        }
+        candidate["modified"] = json!(Utc::now().to_rfc3339());
+        if matches!(validation_mode, ValidationMode::LegacyRest) {
+            legacy_defaults(&mut candidate);
+        }
+        let validation = validation_mode.validate(&candidate, Some(&base.document))?;
+        let diff = document_diff(
+            &public_document(&base.document, &base.revision),
+            &public_document(&candidate, &base.revision),
+        );
+        let next_revision = Ulid::new().to_string();
+        let old_title = title(&base.document)?.to_owned();
+        let next_title = title(&candidate)?.to_owned();
+        if options.dry_run {
+            if old_title != next_title {
+                self.check_title_available(&next_title, id, tenant).await?;
+            }
+            return Ok(
+                json!({"dashboard":public_document(&candidate,&base.revision),"revision":base.revision,"validation":validation,"diff":diff,"dryRun":true,"titleAvailability":{"checked":old_title!=next_title,"reserved":false,"mayConflictAtCommit":true}}),
+            );
+        }
+        // A verified service document already owns its unchanged title. Hot
+        // tile/config updates need one authoritative GET plus one conditional
+        // PUT, without an extra title-index request on every agent operation.
+        let claim = if old_title == next_title
+            && base
+                .document
+                .pointer("/_parseableDashboard/contentRevision")
+                .and_then(Value::as_str)
+                == Some(base.revision.as_str())
+        {
+            None
+        } else {
+            Some(
+                self.claim_title(
+                    &next_title,
+                    id,
+                    Some(&base),
+                    actor,
+                    options,
+                    &request_hash,
+                    tenant,
+                )
+                .await?,
+            )
+        };
+        let previous_claim = if old_title != next_title {
+            self.read_title_claim(&old_title, id, tenant).await?
+        } else {
+            None
+        };
+        stamp(
+            &mut candidate,
+            &next_revision,
+            false,
+            actor,
+            options,
+            &request_hash,
+            false,
+        );
+        let next_revision = revision(&candidate);
+        match self
+            .commit_document(
+                &base.path,
+                &candidate,
+                MetadataWriteCondition::Update(base.version.clone()),
+                tenant,
+                false,
+            )
+            .await
+        {
+            Ok(_) => {}
+            Err(error) => {
+                if let Some(claim) = &claim {
+                    self.settle_failed_claim(claim, tenant).await;
+                }
+                if is_conflict(&error) {
+                    let latest = self.stored(id, tenant).await?;
+                    if let Some(result) = replay(
+                        &latest.document,
+                        &latest.revision,
+                        actor,
+                        options,
+                        &request_hash,
+                        false,
+                    )? {
+                        return Ok(result);
+                    }
+                    return Err(conflict(&latest.revision));
+                }
+                return Err(error);
+            }
+        }
+        if let Some(claim) = claim {
+            self.activate_claim(claim, tenant).await;
+        }
+        if let Some(previous) = previous_claim {
+            self.release_owned_title(previous, tenant).await;
+        }
+        Ok(
+            json!({"dashboard":public_document(&candidate,&next_revision),"revision":next_revision,"validation":validation,"diff":diff}),
+        )
+    }
+
+    pub async fn delete_json(
+        &self,
+        actor: &DashboardActor,
+        id: Ulid,
+        tenant: &Option<String>,
+        options: &DashboardWriteOptions,
+    ) -> Result<(), DashboardError> {
+        if options.dry_run {
+            return self.delete_json_inner(actor, id, tenant, options).await;
+        }
+        // Dropping a request's JoinHandle detaches its commit task. Once a
+        // title is reserved, routine HTTP cancellation cannot strand it.
+        let service = self.clone();
+        let actor = actor.clone();
+        let tenant = tenant.clone();
+        let options = options.clone();
+        tokio::spawn(async move {
+            service
+                .delete_json_inner(&actor, id, &tenant, &options)
+                .await
+        })
+        .await
+        .map_err(|error| {
+            api(
+                500,
+                "dashboard_commit_failed",
+                &format!("Dashboard commit task failed: {error}"),
+                json!({}),
+            )
+        })?
+    }
+
+    async fn delete_json_inner(
+        &self,
+        actor: &DashboardActor,
+        id: Ulid,
+        tenant: &Option<String>,
+        options: &DashboardWriteOptions,
+    ) -> Result<(), DashboardError> {
+        validate_scope(tenant, Some(&actor.user_id))?;
+        validate_options(options)?;
+        let base = self.stored(id, tenant).await?;
+        authorize(actor, &base.document)?;
+        let request_hash = fingerprint(&json!({"operation":"delete"}));
+        if replay(
+            &base.document,
+            &base.revision,
+            actor,
+            options,
+            &request_hash,
+            true,
+        )?
+        .is_some()
+        {
+            return Ok(());
+        }
+        if options.idempotency_key.is_some() && options.expected_revision.is_none() {
+            return Err(api(
+                428,
+                "revision_required",
+                "Keyed dashboard deletion requires an expected revision",
+                json!({"currentRevision":base.revision}),
+            ));
+        }
+        if deleted(&base.document) {
+            if options.expected_revision.is_none() {
+                return Ok(());
+            }
+            return Err(conflict(&base.revision));
+        }
+        check_revision(options, &base.revision)?;
+        if options.dry_run {
+            return Ok(());
+        }
+        let title_claim = self
+            .read_title_claim(title(&base.document)?, id, tenant)
+            .await?;
+        let mut tombstone = compact_tombstone(&base.document);
+        let next_revision = Ulid::new().to_string();
+        tombstone["modified"] = json!(Utc::now().to_rfc3339());
+        stamp(
+            &mut tombstone,
+            &next_revision,
+            true,
+            actor,
+            options,
+            &request_hash,
+            false,
+        );
+        match self
+            .commit_document(
+                &base.path,
+                &tombstone,
+                MetadataWriteCondition::Update(base.version),
+                tenant,
+                false,
+            )
+            .await
+        {
+            Ok(_) => {}
+            Err(error) if is_conflict(&error) => {
+                let latest = self.stored(id, tenant).await?;
+                if replay(
+                    &latest.document,
+                    &latest.revision,
+                    actor,
+                    options,
+                    &request_hash,
+                    true,
+                )?
+                .is_some()
+                {
+                    return Ok(());
+                }
+                return Err(conflict(&latest.revision));
+            }
+            Err(error) => return Err(error),
+        }
+        if let Some(claim) = title_claim {
+            self.release_owned_title(claim, tenant).await;
+        }
+        Ok(())
+    }
+
+    async fn check_title_available(
+        &self,
+        title: &str,
+        id: Ulid,
+        tenant: &Option<String>,
+    ) -> Result<(), DashboardError> {
+        if let Some((claim, _)) = self.read(&title_path(tenant, title), tenant).await? {
+            match claim.get("state").and_then(Value::as_str) {
+                Some("active" | "pending") => {
+                    let claimant = claim
+                        .get("dashboardId")
+                        .and_then(Value::as_str)
+                        .and_then(|id| Ulid::from_string(id).ok())
+                        .ok_or_else(|| corrupt("title reservation owner"))?;
+                    let current = match self.stored(claimant, tenant).await {
+                        Ok(stored) => Some(stored),
+                        Err(error) if is_not_found(&error) => None,
+                        Err(error) => return Err(error),
+                    };
+                    if claimant != id {
+                        if current.as_ref().is_some_and(|stored| {
+                            !deleted(&stored.document)
+                                && stored.document.get("title").and_then(Value::as_str)
+                                    == Some(title)
+                        }) {
+                            return Err(api(
+                                409,
+                                "title_conflict",
+                                "Dashboard title must be unique",
+                                json!({"title":title}),
+                            ));
+                        }
+                        if claim["state"] == "pending"
+                            && !pending_source_obsolete(&claim, current.as_ref())
+                        {
+                            return Err(api(
+                                409,
+                                "title_reservation_pending",
+                                "Dashboard title has an unfinished reservation whose source can still commit",
+                                json!({"title":title}),
+                            ));
+                        }
+                    }
+                }
+                Some("released") => {}
+                _ => return Err(corrupt("title reservation state")),
+            }
+        }
+        if self
+            .legacy_title(title, tenant)
+            .await?
+            .is_some_and(|legacy_id| legacy_id != id)
+        {
+            return Err(api(
+                409,
+                "title_conflict",
+                "Dashboard title must be unique",
+                json!({"title":title}),
+            ));
+        }
+        Ok(())
+    }
+
+    async fn read_title_claim(
+        &self,
+        title: &str,
+        id: Ulid,
+        tenant: &Option<String>,
+    ) -> Result<Option<TitleClaim>, DashboardError> {
+        let path = title_path(tenant, title);
+        Ok(self
+            .read(&path, tenant)
+            .await?
+            .filter(|(claim, _)| {
+                claim.get("dashboardId").and_then(Value::as_str) == Some(id.to_string().as_str())
+                    && claim.get("state").and_then(Value::as_str) != Some("released")
+            })
+            .map(|(document, version)| TitleClaim {
+                path,
+                document,
+                version,
+                acquired: false,
+            }))
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    async fn claim_title(
+        &self,
+        title: &str,
+        id: Ulid,
+        base: Option<&StoredDashboard>,
+        actor: &DashboardActor,
+        options: &DashboardWriteOptions,
+        request_hash: &str,
+        tenant: &Option<String>,
+    ) -> Result<TitleClaim, DashboardError> {
+        let path = title_path(tenant, title);
+        let operation = match &options.idempotency_key {
+            Some(key) => fingerprint(&json!([actor.user_id, key, request_hash])),
+            None => Ulid::new().to_string(),
+        };
+        // This exact object-storage version fences every in-flight attempt
+        // sharing the reservation. A changed source proves its conditional
+        // document write can never commit and permits safe orphan recovery.
+        let source_version = base.map(|stored| metadata_version_json(&stored.version));
+        let proposed = json!({"dashboardId":id.to_string(),"title":title,"state":"pending","operation":operation,"sourceVersion":source_version,"sourceRevision":base.map(|stored|stored.revision.as_str())});
+        for _ in 0..8 {
+            let existing = self.read(&path, tenant).await?;
+            if let Some((claim, version)) = &existing {
+                let state = claim.get("state").and_then(Value::as_str);
+                let claimant = claim
+                    .get("dashboardId")
+                    .and_then(Value::as_str)
+                    .and_then(|id| Ulid::from_string(id).ok());
+                if state == Some("pending") {
+                    if let Some(claimant) = claimant {
+                        let current = match self.stored(claimant, tenant).await {
+                            Ok(stored) => Some(stored),
+                            Err(error) if is_not_found(&error) => None,
+                            Err(error) => return Err(error),
+                        };
+                        if current.as_ref().is_some_and(|stored| {
+                            !deleted(&stored.document)
+                                && stored.document.get("title").and_then(Value::as_str)
+                                    == Some(title)
+                        }) {
+                            // The dashboard itself proves a successful commit,
+                            // even if its writer crashed before activation.
+                            let mut active = claim.clone();
+                            active["state"] = json!("active");
+                            match self
+                                .write(
+                                    &path,
+                                    &active,
+                                    MetadataWriteCondition::Update(version.clone()),
+                                    tenant,
+                                )
+                                .await
+                            {
+                                Ok(_) => continue,
+                                Err(error) if is_conflict(&error) => continue,
+                                Err(error) => return Err(error),
+                            }
+                        }
+                        let source_obsolete = pending_source_obsolete(claim, current.as_ref());
+                        if source_obsolete {
+                            // CAS of this reservation prevents an old cleanup
+                            // from releasing a retry rebound to a newer source.
+                            match self
+                                .write(
+                                    &path,
+                                    &json!({"state":"released"}),
+                                    MetadataWriteCondition::Update(version.clone()),
+                                    tenant,
+                                )
+                                .await
+                            {
+                                Ok(_) => continue,
+                                Err(error) if is_conflict(&error) => continue,
+                                Err(error) => return Err(error),
+                            }
+                        }
+                        if claimant == id
+                            && claim.get("operation") == proposed.get("operation")
+                            && claim.get("sourceVersion") == proposed.get("sourceVersion")
+                        {
+                            // Matching retries share the same source CAS. At
+                            // most one can commit; neither rolls back the other.
+                            return Ok(TitleClaim {
+                                path,
+                                version: version.clone(),
+                                document: claim.clone(),
+                                acquired: options.idempotency_key.is_none(),
+                            });
+                        }
+                    }
+                    return Err(api(
+                        409,
+                        "title_reservation_pending",
+                        "Dashboard title has an unfinished reservation whose source can still commit; retry the original request with its original idempotency key",
+                        json!({"title":title,"dashboardId":claimant.map(|id|id.to_string())}),
+                    ));
+                }
+                if state == Some("active") {
+                    if claimant == Some(id)
+                        && base.is_some_and(|stored| {
+                            stored.document.get("title").and_then(Value::as_str) == Some(title)
+                        })
+                    {
+                        return Ok(TitleClaim {
+                            path,
+                            version: version.clone(),
+                            document: claim.clone(),
+                            acquired: false,
+                        });
+                    }
+                    let claimant = claimant.ok_or_else(|| corrupt("title reservation owner"))?;
+                    match self.stored(claimant, tenant).await {
+                        Ok(stored)
+                            if !deleted(&stored.document)
+                                && stored.document.get("title").and_then(Value::as_str)
+                                    == Some(title) =>
+                        {
+                            return Err(api(
+                                409,
+                                "title_conflict",
+                                "Dashboard title must be unique",
+                                json!({"title":title}),
+                            ));
+                        }
+                        Ok(_) => {}
+                        Err(error) if is_not_found(&error) => {}
+                        Err(error) => return Err(error),
+                    }
+                } else if state != Some("released") {
+                    return Err(corrupt("title reservation state"));
+                }
+            }
+            // Released and stale-active reservations still need the same
+            // authoritative legacy check as an absent reservation.
+            if self
+                .legacy_title(title, tenant)
+                .await?
+                .is_some_and(|legacy_id| legacy_id != id)
+            {
+                return Err(api(
+                    409,
+                    "title_conflict",
+                    "Dashboard title must be unique",
+                    json!({"title":title}),
+                ));
+            }
+            let condition = existing
+                .map(|(_, version)| MetadataWriteCondition::Update(version))
+                .unwrap_or(MetadataWriteCondition::Create);
+            match self.write(&path, &proposed, condition, tenant).await {
+                Ok(version) => {
+                    return Ok(TitleClaim {
+                        path,
+                        version,
+                        document: proposed,
+                        acquired: options.idempotency_key.is_none(),
+                    });
+                }
+                Err(error) => {
+                    if let Some((ours, version)) = self.read(&path, tenant).await?
+                        && ours.get("dashboardId") == proposed.get("dashboardId")
+                        && ours.get("operation") == proposed.get("operation")
+                        && ours.get("sourceVersion") == proposed.get("sourceVersion")
+                        && matches!(
+                            ours.get("state").and_then(Value::as_str),
+                            Some("pending" | "active")
+                        )
+                    {
+                        let acquired =
+                            options.idempotency_key.is_none() && ours["state"] == "pending";
+                        return Ok(TitleClaim {
+                            path,
+                            version,
+                            document: ours,
+                            acquired,
+                        });
+                    }
+                    if is_conflict(&error) {
+                        continue;
+                    }
+                    return Err(error);
+                }
+            }
+        }
+        Err(api(
+            409,
+            "title_contention",
+            "Dashboard title changed repeatedly; retry with the same idempotency key",
+            json!({"title":title}),
+        ))
+    }
+
+    async fn activate_claim(&self, mut claim: TitleClaim, tenant: &Option<String>) {
+        if claim.document.get("state").and_then(Value::as_str) == Some("active") {
+            return;
+        }
+        claim.document["state"] = json!("active");
+        // A failed activation retains the pending claim. Its committed dashboard
+        // allows a subsequent claim/read to safely recover it.
+        if let Err(error) = self
+            .write(
+                &claim.path,
+                &claim.document,
+                MetadataWriteCondition::Update(claim.version),
+                tenant,
+            )
+            .await
+            && !is_conflict(&error)
+        {
+            tracing::warn!(%error,"Dashboard saved; title reservation activation needs recovery");
+        }
+    }
+
+    async fn release_claim(&self, claim: &TitleClaim, tenant: &Option<String>) {
+        if claim.acquired {
+            let released = json!({"state":"released"});
+            if let Err(error) = self
+                .write(
+                    &claim.path,
+                    &released,
+                    MetadataWriteCondition::Update(claim.version.clone()),
+                    tenant,
+                )
+                .await
+                && !is_conflict(&error)
+            {
+                tracing::warn!(%error,"Dashboard title rollback needs recovery");
+            }
+        }
+    }
+
+    async fn release_owned_title(&self, claim: TitleClaim, tenant: &Option<String>) {
+        // Exact reservation version prevents an old rename/delete cleanup from
+        // releasing a newer rename-back claim on this same dashboard ID.
+        let released = json!({"state":"released"});
+        if let Err(error) = self
+            .write(
+                &claim.path,
+                &released,
+                MetadataWriteCondition::Update(claim.version),
+                tenant,
+            )
+            .await
+            && !is_conflict(&error)
+        {
+            tracing::warn!(%error,"Dashboard saved; obsolete title cleanup needs recovery");
+        }
+    }
+}
+
+fn api(status: u16, code: &'static str, message: &str, details: Value) -> DashboardError {
+    DashboardError::api(status, code, message, details)
+}
+fn not_found() -> DashboardError {
+    api(
+        404,
+        "dashboard_not_found",
+        "Dashboard does not exist",
+        json!({}),
+    )
+}
+fn corrupt(what: &str) -> DashboardError {
+    api(
+        500,
+        "dashboard_metadata_invalid",
+        &format!("Invalid {what}"),
+        json!({}),
+    )
+}
+fn conflict(current: &str) -> DashboardError {
+    api(
+        412,
+        "revision_conflict",
+        "Dashboard changed; reload and retry",
+        json!({"currentRevision":current}),
+    )
+}
+fn is_conflict(error: &DashboardError) -> bool {
+    matches!(
+        error,
+        DashboardError::Api {
+            code: "storage_conflict",
+            ..
+        }
+    )
+}
+fn is_not_found(error: &DashboardError) -> bool {
+    matches!(error, DashboardError::Api { status: 404, .. })
+}
+fn storage_error(error: ConditionalMetadataError) -> DashboardError {
+    match error {
+        ConditionalMetadataError::Conflict => api(
+            409,
+            "storage_conflict",
+            "Dashboard storage precondition failed",
+            json!({}),
+        ),
+        ConditionalMetadataError::Unsupported(message) => {
+            api(501, "conditional_storage_unsupported", &message, json!({}))
+        }
+        ConditionalMetadataError::Storage(error) => DashboardError::ObjectStorage(error),
+    }
+}
+fn validate_scope(tenant: &Option<String>, owner: Option<&str>) -> Result<(), DashboardError> {
+    for value in tenant.iter().map(String::as_str).chain(owner) {
+        if value.is_empty() || value == "." || value == ".." || value.contains(['/', '\\', '\0']) {
+            return Err(api(
+                400,
+                "invalid_dashboard_scope",
+                "Invalid dashboard tenant or owner",
+                json!({}),
+            ));
+        }
+    }
+    Ok(())
+}
+fn validate_options(options: &DashboardWriteOptions) -> Result<(), DashboardError> {
+    if let Some(expected) = options.expected_revision.as_deref() {
+        normalize_revision(expected)?;
+    }
+
+    if options
+        .idempotency_key
+        .as_ref()
+        .is_some_and(|key| key.is_empty() || key.len() > 256)
+    {
+        return Err(api(
+            400,
+            "invalid_idempotency_key",
+            "Idempotency key must contain 1 to 256 bytes",
+            json!({}),
+        ));
+    }
+    Ok(())
+}
+fn require_object(value: &Value) -> Result<(), DashboardError> {
+    if !value.is_object() {
+        return Err(api(
+            400,
+            "invalid_dashboard",
+            "Dashboard must be an object",
+            json!({}),
+        ));
+    }
+    Ok(())
+}
+fn reject_internal(value: &Value) -> Result<(), DashboardError> {
+    if value.as_object().is_some_and(|object| {
+        object.keys().any(|key| {
+            key.chars()
+                .filter(|ch| *ch != '_' && *ch != '-')
+                .flat_map(char::to_lowercase)
+                .collect::<String>()
+                == "parseabledashboard"
+        })
+    }) {
+        return Err(api(
+            400,
+            "protected_dashboard_metadata",
+            "Internal dashboard metadata cannot be supplied",
+            json!({}),
+        ));
+    }
+    Ok(())
+}
+fn scope_path(tenant: &Option<String>, suffix: &str) -> String {
+    match tenant {
+        Some(tenant) => format!("{tenant}/{USERS_ROOT_DIR}/{suffix}"),
+        None => format!("{USERS_ROOT_DIR}/{suffix}"),
+    }
+}
+fn dashboard_path(tenant: &Option<String>, owner: &str, id: Ulid) -> String {
+    scope_path(tenant, &format!("{owner}/{DASHBOARDS_DIR}/{id}.json"))
+}
+fn locator_path(tenant: &Option<String>, id: Ulid) -> String {
+    scope_path(tenant, &format!(".dashboard-locations/{id}.json"))
+}
+fn title_path(tenant: &Option<String>, title: &str) -> String {
+    scope_path(
+        tenant,
+        &format!(".dashboard-titles/{}.json", fingerprint(&json!(title))),
+    )
+}
+fn has_nonce(document: &Value, nonce: &str) -> bool {
+    document
+        .pointer("/_parseableDashboard/revision")
+        .and_then(Value::as_str)
+        == Some(nonce)
+}
+fn advance_nonce(document: &mut Value) {
+    let nonce = Ulid::new().to_string();
+    let content_revision = revision_with_nonce(document, Some(&nonce));
+    if !document.get(INTERNAL).is_some_and(Value::is_object) {
+        document[INTERNAL] = json!({});
+    }
+    document[INTERNAL]["revision"] = json!(nonce);
+    document[INTERNAL]["contentRevision"] = json!(content_revision);
+}
+
+fn pending_source_obsolete(claim: &Value, current: Option<&StoredDashboard>) -> bool {
+    current.is_some_and(|stored| deleted(&stored.document))
+        || match claim.get("sourceVersion") {
+            Some(Value::Null) => current.is_some(),
+            Some(source) => {
+                current
+                    .map(|stored| metadata_version_json(&stored.version))
+                    .as_ref()
+                    != Some(source)
+            }
+            None => false,
+        }
+}
+
+fn metadata_version_json(version: &MetadataVersion) -> Value {
+    json!({"eTag":version.e_tag,"version":version.version})
+}
+
+fn fingerprint(value: &Value) -> String {
+    // serde_json maps are ordered in this build. Explicit recursion also keeps
+    // hashes stable if the preserve_order feature is enabled by another crate.
+    fn canonical(value: &Value) -> Value {
+        match value {
+            Value::Object(object) => {
+                let sorted: std::collections::BTreeMap<_, _> = object
+                    .iter()
+                    .map(|(key, value)| (key.clone(), canonical(value)))
+                    .collect();
+                serde_json::to_value(sorted).expect("JSON map serializes")
+            }
+            Value::Array(values) => Value::Array(values.iter().map(canonical).collect()),
+            value => value.clone(),
+        }
+    }
+    hex::encode(Sha256::digest(
+        serde_json::to_vec(&canonical(value)).expect("JSON value serializes"),
+    ))
+}
+fn revision(document: &Value) -> String {
+    revision_with_nonce(
+        document,
+        document
+            .pointer("/_parseableDashboard/revision")
+            .and_then(Value::as_str),
+    )
+}
+fn revision_with_nonce(document: &Value, nonce: Option<&str>) -> String {
+    let mut content = document.clone();
+    if let Some(object) = content.as_object_mut() {
+        object.remove(INTERNAL);
+        object.remove("revision");
+    }
+    // Hash the actual public content too: an older/external node can preserve
+    // our nonce while changing a layout, and must still invalidate If-Match.
+    fingerprint(&json!({"document":content,"nonce":nonce}))
+}
+
+fn public_document(document: &Value, revision: &str) -> Value {
+    let mut public = document.clone();
+    if let Some(object) = public.as_object_mut() {
+        object.remove(INTERNAL);
+        object.insert("revision".into(), json!(revision));
+    }
+    public
+}
+fn deleted(document: &Value) -> bool {
+    document
+        .pointer("/_parseableDashboard/tombstone")
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+}
+fn title(document: &Value) -> Result<&str, DashboardError> {
+    document
+        .get("title")
+        .and_then(Value::as_str)
+        .ok_or_else(|| {
+            api(
+                400,
+                "invalid_title",
+                "Dashboard title must be a string",
+                json!({}),
+            )
+        })
+}
+fn authorize(actor: &DashboardActor, document: &Value) -> Result<(), DashboardError> {
+    if !actor.is_admin && document.get("author").and_then(Value::as_str) != Some(&actor.user_id) {
+        return Err(api(
+            403,
+            "dashboard_forbidden",
+            "Dashboard can only be changed by its owner or an administrator",
+            json!({}),
+        ));
+    }
+    Ok(())
+}
+/// Accept exactly one strong HTTP ETag, or the raw hexadecimal token returned
+/// in legacy JSON bodies. ETag lists, weak validators and wildcards do not
+/// identify one observed dashboard version and are rejected before replay/I/O.
+fn normalize_revision(expected: &str) -> Result<&str, DashboardError> {
+    let expected = expected.trim();
+    if expected.starts_with('"') && expected.ends_with('"') && expected.len() >= 2 {
+        let token = &expected[1..expected.len() - 1];
+        if token
+            .bytes()
+            .all(|byte| byte == 0x21 || (0x23..=0x7e).contains(&byte))
+        {
+            return Ok(token);
+        }
+    } else if expected.len() == 64 && expected.bytes().all(|byte| byte.is_ascii_hexdigit()) {
+        return Ok(expected);
+    }
+    Err(api(
+        400,
+        "invalid_dashboard_revision",
+        "Expected exactly one strong quoted ETag or raw dashboard revision hash",
+        json!({}),
+    ))
+}
+fn check_revision(options: &DashboardWriteOptions, actual: &str) -> Result<(), DashboardError> {
+    if let Some(expected) = options.expected_revision.as_deref()
+        && normalize_revision(expected)? != actual
+    {
+        return Err(conflict(actual));
+    }
+    Ok(())
+}
+
+fn receipt_key(actor: &DashboardActor, key: &str) -> String {
+    fingerprint(&json!([actor.user_id, key]))
+}
+fn replay(
+    document: &Value,
+    current_revision: &str,
+    actor: &DashboardActor,
+    options: &DashboardWriteOptions,
+    request_hash: &str,
+    deleted_ok: bool,
+) -> Result<Option<Value>, DashboardError> {
+    let Some(key) = &options.idempotency_key else {
+        return Ok(None);
+    };
+    let key = receipt_key(actor, key);
+    let create = document
+        .pointer("/_parseableDashboard/createReceipt")
+        .filter(|receipt| !receipt.is_null());
+    let recent = document
+        .pointer("/_parseableDashboard/receipts")
+        .and_then(Value::as_array);
+    for receipt in create.into_iter().chain(recent.into_iter().flatten()) {
+        if receipt.get("key").and_then(Value::as_str) != Some(&key) {
+            continue;
+        }
+        if receipt.get("requestHash").and_then(Value::as_str) != Some(request_hash) {
+            return Err(api(
+                409,
+                "idempotency_conflict",
+                "Idempotency key was already used for different arguments",
+                json!({}),
+            ));
+        }
+        if deleted(document) {
+            let details = json!({"dashboardId":document.get("dashboardId"),"revision":current_revision,"appliedRevision":receipt.get("revision"),"replayed":true,"deleted":true});
+            if !deleted_ok {
+                return Err(api(
+                    410,
+                    "resource_deleted",
+                    "The original operation was applied, but its dashboard has since been deleted",
+                    details,
+                ));
+            }
+            return Ok(Some(details));
+        }
+        return Ok(Some(
+            json!({"dashboard":public_document(document,current_revision),"revision":current_revision,"appliedRevision":receipt.get("revision"),"replayed":true,"validation":{"valid":true,"errors":[],"warnings":[]},"diff":[]}),
+        ));
+    }
+    Ok(None)
+}
+fn stamp(
+    document: &mut Value,
+    next_revision: &str,
+    tombstone: bool,
+    actor: &DashboardActor,
+    options: &DashboardWriteOptions,
+    request_hash: &str,
+    create: bool,
+) {
+    let applied_revision = revision_with_nonce(document, Some(next_revision));
+    let mut create_receipt = document
+        .pointer("/_parseableDashboard/createReceipt")
+        .cloned()
+        .unwrap_or(Value::Null);
+    let mut receipts = document
+        .pointer("/_parseableDashboard/receipts")
+        .and_then(Value::as_array)
+        .cloned()
+        .unwrap_or_default();
+    if let Some(key) = &options.idempotency_key {
+        let receipt = json!({"key":receipt_key(actor,key),"requestHash":request_hash,"revision":applied_revision});
+        if create {
+            create_receipt = receipt;
+        } else {
+            receipts.push(receipt);
+            if receipts.len() > RECEIPT_LIMIT {
+                receipts.drain(..receipts.len() - RECEIPT_LIMIT);
+            }
+        }
+    }
+    document[INTERNAL] = json!({"revision":next_revision,"contentRevision":applied_revision,"tombstone":tombstone,"createReceipt":create_receipt,"receipts":receipts});
+}
+fn compact_tombstone(base: &Value) -> Value {
+    let mut compact = serde_json::Map::new();
+    for field in [
+        "author",
+        "dashboardId",
+        "tenantId",
+        "title",
+        "version",
+        "created",
+        "modified",
+        INTERNAL,
+    ] {
+        if let Some(value) = base.get(field) {
+            compact.insert(field.to_owned(), value.clone());
+        }
+    }
+    Value::Object(compact)
+}
+
+fn mutation_request(mutation: &DashboardMutation) -> Result<Value, DashboardError> {
+    Ok(match mutation {
+        DashboardMutation::Replace(value) => json!({"operation":"replace","document":value}),
+        DashboardMutation::Metadata(metadata) => {
+            json!({"operation":"metadata","metadata":metadata})
+        }
+        DashboardMutation::AddTile(tile) => json!({"operation":"addTile","tile":tile}),
+        DashboardMutation::Patch(operations) => {
+            json!({"operation":"patch","operations":serde_json::to_value(operations)?})
+        }
+    })
+}
+fn apply_metadata(
+    base: &Value,
+    metadata: &HashMap<String, String>,
+) -> Result<Value, DashboardError> {
+    let mut candidate = base.clone();
+    for (key, value) in metadata {
+        match key.as_str() {
+            "isFavorite" => {
+                candidate["isFavorite"] = json!(match value.as_str() {
+                    "true" => true,
+                    "false" => false,
+                    _ =>
+                        return Err(api(
+                            400,
+                            "invalid_favorite",
+                            "isFavorite must be true or false",
+                            json!({})
+                        )),
+                });
+            }
+            "tags" => {
+                candidate["tags"] = json!(
+                    value
+                        .split(',')
+                        .map(str::trim)
+                        .filter(|tag| !tag.is_empty())
+                        .collect::<Vec<_>>()
+                );
+            }
+            "renameTo" => {
+                candidate["title"] = json!(value.trim());
+            }
+            _ => {
+                return Err(api(
+                    400,
+                    "invalid_metadata_field",
+                    "Unsupported dashboard metadata parameter",
+                    json!({"field":key}),
+                ));
+            }
+        }
+    }
+    Ok(candidate)
+}
+fn add_tile(base: &Value, tile: &Value) -> Result<Value, DashboardError> {
+    require_object(tile)?;
+    let id = tile
+        .get("tile_id")
+        .and_then(Value::as_str)
+        .filter(|id| Ulid::from_string(id).is_ok())
+        .ok_or_else(|| {
+            api(
+                400,
+                "invalid_tile_id",
+                "Tile ID must be a valid ULID",
+                json!({}),
+            )
+        })?;
+    let mut candidate = base.clone();
+    if candidate.get("tiles").is_none_or(Value::is_null) {
+        candidate["tiles"] = json!([]);
+    }
+    let tiles = candidate
+        .get_mut("tiles")
+        .and_then(Value::as_array_mut)
+        .ok_or_else(|| {
+            api(
+                400,
+                "invalid_tiles",
+                "Dashboard tiles must be an array",
+                json!({}),
+            )
+        })?;
+    if tiles
+        .iter()
+        .any(|tile| tile.get("tile_id").and_then(Value::as_str) == Some(id))
+    {
+        return Err(api(
+            409,
+            "tile_conflict",
+            "Tile already exists",
+            json!({"tileId":id}),
+        ));
+    }
+    tiles.push(tile.clone());
+    Ok(candidate)
+}
+fn apply_patch_candidate(
+    base: &Value,
+    operations: &[DashboardOperation],
+) -> Result<Value, DashboardError> {
+    apply_patch(base, operations).map_err(|error| {
+        api(
+            400,
+            "invalid_dashboard_patch",
+            &error.to_string(),
+            serde_json::to_value(&error).unwrap_or(Value::Null),
+        )
+    })
+}
+fn legacy_defaults(document: &mut Value) {
+    for (key, default) in [
+        ("tiles", json!([])),
+        ("dashboardType", json!("Dashboard")),
+        ("isFavorite", json!(false)),
+    ] {
+        if document.get(key).is_none_or(Value::is_null) {
+            document[key] = default;
+        }
+    }
+}
+
+impl ValidationMode {
+    fn request_hash(self, request: &Value) -> String {
+        match self {
+            Self::Strict => fingerprint(request),
+            // A legacy receipt must never let a tool replay an input that has
+            // not passed strict validation, even if the caller reuses its key.
+            Self::LegacyRest => fingerprint(&json!({"validation":"legacyRest","request":request})),
+        }
+    }
+
+    fn validate(self, candidate: &Value, base: Option<&Value>) -> Result<Value, DashboardError> {
+        match self {
+            Self::Strict => validate_candidate(candidate, base),
+            Self::LegacyRest => {
+                // The original typed contract allows arbitrary flattened fields.
+                // Do not apply editor-specific chart/layout/query rules here.
+                let document: Dashboard = serde_json::from_value(candidate.clone())?;
+                let mut ids = std::collections::HashSet::new();
+                for tile in document.tiles.iter().flatten() {
+                    if tile.tile_id.is_nil() {
+                        return Err(DashboardError::Metadata("Tile ID must be provided"));
+                    }
+                    if !ids.insert(tile.tile_id) {
+                        return Err(DashboardError::Metadata("Tile IDs must be unique"));
+                    }
+                }
+                // Internal fields are rejected on input and restored from the
+                // authoritative base before this check, in both modes.
+                if candidate.get(INTERNAL) != base.and_then(|base| base.get(INTERNAL)) {
+                    return Err(api(
+                        400,
+                        "protected_dashboard_metadata",
+                        "Internal dashboard metadata cannot be changed",
+                        json!({}),
+                    ));
+                }
+                Ok(json!({"valid":true,"errors":[],"warnings":[]}))
+            }
+        }
+    }
+}
+
+fn validate_candidate(candidate: &Value, base: Option<&Value>) -> Result<Value, DashboardError> {
+    let report = validate_dashboard(candidate, base);
+    let value = serde_json::to_value(&report)?;
+    if !report.valid {
+        return Err(api(
+            422,
+            "dashboard_validation_failed",
+            "Dashboard configuration is invalid",
+            value,
+        ));
+    }
+    Ok(value)
+}
+fn document_diff(base: &Value, candidate: &Value) -> Value {
+    fn walk(base: &Value, candidate: &Value, path: &str, changes: &mut Vec<Value>) {
+        if base == candidate {
+            return;
+        }
+        if let (Some(left), Some(right)) = (base.as_object(), candidate.as_object()) {
+            let keys: std::collections::BTreeSet<_> = left.keys().chain(right.keys()).collect();
+            for key in keys {
+                let pointer = format!("{path}/{}", key.replace('~', "~0").replace('/', "~1"));
+                match (left.get(key), right.get(key)) {
+                    (Some(before), Some(after)) => walk(before, after, &pointer, changes),
+                    (None, Some(after)) => {
+                        changes.push(json!({"op":"add","path":pointer,"value":after}))
+                    }
+                    (Some(before), None) => {
+                        changes.push(json!({"op":"remove","path":pointer,"previous":before}))
+                    }
+                    _ => {}
+                }
+            }
+        } else {
+            changes.push(json!({"op":"replace","path":path,"previous":base,"value":candidate}));
+        }
+    }
+    let mut changes = Vec::new();
+    walk(base, candidate, "", &mut changes);
+    json!(changes)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{
+        metastore::metastores::object_store_metastore::ObjectStoreMetastore, storage::LocalFS,
+    };
+
+    use crate::{
+        parseable::LogStream,
+        storage::{ObjectStorage, ObjectStorageError},
+    };
+    use datafusion::datasource::listing::ListingTableUrl;
+    use object_store::{ListResult, ObjectMeta, buffered::BufReader};
+    use relative_path::{RelativePath, RelativePathBuf};
+    use std::{
+        collections::HashSet,
+        path::{Path, PathBuf},
+        sync::atomic::{AtomicBool, AtomicUsize, Ordering},
+    };
+
+    /// Pause one node immediately before its conditional document write while
+    /// a second independent node can continue to read/write the shared store.
+    #[derive(Debug, Clone, Copy)]
+    enum FaultKind {
+        BeforeStorage,
+        AfterConflict,
+        AfterStorage,
+        AfterConcurrentEdit,
+    }
+    #[derive(Debug)]
+    struct WriteFault {
+        path_contains: String,
+        kind: FaultKind,
+    }
+
+    #[derive(Debug)]
+    struct PausedStorage {
+        inner: LocalFS,
+        pause_path: String,
+        armed: AtomicBool,
+        scans: AtomicUsize,
+        fault: std::sync::Mutex<Option<WriteFault>>,
+        entered: tokio::sync::Notify,
+        released: tokio::sync::Notify,
+    }
+    impl PausedStorage {
+        fn new(root: &Path, pause_path: String) -> Self {
+            Self {
+                inner: LocalFS::new(root.to_path_buf()),
+                pause_path,
+                armed: AtomicBool::new(true),
+                scans: AtomicUsize::new(0),
+                fault: Default::default(),
+                entered: Default::default(),
+                released: Default::default(),
+            }
+        }
+    }
+    #[async_trait::async_trait]
+    impl ObjectStorage for PausedStorage {
+        async fn get_metadata_versioned(
+            &self,
+            path: &RelativePath,
+            tenant: &Option<String>,
+        ) -> Result<Option<VersionedMetadata>, ConditionalMetadataError> {
+            self.inner.get_metadata_versioned(path, tenant).await
+        }
+        async fn put_metadata_conditional(
+            &self,
+            path: &RelativePath,
+            bytes: Bytes,
+            condition: MetadataWriteCondition,
+            tenant: &Option<String>,
+        ) -> Result<MetadataVersion, ConditionalMetadataError> {
+            if (path.as_str() == self.pause_path
+                || (self.pause_path.is_empty() && path.as_str().contains("/dashboards/")))
+                && self.armed.swap(false, Ordering::SeqCst)
+            {
+                self.entered.notify_one();
+                self.released.notified().await;
+            }
+            let fault = {
+                let mut armed = self.fault.lock().unwrap();
+                if armed
+                    .as_ref()
+                    .is_some_and(|fault| path.as_str().contains(&fault.path_contains))
+                {
+                    armed.take()
+                } else {
+                    None
+                }
+            };
+            if matches!(
+                fault.as_ref().map(|fault| fault.kind),
+                Some(FaultKind::BeforeStorage)
+            ) {
+                return Err(ObjectStorageError::Custom(
+                    "injected precommit transport error".into(),
+                )
+                .into());
+            }
+            let version = self
+                .inner
+                .put_metadata_conditional(path, bytes, condition, tenant)
+                .await?;
+            if let Some(fault) = fault {
+                if matches!(fault.kind, FaultKind::AfterConcurrentEdit) {
+                    let current = self
+                        .inner
+                        .get_metadata_versioned(path, tenant)
+                        .await?
+                        .unwrap();
+                    let mut document: Value = serde_json::from_slice(&current.bytes).unwrap();
+                    document["anotherWriterChangedThis"] = json!(true);
+                    advance_nonce(&mut document);
+                    self.inner
+                        .put_metadata_conditional(
+                            path,
+                            Bytes::from(serde_json::to_vec(&document).unwrap()),
+                            MetadataWriteCondition::Update(current.version),
+                            tenant,
+                        )
+                        .await?;
+                }
+                return Err(match fault.kind {
+                    FaultKind::AfterConflict => ConditionalMetadataError::Conflict,
+                    _ => ObjectStorageError::Custom("injected postcommit transport error".into())
+                        .into(),
+                });
+            }
+            Ok(version)
+        }
+        async fn get_buffered_reader(
+            &self,
+            path: &RelativePath,
+            tenant_id: &Option<String>,
+        ) -> Result<BufReader, ObjectStorageError> {
+            self.inner.get_buffered_reader(path, tenant_id).await
+        }
+        async fn head(
+            &self,
+            path: &RelativePath,
+            tenant_id: &Option<String>,
+        ) -> Result<ObjectMeta, ObjectStorageError> {
+            self.inner.head(path, tenant_id).await
+        }
+        async fn parallel_chunked_download(
+            &self,
+            path: &RelativePath,
+            tenant_id: &Option<String>,
+            write_path: PathBuf,
+        ) -> Result<(), ObjectStorageError> {
+            self.inner
+                .parallel_chunked_download(path, tenant_id, write_path)
+                .await
+        }
+        async fn get_object(
+            &self,
+            path: &RelativePath,
+            tenant_id: &Option<String>,
+        ) -> Result<Bytes, ObjectStorageError> {
+            self.inner.get_object(path, tenant_id).await
+        }
+        async fn get_object_ranged(
+            &self,
+            path: &RelativePath,
+            tenant_id: &Option<String>,
+        ) -> Result<Bytes, ObjectStorageError> {
+            self.inner.get_object_ranged(path, tenant_id).await
+        }
+        async fn get_objects(
+            &self,
+            base_path: Option<&RelativePath>,
+            filter_fun: Box<dyn Fn(String) -> bool + Send>,
+            tenant_id: &Option<String>,
+        ) -> Result<Vec<Bytes>, ObjectStorageError> {
+            self.scans.fetch_add(1, Ordering::SeqCst);
+            self.inner
+                .get_objects(base_path, filter_fun, tenant_id)
+                .await
+        }
+        async fn upload_multipart(
+            &self,
+            key: &RelativePath,
+            path: &Path,
+            tenant_id: &Option<String>,
+        ) -> Result<(), ObjectStorageError> {
+            self.inner.upload_multipart(key, path, tenant_id).await
+        }
+        async fn put_object(
+            &self,
+            path: &RelativePath,
+            resource: Bytes,
+            tenant_id: &Option<String>,
+        ) -> Result<(), ObjectStorageError> {
+            self.inner.put_object(path, resource, tenant_id).await
+        }
+        async fn delete_prefix(
+            &self,
+            path: &RelativePath,
+            tenant_id: &Option<String>,
+        ) -> Result<(), ObjectStorageError> {
+            self.inner.delete_prefix(path, tenant_id).await
+        }
+        async fn check(&self, tenant_id: &Option<String>) -> Result<(), ObjectStorageError> {
+            self.inner.check(tenant_id).await
+        }
+        async fn delete_stream(
+            &self,
+            stream_name: &str,
+            tenant_id: &Option<String>,
+        ) -> Result<(), ObjectStorageError> {
+            self.inner.delete_stream(stream_name, tenant_id).await
+        }
+        async fn list_streams(&self) -> Result<HashSet<LogStream>, ObjectStorageError> {
+            self.inner.list_streams().await
+        }
+        async fn list_old_streams(&self) -> Result<HashSet<LogStream>, ObjectStorageError> {
+            self.inner.list_old_streams().await
+        }
+        async fn list_dirs(
+            &self,
+            tenant_id: &Option<String>,
+        ) -> Result<Vec<String>, ObjectStorageError> {
+            self.inner.list_dirs(tenant_id).await
+        }
+        async fn list_dirs_relative(
+            &self,
+            relative_path: &RelativePath,
+            tenant_id: &Option<String>,
+        ) -> Result<Vec<String>, ObjectStorageError> {
+            self.inner
+                .list_dirs_relative(relative_path, tenant_id)
+                .await
+        }
+        async fn list_dates(
+            &self,
+            stream_name: &str,
+            tenant_id: &Option<String>,
+        ) -> Result<Vec<String>, ObjectStorageError> {
+            self.inner.list_dates(stream_name, tenant_id).await
+        }
+        async fn list_hours(
+            &self,
+            stream_name: &str,
+            date: &str,
+            tenant_id: &Option<String>,
+        ) -> Result<Vec<String>, ObjectStorageError> {
+            self.inner.list_hours(stream_name, date, tenant_id).await
+        }
+        async fn list_minutes(
+            &self,
+            stream_name: &str,
+            date: &str,
+            hour: &str,
+            tenant_id: &Option<String>,
+        ) -> Result<Vec<String>, ObjectStorageError> {
+            self.inner
+                .list_minutes(stream_name, date, hour, tenant_id)
+                .await
+        }
+        async fn upload_file(
+            &self,
+            key: &str,
+            path: &Path,
+            tenant_id: &Option<String>,
+        ) -> Result<(), ObjectStorageError> {
+            self.inner.upload_file(key, path, tenant_id).await
+        }
+        async fn delete_object(
+            &self,
+            path: &RelativePath,
+            tenant_id: &Option<String>,
+        ) -> Result<(), ObjectStorageError> {
+            self.inner.delete_object(path, tenant_id).await
+        }
+        async fn get_ingestor_meta_file_paths(
+            &self,
+            tenant_id: &Option<String>,
+        ) -> Result<Vec<RelativePathBuf>, ObjectStorageError> {
+            self.inner.get_ingestor_meta_file_paths(tenant_id).await
+        }
+        async fn try_delete_node_meta(
+            &self,
+            node_filename: String,
+            tenant_id: &Option<String>,
+        ) -> Result<(), ObjectStorageError> {
+            self.inner
+                .try_delete_node_meta(node_filename, tenant_id)
+                .await
+        }
+        fn query_prefixes(&self, prefixes: Vec<String>) -> Vec<ListingTableUrl> {
+            self.inner.query_prefixes(prefixes)
+        }
+        fn absolute_url(&self, prefix: &RelativePath) -> object_store::path::Path {
+            self.inner.absolute_url(prefix)
+        }
+        fn store_url(&self) -> url::Url {
+            self.inner.store_url()
+        }
+        async fn list_with_delimiter(
+            &self,
+            prefix: Option<object_store::path::Path>,
+        ) -> Result<ListResult, ObjectStorageError> {
+            self.inner.list_with_delimiter(prefix).await
+        }
+        fn get_bucket_name(&self) -> String {
+            self.inner.get_bucket_name()
+        }
+    }
+
+    fn actor() -> DashboardActor {
+        DashboardActor {
+            user_id: "owner-hash".into(),
+            is_admin: false,
+        }
+    }
+    fn services(root: &std::path::Path) -> (Arc<DashboardService>, Arc<DashboardService>) {
+        let make = || {
+            Arc::new(DashboardService::new(Arc::new(ObjectStoreMetastore {
+                storage: Arc::new(LocalFS::new(root.to_path_buf())),
+            })))
+        };
+        (make(), make())
+    }
+    fn options(revision: &str, key: Option<&str>) -> DashboardWriteOptions {
+        DashboardWriteOptions {
+            expected_revision: Some(revision.into()),
+            idempotency_key: key.map(str::to_owned),
+            dry_run: false,
+        }
+    }
+    fn id(result: &Value) -> Ulid {
+        Ulid::from_string(result["dashboard"]["dashboardId"].as_str().unwrap()).unwrap()
+    }
+    fn revision_of(result: &Value) -> &str {
+        result["revision"].as_str().unwrap()
+    }
+    fn metadata(value: bool) -> DashboardMutation {
+        DashboardMutation::Metadata(HashMap::from([("isFavorite".into(), value.to_string())]))
+    }
+    fn operation(path: &str, value: Value) -> DashboardOperation {
+        serde_json::from_value(
+            json!({"op":"add","target":{"type":"dashboard"},"path":path,"value":value}),
+        )
+        .unwrap()
+    }
+
+    #[tokio::test]
+    async fn legacy_rest_accepts_flattened_config_while_agent_mutations_stay_strict() {
+        let directory = tempfile::tempdir().unwrap();
+        let (service, _) = services(directory.path());
+        let owner = actor();
+        let tile_id = Ulid::new().to_string();
+        let tile = json!({"tile_id":tile_id,"tileType":"ai","chartType":{"future":true},
+            "layout":{"x":-99,"h":"auto"},"config":{"arbitrary":[false,7]}});
+        let document = json!({"title":"Legacy arbitrary config","tiles":[tile],
+            "refreshInterval":"custom","variables":{"extension":true},
+            "author":"forged","tenantId":"forged","dashboardId":Ulid::new().to_string(),
+            "opaque":{"keep":true}});
+        assert!(matches!(
+            service
+                .create_json(&owner, &None, document.clone(), &Default::default())
+                .await,
+            Err(DashboardError::Api { status: 422, .. })
+        ));
+        let created = service
+            .create_legacy_json(
+                &owner,
+                &None,
+                serde_json::from_value(document).unwrap(),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let dashboard_id = id(&created);
+        assert_eq!(created["dashboard"]["tiles"][0], tile);
+        assert_eq!(created["dashboard"]["author"], owner.user_id);
+        assert_eq!(created["dashboard"]["tenantId"], Value::Null);
+        let mut replacement = created["dashboard"].clone();
+        replacement["tiles"][0]["config"] = json!({"changed":[1,2,3]});
+        replacement["author"] = json!("forged-again");
+        replacement["dashboardId"] = json!(Ulid::new().to_string());
+        replacement["created"] = json!("2000-01-01T00:00:00Z");
+        let replaced = service
+            .mutate_legacy_json(
+                &owner,
+                dashboard_id,
+                &None,
+                DashboardMutation::Replace(replacement),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(
+            replaced["dashboard"]["tiles"][0]["config"],
+            json!({"changed":[1,2,3]})
+        );
+        for key in [
+            "author",
+            "dashboardId",
+            "created",
+            "version",
+            "tenantId",
+            "opaque",
+        ] {
+            assert_eq!(
+                replaced["dashboard"][key], created["dashboard"][key],
+                "{key}"
+            );
+        }
+        let mut second_tile = tile.clone();
+        second_tile["tile_id"] = json!(Ulid::new().to_string());
+        let added = service
+            .mutate_legacy_json(
+                &owner,
+                dashboard_id,
+                &None,
+                DashboardMutation::AddTile(second_tile.clone()),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(added["dashboard"]["tiles"][1], second_tile);
+        let mut strict_replacement = added["dashboard"].clone();
+        strict_replacement["tiles"][0]["tileType"] = json!("new-unsupported-type");
+        let mut third_tile = tile.clone();
+        third_tile["tile_id"] = json!(Ulid::new().to_string());
+        let patch: DashboardOperation = serde_json::from_value(json!({"op":"replace",
+            "target":{"type":"tile","id":tile_id},"path":"/tileType","value":"new-unsupported-type"})).unwrap();
+        for mutation in [
+            DashboardMutation::Replace(strict_replacement),
+            DashboardMutation::AddTile(third_tile),
+            DashboardMutation::Patch(vec![patch]),
+        ] {
+            assert!(matches!(
+                service
+                    .mutate_json(
+                        &owner,
+                        dashboard_id,
+                        &None,
+                        mutation,
+                        &options(revision_of(&added), None)
+                    )
+                    .await,
+                Err(DashboardError::Api { status: 422, .. })
+            ));
+        }
+        // Even an accidentally routed PATCH cannot select legacy validation.
+        let patch: DashboardOperation = serde_json::from_value(json!({"op":"replace",
+            "target":{"type":"tile","id":tile_id},"path":"/tileType","value":"new-unsupported-type"})).unwrap();
+        assert!(matches!(
+            service
+                .mutate_legacy_json(
+                    &owner,
+                    dashboard_id,
+                    &None,
+                    DashboardMutation::Patch(vec![patch]),
+                    &options(revision_of(&added), None)
+                )
+                .await,
+            Err(DashboardError::Api { status: 422, .. })
+        ));
+        assert_eq!(
+            service.get_json(dashboard_id, &None).await.unwrap(),
+            added["dashboard"]
+        );
+
+        let stranger = DashboardActor {
+            user_id: "stranger".into(),
+            is_admin: false,
+        };
+        assert!(matches!(
+            service
+                .mutate_legacy_json(
+                    &stranger,
+                    dashboard_id,
+                    &None,
+                    metadata(true),
+                    &Default::default()
+                )
+                .await,
+            Err(DashboardError::Api { status: 403, .. })
+        ));
+        assert!(matches!(
+            service
+                .mutate_legacy_json(
+                    &owner,
+                    dashboard_id,
+                    &None,
+                    metadata(true),
+                    &options(revision_of(&created), None)
+                )
+                .await,
+            Err(DashboardError::Api { status: 412, .. })
+        ));
+        let mut internal = added["dashboard"].clone();
+        internal[INTERNAL] = json!({"tombstone":true});
+        assert!(matches!(
+            service
+                .mutate_legacy_json(
+                    &owner,
+                    dashboard_id,
+                    &None,
+                    DashboardMutation::Replace(internal),
+                    &options(revision_of(&added), None)
+                )
+                .await,
+            Err(DashboardError::Api {
+                status: 400,
+                code: "protected_dashboard_metadata",
+                ..
+            })
+        ));
+    }
+
+    #[tokio::test]
+    async fn legacy_receipts_cannot_bypass_strict_validation_on_replay() {
+        let directory = tempfile::tempdir().unwrap();
+        let (service, _) = services(directory.path());
+        let owner = actor();
+        let document: Dashboard = serde_json::from_value(json!({"title":"Legacy keyed",
+            "tiles":[{"tile_id":Ulid::new().to_string(),"tileType":"ai"}]}))
+        .unwrap();
+        let create_options = DashboardWriteOptions {
+            idempotency_key: Some("create-key".into()),
+            ..Default::default()
+        };
+        let created = service
+            .create_legacy_json(&owner, &None, document.clone(), &create_options)
+            .await
+            .unwrap();
+        let replayed = service
+            .create_legacy_json(&owner, &None, document.clone(), &create_options)
+            .await
+            .unwrap();
+        assert_eq!(replayed["dashboard"], created["dashboard"]);
+        assert!(matches!(
+            service
+                .create_json(
+                    &owner,
+                    &None,
+                    serde_json::to_value(document).unwrap(),
+                    &create_options
+                )
+                .await,
+            Err(DashboardError::Api {
+                status: 409,
+                code: "idempotency_conflict",
+                ..
+            })
+        ));
+        let dashboard_id = id(&created);
+        let tile = json!({"tile_id":Ulid::new().to_string(),"tileType":"ai"});
+        let write_options = options(revision_of(&created), Some("add-key"));
+        let added = service
+            .mutate_legacy_json(
+                &owner,
+                dashboard_id,
+                &None,
+                DashboardMutation::AddTile(tile.clone()),
+                &write_options,
+            )
+            .await
+            .unwrap();
+        let replayed = service
+            .mutate_legacy_json(
+                &owner,
+                dashboard_id,
+                &None,
+                DashboardMutation::AddTile(tile.clone()),
+                &write_options,
+            )
+            .await
+            .unwrap();
+        assert_eq!(replayed["dashboard"], added["dashboard"]);
+        assert!(matches!(
+            service
+                .mutate_json(
+                    &owner,
+                    dashboard_id,
+                    &None,
+                    DashboardMutation::AddTile(tile),
+                    &write_options
+                )
+                .await,
+            Err(DashboardError::Api {
+                status: 409,
+                code: "idempotency_conflict",
+                ..
+            })
+        ));
+    }
+
+    #[tokio::test]
+    async fn legacy_rest_still_requires_typed_fields_and_unique_non_nil_tile_ids() {
+        let directory = tempfile::tempdir().unwrap();
+        let (service, _) = services(directory.path());
+        let owner = actor();
+        let tile_id = Ulid::new().to_string();
+        for tiles in [
+            json!([{"tile_id":Ulid::nil().to_string()}]),
+            json!([{"tile_id":tile_id},{"tile_id":tile_id}]),
+        ] {
+            let error = service
+                .create_legacy_json(
+                    &owner,
+                    &None,
+                    serde_json::from_value(json!({"title":"Identity","tiles":tiles})).unwrap(),
+                    &Default::default(),
+                )
+                .await
+                .unwrap_err();
+            assert!(matches!(error, DashboardError::Metadata(_)));
+        }
+        // Whitespace-only create titles and empty replacement titles were typed
+        // REST inputs; editor validation still rejects them on strict routes.
+        let created = service
+            .create_legacy_json(
+                &owner,
+                &None,
+                serde_json::from_value(json!({"title":"   "})).unwrap(),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let dashboard_id = id(&created);
+        let replaced = service
+            .mutate_legacy_json(
+                &owner,
+                dashboard_id,
+                &None,
+                DashboardMutation::Replace(
+                    json!({"title":"","tiles":null,"isFavorite":null,"dashboardType":null}),
+                ),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(replaced["dashboard"]["title"], "");
+        assert_eq!(replaced["dashboard"]["tiles"], json!([]));
+        assert_eq!(replaced["dashboard"]["isFavorite"], false);
+        assert_eq!(replaced["dashboard"]["dashboardType"], "Dashboard");
+        for document in [
+            json!({"title":12}),
+            json!({"title":"Bad","tags":[12]}),
+            json!({"title":"Bad","tiles":[{"tile_id":"invalid"}]}),
+        ] {
+            assert!(matches!(
+                service
+                    .mutate_legacy_json(
+                        &owner,
+                        dashboard_id,
+                        &None,
+                        DashboardMutation::Replace(document),
+                        &Default::default()
+                    )
+                    .await,
+                Err(DashboardError::Serde(_))
+            ));
+        }
+        let mut internal: Dashboard =
+            serde_json::from_value(json!({"title":"Protected", "_parseableDashboard":{}})).unwrap();
+        assert!(matches!(
+            service
+                .create_legacy_json(&owner, &None, internal.clone(), &Default::default())
+                .await,
+            Err(DashboardError::Api {
+                status: 400,
+                code: "protected_dashboard_metadata",
+                ..
+            })
+        ));
+        internal.title.clear();
+        assert!(matches!(
+            service
+                .create_legacy_json(&owner, &None, internal, &Default::default())
+                .await,
+            Err(DashboardError::Metadata("Title must be provided"))
+        ));
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn legacy_replacement_without_revision_uses_cas_and_cannot_lose_a_concurrent_edit() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let created = first
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Legacy PUT"}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let id = id(&created);
+        let paused = Arc::new(PausedStorage::new(
+            directory.path(),
+            dashboard_path(&None, &owner.user_id, id),
+        ));
+        let legacy = DashboardService::new(Arc::new(ObjectStoreMetastore {
+            storage: paused.clone(),
+        }));
+        let caller = tokio::spawn({
+            let owner = owner.clone();
+            async move {
+                legacy
+                    .mutate_legacy_json(
+                        &owner,
+                        id,
+                        &None,
+                        DashboardMutation::Replace(json!({"title":"Legacy PUT","legacy":true})),
+                        &Default::default(),
+                    )
+                    .await
+            }
+        });
+        tokio::time::timeout(std::time::Duration::from_secs(2), paused.entered.notified())
+            .await
+            .unwrap();
+        second
+            .mutate_json(&owner, id, &None, metadata(true), &Default::default())
+            .await
+            .unwrap();
+        paused.released.notify_one();
+        assert!(matches!(
+            caller.await.unwrap(),
+            Err(DashboardError::Api { status: 412, .. })
+        ));
+        let current = first.get_json(id, &None).await.unwrap();
+        assert_eq!(current["isFavorite"], true);
+        assert!(current.get("legacy").is_none());
+        let result = first
+            .mutate_legacy_json(
+                &owner,
+                id,
+                &None,
+                DashboardMutation::Replace(json!({"title":"Legacy PUT","legacy":true})),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(result["dashboard"]["legacy"], true);
+    }
+
+    #[tokio::test]
+    async fn listing_skips_corrupt_json_and_invalid_legacy_shapes() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, _) = services(directory.path());
+        let owner = actor();
+        first
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Valid","tags":["healthy"]}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let storage = LocalFS::new(directory.path().to_path_buf());
+        for bytes in ["{", "[]", "{\"title\":1}"] {
+            let path = dashboard_path(&None, &owner.user_id, Ulid::new());
+            storage
+                .put_object(RelativePath::new(&path), Bytes::from(bytes), &None)
+                .await
+                .unwrap();
+        }
+        let rows = first.list_json(&None).await.unwrap();
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0]["tags"], json!(["healthy"]));
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn independent_nodes_same_revision_have_exactly_one_winner() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let tenant = Some("tenant".into());
+        let created = first
+            .create_json(
+                &owner,
+                &tenant,
+                json!({"title":"Concurrent"}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let id = id(&created);
+        let observed = revision_of(&created).to_owned();
+        let barrier = Arc::new(tokio::sync::Barrier::new(24));
+        let mut tasks = tokio::task::JoinSet::new();
+        for index in 0..24 {
+            let service = if index % 2 == 0 {
+                first.clone()
+            } else {
+                second.clone()
+            };
+            let owner = owner.clone();
+            let tenant = tenant.clone();
+            let observed = observed.clone();
+            let barrier = barrier.clone();
+            tasks.spawn(async move {
+                barrier.wait().await;
+                service
+                    .mutate_json(
+                        &owner,
+                        id,
+                        &tenant,
+                        metadata(index % 2 == 0),
+                        &options(&observed, None),
+                    )
+                    .await
+            });
+        }
+        let mut wins = 0;
+        while let Some(result) = tasks.join_next().await {
+            match result.unwrap() {
+                Ok(_) => wins += 1,
+                Err(DashboardError::Api { status: 412, .. }) => {}
+                Err(error) => panic!("unexpected error: {error}"),
+            }
+        }
+        assert_eq!(wins, 1);
+        assert_ne!(
+            first.get_json(id, &tenant).await.unwrap()["revision"],
+            observed
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn agents_retry_disjoint_changes_without_losing_fields() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let created = first
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Merge","opaque":{"nested":[1,2,3]}}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let id = id(&created);
+        let mut tasks = tokio::task::JoinSet::new();
+        for index in 0..8 {
+            let service = if index % 2 == 0 {
+                first.clone()
+            } else {
+                second.clone()
+            };
+            let owner = owner.clone();
+            tasks.spawn(async move {
+                for _ in 0..8 {
+                    let current = service.get_json(id, &None).await.unwrap();
+                    let key = format!("agent-{index}");
+                    let mutation = DashboardMutation::Patch(vec![operation(
+                        &format!("/agent{index}"),
+                        json!(index),
+                    )]);
+                    match service
+                        .mutate_json(
+                            &owner,
+                            id,
+                            &None,
+                            mutation,
+                            &options(current["revision"].as_str().unwrap(), Some(&key)),
+                        )
+                        .await
+                    {
+                        Ok(_) => return,
+                        Err(DashboardError::Api { status: 412, .. }) => {
+                            tokio::task::yield_now().await
+                        }
+                        Err(error) => panic!("unexpected retry error: {error}"),
+                    }
+                }
+                panic!("exhausted bounded retries");
+            });
+        }
+        while let Some(result) = tasks.join_next().await {
+            result.unwrap();
+        }
+        let final_document = second.get_json(id, &None).await.unwrap();
+        for index in 0..8 {
+            assert_eq!(final_document[format!("agent{index}")], json!(index));
+        }
+        assert_eq!(final_document["opaque"], json!({"nested":[1,2,3]}));
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn legacy_delta_adds_rebase_without_losing_tiles() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let created = first
+            .create_json(&owner, &None, json!({"title":"Tiles"}), &Default::default())
+            .await
+            .unwrap();
+        let id = id(&created);
+        let mut tasks = tokio::task::JoinSet::new();
+        for index in 0..8 {
+            let service = if index % 2 == 0 {
+                first.clone()
+            } else {
+                second.clone()
+            };
+            let owner = owner.clone();
+            tasks.spawn(async move {
+                let tile=json!({"tile_id":Ulid::new().to_string(),"name":format!("Tile {index}"),"tileType":"code","chartType":"table","chartQuery":"SELECT 1","dbName":"logs"});
+                service.mutate_json(&owner,id,&None,DashboardMutation::AddTile(tile),&Default::default()).await.unwrap();
+            });
+        }
+        while let Some(result) = tasks.join_next().await {
+            result.unwrap();
+        }
+        assert_eq!(
+            second.get_json(id, &None).await.unwrap()["tiles"]
+                .as_array()
+                .unwrap()
+                .len(),
+            8
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn tombstone_and_patch_cannot_both_commit_from_one_revision() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let created = first
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Delete race"}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let id = id(&created);
+        let opts = options(revision_of(&created), None);
+        let (removed, changed) = tokio::join!(
+            first.delete_json(&owner, id, &None, &opts),
+            second.mutate_json(
+                &owner,
+                id,
+                &None,
+                DashboardMutation::Patch(vec![operation("/extra", json!(true))]),
+                &opts
+            )
+        );
+        assert_eq!(
+            usize::from(removed.is_ok()) + usize::from(changed.is_ok()),
+            1
+        );
+        if removed.is_ok() {
+            assert!(matches!(
+                second.get_json(id, &None).await,
+                Err(DashboardError::Api { status: 404, .. })
+            ));
+            assert!(second.list_json(&None).await.unwrap().is_empty());
+            second
+                .create_json(
+                    &owner,
+                    &None,
+                    json!({"title":"Delete race"}),
+                    &Default::default(),
+                )
+                .await
+                .unwrap();
+        } else {
+            assert_eq!(second.get_json(id, &None).await.unwrap()["extra"], true);
+        }
+    }
+
+    #[tokio::test]
+    async fn owner_tenant_extensions_and_full_replacement_revision_are_enforced() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let tenant = Some("trusted".into());
+        let created=first.create_json(&owner,&tenant,json!({"title":"Ownership","author":"forged","tenantId":"other","custom":{"unknown":[1,null,{"x":true}]}}),&Default::default()).await.unwrap();
+        let id = id(&created);
+        assert_eq!(created["dashboard"]["author"], owner.user_id);
+        assert_eq!(created["dashboard"]["tenantId"], "trusted");
+        assert!(matches!(
+            second.get_json(id, &Some("other".into())).await,
+            Err(DashboardError::Api { status: 404, .. })
+        ));
+        let intruder = DashboardActor {
+            user_id: "intruder".into(),
+            is_admin: false,
+        };
+        assert!(matches!(
+            second
+                .mutate_json(&intruder, id, &tenant, metadata(true), &Default::default())
+                .await,
+            Err(DashboardError::Api { status: 403, .. })
+        ));
+        assert!(matches!(
+            first
+                .mutate_json(
+                    &owner,
+                    id,
+                    &tenant,
+                    DashboardMutation::Replace(json!({"title":"Blind"})),
+                    &Default::default()
+                )
+                .await,
+            Err(DashboardError::Api { status: 428, .. })
+        ));
+        let admin = DashboardActor {
+            user_id: "admin".into(),
+            is_admin: true,
+        };
+        let mut replacement = created["dashboard"].clone();
+        replacement["author"] = json!("admin");
+        replacement["tenantId"] = json!("forged");
+        replacement["title"] = json!("Admin rename");
+        let changed = second
+            .mutate_json(
+                &admin,
+                id,
+                &tenant,
+                DashboardMutation::Replace(replacement),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(changed["dashboard"]["author"], owner.user_id);
+        assert_eq!(changed["dashboard"]["tenantId"], "trusted");
+        assert_eq!(
+            changed["dashboard"]["custom"],
+            created["dashboard"]["custom"]
+        );
+        assert!(changed["dashboard"].get(INTERNAL).is_none());
+        assert_eq!(second.list_json(&tenant).await.unwrap().len(), 1);
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn durable_create_and_mutation_receipts_replay_across_nodes() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let create_options = DashboardWriteOptions {
+            idempotency_key: Some("create-once".into()),
+            ..Default::default()
+        };
+        let (one, two) = tokio::join!(
+            first.create_json(&owner, &None, json!({"title":"Once"}), &create_options),
+            second.create_json(&owner, &None, json!({"title":"Once"}), &create_options)
+        );
+        let one = one.unwrap();
+        let two = two.unwrap();
+        assert_eq!(id(&one), id(&two));
+        assert_eq!(one["revision"], two["revision"]);
+        assert_eq!(second.list_json(&None).await.unwrap().len(), 1);
+        let id = id(&one);
+        let opts = options(revision_of(&one), Some("favorite-once"));
+        let changed = first
+            .mutate_json(&owner, id, &None, metadata(true), &opts)
+            .await
+            .unwrap();
+        let replayed = second
+            .mutate_json(&owner, id, &None, metadata(true), &opts)
+            .await
+            .unwrap();
+        assert_eq!(changed["revision"], replayed["revision"]);
+        assert_eq!(replayed["replayed"], true);
+        assert_eq!(replayed["appliedRevision"], changed["revision"]);
+        assert!(matches!(
+            second
+                .mutate_json(&owner, id, &None, metadata(false), &opts)
+                .await,
+            Err(DashboardError::Api {
+                status: 409,
+                code: "idempotency_conflict",
+                ..
+            })
+        ));
+        // Eviction never replays the old request against a newer base.
+        for index in 0..=RECEIPT_LIMIT {
+            let current = first.get_json(id, &None).await.unwrap();
+            let key = format!("receipt-{index}");
+            first
+                .mutate_json(
+                    &owner,
+                    id,
+                    &None,
+                    metadata(index % 2 == 0),
+                    &options(current["revision"].as_str().unwrap(), Some(&key)),
+                )
+                .await
+                .unwrap();
+        }
+        assert!(matches!(
+            second
+                .mutate_json(&owner, id, &None, metadata(true), &opts)
+                .await,
+            Err(DashboardError::Api { status: 412, .. })
+        ));
+        let stored = first.stored(id, &None).await.unwrap();
+        assert_eq!(
+            stored.document[INTERNAL]["receipts"]
+                .as_array()
+                .unwrap()
+                .len(),
+            RECEIPT_LIMIT
+        );
+    }
+
+    #[tokio::test]
+    async fn pending_title_claim_recovers_only_original_idempotent_operation() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let request = json!({"title":"Interrupted"});
+        let opts = DashboardWriteOptions {
+            idempotency_key: Some("original-create".into()),
+            ..Default::default()
+        };
+        let digest = Sha256::digest(
+            serde_json::to_vec(&json!([Value::Null, owner.user_id, "original-create"])).unwrap(),
+        );
+        let planned_id = Ulid::from_bytes(digest[..16].try_into().unwrap());
+        let request_hash = fingerprint(&json!({"operation":"create","document":request}));
+        first
+            .claim_title(
+                "Interrupted",
+                planned_id,
+                None,
+                &owner,
+                &opts,
+                &request_hash,
+                &None,
+            )
+            .await
+            .unwrap();
+        assert!(matches!(
+            second
+                .create_json(&owner, &None, request.clone(), &Default::default())
+                .await,
+            Err(DashboardError::Api {
+                code: "title_reservation_pending",
+                ..
+            })
+        ));
+        let recovered = second
+            .create_json(&owner, &None, request, &opts)
+            .await
+            .unwrap();
+        assert_eq!(id(&recovered), planned_id);
+        assert!(matches!(
+            first
+                .create_json(
+                    &owner,
+                    &None,
+                    json!({"title":"Interrupted"}),
+                    &Default::default()
+                )
+                .await,
+            Err(DashboardError::Api {
+                code: "title_conflict",
+                ..
+            })
+        ));
+    }
+
+    #[tokio::test]
+    async fn dry_run_invalid_batches_and_reserved_fields_never_persist() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let created = first
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Preview","extra":"before"}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let id = id(&created);
+        let preview = DashboardWriteOptions {
+            dry_run: true,
+            ..options(revision_of(&created), None)
+        };
+        let changed = first
+            .mutate_json(
+                &owner,
+                id,
+                &None,
+                DashboardMutation::Patch(vec![operation("/extra", json!("after"))]),
+                &preview,
+            )
+            .await
+            .unwrap();
+        assert_eq!(changed["dashboard"]["extra"], "after");
+        assert_eq!(second.get_json(id, &None).await.unwrap()["extra"], "before");
+        assert!(
+            first
+                .mutate_json(
+                    &owner,
+                    id,
+                    &None,
+                    DashboardMutation::Patch(vec![
+                        operation("/extra", json!("after")),
+                        operation("/author", json!("attacker"))
+                    ]),
+                    &options(revision_of(&created), None)
+                )
+                .await
+                .is_err()
+        );
+        assert_eq!(second.get_json(id, &None).await.unwrap()["extra"], "before");
+        assert!(
+            first
+                .create_json(
+                    &owner,
+                    &None,
+                    json!({"title":"Hidden",INTERNAL:{"tombstone":false}}),
+                    &Default::default()
+                )
+                .await
+                .is_err()
+        );
+    }
+
+    #[tokio::test]
+    async fn preserved_nonce_cannot_hide_an_external_content_change() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let created = first
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"External","layoutExtra":{"x":1}}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let id = id(&created);
+        let stored = first.stored(id, &None).await.unwrap();
+        let nonce = stored.document[INTERNAL]["revision"].clone();
+        let mut external = stored.document;
+        external["layoutExtra"]["x"] = json!(9);
+        let storage = LocalFS::new(directory.path().to_path_buf());
+        crate::storage::ObjectStorage::put_object(
+            &storage,
+            relative_path::RelativePath::new(&stored.path),
+            Bytes::from(serde_json::to_vec(&external).unwrap()),
+            &None,
+        )
+        .await
+        .unwrap();
+        let current = second.get_json(id, &None).await.unwrap();
+        assert_ne!(current["revision"], created["revision"]);
+        assert_eq!(external[INTERNAL]["revision"], nonce);
+        assert_eq!(
+            second.list_json(&None).await.unwrap()[0]["revision"],
+            current["revision"]
+        );
+        assert!(matches!(
+            first
+                .mutate_json(
+                    &owner,
+                    id,
+                    &None,
+                    metadata(true),
+                    &options(revision_of(&created), None)
+                )
+                .await,
+            Err(DashboardError::Api { status: 412, .. })
+        ));
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn a_blocked_dashboard_writer_does_not_block_other_dashboards() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let a = first
+            .create_json(&owner, &None, json!({"title":"Held"}), &Default::default())
+            .await
+            .unwrap();
+        let b = second
+            .create_json(&owner, &None, json!({"title":"Free"}), &Default::default())
+            .await
+            .unwrap();
+        let a_id = id(&a);
+        let b_id = id(&b);
+        let lock_path = LocalFS::new(directory.path().to_path_buf()).metadata_lock_path(
+            RelativePath::new(&dashboard_path(&None, &owner.user_id, a_id)),
+        );
+        let lock = std::fs::OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(lock_path)
+            .unwrap();
+        lock.lock().unwrap();
+        let blocked = tokio::spawn({
+            let first = first.clone();
+            let owner = owner.clone();
+            async move {
+                first
+                    .mutate_json(&owner, a_id, &None, metadata(true), &Default::default())
+                    .await
+            }
+        });
+        let independent = tokio::time::timeout(
+            std::time::Duration::from_secs(2),
+            second.mutate_json(&owner, b_id, &None, metadata(true), &Default::default()),
+        )
+        .await;
+        drop(lock);
+        blocked.await.unwrap().unwrap();
+        independent
+            .expect("different dashboard was blocked by shared state")
+            .unwrap();
+    }
+
+    #[tokio::test]
+    async fn quoted_etags_and_body_revisions_work_but_malformed_validators_fail() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let created = first
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Quoted"}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let id = id(&created);
+        let quoted = format!("\"{}\"", revision_of(&created));
+        let changed = first
+            .mutate_json(&owner, id, &None, metadata(true), &options(&quoted, None))
+            .await
+            .unwrap();
+        assert!(matches!(
+            second
+                .mutate_json(&owner, id, &None, metadata(false), &options(&quoted, None))
+                .await,
+            Err(DashboardError::Api { status: 412, .. })
+        ));
+        let mut body = changed["dashboard"].clone();
+        body["revision"] = json!(format!("\"{}\"", revision_of(&changed)));
+        body["custom"] = json!(true);
+        let replaced = second
+            .mutate_json(
+                &owner,
+                id,
+                &None,
+                DashboardMutation::Replace(body),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(replaced["dashboard"]["custom"], true);
+        let current = revision_of(&replaced);
+        for malformed in [
+            format!("W/\"{current}\""),
+            "*".into(),
+            format!("\"{current}\", \"other\""),
+            format!("\"{current}"),
+            format!("{current}\""),
+            format!("\"bad\nvalue\""),
+            "not-a-hash".into(),
+        ] {
+            assert!(
+                matches!(
+                    second
+                        .mutate_json(
+                            &owner,
+                            id,
+                            &None,
+                            metadata(false),
+                            &options(&malformed, None)
+                        )
+                        .await,
+                    Err(DashboardError::Api {
+                        status: 400,
+                        code: "invalid_dashboard_revision",
+                        ..
+                    })
+                ),
+                "accepted malformed validator {malformed:?}"
+            );
+            let mut body = replaced["dashboard"].clone();
+            body["revision"] = json!(malformed);
+            assert!(matches!(
+                second
+                    .mutate_json(
+                        &owner,
+                        id,
+                        &None,
+                        DashboardMutation::Replace(body),
+                        &Default::default()
+                    )
+                    .await,
+                Err(DashboardError::Api { status: 400, .. })
+            ));
+        }
+        assert!(matches!(
+            second
+                .mutate_json(
+                    &owner,
+                    id,
+                    &None,
+                    metadata(false),
+                    &options("\"syntactically-valid-but-stale\"", None)
+                )
+                .await,
+            Err(DashboardError::Api { status: 412, .. })
+        ));
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn obsolete_pending_rename_is_reclaimed_after_delete_or_other_source_change() {
+        for delete in [true, false] {
+            let directory = tempfile::tempdir().unwrap();
+            let (first, second) = services(directory.path());
+            let owner = actor();
+            let created = first
+                .create_json(
+                    &owner,
+                    &None,
+                    json!({"title":"Source X"}),
+                    &Default::default(),
+                )
+                .await
+                .unwrap();
+            let source_id = id(&created);
+            let paused = Arc::new(PausedStorage::new(
+                directory.path(),
+                dashboard_path(&None, &owner.user_id, source_id),
+            ));
+            let renaming = Arc::new(DashboardService::new(Arc::new(ObjectStoreMetastore {
+                storage: paused.clone(),
+            })));
+            let task = tokio::spawn({
+                let renaming = renaming.clone();
+                let owner = owner.clone();
+                let observed = revision_of(&created).to_owned();
+                async move {
+                    renaming
+                        .mutate_json(
+                            &owner,
+                            source_id,
+                            &None,
+                            DashboardMutation::Metadata(HashMap::from([(
+                                "renameTo".into(),
+                                "Target Y".into(),
+                            )])),
+                            &options(&observed, Some("paused-rename")),
+                        )
+                        .await
+                }
+            });
+            tokio::time::timeout(std::time::Duration::from_secs(2), paused.entered.notified())
+                .await
+                .expect("rename did not reach storage barrier");
+            let reservation = first
+                .read(&title_path(&None, "Target Y"), &None)
+                .await
+                .unwrap()
+                .unwrap()
+                .0;
+            assert_eq!(reservation["state"], "pending");
+            assert!(reservation["sourceVersion"].is_object());
+            if delete {
+                second
+                    .delete_json(
+                        &owner,
+                        source_id,
+                        &None,
+                        &options(revision_of(&created), None),
+                    )
+                    .await
+                    .unwrap();
+            } else {
+                second
+                    .mutate_json(
+                        &owner,
+                        source_id,
+                        &None,
+                        metadata(true),
+                        &options(revision_of(&created), None),
+                    )
+                    .await
+                    .unwrap();
+            }
+            // Reclaim before the original writer resumes: its exact source CAS
+            // is already impossible, so no lease or writer timeout is needed.
+            let replacement = second
+                .create_json(
+                    &owner,
+                    &None,
+                    json!({"title":"Target Y"}),
+                    &DashboardWriteOptions {
+                        idempotency_key: Some("replacement-create".into()),
+                        ..Default::default()
+                    },
+                )
+                .await;
+            paused.released.notify_one();
+            let lost = task.await.unwrap();
+            assert!(matches!(lost, Err(DashboardError::Api { status: 412, .. })));
+            let replacement = replacement.unwrap();
+            assert_ne!(id(&replacement), source_id);
+            assert_eq!(
+                first.get_json(id(&replacement), &None).await.unwrap()["title"],
+                "Target Y"
+            );
+            if delete {
+                assert!(matches!(
+                    first.get_json(source_id, &None).await,
+                    Err(DashboardError::Api { status: 404, .. })
+                ));
+            } else {
+                let source = first.get_json(source_id, &None).await.unwrap();
+                assert_eq!(source["title"], "Source X");
+                assert_eq!(source["isFavorite"], true);
+            }
+        }
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn pending_rename_is_not_stolen_while_its_source_can_still_commit() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let created = first
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Live X"}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let source_id = id(&created);
+        let paused = Arc::new(PausedStorage::new(
+            directory.path(),
+            dashboard_path(&None, &owner.user_id, source_id),
+        ));
+        let renaming = Arc::new(DashboardService::new(Arc::new(ObjectStoreMetastore {
+            storage: paused.clone(),
+        })));
+        let task = tokio::spawn({
+            let owner = owner.clone();
+            let observed = revision_of(&created).to_owned();
+            async move {
+                renaming
+                    .mutate_json(
+                        &owner,
+                        source_id,
+                        &None,
+                        DashboardMutation::Metadata(HashMap::from([(
+                            "renameTo".into(),
+                            "Live Y".into(),
+                        )])),
+                        &options(&observed, Some("live-rename")),
+                    )
+                    .await
+            }
+        });
+        tokio::time::timeout(std::time::Duration::from_secs(2), paused.entered.notified())
+            .await
+            .unwrap();
+        let competing = second
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Live Y"}),
+                &Default::default(),
+            )
+            .await;
+        paused.released.notify_one();
+        let changed = task.await.unwrap().unwrap();
+        assert!(matches!(
+            competing,
+            Err(DashboardError::Api {
+                code: "title_reservation_pending",
+                ..
+            })
+        ));
+        assert_eq!(changed["dashboard"]["title"], "Live Y");
+        assert_eq!(
+            first.get_json(source_id, &None).await.unwrap()["title"],
+            "Live Y"
+        );
+    }
+
+    async fn wait_for_active_title(service: &DashboardService, title: &str) -> Value {
+        tokio::time::timeout(std::time::Duration::from_secs(3), async {
+            loop {
+                if let Some((claim, _)) = service
+                    .read(&title_path(&None, title), &None)
+                    .await
+                    .unwrap()
+                {
+                    if claim["state"] == "active" {
+                        return claim;
+                    }
+                }
+                tokio::task::yield_now().await;
+            }
+        })
+        .await
+        .expect("detached commit did not activate title")
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+    async fn cancelling_unkeyed_create_or_rename_does_not_cancel_commit() {
+        let directory = tempfile::tempdir().unwrap();
+        let (observer, _) = services(directory.path());
+        let owner = actor();
+        let paused = Arc::new(PausedStorage::new(directory.path(), String::new()));
+        let service = Arc::new(DashboardService::new(Arc::new(ObjectStoreMetastore {
+            storage: paused.clone(),
+        })));
+        let caller = tokio::spawn({
+            let service = service.clone();
+            let owner = owner.clone();
+            async move {
+                service
+                    .create_json(
+                        &owner,
+                        &None,
+                        json!({"title":"Cancelled create"}),
+                        &Default::default(),
+                    )
+                    .await
+            }
+        });
+        tokio::time::timeout(std::time::Duration::from_secs(2), paused.entered.notified())
+            .await
+            .unwrap();
+        caller.abort();
+        assert!(caller.await.unwrap_err().is_cancelled());
+        paused.released.notify_one();
+        let claim = wait_for_active_title(&observer, "Cancelled create").await;
+        let created_id = Ulid::from_string(claim["dashboardId"].as_str().unwrap()).unwrap();
+        let created = observer.get_json(created_id, &None).await.unwrap();
+        assert!(matches!(
+            observer
+                .create_json(
+                    &owner,
+                    &None,
+                    json!({"title":"Cancelled create"}),
+                    &Default::default()
+                )
+                .await,
+            Err(DashboardError::Api {
+                code: "title_conflict",
+                ..
+            })
+        ));
+        let paused = Arc::new(PausedStorage::new(
+            directory.path(),
+            dashboard_path(&None, &owner.user_id, created_id),
+        ));
+        let service = Arc::new(DashboardService::new(Arc::new(ObjectStoreMetastore {
+            storage: paused.clone(),
+        })));
+        let caller = tokio::spawn({
+            let owner = owner.clone();
+            let observed = created["revision"].as_str().unwrap().to_owned();
+            async move {
+                service
+                    .mutate_json(
+                        &owner,
+                        created_id,
+                        &None,
+                        DashboardMutation::Metadata(HashMap::from([(
+                            "renameTo".into(),
+                            "Cancelled rename".into(),
+                        )])),
+                        &options(&observed, None),
+                    )
+                    .await
+            }
+        });
+        tokio::time::timeout(std::time::Duration::from_secs(2), paused.entered.notified())
+            .await
+            .unwrap();
+        caller.abort();
+        assert!(caller.await.unwrap_err().is_cancelled());
+        paused.released.notify_one();
+        wait_for_active_title(&observer, "Cancelled rename").await;
+        assert_eq!(
+            observer.get_json(created_id, &None).await.unwrap()["title"],
+            "Cancelled rename"
+        );
+        observer
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Cancelled create"}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+    }
+
+    #[tokio::test]
+    async fn legacy_bootstrap_scans_once_and_does_not_hide_new_remote_locators() {
+        let directory = tempfile::tempdir().unwrap();
+        let owner = actor();
+        let legacy_id = Ulid::new();
+        let local = LocalFS::new(directory.path().to_path_buf());
+        let legacy = json!({"dashboardId":legacy_id.to_string(),"author":owner.user_id,"title":"Legacy title","tiles":[],"opaque":{"preserve":true}});
+        local
+            .put_object(
+                RelativePath::new(&dashboard_path(&None, &owner.user_id, legacy_id)),
+                Bytes::from(serde_json::to_vec(&legacy).unwrap()),
+                &None,
+            )
+            .await
+            .unwrap();
+        let counted = Arc::new(PausedStorage::new(directory.path(), "never-match".into()));
+        counted.armed.store(false, Ordering::SeqCst);
+        let service = DashboardService::new(Arc::new(ObjectStoreMetastore {
+            storage: counted.clone(),
+        }));
+        let (_, remote) = services(directory.path());
+        let create_key = "remote-after-negative";
+        let digest = Sha256::digest(
+            serde_json::to_vec(&json!([Value::Null, owner.user_id, create_key])).unwrap(),
+        );
+        let future_id = Ulid::from_bytes(digest[..16].try_into().unwrap());
+        assert!(matches!(
+            service.get_json(future_id, &None).await,
+            Err(DashboardError::Api { status: 404, .. })
+        ));
+        let baseline = counted.scans.load(Ordering::SeqCst);
+        assert!(baseline > 0);
+        for _ in 0..8 {
+            assert!(service.get_json(Ulid::new(), &None).await.is_err());
+        }
+        for index in 0..4 {
+            service
+                .create_json(
+                    &owner,
+                    &None,
+                    json!({"title":format!("New title {index}")}),
+                    &Default::default(),
+                )
+                .await
+                .unwrap();
+        }
+        assert_eq!(counted.scans.load(Ordering::SeqCst), baseline);
+        remote
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Remote new"}),
+                &DashboardWriteOptions {
+                    idempotency_key: Some(create_key.into()),
+                    ..Default::default()
+                },
+            )
+            .await
+            .unwrap();
+        assert_eq!(
+            service.get_json(future_id, &None).await.unwrap()["title"],
+            "Remote new"
+        );
+        let observed = remote.get_json(legacy_id, &None).await.unwrap();
+        remote
+            .mutate_json(
+                &owner,
+                legacy_id,
+                &None,
+                DashboardMutation::Metadata(HashMap::from([(
+                    "renameTo".into(),
+                    "Legacy moved".into(),
+                )])),
+                &options(observed["revision"].as_str().unwrap(), None),
+            )
+            .await
+            .unwrap();
+        // Stale bootstrap title must be checked against the remote rename.
+        service
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Legacy title"}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(counted.scans.load(Ordering::SeqCst), baseline);
+    }
+
+    #[tokio::test]
+    async fn create_receipt_survives_recent_ring_eviction_and_deleted_replays_are_explicit() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let create_options = DashboardWriteOptions {
+            idempotency_key: Some("permanent-create".into()),
+            ..Default::default()
+        };
+        let request =
+            json!({"title":"Persistent create","heavyExtension":{"queries":vec!["payload";128]}});
+        let created = first
+            .create_json(&owner, &None, request.clone(), &create_options)
+            .await
+            .unwrap();
+        let dashboard_id = id(&created);
+        for index in 0..=RECEIPT_LIMIT {
+            let current = first.get_json(dashboard_id, &None).await.unwrap();
+            let key = format!("evict-{index}");
+            first
+                .mutate_json(
+                    &owner,
+                    dashboard_id,
+                    &None,
+                    metadata(index % 2 == 0),
+                    &options(current["revision"].as_str().unwrap(), Some(&key)),
+                )
+                .await
+                .unwrap();
+        }
+        let replayed = second
+            .create_json(&owner, &None, request.clone(), &create_options)
+            .await
+            .unwrap();
+        assert_eq!(id(&replayed), dashboard_id);
+        assert_eq!(replayed["replayed"], true);
+        assert_eq!(replayed["appliedRevision"], created["revision"]);
+        let before = first.get_json(dashboard_id, &None).await.unwrap();
+        let update_options = options(
+            before["revision"].as_str().unwrap(),
+            Some("update-before-delete"),
+        );
+        let updated = first
+            .mutate_json(&owner, dashboard_id, &None, metadata(true), &update_options)
+            .await
+            .unwrap();
+        let delete_options = options(revision_of(&updated), Some("delete-once"));
+        second
+            .delete_json(&owner, dashboard_id, &None, &delete_options)
+            .await
+            .unwrap();
+        second
+            .delete_json(&owner, dashboard_id, &None, &delete_options)
+            .await
+            .unwrap();
+        for replay in [
+            first
+                .create_json(&owner, &None, request, &create_options)
+                .await,
+            first
+                .mutate_json(&owner, dashboard_id, &None, metadata(true), &update_options)
+                .await,
+        ] {
+            match replay {
+                Err(DashboardError::Api {
+                    status: 410,
+                    code: "resource_deleted",
+                    details,
+                    ..
+                }) => {
+                    assert_eq!(details["dashboardId"], dashboard_id.to_string());
+                    assert!(details["appliedRevision"].is_string());
+                }
+                other => panic!("expected explicit deleted replay, got {other:?}"),
+            }
+        }
+        let stored = first.stored(dashboard_id, &None).await.unwrap();
+        assert!(stored.document.get("heavyExtension").is_none());
+        assert!(stored.document.get("tiles").is_none());
+        assert!(stored.document[INTERNAL]["createReceipt"].is_object());
+    }
+
+    #[tokio::test]
+    async fn dry_run_checks_title_without_writing_reservations() {
+        let directory = tempfile::tempdir().unwrap();
+        let (first, second) = services(directory.path());
+        let owner = actor();
+        let existing = first
+            .create_json(&owner, &None, json!({"title":"Taken"}), &Default::default())
+            .await
+            .unwrap();
+        let other = first
+            .create_json(&owner, &None, json!({"title":"Other"}), &Default::default())
+            .await
+            .unwrap();
+        let other_id = id(&other);
+        let preview = DashboardWriteOptions {
+            dry_run: true,
+            ..Default::default()
+        };
+        assert!(matches!(
+            second
+                .create_json(&owner, &None, json!({"title":"Taken"}), &preview)
+                .await,
+            Err(DashboardError::Api {
+                code: "title_conflict",
+                ..
+            })
+        ));
+        let rename_preview = DashboardWriteOptions {
+            dry_run: true,
+            ..options(revision_of(&other), None)
+        };
+        assert!(matches!(
+            second
+                .mutate_json(
+                    &owner,
+                    other_id,
+                    &None,
+                    DashboardMutation::Metadata(HashMap::from([(
+                        "renameTo".into(),
+                        "Taken".into()
+                    )])),
+                    &rename_preview
+                )
+                .await,
+            Err(DashboardError::Api {
+                code: "title_conflict",
+                ..
+            })
+        ));
+        let available = second
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Available preview"}),
+                &preview,
+            )
+            .await
+            .unwrap();
+        assert_eq!(available["titleAvailability"]["reserved"], false);
+        assert_eq!(available["titleAvailability"]["mayConflictAtCommit"], true);
+        assert!(
+            first
+                .read(&title_path(&None, "Available preview"), &None)
+                .await
+                .unwrap()
+                .is_none()
+        );
+        assert_eq!(first.list_json(&None).await.unwrap().len(), 2);
+        assert_eq!(
+            first.get_json(id(&existing), &None).await.unwrap()["title"],
+            "Taken"
+        );
+    }
+
+    fn fault_service(
+        root: &Path,
+        target: &str,
+        kind: FaultKind,
+    ) -> (DashboardService, Arc<PausedStorage>) {
+        let storage = Arc::new(PausedStorage::new(root, "never-match".into()));
+        *storage.fault.lock().unwrap() = Some(WriteFault {
+            path_contains: target.into(),
+            kind,
+        });
+        (
+            DashboardService::new(Arc::new(ObjectStoreMetastore {
+                storage: storage.clone(),
+            })),
+            storage,
+        )
+    }
+
+    #[tokio::test]
+    async fn committed_documents_and_title_claims_survive_transport_conflict_or_error() {
+        for fault in [FaultKind::AfterConflict, FaultKind::AfterStorage] {
+            for target in ["/dashboards/", "/.dashboard-titles/"] {
+                let directory = tempfile::tempdir().unwrap();
+                let owner = actor();
+                let (service, _) = fault_service(directory.path(), target, fault);
+                let created = service
+                    .create_json(
+                        &owner,
+                        &None,
+                        json!({"title":"Committed create"}),
+                        &Default::default(),
+                    )
+                    .await
+                    .unwrap();
+                assert_eq!(
+                    service.get_json(id(&created), &None).await.unwrap()["title"],
+                    "Committed create"
+                );
+                assert!(matches!(
+                    service
+                        .create_json(
+                            &owner,
+                            &None,
+                            json!({"title":"Committed create"}),
+                            &Default::default()
+                        )
+                        .await,
+                    Err(DashboardError::Api {
+                        code: "title_conflict",
+                        ..
+                    })
+                ));
+            }
+            for operation in ["rename", "delete"] {
+                let directory = tempfile::tempdir().unwrap();
+                let (plain, observer) = services(directory.path());
+                let owner = actor();
+                let created = plain
+                    .create_json(
+                        &owner,
+                        &None,
+                        json!({"title":"Committed source"}),
+                        &Default::default(),
+                    )
+                    .await
+                    .unwrap();
+                let dashboard_id = id(&created);
+                let (faulty, _) = fault_service(directory.path(), "/dashboards/", fault);
+                if operation == "rename" {
+                    let changed = faulty
+                        .mutate_json(
+                            &owner,
+                            dashboard_id,
+                            &None,
+                            DashboardMutation::Metadata(HashMap::from([(
+                                "renameTo".into(),
+                                "Committed target".into(),
+                            )])),
+                            &options(revision_of(&created), None),
+                        )
+                        .await
+                        .unwrap();
+                    assert_eq!(changed["dashboard"]["title"], "Committed target");
+                    assert!(matches!(
+                        observer
+                            .create_json(
+                                &owner,
+                                &None,
+                                json!({"title":"Committed target"}),
+                                &Default::default()
+                            )
+                            .await,
+                        Err(DashboardError::Api {
+                            code: "title_conflict",
+                            ..
+                        })
+                    ));
+                    observer
+                        .create_json(
+                            &owner,
+                            &None,
+                            json!({"title":"Committed source"}),
+                            &Default::default(),
+                        )
+                        .await
+                        .unwrap();
+                } else {
+                    faulty
+                        .delete_json(
+                            &owner,
+                            dashboard_id,
+                            &None,
+                            &options(revision_of(&created), None),
+                        )
+                        .await
+                        .unwrap();
+                    assert!(matches!(
+                        observer.get_json(dashboard_id, &None).await,
+                        Err(DashboardError::Api { status: 404, .. })
+                    ));
+                    observer
+                        .create_json(
+                            &owner,
+                            &None,
+                            json!({"title":"Committed source"}),
+                            &Default::default(),
+                        )
+                        .await
+                        .unwrap();
+                }
+            }
+        }
+    }
+
+    #[tokio::test]
+    async fn failed_unkeyed_create_is_fenced_and_keyed_create_remains_retryable() {
+        for keyed in [false, true] {
+            let directory = tempfile::tempdir().unwrap();
+            let owner = actor();
+            let (service, _) =
+                fault_service(directory.path(), "/dashboards/", FaultKind::BeforeStorage);
+            let request = json!({"title":"Transient create"});
+            let opts = DashboardWriteOptions {
+                idempotency_key: keyed.then(|| "recoverable-create".into()),
+                ..Default::default()
+            };
+            assert!(
+                service
+                    .create_json(&owner, &None, request.clone(), &opts)
+                    .await
+                    .is_err()
+            );
+            let claim = service
+                .read(&title_path(&None, "Transient create"), &None)
+                .await
+                .unwrap()
+                .unwrap()
+                .0;
+            assert_eq!(claim["state"], if keyed { "pending" } else { "released" });
+            let recovered = service
+                .create_json(&owner, &None, request, &opts)
+                .await
+                .unwrap();
+            assert_eq!(recovered["dashboard"]["title"], "Transient create");
+            assert_eq!(service.list_json(&None).await.unwrap().len(), 1);
+        }
+    }
+
+    #[tokio::test]
+    async fn uncertain_rename_is_fenced_without_losing_source_content() {
+        let directory = tempfile::tempdir().unwrap();
+        let (plain, observer) = services(directory.path());
+        let owner = actor();
+        let created = plain
+            .create_json(
+                &owner,
+                &None,
+                json!({"title":"Stable old","opaque":{"preserve":[1,2,3]}}),
+                &Default::default(),
+            )
+            .await
+            .unwrap();
+        let dashboard_id = id(&created);
+        let (faulty, _) = fault_service(directory.path(), "/dashboards/", FaultKind::BeforeStorage);
+        let rename = || {
+            DashboardMutation::Metadata(HashMap::from([("renameTo".into(), "Retry target".into())]))
+        };
+        assert!(
+            faulty
+                .mutate_json(
+                    &owner,
+                    dashboard_id,
+                    &None,
+                    rename(),
+                    &options(revision_of(&created), None)
+                )
+                .await
+                .is_err()
+        );
+        let current = observer.get_json(dashboard_id, &None).await.unwrap();
+        assert_eq!(current["title"], "Stable old");
+        assert_eq!(current["opaque"], created["dashboard"]["opaque"]);
+        assert_ne!(current["revision"], created["revision"]);
+        let recovered = faulty
+            .mutate_json(
+                &owner,
+                dashboard_id,
+                &None,
+                rename(),
+                &options(current["revision"].as_str().unwrap(), None),
+            )
+            .await
+            .unwrap();
+        assert_eq!(recovered["dashboard"]["title"], "Retry target");
+    }
+
+    #[tokio::test]
+    async fn later_concurrent_edit_cannot_make_error_cleanup_release_committed_title() {
+        for rename in [false, true] {
+            let directory = tempfile::tempdir().unwrap();
+            let (plain, observer) = services(directory.path());
+            let owner = actor();
+            let (faulty, _) = fault_service(
+                directory.path(),
+                "/dashboards/",
+                FaultKind::AfterConcurrentEdit,
+            );
+            let final_title = if rename {
+                "Advanced target"
+            } else {
+                "Advanced create"
+            };
+            if rename {
+                let created = plain
+                    .create_json(
+                        &owner,
+                        &None,
+                        json!({"title":"Advanced source"}),
+                        &Default::default(),
+                    )
+                    .await
+                    .unwrap();
+                assert!(
+                    faulty
+                        .mutate_json(
+                            &owner,
+                            id(&created),
+                            &None,
+                            DashboardMutation::Metadata(HashMap::from([(
+                                "renameTo".into(),
+                                final_title.into()
+                            )])),
+                            &options(revision_of(&created), None)
+                        )
+                        .await
+                        .is_err()
+                );
+            } else {
+                assert!(
+                    faulty
+                        .create_json(
+                            &owner,
+                            &None,
+                            json!({"title":final_title}),
+                            &Default::default()
+                        )
+                        .await
+                        .is_err()
+                );
+            }
+            assert!(matches!(
+                observer
+                    .create_json(
+                        &owner,
+                        &None,
+                        json!({"title":final_title}),
+                        &Default::default()
+                    )
+                    .await,
+                Err(DashboardError::Api {
+                    code: "title_conflict",
+                    ..
+                })
+            ));
+            let listed = observer.list_json(&None).await.unwrap();
+            assert_eq!(listed.len(), 1);
+            assert_eq!(listed[0]["title"], final_title);
+            assert_eq!(listed[0]["anotherWriterChangedThis"], true);
+        }
+    }
+
+    #[tokio::test]
+    async fn released_or_stale_reservations_still_check_legacy_title_authoritatively() {
+        for state in ["released", "active"] {
+            let directory = tempfile::tempdir().unwrap();
+            let (service, _) = services(directory.path());
+            let owner = actor();
+            let legacy_id = Ulid::new();
+            let storage = LocalFS::new(directory.path().to_path_buf());
+            let legacy = json!({"title":"Legacy reserved","dashboardId":legacy_id.to_string(),"author":owner.user_id,"tiles":[]});
+            storage
+                .put_object(
+                    RelativePath::new(&dashboard_path(&None, &owner.user_id, legacy_id)),
+                    Bytes::from(serde_json::to_vec(&legacy).unwrap()),
+                    &None,
+                )
+                .await
+                .unwrap();
+            service.write(&title_path(&None,"Legacy reserved"),&json!({"state":state,"dashboardId":Ulid::new().to_string(),"title":"Legacy reserved"}),MetadataWriteCondition::Create,&None).await.unwrap();
+            assert!(matches!(
+                service
+                    .create_json(
+                        &owner,
+                        &None,
+                        json!({"title":"Legacy reserved"}),
+                        &Default::default()
+                    )
+                    .await,
+                Err(DashboardError::Api {
+                    code: "title_conflict",
+                    ..
+                })
+            ));
+        }
+    }
+}
diff --git a/src/users/dashboard_tools.rs b/src/users/dashboard_tools.rs
new file mode 100644
index 000000000..97cf617e3
--- /dev/null
+++ b/src/users/dashboard_tools.rs
@@ -0,0 +1,387 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//! Dashboard tools are thin authenticated adapters over the same service as REST.
+use super::{
+    dashboard_patch::{self, DashboardPatchRequest},
+    dashboard_service::{self, DashboardMutation},
+};
+use crate::{
+    handlers::http::{
+        middleware,
+        users::dashboards::{self, DashboardError},
+    },
+    rbac::{Response, Users, role::Action},
+    tool_catalog::ToolSpec,
+    utils::actix::extract_session_key_from_req,
+};
+use actix_web::{HttpRequest, ResponseError, web};
+use serde_json::{Value, json};
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct DashboardToolPolicy {
+    pub writes_enabled: bool,
+}
+pub fn writes_enabled(req: &HttpRequest) -> bool {
+    req.app_data::<web::Data<DashboardToolPolicy>>()
+        .is_some_and(|policy| policy.writes_enabled)
+}
+
+fn schema(properties: Value, required: &[&str]) -> Value {
+    json!({"type":"object","properties":properties,"required":required,"additionalProperties":false})
+}
+fn string(description: &str) -> Value {
+    json!({"type":"string","minLength":1,"maxLength":512,"description":description})
+}
+fn tool(
+    name: &'static str,
+    title: &'static str,
+    description: &'static str,
+    properties: Value,
+    required: &[&str],
+) -> ToolSpec {
+    ToolSpec::new(name, title, description, schema(properties, required))
+}
+fn operations() -> Value {
+    static OPERATION_SCHEMA: std::sync::LazyLock<Value> =
+        std::sync::LazyLock::new(dashboard_patch::operation_item_schema);
+    json!({"type":"array","minItems":1,"maxItems":256,"items":&*OPERATION_SCHEMA,"description":"Atomic Parseable operations addressed by stable tile, section and variable identifiers."})
+}
+
+pub fn read_specs() -> Vec<ToolSpec> {
+    vec![
+        tool(
+            "get_dashboard_capabilities",
+            "Get dashboard capabilities",
+            "Discover dashboard configuration, patch operations, chart styles, limits, and effective caller permissions.",
+            json!({}),
+            &[],
+        ),
+        tool(
+            "validate_dashboard",
+            "Validate dashboard configuration",
+            "Validate a complete configuration without writing or running SQL, PromQL, variables or dataset probes.",
+            json!({"document":{"type":"object"}}),
+            &["document"],
+        ),
+        tool(
+            "preview_dashboard_changes",
+            "Preview dashboard changes",
+            "Apply proposed changes to the current revision without saving or executing queries; returns the candidate, validation and exact diff.",
+            json!({"dashboardId":string("Dashboard ULID."),"revision":string("Revision returned by get_dashboard."),"operations":operations()}),
+            &["dashboardId", "revision", "operations"],
+        ),
+        tool(
+            "run_dashboard_queries",
+            "Run dashboard queries",
+            "Explicitly execute selected dashboard tiles with bounded query concurrency, time and results. This never saves configuration.",
+            json!({"dashboardId":string("Saved dashboard ID; or provide document."),"document":{"type":"object"},"operations":operations(),"revision":string("Source revision for proposed operations."),"tileIds":{"type":"array","maxItems":32,"items":{"type":"string"}},"startTime":string("RFC3339 inclusive start time."),"endTime":string("RFC3339 exclusive end time."),"variables":{"type":"object"},"rowLimit":{"type":"integer","minimum":1,"maximum":500}}),
+            &["startTime", "endTime"],
+        ),
+    ]
+}
+
+pub fn write_specs() -> Vec<ToolSpec> {
+    vec![
+        tool(
+            "create_dashboard",
+            "Create dashboard",
+            "Create a configured dashboard. Requires the server dashboard-agent-write policy, normal dashboard RBAC and an idempotency key.",
+            json!({"dashboard":{"type":"object"},"idempotencyKey":string("Unique retry key, bound to principal, tenant and arguments.")}),
+            &["dashboard", "idempotencyKey"],
+        ),
+        tool(
+            "update_dashboard",
+            "Update dashboard",
+            "Atomically apply an ID-addressed patch or full replacement against an observed revision. Use preview_dashboard_changes for a dry run.",
+            json!({"dashboardId":string("Dashboard ULID."),"revision":string("Observed revision."),"operations":operations(),"replacement":{"type":"object"},"idempotencyKey":string("Unique retry key.")}),
+            &["dashboardId", "revision", "idempotencyKey"],
+        ),
+        tool(
+            "save_tile",
+            "Add dashboard tile",
+            "Add one fully configured tile using its stable tile_id, conditional on the observed dashboard revision.",
+            json!({"dashboardId":string("Dashboard ULID."),"revision":string("Observed revision."),"tile":{"type":"object"},"idempotencyKey":string("Unique retry key.")}),
+            &["dashboardId", "revision", "tile", "idempotencyKey"],
+        ),
+        tool(
+            "delete_dashboard",
+            "Delete dashboard",
+            "Conditionally delete a dashboard. Requires delete permission and ownership or administrator access.",
+            json!({"dashboardId":string("Dashboard ULID."),"revision":string("Observed revision."),"idempotencyKey":string("Unique retry key.")}),
+            &["dashboardId", "revision", "idempotencyKey"],
+        ),
+    ]
+}
+
+pub fn is_dashboard_tool(name: &str) -> bool {
+    matches!(
+        name,
+        "list_dashboards"
+            | "get_dashboard"
+            | "list_dashboard_tags"
+            | "get_dashboard_capabilities"
+            | "validate_dashboard"
+            | "preview_dashboard_changes"
+            | "run_dashboard_queries"
+            | "create_dashboard"
+            | "update_dashboard"
+            | "save_tile"
+            | "delete_dashboard"
+    )
+}
+pub fn is_write(name: &str) -> bool {
+    matches!(
+        name,
+        "create_dashboard" | "update_dashboard" | "save_tile" | "delete_dashboard"
+    )
+}
+pub fn required_action(name: &str) -> Action {
+    match name {
+        "list_dashboards" | "list_dashboard_tags" => Action::ListDashboard,
+        "get_dashboard" | "get_dashboard_capabilities" => Action::GetDashboard,
+        "delete_dashboard" => Action::DeleteDashboard,
+        "run_dashboard_queries" => Action::Query,
+        _ => Action::CreateDashboard,
+    }
+}
+
+pub fn authorize(req: &HttpRequest, name: &str) -> Result<(), DashboardError> {
+    let key = extract_session_key_from_req(req).map_err(|_| {
+        DashboardError::api(
+            401,
+            "UNAUTHENTICATED",
+            "Valid authentication is required",
+            json!({}),
+        )
+    })?;
+    let action = required_action(name);
+    let tenant = crate::utils::get_tenant_id_from_request(req);
+    if let Response::Suspended(message) =
+        middleware::check_suspension_for_tenant(tenant.as_deref(), action)
+    {
+        return Err(DashboardError::api(403, "SUSPENDED", message, json!({})));
+    }
+    if Users.authorize(key, action, None, None) != Response::Authorized {
+        return Err(DashboardError::api(
+            403,
+            "FORBIDDEN",
+            "Dashboard tool permission denied",
+            json!({"action":format!("{action:?}")}),
+        ));
+    }
+    if is_write(name) && !writes_enabled(req) {
+        return Err(DashboardError::api(
+            403,
+            "AGENT_WRITES_DISABLED",
+            "External dashboard writes require P_DASHBOARD_AGENT_WRITES=true",
+            json!({}),
+        ));
+    }
+    Ok(())
+}
+fn required<'a>(args: &'a Value, key: &str) -> Result<&'a str, DashboardError> {
+    args.get(key)
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| {
+            DashboardError::api(
+                400,
+                "INVALID_ARGUMENT",
+                format!("{key} is required"),
+                json!({"path":key}),
+            )
+        })
+}
+
+pub async fn execute(req: &HttpRequest, name: &str, args: &Value) -> Result<Value, DashboardError> {
+    authorize(req, name)?;
+    let (actor, tenant) = dashboards::actor(req)?;
+    let mut options = dashboards::write_options(req)?;
+    options.expected_revision = args
+        .get("revision")
+        .and_then(Value::as_str)
+        .map(str::to_owned);
+    options.idempotency_key = args
+        .get("idempotencyKey")
+        .and_then(Value::as_str)
+        .map(str::to_owned);
+    match name {
+        "get_dashboard_capabilities" => {
+            let mut result = dashboard_patch::capabilities();
+            let key =
+                extract_session_key_from_req(req).map_err(|_| DashboardError::Unauthorized)?;
+            result["permissions"] = json!({"agentWritesEnabled":writes_enabled(req),"canCreate":Users.authorize(key.clone(),Action::CreateDashboard,None,None)==Response::Authorized,"canDelete":Users.authorize(key,Action::DeleteDashboard,None,None)==Response::Authorized,"ownerRequired":!actor.is_admin});
+            result["generatedIds"] = json!({"tileIds":(0..4).map(|_| dashboard_patch::generate_tile_id()).collect::<Vec<_>>(),"sectionIds":(0..2).map(|_| ulid::Ulid::new().to_string()).collect::<Vec<_>>()});
+            result["revisionTransport"] =
+                json!({"rest":"If-Match","tool":"revision","requiredForAgentUpdates":true});
+            Ok(result)
+        }
+        "validate_dashboard" => Ok(serde_json::to_value(dashboard_patch::validate_dashboard(
+            &args["document"],
+            None,
+        ))?),
+        "run_dashboard_queries" => super::dashboard_runtime::preview_value(req, args.clone()).await,
+        "create_dashboard" => {
+            dashboard_service::create_json(&actor, &tenant, args["dashboard"].clone(), &options)
+                .await
+        }
+        "get_dashboard" => {
+            dashboard_service::get_json(
+                crate::users::dashboards::validate_dashboard_id(
+                    required(args, "dashboardId")?.to_owned(),
+                )?,
+                &tenant,
+            )
+            .await
+        }
+        "list_dashboards" => {
+            let rows = dashboards::list_dashboards_internal(0, None, &tenant).await?;
+            let query = args
+                .get("query")
+                .and_then(Value::as_str)
+                .unwrap_or("")
+                .to_lowercase();
+            let after = args.get("after").and_then(Value::as_str).unwrap_or("");
+            let limit = args
+                .get("limit")
+                .and_then(Value::as_u64)
+                .unwrap_or(100)
+                .clamp(1, 500) as usize;
+            let mut matching = rows
+                .into_iter()
+                .filter(|d| {
+                    d["dashboardId"].as_str().is_some_and(|id| id > after)
+                        && d["title"]
+                            .as_str()
+                            .unwrap_or("")
+                            .to_lowercase()
+                            .contains(&query)
+                })
+                .collect::<Vec<_>>();
+            matching.sort_by(|a, b| a["dashboardId"].as_str().cmp(&b["dashboardId"].as_str()));
+            let more = matching.len() > limit;
+            matching.truncate(limit);
+            let next = more.then(|| {
+                matching
+                    .last()
+                    .and_then(|v| v["dashboardId"].as_str())
+                    .unwrap_or("")
+                    .to_owned()
+            });
+            Ok(json!({"dashboards":matching,"nextCursor":next}))
+        }
+        "list_dashboard_tags" => Ok(json!(dashboards::list_tags_internal(&tenant).await?)),
+        "preview_dashboard_changes" | "update_dashboard" | "save_tile" | "delete_dashboard" => {
+            let id = crate::users::dashboards::validate_dashboard_id(
+                required(args, "dashboardId")?.to_owned(),
+            )?;
+            if options.expected_revision.is_none() {
+                return Err(DashboardError::api(
+                    428,
+                    "REVISION_REQUIRED",
+                    "An observed dashboard revision is required",
+                    json!({}),
+                ));
+            }
+            if name == "delete_dashboard" {
+                dashboard_service::delete_json(&actor, id, &tenant, &options).await?;
+                return Ok(json!({"deleted":true,"dashboardId":id.to_string()}));
+            }
+            let mutation = if name == "save_tile" {
+                DashboardMutation::AddTile(args["tile"].clone())
+            } else if let Some(operations) = args.get("operations") {
+                if args.get("replacement").is_some() {
+                    return Err(DashboardError::api(
+                        400,
+                        "INVALID_ARGUMENT",
+                        "Choose operations or replacement",
+                        json!({}),
+                    ));
+                }
+                let patch: DashboardPatchRequest =
+                    serde_json::from_value(json!({"operations":operations} ))?;
+                DashboardMutation::Patch(patch.operations)
+            } else {
+                DashboardMutation::Replace(args.get("replacement").cloned().ok_or_else(|| {
+                    DashboardError::api(
+                        400,
+                        "INVALID_ARGUMENT",
+                        "Provide operations or replacement",
+                        json!({}),
+                    )
+                })?)
+            };
+            options.dry_run = name == "preview_dashboard_changes";
+            dashboard_service::mutate_json(&actor, id, &tenant, mutation, &options).await
+        }
+        _ => Err(DashboardError::api(
+            404,
+            "UNKNOWN_TOOL",
+            "Unknown dashboard tool",
+            json!({}),
+        )),
+    }
+}
+
+pub fn tool_error(error: &DashboardError) -> Value {
+    json!({"code":error.detail()["code"],"message":error.to_string(),"status":error.status_code().as_u16(),"details":error.detail()["details"]})
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn dashboard_write_catalog_is_explicit_and_small() {
+        assert_eq!(
+            write_specs().iter().map(|t| t.name).collect::<Vec<_>>(),
+            vec![
+                "create_dashboard",
+                "update_dashboard",
+                "save_tile",
+                "delete_dashboard"
+            ]
+        );
+        assert!(!is_write("create_alert"));
+        assert!(read_specs().iter().all(|t| !is_write(t.name)));
+    }
+    #[test]
+    fn mutation_schema_requires_revision_and_retry_identity() {
+        for tool in write_specs()
+            .into_iter()
+            .filter(|t| t.name != "create_dashboard")
+        {
+            assert!(
+                tool.validate_arguments(&json!({"dashboardId":"id","idempotencyKey":"key"}))
+                    .is_err()
+            );
+        }
+    }
+}
+
+pub fn output_schema(name: &str) -> Option<Value> {
+    let string = json!({"type":"string"});
+    let document = json!({"type":"object","properties":{"dashboardId":string,"title":{"type":"string"},"revision":{"type":"string"}},"required":["dashboardId","title","revision"],"additionalProperties":true});
+    let result = match name {
+        "get_dashboard" => document.clone(),
+        "create_dashboard" | "update_dashboard" | "save_tile" | "preview_dashboard_changes" => {
+            json!({"type":"object","properties":{"dashboard":document,"revision":{"type":"string"},"validation":{"type":"object"},"diff":{"type":"array"},"replayed":{"type":"boolean"}},"required":["dashboard","revision","validation","diff"],"additionalProperties":true})
+        }
+        "list_dashboards" => {
+            json!({"type":"object","properties":{"dashboards":{"type":"array","items":{"type":"object"}},"nextCursor":{"type":["string","null"]}},"required":["dashboards","nextCursor"]})
+        }
+        "list_dashboard_tags" => json!({"type":"array","items":{"type":"string"}}),
+        "validate_dashboard" => {
+            json!({"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array"},"warnings":{"type":"array"}},"required":["valid","errors","warnings"]})
+        }
+        "delete_dashboard" => {
+            json!({"type":"object","properties":{"deleted":{"type":"boolean"},"dashboardId":{"type":"string"}},"required":["deleted","dashboardId"]})
+        }
+        "run_dashboard_queries" => {
+            json!({"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}}},"required":["results"],"additionalProperties":true})
+        }
+        "get_dashboard_capabilities" => json!({"type":"object","additionalProperties":true}),
+        _ => return None,
+    };
+    Some(
+        json!({"type":"object","properties":{"result":result,"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["message"]}},"anyOf":[{"required":["result"]},{"required":["error"]}]}),
+    )
+}
diff --git a/src/users/dashboards.rs b/src/users/dashboards.rs
index 8b8bfde40..ed4c6c851 100644
--- a/src/users/dashboards.rs
+++ b/src/users/dashboards.rs
@@ -16,20 +16,17 @@
  *
  */
 
-use std::collections::HashMap;
-
 use chrono::{DateTime, Utc};
 use once_cell::sync::Lazy;
 use relative_path::RelativePathBuf;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
-use tokio::sync::RwLock;
 use ulid::Ulid;
 
 use crate::{
     handlers::http::users::{DASHBOARDS_DIR, USERS_ROOT_DIR, dashboards::DashboardError},
     metastore::metastore_traits::MetastoreObject,
-    parseable::{DEFAULT_TENANT, PARSEABLE},
+    parseable::PARSEABLE,
 };
 
 pub static DASHBOARDS: Lazy<Dashboards> = Lazy::new(Dashboards::default);
@@ -189,6 +186,13 @@ impl Dashboard {
             serde_json::Value::Bool(self.is_favorite.unwrap_or(false)),
         );
 
+        if let Some(revision) = self
+            .other_fields
+            .as_ref()
+            .and_then(|fields| fields.get("revision"))
+        {
+            map.insert("revision".into(), revision.clone());
+        }
         map
     }
 }
@@ -201,101 +205,40 @@ pub fn validate_dashboard_id(dashboard_id: String) -> Result<Ulid, DashboardErro
         .map_err(|_| DashboardError::Metadata("Invalid dashboard ID format - must be a valid ULID"))
 }
 
+/// Compatibility facade. Authoritative state and all writes live in the shared
+/// dashboard service; no in-memory snapshot is used to authorize or persist.
 #[derive(Default, Debug)]
-pub struct Dashboards(RwLock<HashMap<String, Vec<Dashboard>>>);
+pub struct Dashboards;
 
 impl Dashboards {
-    /// Load all dashboards from the object store
-    /// and store them in memory
-    /// This function is called on server start
     pub async fn load(&self) -> anyhow::Result<()> {
-        let mut this: HashMap<String, Vec<Dashboard>> = HashMap::new();
-
-        let all_dashboards = PARSEABLE.metastore.get_dashboards().await?;
-
-        for (tenant_id, dashboards) in all_dashboards {
-            let mut tenant_dbs = Vec::new();
-
-            if dashboards.is_empty() {
-                continue;
-            }
-
-            for dashboard in dashboards {
-                let dashboard_value = match serde_json::from_slice::<serde_json::Value>(&dashboard)
-                {
-                    Ok(value) => value,
-                    Err(err) => {
-                        tracing::warn!("Failed to parse dashboard JSON: {}", err);
-                        continue;
-                    }
-                };
-
-                if let Ok(dashboard) = serde_json::from_value::<Dashboard>(dashboard_value.clone())
-                {
-                    tenant_dbs.retain(|d: &Dashboard| d.dashboard_id != dashboard.dashboard_id);
-                    tenant_dbs.push(dashboard);
-                } else {
-                    tracing::warn!("Failed to deserialize dashboard: {:?}", dashboard_value);
-                }
-            }
-
-            this.entry(tenant_id).or_default().extend(tenant_dbs);
-        }
-
-        let mut s = self.0.write().await;
-        // s.append(&mut this);
-        s.clone_from(&this);
-
-        Ok(())
-    }
-
-    /// Save the dashboard to the object store
-    /// This function is called when creating or updating a dashboard
-    async fn save_dashboard(
-        &self,
-        // user_id: &str,
-        dashboard: &Dashboard,
-        tenant_id: &Option<String>,
-    ) -> Result<(), DashboardError> {
-        PARSEABLE
-            .metastore
-            .put_dashboard(dashboard, tenant_id)
-            .await?;
-
+        // Keep the startup connectivity check without retaining a stale copy of
+        // documents that other query nodes/agents can subsequently modify.
+        PARSEABLE.metastore.get_dashboards().await?;
         Ok(())
     }
 
-    /// Create a new dashboard
-    /// This function is called when creating a new dashboard
-    /// add dashboard in memory and save it to the object store
     pub async fn create(
         &self,
         user_id: &str,
         dashboard: &mut Dashboard,
         tenant_id: &Option<String>,
     ) -> Result<(), DashboardError> {
-        dashboard.created = Some(Utc::now());
-        dashboard.set_metadata(user_id, None);
-        let tenant = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-        let mut dashboards = self.0.write().await;
-
-        let dbs = dashboards.entry(tenant.to_owned()).or_default();
-        let has_duplicate = dbs
-            .iter()
-            .any(|d| d.title == dashboard.title && d.dashboard_id != dashboard.dashboard_id);
-        if has_duplicate {
-            return Err(DashboardError::Metadata("Dashboard title must be unique"));
-        }
-        self.save_dashboard(dashboard, tenant_id).await?;
-
-        dbs.push(dashboard.clone());
-
+        let actor = super::dashboard_service::DashboardActor {
+            user_id: user_id.to_owned(),
+            is_admin: false,
+        };
+        let result = super::dashboard_service::create_json(
+            &actor,
+            tenant_id,
+            serde_json::to_value(&*dashboard)?,
+            &Default::default(),
+        )
+        .await?;
+        *dashboard = serde_json::from_value(result["dashboard"].clone())?;
         Ok(())
     }
 
-    /// Update an existing dashboard
-    /// This function is called when updating a dashboard
-    /// update dashboard in memory and save it to the object store
     pub async fn update(
         &self,
         user_id: &str,
@@ -303,57 +246,30 @@ impl Dashboards {
         dashboard: &mut Dashboard,
         tenant_id: &Option<String>,
     ) -> Result<(), DashboardError> {
-        let mut dashboards = self.0.write().await;
-        let tenant = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-        if let Some(dbs) = dashboards.get_mut(tenant) {
-            let existing_dashboard = dbs
-                .iter()
-                .find(|d| {
-                    d.dashboard_id == Some(dashboard_id) && d.author == Some(user_id.to_string())
-                })
-                .cloned()
-                .ok_or_else(|| {
-                    DashboardError::Metadata(
-                        "Dashboard does not exist or you do not have permission to access it",
-                    )
-                })?;
-            dashboard.set_metadata(user_id, Some(dashboard_id));
-            dashboard.created = existing_dashboard.created;
-
-            let has_duplicate = dbs
-                .iter()
-                .any(|d| d.title == dashboard.title && d.dashboard_id != dashboard.dashboard_id);
-
-            if has_duplicate {
-                return Err(DashboardError::Metadata("Dashboard title must be unique"));
-            }
-
-            self.save_dashboard(dashboard, tenant_id).await?;
-
-            dbs.retain(|d| d.dashboard_id != Some(dashboard_id));
-            dbs.push(dashboard.clone());
-        } else {
-            return Err(DashboardError::Metadata(
-                "Dashboard does not exist or you do not have permission to access it",
-            ));
+        let actor = super::dashboard_service::DashboardActor {
+            user_id: user_id.to_owned(),
+            is_admin: false,
         };
-
-        // let existing_dashboard = dashboards
-        //     .iter()
-        //     .find(|d| d.dashboard_id == Some(dashboard_id) && d.author == Some(user_id.to_string()))
-        //     .cloned()
-        //     .ok_or_else(|| {
-        //         DashboardError::Metadata(
-        //             "Dashboard does not exist or you do not have permission to access it",
-        //         )
-        //     })?;
-
+        let document = serde_json::to_value(&*dashboard)?;
+        let options = super::dashboard_service::DashboardWriteOptions {
+            expected_revision: document
+                .get("revision")
+                .and_then(Value::as_str)
+                .map(str::to_owned),
+            ..Default::default()
+        };
+        let result = super::dashboard_service::mutate_json(
+            &actor,
+            dashboard_id,
+            tenant_id,
+            super::dashboard_service::DashboardMutation::Replace(document),
+            &options,
+        )
+        .await?;
+        *dashboard = serde_json::from_value(result["dashboard"].clone())?;
         Ok(())
     }
 
-    /// Delete a dashboard
-    /// This function is called when deleting a dashboard
-    /// delete dashboard in memory and from the object store
     pub async fn delete_dashboard(
         &self,
         user_id: &str,
@@ -361,55 +277,28 @@ impl Dashboards {
         is_admin: bool,
         tenant_id: &Option<String>,
     ) -> Result<(), DashboardError> {
-        let obj = self
-            .ensure_dashboard_ownership(dashboard_id, user_id, is_admin, tenant_id)
-            .await?;
-
-        {
-            // validation has happened, dashboard exists and can be deleted by the user
-            PARSEABLE
-                .metastore
-                .delete_dashboard(&obj, tenant_id)
-                .await?;
-        }
-
-        // delete from in-memory
-        self.0
-            .write()
+        let actor = super::dashboard_service::DashboardActor {
+            user_id: user_id.to_owned(),
+            is_admin,
+        };
+        super::dashboard_service::delete_json(&actor, dashboard_id, tenant_id, &Default::default())
             .await
-            .get_mut(tenant_id.as_deref().unwrap_or(DEFAULT_TENANT))
-            .map(|dashboards| dashboards.retain(|d| d.dashboard_id != Some(dashboard_id)))
-            .iter()
-            .for_each(drop);
-
-        Ok(())
     }
 
-    /// Get a dashboard by ID
-    /// fetch dashboard from memory
     pub async fn get_dashboard(
         &self,
         dashboard_id: Ulid,
         tenant_id: &Option<String>,
     ) -> Option<Dashboard> {
-        let tenant_id = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-        let dashboards = self.0.read().await;
-        if let Some(dashboards) = dashboards.get(tenant_id) {
-            dashboards
-                .iter()
-                .find(|d| {
-                    d.dashboard_id
-                        .as_ref()
-                        .is_some_and(|id| *id == dashboard_id)
-                })
-                .cloned()
-        } else {
-            None
+        match super::dashboard_service::get_json(dashboard_id, tenant_id).await {
+            Ok(document) => serde_json::from_value(document).ok(),
+            Err(error) => {
+                tracing::debug!(%error,"Dashboard compatibility lookup failed");
+                None
+            }
         }
     }
 
-    /// Get a dashboard by ID and user ID
-    /// fetch dashboard from memory
     pub async fn get_dashboard_by_user(
         &self,
         dashboard_id: Ulid,
@@ -417,143 +306,65 @@ impl Dashboards {
         is_admin: bool,
         tenant_id: &Option<String>,
     ) -> Option<Dashboard> {
-        let tenant_id = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-        let dashboards = self.0.read().await;
-        if let Some(dashboards) = dashboards.get(tenant_id) {
-            dashboards
-                .iter()
-                .find(|d| {
-                    d.dashboard_id
-                        .as_ref()
-                        .is_some_and(|id| *id == dashboard_id)
-                        && (d.author == Some(user_id.to_string()) || is_admin)
-                })
-                .cloned()
-        } else {
-            None
-        }
-        // self.0
-        //     .read()
-        //     .await
-        //     .iter()
-        //     .find(|d| {
-        //         d.dashboard_id
-        //             .as_ref()
-        //             .is_some_and(|id| *id == dashboard_id)
-        //             && (d.author == Some(user_id.to_string()) || is_admin)
-        //     })
-        //     .cloned()
+        self.get_dashboard(dashboard_id, tenant_id)
+            .await
+            .filter(|dashboard| is_admin || dashboard.author.as_deref() == Some(user_id))
     }
 
-    /// List all dashboards
-    /// fetch all dashboards from memory
     pub async fn list_dashboards(
         &self,
         limit: usize,
         tenant_id: &Option<String>,
     ) -> Vec<Dashboard> {
-        // limit the number of dashboards returned in order of modified date
-        // if limit is 0, return all dashboards
-        let tenant_id = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-        let dashboards = self.0.read().await;
-
-        let mut sorted_dashboards = if let Some(dashboards) = dashboards.get(tenant_id) {
-            dashboards
-                .iter()
-                .filter(|d| d.dashboard_id.is_some())
-                .cloned()
-                .collect::<Vec<Dashboard>>()
-        } else {
-            vec![]
+        let mut dashboards = match super::dashboard_service::list_json(tenant_id).await {
+            Ok(documents) => documents
+                .into_iter()
+                .filter_map(|document| serde_json::from_value(document).ok())
+                .collect::<Vec<Dashboard>>(),
+            Err(error) => {
+                tracing::warn!(%error,"Dashboard compatibility listing failed");
+                Vec::new()
+            }
         };
-
-        // let mut sorted_dashboards = dashboards
-        //     .iter()
-        //     .filter(|d| d.dashboard_id.is_some())
-        //     .cloned()
-        //     .collect::<Vec<Dashboard>>();
-        sorted_dashboards.sort_by_key(|d| std::cmp::Reverse(d.modified));
+        dashboards.sort_by_key(|dashboard| std::cmp::Reverse(dashboard.modified));
         if limit > 0 {
-            sorted_dashboards.truncate(limit);
+            dashboards.truncate(limit);
         }
-        sorted_dashboards
+        dashboards
     }
 
-    /// List tags from all dashboards
-    /// This function returns a list of unique tags from all dashboards
     pub async fn list_tags(&self, tenant_id: &Option<String>) -> Vec<String> {
-        let tenant_id = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-        let dashboards = self.0.read().await;
-        let mut tags = if let Some(dashboards) = dashboards.get(tenant_id) {
-            dashboards
-                .iter()
-                .filter_map(|d| d.tags.as_ref())
-                .flat_map(|t| t.iter().cloned())
-                .collect::<Vec<String>>()
-        } else {
-            vec![]
-        };
-        // let mut tags = dashboards
-        //     .iter()
-        //     .filter_map(|d| d.tags.as_ref())
-        //     .flat_map(|t| t.iter().cloned())
-        //     .collect::<Vec<String>>();
+        let mut tags = self
+            .list_dashboards(0, tenant_id)
+            .await
+            .into_iter()
+            .filter_map(|dashboard| dashboard.tags)
+            .flatten()
+            .collect::<Vec<_>>();
         tags.sort();
         tags.dedup();
         tags
     }
 
-    /// List dashboards by tag
-    /// This function returns a list of dashboards that match any of the provided tags
-    /// If no tags are provided, it returns an empty list
     pub async fn list_dashboards_by_tags(
         &self,
         tags: Vec<String>,
         tenant_id: &Option<String>,
     ) -> Vec<Dashboard> {
-        let tenant_id = tenant_id.as_deref().unwrap_or(DEFAULT_TENANT);
-        let dashboards = self.0.read().await;
-        if let Some(dashboards) = dashboards.get(tenant_id) {
-            dashboards
-                .iter()
-                .filter(|d| {
-                    if let Some(dashboard_tags) = &d.tags {
-                        dashboard_tags
-                            .iter()
-                            .any(|dashboard_tag| tags.contains(dashboard_tag))
-                    } else {
-                        false
-                    }
-                })
-                .cloned()
-                .collect()
-        } else {
-            vec![]
-        }
+        self.list_dashboards(0, tenant_id)
+            .await
+            .into_iter()
+            .filter(|dashboard| {
+                dashboard
+                    .tags
+                    .as_ref()
+                    .is_some_and(|stored| stored.iter().any(|tag| tags.contains(tag)))
+            })
+            .collect()
     }
 
     pub async fn delete_tenant(&self, tenant_id: &str) {
-        self.0.write().await.remove(tenant_id);
-    }
-
-    /// Ensure the user is the owner of the dashboard
-    /// This function is called when updating or deleting a dashboard
-    /// check if the user is the owner of the dashboard
-    /// if the user is not the owner, return an error
-    async fn ensure_dashboard_ownership(
-        &self,
-        dashboard_id: Ulid,
-        user_id: &str,
-        is_admin: bool,
-        tenant_id: &Option<String>,
-    ) -> Result<Dashboard, DashboardError> {
-        self.get_dashboard_by_user(dashboard_id, user_id, is_admin, tenant_id)
-            .await
-            .ok_or_else(|| {
-                DashboardError::Metadata(
-                    "Dashboard does not exist or you do not have permission to access it",
-                )
-            })
+        super::dashboard_service::forget_tenant(tenant_id);
     }
 }
 
diff --git a/src/users/mod.rs b/src/users/mod.rs
index c48afcd2b..bb7153b5e 100644
--- a/src/users/mod.rs
+++ b/src/users/mod.rs
@@ -16,6 +16,7 @@
  *
  */
 
+pub mod dashboard_patch;
 pub mod dashboards;
 pub mod filters;
 
@@ -26,3 +27,9 @@ pub struct TimeFilter {
     to: String,
     from: String,
 }
+
+pub mod dashboard_service;
+
+pub mod dashboard_tools;
+
+pub mod dashboard_runtime;