refactor: extract the shared query model behind dashboards and alerts

[Makisuo]

Groundwork for making dashboard widgets and alert rules share one query model. This is phases 1–3 of a larger refactor; each commit is independently shippable and nothing here changes a persisted schema or a wire shape yet.

Why

Widgets and alert rules describe the same thing — a warehouse query plus how to draw it — but store it incompatibly:

• Widget: { endpoint: string, params: Record<string, unknown> }, where endpoint names a web-side server function and params is untyped.
• Alert rule: a typed queryBuilderDraft plus a server-compiled querySpecJson.

Both lower through the same shared code (buildTimeseriesQuerySpec, resolveGroupBy). The incompatibility is purely at the storage/type boundary — and it is what forces the downstream duplication: "create an alert from this chart" needs a 287-line translator that sniffs endpoint strings and runtime-validates a bag, the metric-selection hook exists twice, and variable interpolation has to guess which strings are where-clauses by key name.

What changed

1. @maple/query-model — the leaf the codebase already asked for.

packages/widgets/src/index.ts named this exact blocker:

QueryBuilderQueryDraftSchema. Alert rules persist it too, so it is a shared query primitive rather than a widget concept; it stays in @maple/domain/http until it gets a leaf of its own.

@maple/widgets sits below @maple/domain (domain's MapleApi embeds the widget schemas), so a widget schema cannot reach up for the draft. The new package depends on @maple/primitives + effect only, so both halves can import it. It holds the draft schemas, TimeRangeSchema, and a new QuerySetSchema (queries + formulas + comparison) — the value both surfaces will eventually store.

Pure move: every previous export is re-exported from its old home, so no call site changed.

2. Collapsed duplicated backend plumbing.

Bucket sizing had four implementations, not the one the module header claims — the canonical one, a private ladder in the raw-SQL route whose comment pointed at a file deleted long ago, an alias that just called the shared one under a second name, and a copy in apps/mobile. The private ladder differed in exactly two ways (a 30-point target, a 300s floor), so ComputeBucketSecondsOptions now expresses the floor as minBucketSeconds. Tests pin the deleted ladder's outputs.

Reducers were declared five times, including a copy in settings-fields.tsx that shadowed the shared set and was hand-maintained separately from the schema validating it. All now derive from one table. The two literal sets stay distinct on purpose — widgets persist "first", rules persist "identity", and they coincide only on a one-bucket window — but a reducer added to one must now declare whether it has a counterpart in the other.

toStorageGroupKey names the engine-vs-storage group-key boundary ("all" vs "__total__"), previously open-coded at each site. An alert_rule_states row keyed "all" is invisible to every reader.

3. Version-agnostic data-source accessors.

Every backend consumer that reached into dataSource.endpoint/.params by hand now goes through accessors reading both the current shape and the planned typed union. access.test.ts states both shapes per case and asserts one result, so a drift fails there rather than at cutover. This is what keeps the eventual flip a small diff.

Bugs fixed along the way

• migrateToLatest restamped documents from a newer build downward. Unknown versions read as version 1, so a rollback would run a newer document through the whole migration chain as the oldest shape and then stamp it current. Decode fails either way — but stamped, the next writer persists the lie and the original version is gone. Failing to read is recoverable; corrupting is not.
• Wrote the guard test display.ts has been citing by name. It points at params/interpolation-keys.test.ts to protect the load-bearing listWhereClause field; that file did not exist. Interpolation picks formatting by key name, so renaming that field compiles, passes every schema, and silently changes behaviour. The test pins the real failure shape: a renamed key stops dropping an All-selected clause and expands it to environment = prd,stg — a filter matching nothing, where the user asked for no filter at all.

For the reviewer

One finding that changes the plan for the follow-up PR. apps/mobile fetches /api/dashboards/ — the v1 API — and dispatches by reading dataSource.endpoint/.params directly. v1's DashboardsListResponse embeds DashboardDocument, the alias bound to the current schema version, so bumping that version changes the v1 wire. Plans for the typed union protect the v2 wire (which declares its own shape and has a parity test); nothing protects v1.

Mobile also has zero @maple/* dependencies by design, so it will not fail to typecheck when a shared schema changes — it breaks at runtime, in a build that cannot be force-updated. The cutover must therefore encode back to the legacy {endpoint, params} shape on both v1 and v2, with parity tests on each. Nothing in this PR is affected.

Two places I deliberately did not dedupe, because the apparent duplication is real distinction:

• The editor-state draft interface has every field required; the stored schema has them all optional. The builder always holds a populated draft (an empty where-clause is "", not absent); a stored one omits what the user never set. Merging them would make whereClause possibly-undefined at every read in the builder to buy nothing.
• apps/web/.../timeseries-utils.ts looks like a fifth bucket-sizing copy but already delegates to the canonical one, adding string parsing and invalid-input fallback. Left alone.

apps/mobile keeps its own copy of computeBucketSeconds for the dependency reason above; it now says so in a comment.

Verification

• bun typecheck — 41/41 tasks pass, on every commit.
• 91 widgets, 243 alert, 224 api mcp/dashboard, 57 datetime, 13 query-model tests pass.
• No persisted schema, wire shape, or user-visible behaviour changes in this PR. The reducer picker order and every bucket-sizing output are preserved by test.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}