fix(api,web,db): optimistic-locking for dashboards + service-map nested aggregate

[Makisuo]

Summary

Closes Section 4 (dashboard concurrency / lost updates) and Section 6 (service-map nested-aggregate SQL error) of the DeepSec triage in .claude/plans/we-created-an-depsec-cuddly-tarjan.md.

• Dashboards now use optimistic concurrency via a new dashboards.version column + CAS upsert. Two concurrent MCP calls or browser edits can no longer silently lose one update; the loser surfaces a typed DashboardConcurrencyError (HTTP 409) and the web hook auto-refetches.
• Service map ClickHouse query no longer trips the UNION-ALL+GROUP-BY optimizer into producing sum(sum(...)); aliases are renamed and the average is now properly weighted across MV + raw branches.

What changed

Schema (held until human review)

• packages/db/drizzle/0009_dashboard_versioning.sql — adds dashboards.version INTEGER NOT NULL DEFAULT 0 and a unique index on dashboard_versions(org_id, dashboard_id, version_number).
• packages/db/src/schema/dashboards.ts, packages/db/drizzle/meta/0009_snapshot.json, _journal.json updated to match.

Domain

• DashboardConcurrencyError (HTTP 409) added to @maple/domain/http. Wired into the upsert, restoreVersion, create, and instantiateTemplate HTTP endpoints' error unions.

Persistence

• DashboardPersistenceService.upsert now reads current version and runs UPDATE ... WHERE id = ? AND version = ?. Zero rows affected → conflict.
• New DashboardPersistenceService.mutate(orgId, userId, dashboardId, transform) runs the read-CAS-write loop with up to 5 retries before surfacing the typed conflict. The MCP withDashboardMutation helper now delegates to it, so every widget tool inherits retry-on-conflict.

MCP tools

• update-dashboard: preserves existing.variables in both the metadata-only and full-replacement branches (the full-replacement path was silently wiping it).
• reorder-dashboard-widgets: server-side geometry validation (x>=0, y>=0, 1<=w<=12, h>=1, x+w<=12).

Web client

• useDashboardStore now serializes mutations per dashboard with a FIFO queue (Map<id, Promise>), so back-to-back edits can't race against each other.
• On DashboardConcurrencyError the optimistic update rolls back, a banner surfaces the conflict, and useAtomRefresh triggers a refetch — the existing list-result effect clears the banner once fresh state lands.

Service map (separate root-cause, same PR)

• Inner branches in serviceDependenciesSQL and serviceDbEdgesSQL expose distinct bucket* aliases so the outer sum(...) AS callCount has no inner name to fold against.
• Outer average switched from avg(avgDurationMs) (averaging averages) to sum(bucketDurationSumMs) / nullIf(sum(bucketCallCount), 0) (properly weighted across branches).
• MV branch reads Hour < toStartOfHour(endTime) only; raw branch reads Timestamp >= toStartOfHour(endTime) to endTime. Previously both overlapped on the trailing hour and double-counted spans.

Tests

• apps/api/src/mcp/tools/__tests__/dashboard-concurrency.test.ts — 3 vitest cases:
  1. Two concurrent mutate calls both land via retry — no lost update.
  2. Two concurrent upsert calls — loser surfaces DashboardConcurrencyError instead of silently overwriting.
  3. After a conflict, a refetch+retry resolves cleanly.

Whole api test suite (279 tests across 20 files) green.

Test plan

• bun typecheck clean on @maple/api, @maple/web, @maple/db, @maple/domain, @maple/query-engine (only pre-existing unrelated worker.ts import error remains)
• bun test from apps/api — 279 pass, 0 fail
• D1 migration 0009_dashboard_versioning.sql applies cleanly via wrangler d1 migrations apply --local
• Browser preview verified: created a dashboard (version=1, audit row created), added a Bar Chart widget (version=2, audit row widget_added), fired two parallel PUT /api/dashboards/:id requests (both committed against fresh state, version advanced 2→4 — local D1 serializes so neither write actually overlapped, but both succeeded which is the correct CAS behavior; the actual race-window assertion is covered by the unit tests)
• Browser preview verified: service-map page renders cleanly — previously failed with the nested-aggregate SQL error, now returns 200 OK with proper content
• Generated SQL inspected: zero sum(sum(...)) patterns, single AS callCount (outer only) in both queries

Reviewer notes

• Schema migration apply is held per the plan — please review 0009_dashboard_versioning.sql before running it through the release flow. SQLite-friendly (ADD COLUMN ... DEFAULT 0 NOT NULL), no backfill required.
• HTTP upsert does single-attempt CAS (no retry) so the client gets a 409 to refetch from. MCP mutate retries internally because the transform is re-applied on top of fresh state — that's safe; HTTP retry would silently overwrite.
• recordVersion is still wrapped in Effect.ignore (best-effort audit). The new unique index protects against duplicate version_number rows under racy recordVersion calls; the worst case is a missed audit row, which is acceptable given the dashboard-table CAS guarantees the actual state is consistent.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

[pullfrog]

This run croaked 😵

The workflow encountered an error before any progress could be reported. Please check the link below for details.

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ 𝕏}