Spike: sqlc -> Clojure query codegen with Malli schemas

Generate Clojure query fns with Malli result schemas from .sql files, using
sqlc for SQL parsing and type inference and sqlc-gen-json to expose its
analysis as JSON.

Verified end to end: migrations against Postgres 16 (1427 changesets, 190
tables), pg_dump fed to sqlc unmodified, real queries ported from the
glossary/sso HugSQL spike branches, and the generated file compiles with
schemas that accept valid rows and reject bad ones.

See dev/src/dev/sqlc/README.md for open issues (no H2 engine, weak param
type inference, no dynamic SQL).

.claude/agents/modules-backend-expert.md

@@ -81,7 +81,7 @@ Everything else in the module is **internal** and not allowed to be referenced f
 
 `dev/src/dev/modularization_help.clj` — `potemkin-ns!` helper that generates `.core` re-export boilerplate from a target namespace.
 
-`test/metabase/core/modules_test.clj` — runs on config changes; validates structure, team assignments, API and model boundaries.
+`dev/test/metabase/core/modules_test.clj` — runs on config changes; validates structure, team assignments, API and model boundaries.
 
 ### API Design Inside a Module
 
@@ -119,7 +119,7 @@ When the linter complains, the answer is **always refactoring**, never suppressi
 - `dev/src/dev/module_score.clj` — quality scoring
 - `dev/src/dev/modularization_help.clj` — Potemkin re-export helper
 - `dev/src/dev/model_boundary_config.clj` + `dev/src/dev/model_tracking.clj` — model-level enforcement
-- `test/metabase/core/modules_test.clj` — config validation tests
+- `dev/test/metabase/core/modules_test.clj` — config validation tests
 - `src/metabase/core/init.clj` — OSS module init aggregation
 - `enterprise/backend/src/metabase_enterprise/core/init.clj` — EE module init aggregation
 - `src/metabase/models/resolution.clj` — `:model/X` keyword → namespace map
@@ -198,6 +198,6 @@ Use the `clojure-eval` skill (preferred) or `clj-nrepl-eval` to drive the dev to
 (dev.module-score/scores (dev.module-score/deps) (dev.module-score/config))
 ```
 
-For tests of the config itself, use `./bin/test-agent :only '[metabase.core.modules-test]'`. After editing Clojure files, run `clj-paren-repair`. After editing `config.edn`, re-run the modules-test.
+For tests of the config itself, use `./bin/mage project-tests modules`. After editing Clojure files, run `clj-paren-repair`. After editing `config.edn`, re-run the modules-test.
 
 **Update your agent memory** as you discover idioms: which modules use `:friends` and why, which models are most-imported (suggesting they belong in their own module), which settings are accessed cross-module via `(setting/get …)` instead of `:uses` deps, and which refactors the team is actively running.

.claude/commands/fix-flaky-test.md

@@ -1,297 +0,0 @@
----
-description: Diagnose and fix a flaky Cypress e2e test, then verify the fix with CI stress runs in a bounded loop
----
-
-Fix flaky e2e test: $ARGUMENTS
-
-You are orchestrating a **bounded flake-fix loop** with a real CI feedback signal. The
-only integration tool for the loop is `gh` (trigger the stress workflow + read results).
-The Linear issue is the input. Everything else is reasoning over files.
-
-**Hard rules — do not deviate:**
-- **Max 3 attempts.** One attempt = diagnose → fix → push → 2 stress runs → interpret.
-  After 3 failed attempts, stop and hand back.
-- **Branch existence is the go/no-go gate.** Before starting, check whether the remote branch
-  `automated-e2e-flake-fix-<LINEAR_ID>` already exists (Phase 0). If it does, a run
-  is already in flight (or already landed a fix) → **stop, do nothing**. If it doesn't,
-  proceed through the whole loop and push without pausing for confirmation. This runs
-  identically whether a human or automation triggered the command.
-- **Linear access:** prefer the Linear MCP (`mcp__linear__*`); if it's unavailable (e.g.
-  headless CI), fall back to the Linear REST/GraphQL API with a token — for both reads and
-  comment writes.
-- **Always write to the *resolved* issue, never the raw `$ARGUMENTS` ref.** Issues are born
-  `DEV-####` and **re-keyed when moved to another team** (`DEV-2180` → `UXW-4514`). `get_issue`
-  resolves the old ref (it's redirect-aware), but `list_comments`/`save_comment` with the stale
-  ref **404**. Capture the issue's UUID + current identifier in Phase 0 and use the **UUID** for
-  every Linear read/write.
-- **Heartbeat — post progress at every phase boundary.** It's the only run-visibility in
-  headless CI (the GH job log isn't streamed live), so never skip it. Prefer ONE rolling comment
-  (record its id in the state file, update it in place); if your write path can't update, post
-  terse per-phase comments instead. Update at: run start (+ `GITHUB_ACTIONS_RUN_URL` if set),
-  diagnosis done (#1 reason + hypothesis), branch pushed + **both stress run URLs**, and each
-  attempt's verdict.
-- **Each attempt triggers TWO stress runs in parallel** — `enable_network_throttling=true`
-  and `=false` — on the same branch/commit. The fix is verified only if **both** pass.
-- **CI is the source of truth.** No local Cypress runs, no `bin/` stress scripts.
-- **Branch names use `-` only, never `/`.**
-- **Persist state** to a scratch file so the loop survives `ScheduleWakeup` and context
-  summarization.
-
----
-
-## Phase 0 — Resolve the target
-
-1. Parse `$ARGUMENTS`:
-   - If it's a Linear ref (`DEV-####` or a Linear URL) → `mcp__linear__get_issue`. **Capture the
-     issue's UUID + current identifier + team** from the response and use them for all later
-     Linear ops (the ref you were handed may be stale — see the Linear-access rule). Read the
-     body for failure detail / screenshots / stack, and capture the **ranked failure reasons**
-     (Trunk lists them "most common" first) — #1 is what you fix first (Phase 1).
-   - **Derive the grep from the FULL Trunk test title, verbatim.** Trunk's `Test:` field is the
-     complete runtime title (e.g. `data model > data studio Undos allows to undo every action`).
-     Use the **whole string** as the grep — do **not** split on `>` or reduce it to the leaf
-     `it()` name. The `>` is often part of a `describe.each("… > %s")` template, not a separator,
-     and the discriminator (`data studio` vs `admin`) lives mid-title; dropping it makes the grep
-     match sibling parameterizations and burn the stress run on the wrong (non-flaky) branch.
-   - Otherwise treat it as a spec path or fuzzy test name (fallback; no Linear context).
-2. **Compute the branch name + dedup gate (this is the go decision).** `<LINEAR_ID>` is the **bare**
-   dispatched Linear identifier (e.g. `DEV-2180`) — the same value the workflow uses to build the
-   branch (`automated-e2e-flake-fix-<LINEAR_ID>`). If `$ARGUMENTS` is a Linear **URL**, extract the
-   `DEV-####` identifier from it first — a URL contains `/` and is not a valid branch component.
-   The branch name is derived **only** from `<LINEAR_ID>`, and it's the **dispatched** identifier —
-   never the re-keyed canonical id (so dedup stays stable across a team move) and never the test
-   name:
-   `automated-e2e-flake-fix-<LINEAR_ID>` (e.g. `DEV-2181` →
-   `automated-e2e-flake-fix-DEV-2181`). Check whether it already exists on the remote:
-   ```bash
-   git ls-remote --exit-code --heads origin automated-e2e-flake-fix-<LINEAR_ID>
-   ```
-   - **Exists (exit 0)** → a run is already in flight or already landed a fix → **stop, do
-     nothing.** This is the whole dedup mechanism.
-   - **Doesn't exist (exit 2)** → that's the **go** signal. Proceed without pausing for
-     confirmation.
-   (On the no-Linear fallback path there's no ref to build the name from; that path stays
-   interactive and is for local debugging only.)
-3. **Resolve the spec file** using the leaf `it()` name (just to locate the file):
-   ```bash
-   grep -rl "<leaf it() name>" e2e/test/scenarios
-   ```
-   Require **exactly one** *file* match. If 0 or >1, stop and ask the user to disambiguate. (Try
-   a shorter unique substring if the literal has special characters.) The **grep** passed to the
-   stress run is still the **full title** from step 1 — the leaf name is only for finding the file.
-   - **Watch for parameterized suites.** A single source `it()` under `describe.each(...)` /
-     `forEach` expands into **N runtime tests** (one per parameter), so one source match does
-     **not** mean one runtime test. Confirm the full-title grep targets exactly the flaky
-     parameterization (its discriminator must be present), or the stress run also executes the
-     non-flaky siblings — slow, and it dilutes `burn_in`.
-4. **Decide `qa_db`:** scan the spec / its `describe` for external-DB helpers
-   (postgres/mysql/mongo-writable) or an `@external` tag → `true`, else `false`.
-5. **Write the state file** `local/claude/e2e-flake-fix/<LINEAR_ID>.md`:
-   ```markdown
-   # Flake fix: <test name>
-   - linear_ref (dispatched): <DEV-#### or n/a>
-   - linear_uuid: <issue UUID — use for ALL Linear writes>
-   - linear_current_id: <e.g. UXW-#### — current identifier>
-   - heartbeat_comment_id: <set after the first progress comment>
-   - spec: <spec path>
-   - grep (full Trunk title): <full runtime title — NOT the leaf it() name>
-   - qa_db: <true|false>
-   - edition: ee
-   - branch: automated-e2e-flake-fix-<LINEAR_ID>
-   - attempt: 0 / 3
-
-   ## Failure reasons (Trunk, ranked — fix #1 first)
-   1. <dominant / most common>
-   2. <rarer>
-   ...
-
-   ## Attempts
-   ```
-   This file is the durable record. Re-read it on every `ScheduleWakeup` wake.
-
-## Phase 1 — Diagnose (run at the start of every attempt)
-
-- **Anchor on the #1 / most-common failure reason first.** Trunk lists the issue's failure
-  reasons ranked by frequency ("The N most common failure reasons…"). Fix the **dominant**
-  one and ignore the rarer reasons (#2, #3, …) unless the dominant one is fixed and they
-  still surface in CI. Do **not** rabbit-hole on a lower-frequency reason — that is the most
-  common way this loop wastes its 3 attempts. (Capture the ranked reasons in the state file
-  during Phase 0 so each attempt re-grounds on #1.)
-- Read the spec, focused on the failing test, its `describe`, and any `before*`/`after*`
-  hooks. Read shared helpers it calls.
-- Apply the flake anti-pattern checklist (from the `e2e-test-review` skill, as a mental
-  model — don't invoke it):
-  - numeric `cy.wait(<ms>)` instead of waiting on an alias
-  - `cy.intercept` registered **after** the action that triggers the request
-  - `.should("not.exist")` / negative assertions without a positive anchor first
-  - unscoped text selectors that can match more than one element
-  - off-by-one `.last()` / `.eq(-1)` without a length assertion
-  - JS conditionals on `cy` chains (no retry semantics)
-  - shared state / ordering assumptions between tests
-- Fold in any failure detail from the Linear issue (and, on attempts 2–3, the downloaded
-  CI artifacts from the previous attempt).
-- Write a **concrete hypothesis** to the state file's Attempts log before editing code.
-
-## Phase 2 — Fix on a branch
-
-- On **attempt 1 only**, create the branch computed in Phase 0 (dashes only, no `/`):
-  ```bash
-  git switch -c automated-e2e-flake-fix-<LINEAR_ID>
-  ```
-  On later attempts, keep committing to the same branch.
-- Apply a **minimal** fix:
-  - **Default:** test-scoped (deterministic waits via `cy.intercept` + `cy.wait("@alias")`
-    before asserting; positive anchor before a negative assertion; scoped selectors).
-  - **Source code is allowed** only when you have **high conviction** the root cause is a
-    real product defect the test merely surfaces (e.g. a genuine race or non-deterministic
-    ordering). When you do, write the evidence for that conviction in the state file and
-    keep the **blast radius minimal**.
-
-## Phase 2.5 — Share the diagnosis on Linear (before pushing)
-
-- Once you have a confirmed root cause and a fix in hand, **before** the push/CI gate, post
-  the **debugging story** to the resolved issue (this doubles as the diagnosis heartbeat).
-  Keep it a tight narrative: the observed failure, the root cause (why the request never
-  fires), and the fix. Skip silently only if there's no Linear issue (spec/test fallback path).
-- **Interactive vs headless:** when a human is driving interactively, draft it and let them
-  edit/approve first. When running **non-interactively** (headless CI, or the invocation says
-  not to ask), **just post it — never wait for an approval that can't come.**
-- This is separate from the Phase 5 closeout comment — the value here is capturing the *why*
-  while it's fresh, independent of whether CI later confirms.
-
-## Phase 3 — Push + stress (burn_in=50, fail_fast=true)
-
-**One run, `fail_fast=true`, does both jobs.** A bad fix fails on the **first** iteration
-and stops immediately (fast red + artifacts) — no need for a separate cheap sanity stage.
-A good fix runs all 50 to green (full confirmation). So every attempt is a single pair of
-runs at `burn_in=50` with `fail_fast=true` (throttle on + off).
-
-- **Push without pausing for confirmation.** The branch-existence check in Phase 0 was the
-  go decision; if you reached this phase you're clear to commit, push, and trigger (same for
-  a human or automated trigger).
-- Commit and push (first attempt only creates the branch; later attempts push the revised
-  fix), then trigger.
-
-- **Decide `build_jar` (cumulative across the branch, not per-attempt).** With
-  `build_jar=false` the run downloads a prebuilt uberjar by walking the current commit's
-  ancestors; with `build_jar=true` it builds the uberjar from this branch, so the JAR is
-  guaranteed to match your source. Rule:
-  - If **every** commit on the branch (vs. the base) touches **only** test/spec code →
-    `build_jar=false`. There is no source change for a JAR to miss, so a download is correct
-    and saves the build time.
-  - If **any** commit on the branch changed backend or frontend source — whether this attempt
-    made it or an earlier one did → `build_jar=true`, and keep it `true` on every later run
-    (including a test-only attempt 2). We build defensively: it may be redundant if a matching
-    branch JAR already exists, but it removes any doubt that the stress run tested your actual
-    source. A redundant build is far cheaper than a hard-to-debug false green from a JAR that
-    silently didn't include the fix.
-  - Check with `git diff --name-only <base>...HEAD` and treat anything outside test paths
-    (`e2e/`, `**/*_test.clj`, `**.unit.*`, etc.) as source. Record the chosen value in the
-    state file.
-
-### Trigger helper
-**Always `git push` and confirm the remote branch is at your new commit BEFORE triggering.**
-`gh workflow run --ref <branch>` resolves the ref on GitHub's side at dispatch time, so a
-trigger that races an in-flight push will run the *previous* commit. After triggering,
-verify with `gh run view <id> --json headSha` and re-trigger if it's stale.
-```bash
-git add -A && git commit -m "Fix flaky test: <test name>"
-git push -u origin <branch>          # PUSH FIRST — then trigger
-TRIGGERED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-for throttle in true false; do
-  gh workflow run e2e-stress-test-flake-fix.yml --ref <branch> \
-    -f spec="<spec path>" \
-    -f grep="<full Trunk title from Phase 0 — NOT the leaf it() name>" \
-    -f burn_in="50" \
-    -f mb_edition="ee" \
-    -f qa_db="<true|false>" \
-    -f build_jar="<true|false>" \
-    -f enable_network_throttling="$throttle" \
-    -f fail_fast="true"
-done
-```
-- **Capture both run IDs**, then **verify each `headSha` matches your pushed commit**:
-  ```bash
-  gh run list --workflow=e2e-stress-test-flake-fix.yml --branch <branch> \
-    --json databaseId,status,createdAt,event,headSha --limit 10
-  ```
-  Save both run IDs + URLs to the state file, tagged `throttled` / `unthrottled`.
-
-## Phase 4 — Wait + interpret (gh only)
-
-- **Auto-poll** with `ScheduleWakeup` (~900s / 15 min cadence) until **both** runs leave
-  `queued`/`in_progress`. Pass the same `/fix-flaky-test $ARGUMENTS`
-  back so the loop resumes; re-read the state file on each wake (a manual wake must also
-  work). Don't poll faster than ~900s.
-- When both finish, read each conclusion:
-  ```bash
-  gh run view <id> --json status,conclusion
-  ```
-  - **Either `cancelled`** → assume a **human cancelled** it. Stop the whole task
-    immediately — do **not** retry, do **not** open a PR. Note it in the state file and
-    hand back. (A `cancelled` conclusion means manual cancellation; a `timed_out`
-    conclusion does **not** — treat `timed_out` like a failure below.)
-  - **Either `failure` / `timed_out`** → fix is not holding (`fail_fast` stopped at the
-    first bad iteration, so the artifact is fresh and minimal):
-    ```bash
-    gh run download <failed-id> --dir local/claude/e2e-flake-fix/<failed-id>-artifacts
-    ```
-    The Cypress error lives in the GitHub step log (`gh run view <id> --log-failed`) and the
-    screenshots/video — **not** in `logs/test.log` (that's only the backend health log).
-    Read the failure screenshot(s) (vision) and the step-log error; append findings to the
-    state file; increment `attempt`. If `attempt < 3` → loop back to **Phase 1** with the
-    new evidence. If `attempt == 3` → Phase 5 (exhausted).
-  - **Both `success`** (all 50 iterations passed, both throttle modes) → fixed → Phase 5.
-- Don't worry about CI cost.
-
-## Phase 5 — Conclude
-
-- **Fixed** — open a PR (the upfront OK already authorized the push; don't re-gate):
-  ```bash
-  gh pr create --title "Fix flaky test: <test name>" --body "<body>"
-  ```
-  **The PR can NEVER auto-merge** — it always requires at least one human approval, no
-  matter how green the stress runs are, and never enable auto-merge. A passing stress run is
-  *necessary but not sufficient*: it proves the test is stable, not that the root cause was
-  fixed rather than masked. The human owns the merge decision.
-  The PR description **must follow this exact order**: (1) the **first line is ALWAYS
-  `Resolves <current-identifier>`** (the **current** key from Phase 0, e.g. `UXW-####` — a stale
-  `DEV-####` may fail to link), then (2) the root cause / fix / stress-test sections. The PR body
-  **must always include both stress-test runs** as links with their pass results:
-  ```markdown
-  Resolves <current-identifier>
-
-  ## Root cause
-  <one paragraph>
-
-  ## Fix
-  <what changed and why; note if source code was touched and the blast radius>
-
-  ## Stress test (burn_in=50, single test via grep)
-  - ✅ network throttling ON:  <run URL>
-  - ✅ network throttling OFF: <run URL>
-  ```
-  That `Resolves <ID>` reference (in the **PR description only — NEVER in a commit message
-  or body**, which would reopen the issue) closes the Linear issue **on merge**, via
-  Linear's GitHub integration. **NEVER close the Linear issue or change its status yourself**
-  (no status edits via the Linear MCP — only comments). Linear moves it to *In Progress* when
-  the PR links and to *Done* when the PR merges. Comment the outcome on the issue (link the
-  PR), and leave a copy-pasteable summary inline AND in `local/claude/`.
-- **Exhausted (3 attempts)** — do **not** guess further. Report each hypothesis tried, the
-  fixes attempted, all 6 stress-run links, and where the artifacts are. Hand back for human
-  judgment.
-
-- **Always — attach the run log to Linear (regardless of outcome).** As the final step on
-  both the fixed and exhausted paths, post the full state file
-  `local/claude/e2e-flake-fix/<LINEAR_ID>.md` to the Linear issue as a comment titled
-  **"🤖 Flake-fix run log (audit trail)"** (fence it so it renders verbatim). This is the
-  end-to-end audit trail — every hypothesis, fix, commit, run URL, and verdict — kept for a
-  human reviewer and as a learning artifact even when the fix didn't land. Skip only on the
-  no-Linear fallback path.
-  - **Lead the comment with a run-cost line** (above the fenced log):
-    **total wall-clock time spent** on the run and **total tokens used** — e.g.
-    `⏱ 2h 14m · 🪙 1.8M tokens (N attempts)`. Compute time from the first state-file
-    timestamp to now; report tokens for the whole session (best available figure). This makes
-    the cost of each automated run visible at a glance on the issue. (Posting the markdown as a comment is sufficient; a file
-  attachment via `mcp__linear__create_attachment_from_upload` is optional if the user wants
-  a downloadable file.)

.claude/skills/_shared/clojure-style-guide.md

@@ -27,9 +27,28 @@ This guide covers Clojure and ClojureScript coding conventions for Metabase. See
 - Format using Markdown conventions
 - Reference other vars with `[[other-var]]` not backticks
 
+A docstring states the *contract*: what it returns (including when it returns nil), what its
+params mean, what it throws versus swallows, and any precondition or invariant the caller must
+respect. A params block for non-obvious or optional args is good documentation — length is not
+the problem.
+
+These seven things are, and each is a reason to cut or relocate:
+
+| Anti-pattern | Why | Where it goes instead |
+| --- | --- | --- |
+| **Facts you don't own** — how a *callee*, another namespace, or another repo works internally | Drifts silently; nothing fails when it goes stale | Cut. Name the callee and let its own docstring say it |
+| **Said twice** — ns docstring restating its vars', a caller restating its callee's, sibling fns repeating boilerplate | Two copies means one is already wrong | Cut the copy. One fact, one owner |
+| **Design rationale** — why this approach, why it lives in this module, what the alternative was | The caller can't act on it | Commit message, or an inline comment on the specific line it constrains |
+| **Development history** — "matching master", "the X branch", "currently", "for now", "used to" | Stale by construction | Cut |
+| **Instructions to the reader** — "callers should trust this", "don't bother checking", "you should use X" | State the contract; the caller decides | Cut, keeping any actual guarantee as a plain statement |
+| **Invented precision** — score bands, thresholds, or tables no code enforces | Reads as spec, isn't | Cut, or make the code enforce it |
+| **A note on the wrong var** — describing how overrides behave, on the base/default impl | Nobody reading the override sees it | Move to the overrides it describes |
+
 **Comments:**
 
 - `TODO` format: `;; TODO (Name YYYY-MM-DD) -- description`
+- Prefer an inline comment over docstring prose for anything that explains *the body*. Put it on
+  the line it explains, not at the top of the function.
 
 ## Code Organization
 
@@ -285,12 +304,13 @@ Tag response Malli `:map` schemas with `{:closed true}` so the generated OpenAPI
 
 **Linter Suppressions:**
 
-The right shape is a **reader-discard map** placed directly above the form being silenced, listing the rule keywords explicitly:
+The right shape is a **reader-discard map** placed directly above the form being silenced, listing the
+rule keywords explicitly and including the required explanation:
 
 ```clojure
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-route-uses-kebab-case
-                      :metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/api_key" ...)
+;; Loaded by name from the plugin registry.
+#_{:clj-kondo/ignore [:clojure-lsp/unused-public-var]}
+(defn plugin-entrypoint ...)
 ```
 
 For a single require entry, hang it as metadata on that entry:
@@ -301,7 +321,12 @@ For a single require entry, hang it as metadata on that entry:
  [metabase.query-processor.store :as qp.store])
 ```
 
-Common Metabase-specific rules you'll see: `:metabase/modules`, `:metabase/validate-defendpoint-route-uses-kebab-case`, `:metabase/validate-defendpoint-has-response-schema`, `:metabase/prefer-with-dynamic-fn-redefs`, `:deprecated-namespace`, `:discouraged-namespace`. Don't use the keyword form (`#_:clj-kondo/ignore`); always the map form so it's grep-able by which rule(s) are suppressed.
+Use the map form, not the keyword form (`#_:clj-kondo/ignore`), so searches can identify the suppressed
+rules. Keep `:clj-kondo/ignore` as the map's first key; the ratchet scanner rejects other orderings.
+
+Fix the warning when possible. Adding a suppression is a last resort and requires approval. If one is
+necessary, add an explanatory `;;` comment directly above it or at the end of the same line. CI enforces
+these requirements with `./bin/mage kondo-ratchets`.
 
 **Configurable Options:**
 

.claude/skills/_shared/development-workflow.md

@@ -6,3 +6,4 @@
 - Run targeted tests, and lint continuously during development
 - Prioritize understanding existing patterns before implementing
 - Don't commit changes, leave it for the user to review and make commits
+- Minimize comments. Document only non-obvious intent, trade-offs, or constraints that the code itself cannot convey. Do not narrate what the code does — keep code self-descriptive through naming and structure.

.claude/skills/add-malli-schemas/SKILL.md

@@ -149,8 +149,7 @@ ms/NonBlankString               ;; Non-empty string
 ms/BooleanValue                 ;; String "true"/"false" or boolean
 ms/MaybeBooleanValue            ;; BooleanValue or nil
 ms/TemporalString               ;; ISO-8601 date/time string (for REQUEST params only!)
-ms/Map                          ;; Any map
-ms/JSONString                   ;; JSON-encoded string
+ms/OpaqueJSONObject             ;; JSON object whose keys are not ours to declare; string-keyed
 ms/PositiveNum                  ;; Positive number
 ms/IntGreaterThanOrEqualToZero  ;; 0 or positive
 ```

.claude/skills/analytics-events/SKILL.md

@@ -10,23 +10,23 @@ This skill helps you add product analytics (Snowplow) events to track user inter
 
 ## Quick Reference
 
-Analytics events in Metabase use Snowplow with typed event schemas. All events must be defined in TypeScript types before use.
+Analytics events in Metabase use Snowplow with typed event schemas. Simple events are declared **where they are used** — `trackSimpleEvent` is generic and validates the payload at the call site.
 
 **Key Files:**
-- `frontend/src/metabase-types/analytics/event.ts` - Event type definitions
-- `frontend/src/metabase-types/analytics/schema.ts` - Schema registry
-- `frontend/src/metabase/analytics/` - Core tracking functions (import from `metabase/analytics`)
-- Feature-specific `analytics.ts` files - Tracking function wrappers
+- `frontend/src/metabase/analytics/event.ts` - Core tracking functions, `trackSimpleEvent` / `trackSchemaEvent` (import from `metabase/analytics`)
+- `frontend/src/metabase-types/analytics/event.ts` - The shared `SimpleEventSchema` only. **Do not add event types here** (see below)
+- `frontend/src/metabase-types/analytics/schema.ts` - Schema registry (custom/legacy schemas only)
+- Feature-specific `analytics.ts` files - Where your tracking functions and any local types live
 
 ## Quick Checklist
 
 When adding a new analytics event:
 
-- [ ] Define event type in `frontend/src/metabase-types/analytics/event.ts`
-- [ ] Add event to appropriate union type (e.g., `DataStudioEvent`, `SimpleEvent`)
-- [ ] Create tracking function in feature's `analytics.ts` file
-- [ ] Import and call tracking function at the interaction point
-- [ ] Use `trackSimpleEvent()` for basic events (most common)
+- [ ] Pick an event name (snake_case, past tense)
+- [ ] Add a tracking function to the feature's `analytics.ts` file, calling `trackSimpleEvent()`
+- [ ] Keep any field unions (e.g. `"success" | "failure"`) as local types in that same file
+- [ ] Import and call the tracking function at the interaction point
+- [ ] Do **not** add an event type to `metabase-types/analytics/event.ts` or to any union
 
 ## Event Schema Types
 
@@ -47,6 +47,25 @@ type SimpleEventSchema = {
 
 **When to use:** 90% of events fit this schema. Use for clicks, opens, closes, creates, deletes, etc.
 
+`trackSimpleEvent` is generic and enforces this schema on the object literal you pass it:
+
+```typescript
+// frontend/src/metabase/analytics/event.ts
+export function trackSimpleEvent<
+  T extends SimpleEventSchema &
+    Record<Exclude<keyof T, keyof SimpleEventSchema>, never>,
+>(event: T) {
+  trackSchemaEvent("simple_event", event);
+}
+```
+
+That means a missing `event` or any field outside `SimpleEventSchema` is a compile error at the call
+site. There is no separate event type to declare and no `satisfies` clause to add — the old
+`ValidateEvent<...>` helper is no longer exported and is not part of the workflow.
+
+`trackSchemaEvent` is generic too: it correlates the schema name with the payload type, so you can't
+send a dashboard event under the `simple_event` schema.
+
 ### 2. Custom Schemas (legacy, no events are being added)
 
 Consider adding new event schema only in very special cases.
@@ -57,36 +76,7 @@ Consider adding new event schema only in very special cases.
 
 ### Example: Track when a user applies filters in a table picker
 
-#### Step 1: Define Event Types
-
-Add event type definitions to `frontend/src/metabase-types/analytics/event.ts`:
-
-```typescript
-export type DataStudioTablePickerFiltersAppliedEvent = ValidateEvent<{
-  event: "data_studio_table_picker_filters_applied";
-}>;
-
-export type DataStudioTablePickerFiltersClearedEvent = ValidateEvent<{
-  event: "data_studio_table_picker_filters_cleared";
-}>;
-```
-
-#### Step 2: Add to Union Type
-
-Find or create the appropriate union type and add your events:
-
-```typescript
-export type DataStudioEvent =
-  | DataStudioLibraryCreatedEvent
-  | DataStudioTablePublishedEvent
-  | DataStudioGlossaryCreatedEvent
-  | DataStudioGlossaryEditedEvent
-  | DataStudioGlossaryDeletedEvent
-  | DataStudioTablePickerFiltersAppliedEvent  // <- Add here
-  | DataStudioTablePickerFiltersClearedEvent; // <- Add here
-```
-
-#### Step 3: Create Tracking Functions
+#### Step 1: Create Tracking Functions
 
 In your feature's `analytics.ts` file (e.g., `enterprise/frontend/src/metabase-enterprise/data-studio/analytics.ts`):
 
@@ -106,7 +96,7 @@ export const trackDataStudioTablePickerFiltersCleared = () => {
 };
 ```
 
-#### Step 4: Use in Components
+#### Step 2: Use in Components
 
 Import and call the tracking function at the interaction point:
 
@@ -138,16 +128,11 @@ function FilterPopover({ filters, onSubmit }) {
 
 ## Using SimpleEventSchema Fields
 
+All examples below live in the feature's own `analytics.ts` — nothing is registered centrally.
+
 ### Example: Event with target_id
 
 ```typescript
-// Type definition
-export type DataStudioLibraryCreatedEvent = ValidateEvent<{
-  event: "data_studio_library_created";
-  target_id: number | null;
-}>;
-
-// Tracking function
 export const trackDataStudioLibraryCreated = (id: CollectionId) => {
   trackSimpleEvent({
     event: "data_studio_library_created",
@@ -162,14 +147,10 @@ trackDataStudioLibraryCreated(newLibrary.id);
 ### Example: Event with triggered_from
 
 ```typescript
-// Type definition
-export type NewButtonClickedEvent = ValidateEvent<{
-  event: "new_button_clicked";
-  triggered_from: "app-bar" | "empty-collection";
-}>;
+// Local union, exported only if another feature needs to pass the same value
+export type NewButtonLocation = "app-bar" | "empty-collection";
 
-// Tracking function
-export const trackNewButtonClicked = (location: "app-bar" | "empty-collection") => {
+export const trackNewButtonClicked = (location: NewButtonLocation) => {
   trackSimpleEvent({
     event: "new_button_clicked",
     triggered_from: location,
@@ -187,44 +168,31 @@ export const trackNewButtonClicked = (location: "app-bar" | "empty-collection")
 
 ### Example: Event with event_detail
 
-```typescript
-// Type definition
-export type MetadataEditEvent = ValidateEvent<{
-  event: "metadata_edited";
-  event_detail: "type_casting" | "semantic_type_change" | "visibility_change";
-  triggered_from: "admin" | "data_studio";
-}>;
+Real example — `frontend/src/metabase/metadata/pages/shared/analytics.ts`:
 
-// Tracking function
-export const trackMetadataChange = (
-  detail: "type_casting" | "semantic_type_change" | "visibility_change",
-  location: "admin" | "data_studio"
-) => {
+```typescript
+export type MetadataEditEventDetail =
+  | "type_casting"
+  | "semantic_type_change"
+  | "visibility_change";
+
+export const trackMetadataChange = (detail: MetadataEditEventDetail) => {
   trackSimpleEvent({
     event: "metadata_edited",
     event_detail: detail,
-    triggered_from: location,
+    triggered_from: "admin",
   });
 };
 
 // Usage
-trackMetadataChange("semantic_type_change", "data_studio");
+trackMetadataChange("semantic_type_change");
 ```
 
 ### Example: Event with result and duration
 
-```typescript
-// Type definition
-export type MoveToTrashEvent = ValidateEvent<{
-  event: "moved-to-trash";
-  target_id: number | null;
-  triggered_from: "collection" | "detail_page" | "cleanup_modal";
-  duration_ms: number | null;
-  result: "success" | "failure";
-  event_detail: "question" | "model" | "metric" | "dashboard";
-}>;
+See `frontend/src/metabase/archive/analytics.ts` for the real version of this.
 
-// Tracking function
+```typescript
 export const trackMoveToTrash = (params: {
   targetId: number | null;
   triggeredFrom: "collection" | "detail_page" | "cleanup_modal";
@@ -280,17 +248,16 @@ try {
 "filters-applied"            // Use underscore, not hyphen
 ```
 
-### Event Type Names (PascalCase with "Event" suffix)
+### Local Field Types (PascalCase, named after the field)
+
+There is usually no `...Event` type to name anymore. When you do need a union for a field, name it
+after the field it feeds:
 
 ```typescript
 // Good
-DataStudioLibraryCreatedEvent
-TablePickerFiltersAppliedEvent
-MetabotChatOpenedEvent
-
-// Bad
-dataStudioLibraryCreated      // Wrong case
-DataStudioLibraryCreated      // Missing "Event" suffix
+type MetricDimensionResult = "success" | "failure";     // -> result
+export type MetadataEditEventDetail = "type_casting";   // -> event_detail
+type NewButtonLocation = "app-bar" | "empty-collection"; // -> triggered_from
 ```
 
 ### Tracking Function Names (camelCase with "track" prefix)
@@ -309,29 +276,28 @@ logLibraryCreated             // Use "track" prefix
 
 ## Common Patterns
 
-### Pattern 1: Feature-Specific Union Types
+### Pattern 1: Sharing Field Types Across Features
 
-Group related events together:
+When two features send the same event with a different `triggered_from`, export the field union from
+the owning feature's `analytics.ts` and import it — don't hoist anything into `metabase-types`:
 
 ```typescript
-export type DataStudioEvent =
-  | DataStudioLibraryCreatedEvent
-  | DataStudioTablePublishedEvent
-  | DataStudioGlossaryCreatedEvent;
+// frontend/src/metabase/data-studio/data-model/analytics.ts
+import { trackSimpleEvent } from "metabase/analytics";
+import type { MetadataEditEventDetail } from "metabase/metadata/pages/shared/analytics";
 
-export type MetabotEvent =
-  | MetabotChatOpenedEvent
-  | MetabotRequestSentEvent
-  | MetabotFixQueryClickedEvent;
-
-// Then add to SimpleEvent union
-export type SimpleEvent =
-  | /* other events */
-  | DataStudioEvent
-  | MetabotEvent
-  | /* more events */;
+export function trackMetadataChange(detail: MetadataEditEventDetail) {
+  trackSimpleEvent({
+    event: "metadata_edited",
+    event_detail: detail,
+    triggered_from: "data_studio",
+  });
+}
 ```
 
+This is the point of the extensible-events design: enterprise and feature-tier types stay in their
+own module instead of being imported down into a shared union.
+
 ### Pattern 2: Conditional Tracking
 
 Track different events based on user action:
@@ -350,10 +316,10 @@ const handleSave = async () => {
 
 ## Common Pitfalls
 
-### Don't: Add custom fields to SimpleEvent
+### Don't: Add custom fields to a simple event
 
 ```typescript
-// WRONG - SimpleEvent doesn't support custom fields
+// WRONG - SimpleEventSchema doesn't support custom fields (this is a compile error)
 export const trackFiltersApplied = (filters: FilterState) => {
   trackSimpleEvent({
     event: "filters_applied",
@@ -379,23 +345,43 @@ export const trackFilterApplied = (filterType: string) => {
 };
 ```
 
-### Don't: Forget to add event to union type
+### Don't: Add event types to `metabase-types/analytics/event.ts`
+
+The central `SimpleEvent` union was removed — it forced feature-tier types to be imported down into
+shared code, causing module-boundary violations. `trackSimpleEvent` is generic now, so the type adds
+nothing but duplication.
 
 ```typescript
-// Define the event
+// ❌ WRONG - central declaration + re-import for a `satisfies` clause
+// frontend/src/metabase-types/analytics/event.ts
 export type NewFeatureClickedEvent = ValidateEvent<{
   event: "new_feature_clicked";
+  target_id: number;
 }>;
 
-// ❌ WRONG - Forgot to add to SimpleEvent union
-// Event won't be recognized by TypeScript
+// frontend/src/metabase/my-feature/analytics.ts
+import type { NewFeatureClickedEvent } from "metabase-types/analytics";
 
-// ✓ RIGHT - Add to appropriate union
-export type SimpleEvent =
-  | /* other events */
-  | NewFeatureClickedEvent;
+export const trackNewFeatureClicked = (id: number) => {
+  trackSimpleEvent({
+    event: "new_feature_clicked",
+    target_id: id,
+  } satisfies NewFeatureClickedEvent);
+};
+
+// ✓ RIGHT - the object literal is already checked by the generic
+// frontend/src/metabase/my-feature/analytics.ts
+export const trackNewFeatureClicked = (id: number) => {
+  trackSimpleEvent({
+    event: "new_feature_clicked",
+    target_id: id,
+  });
+};
 ```
 
+A few `...Event` types still sit in `metabase-types/analytics/event.ts`. They are leftovers from PRs
+that landed around the refactor — don't copy them, and don't add to them.
+
 ### Don't: Mix up event name formats
 
 ```typescript
@@ -463,41 +449,44 @@ Example console output:
 ### Where to put tracking functions:
 
 ```
-Feature-specific analytics functions:
+Tracking functions AND their local field types (this is where new events live):
 frontend/src/metabase/{feature}/analytics.ts
 enterprise/frontend/src/metabase-enterprise/{feature}/analytics.ts
 
-Event type definitions (all in one place):
-frontend/src/metabase-types/analytics/event.ts
-
 Core tracking utilities:
 frontend/src/metabase/analytics/ (import from `metabase/analytics`)
+
+Shared SimpleEventSchema only — nothing new goes here:
+frontend/src/metabase-types/analytics/event.ts
 ```
 
+In embedding SDK code, use `trackSdkSimpleEvent`
+(`frontend/src/embedding-sdk-bundle/analytics/snowplow.ts`) instead — the main-app `"sp"` tracker
+isn't initialized in the customer's page, so `trackSimpleEvent`'s Snowplow leg is a no-op there.
+
 ## Real-World Examples
 
 See these files for reference:
 
-- **Simple events**: `enterprise/frontend/src/metabase-enterprise/data-studio/analytics.ts`
-- **Events with variants**: `frontend/src/metabase/dashboard/analytics.ts`
-- **Complex events**: `frontend/src/metabase/query_builder/analytics.js`
-- **Event type examples**: `frontend/src/metabase-types/analytics/event.ts`
+- **Simple events + local field union**: `frontend/src/metabase/metadata/pages/shared/analytics.ts`
+- **Reusing another feature's field type**: `frontend/src/metabase/data-studio/data-model/analytics.ts`
+- **Result + duration timing**: `frontend/src/metabase/archive/analytics.ts`
+- **Enterprise feature events**: `enterprise/frontend/src/metabase-enterprise/google_drive/analytics.ts`
 
 ## Workflow Summary
 
 1. **Identify the user interaction** to track
 2. **Decide on event name** (snake_case, descriptive)
-3. **Define event type** in `event.ts` using `ValidateEvent`
-4. **Add to union type** (create feature union if needed)
-5. **Create tracking function** in feature's `analytics.ts`
-6. **Import and call** at the interaction point
-7. **Test** that events fire correctly
+3. **Create tracking function** in feature's `analytics.ts`, calling `trackSimpleEvent()`
+4. **Add local field unions** in that same file if a field has a fixed set of values
+5. **Import and call** at the interaction point
+6. **Test** that events fire correctly
 
 ## Tips
 
 - **Be specific** - `filters_applied` is better than `action_performed`
 - **Use past tense** - `library_created` not `create_library`
-- **Group related events** - Create feature-specific event union types
+- **Group related events** - Keep a feature's tracking functions together in its `analytics.ts`
 - **Track meaningful actions** - Not every click needs tracking
 - **Consider the data** - What would you want to analyze later?
 - **Stay consistent** - Follow existing naming patterns in the codebase

.claude/skills/clojure-review/SKILL.md

@@ -56,6 +56,11 @@ Use this to scan through changes efficiently:
 - [ ] References use `[[other-var]]` not backticks
 - [ ] `TODO` comments include author and date: `;; TODO (Name 2025-01-01) -- description`
 
+Docstring content — check every new or rewritten docstring against the anti-pattern table in the
+style guide above. Read the diff's docstrings on their own, separately from the code: prose is
+where review attention slides off, and a long docstring reads as diligence rather than as the
+liability it usually is.
+
 ### Code Organization
 
 - [ ] Everything `^:private` unless used elsewhere
@@ -106,7 +111,12 @@ Use this to scan through changes efficiently:
 ### Miscellaneous
 
 - [ ] Example data is bird-themed when possible
-- [ ] Kondo linter suppressions use proper format (not `#_:clj-kondo/ignore` keyword form)
+- [ ] Kondo suppressions use a reader-discard map, not `#_:clj-kondo/ignore`, with
+      `:clj-kondo/ignore` as the first key
+- [ ] Each new suppression is approved and has a `;;` comment explaining why the warning cannot be fixed
+- [ ] Any ratchet budget increase is explained in the PR
+- [ ] PRs that remove ignores leave ratchet budgets unchanged; the shrink workflow records reductions on
+      `master`
 
 ## Pattern matching table
 
@@ -135,6 +145,17 @@ Quick scan for common issues:
 
 > This public var needs a docstring explaining its purpose, inputs, and outputs.
 
+**For docstrings documenting code they don't own:**
+
+> This describes how `lib` decides binning strategies internally. Nothing here fails when that
+> changes, so it will go stale silently — drop it and let `available-binning-strategies` answer
+> for its own behavior.
+
+**For docstring content that belongs in the body:**
+
+> This paragraph explains why the branches are ordered this way, which is what someone editing
+> the `cond` needs — but a caller can't act on it. Move it to an inline comment above the `cond`.
+
 **For organization issues:**
 
 > This function is only used in this namespace, so it should be marked `^:private`.

.claude/skills/clojure-write/SKILL.md

@@ -82,10 +82,29 @@ either a bug, or it means callers must handle each case themselves — and
 in *that* case it is the *absence* of the property that must be
 documented. Document deviations from expectation, not conformance to it.
 
-Heuristic: if a sentence would still be true after a full rewrite of the
-body, it may belong in the docstring. If it describes *how the current
-body works*, it belongs in the body — as an inline comment, if it is
-non-obvious.
+Heuristic — a sentence earns its place in the docstring only if it
+passes both tests:
+
+1. Rewrite test (necessary, not sufficient): if rewriting the body to a
+   different implementation with an identical contract could make the
+   sentence false, it describes the implementation, not the contract.
+   Relocate it to an inline comment at the point in the body where it
+   applies.
+
+2. Ownership test: if the sentence states a fact about code this
+   function does not own — a callee's behavior, a library's guarantee —
+   it survives any rewrite trivially, which is exactly why the rewrite
+   test alone is not enough. If this body *relies* on that fact, it is
+   implementation context: relocate it to the call site. If nothing here
+   relies on it, it is blather about someone else's code: delete it, and
+   let the callee's own docstring answer for it.
+
+Say each fact once. Duplicated prose is a stale comment in advance: when
+the fact changes, one copy gets updated and the rest quietly rot. This
+holds even within code you own — a namespace docstring that
+re-summarizes its own multimethods, three sibling functions carrying the
+same paragraph about retry behavior. Give the fact one home, and have
+the other places name it rather than restate it.
 
 Multi-line docstrings are not banned — a genuinely non-obvious constraint
 the code had to deal with can be worth explaining. But be prudent; the
@@ -102,3 +121,14 @@ breakage keeps happening, *that* is the signal a comment was warranted.
 - End all files with a newline
 - When editing tabular code, where the columns line up, try to keep them aligned
 - Spaces on a line with nothing after it is not allowed
+- After changing module boundaries (adding/removing/renaming a `src` namespace, a cross-module `require`
+  or `:model/X` reference, or a new module), run `./bin/mage fix-modules-config` to regenerate
+  `.clj-kondo/config/modules/config.edn`, then run `./bin/mage project-tests modules`. The fixer is a no-op when
+  nothing drifted; see "Module Boundaries" in the project `CLAUDE.md`.
+- Fix kondo warnings instead of suppressing them. Add a suppression only as a last resort, with approval
+  and a `;;` comment explaining why it is necessary.
+- Do not lower budgets in `.clj-kondo/ratchets.edn` after removing ignores. The shrink workflow records
+  reductions on `master`.
+- If `.clj-kondo/ratchets.edn` conflicts during a merge, rebase, or restack, run
+  `./bin/merge-kondo-ratchets`. It preserves one-sided changes, chooses the policy that allows fewer
+  suppressions when both sides change the same entry, and stops when the conflict needs a human decision.

.claude/skills/e2e-test-review/SKILL.md

@@ -22,10 +22,11 @@ Before starting, determine which mode to use:
 3. **(Conditional)** If after reading the spec a specific assertion or selector is **ambiguous** — you can't tell if it's the right anchor, or whether the test actually verifies what its title claims — briefly grep the related component for the test ID / role / text. **Don't read components by default.** Only do this when there's a real signal of confusion in the spec.
 4. Scan against the checklist + pattern table below.
 5. Number all issues sequentially. Skip nits — only flag what's worth fixing.
+6. **Always** finish with the honest e2e-vs-unit breakdown (see the section of that name below). It's part of every report, not an optional add-on.
 
 ### When to hand off instead of review
 
-If the spec references an issue (`metabase#NNNNN`) and the user wants to **fix** flakiness or assess whether the test still reproduces the original bug, that's outside the review skill's scope. Point them at `/fix-flakey-test` (or the dedicated flake-fixing workflow), which knows to fetch the issue and the resolving PR's diff. The review skill stays focused on "is this test well-written and conformant" — it doesn't fetch external issue context by default.
+If the spec references an issue (`metabase#NNNNN`) and the user wants to **fix** flakiness or assess whether the test still reproduces the original bug, that's outside the review skill's scope. Point them at the dedicated flake-fixing workflow, which knows to fetch the issue and the resolving PR's diff. The review skill stays focused on "is this test well-written and conformant" — it doesn't fetch external issue context by default.
 
 ## Review checklist
 
@@ -194,8 +195,41 @@ Use the pending review workflow:
 
 Each comment body starts with `**Issue N: [Brief title]**`.
 
+## Honest e2e-vs-unit breakdown (always include)
+
+Every report ends with this section. The numbered issues above are about whether the test is *well-written*; this section is about whether it should be an **e2e test at all**. They're orthogonal — a flawless spec can still be paying e2e prices for component-test value, and that's worth saying out loud.
+
+The bar is simple: **an `it()` earns its place in e2e only if it exercises a layer you cannot fake without gutting the test's value.** In this codebase that means one or more of:
+
+- a **real backend query against seeded data** (the assertion depends on the server actually filtering/sorting/bucketing rows, not on a mocked response);
+- **real rendering you then interact with** — clicking a charted ECharts SVG element at computed coordinates, drag/hit-testing, drill-through;
+- **routing across screens** — navigation, URL param round-trips that the backend then honors, browser back/forward;
+- **cross-screen traversal** — list → detail → back, where the value is the seam between screens.
+
+Conversely, a test belongs in **Jest + RTL** (the cheaper layer this repo already uses for component/unit coverage) when its real subject is frontend-only:
+
+- **pure frontend logic** — a bucketing/formatting/derivation decision (e.g. "single-day range → bucket by hour") that has one right answer independent of the backend;
+- **render assertions** — "the page mounts N titled cards and an SVG exists." A mocked dataset response + RTL verifies the titles; that an ECharts SVG renders is library behavior, not your logic;
+- **state/wiring** — tab → `aria-selected` → active-state, or select → querystring mapping. The *URL gets the param* half is component-level; only the *backend honors the param* half needs e2e.
+
+Write the breakdown in three honest buckets. Ground each call in **which layers the test actually touches**, not in how the test is named:
+
+1. **Genuinely must-be-e2e (keep)** — load-bearing. Name the layer(s) only a browser + backend can verify together.
+2. **Defensible-but-narrowable e2e** — justified as integration, but over-split or doing more boots than the coverage requires. Say what to merge.
+3. **Should be unit / component tests** — where the real savings are. Name the cheaper layer and what it would assert (often *more precisely* than the e2e test does indirectly).
+
+Then a one-paragraph **bottom line**: what to keep as e2e, what to push down, and — if you pulled CI timing from `e2e/support/timings.json` for the Performance check — roughly how much of that wall time is *earned* by the must-be-e2e set versus paid by the rest.
+
+Rules of engagement so this stays honest, not performative:
+
+- **Don't inflate the keep bucket to look balanced.** If most of the spec is component-test value paying e2e prices, say exactly that. If every test is load-bearing, say that too — a spec where all 12 tests must be e2e is a legitimate outcome, not a failure to find candidates.
+- **Be specific.** Cite the `it()` titles and line ranges. "Several tests could be unit tests" is useless; "tests 1/17/18 assert only that N titled cards mount — RTL with a mocked dataset" is actionable.
+- **This is advice to the author, not a blocking issue.** It's a recommendation, separate from the numbered issues. Don't renumber it into the issue list.
+- **Stay rooted in what exists.** The cheaper layer here is Jest + RTL component/unit tests. Don't invent infrastructure the repo doesn't have, and don't recommend deleting backend-dependent coverage just because part of the test is frontend-only — split it, keep the integration half.
+
 ## Final check
 
 1. Trim issues that won't materially help the author.
 2. Verify sequential numbering with no gaps.
 3. In PR mode, verify each issue was posted as a separate review comment.
+4. Verify the honest e2e-vs-unit breakdown is present — it's required in every report, even when the answer is "all of these need to be e2e."

.claude/skills/e2e-test/SKILL.md

@@ -37,14 +37,16 @@ First check if snapshots exist:
 ls e2e/snapshots/default.sql 2>/dev/null && echo "snapshots exist" || echo "snapshots missing"
 ```
 
+Always pass the spec path via `--spec`. The runner feeds its arguments to Cypress's CLI parser (`cypress.cli.parseRunArguments`), which silently drops bare positional paths and then runs the entire suite. A leading `run` argument is harmless, but the path itself must follow `--spec`. Sanity-check that the first `Running:` line says `(1 of 1)`.
+
 If snapshots exist, skip regeneration for speed:
 ```bash
-MB_EDITION=oss CYPRESS_VIDEO=false CYPRESS_RETRIES=0 CYPRESS_GUI=false GENERATE_SNAPSHOTS=false bun test-cypress $ARGUMENTS
+MB_EDITION=oss CYPRESS_VIDEO=false CYPRESS_RETRIES=0 CYPRESS_GUI=false GENERATE_SNAPSHOTS=false bun test-cypress --spec path/to/spec.cy.spec.js
 ```
 
 If snapshots are missing (first run), let the runner generate them:
 ```bash
-MB_EDITION=oss CYPRESS_VIDEO=false CYPRESS_RETRIES=0 CYPRESS_GUI=false bun test-cypress $ARGUMENTS
+MB_EDITION=oss CYPRESS_VIDEO=false CYPRESS_RETRIES=0 CYPRESS_GUI=false bun test-cypress --spec path/to/spec.cy.spec.js
 ```
 
 When running enterprise tests, replace `MB_EDITION=oss` with `MB_EDITION=ee` in the commands above.
@@ -67,9 +69,11 @@ GREP="test name here" MB_EDITION=oss bun test-cypress --spec path/to/spec.js
 When the user asks to verify a test is not flaky:
 
 ```bash
-MB_EDITION=oss bin/e2e-stress-test $ARGUMENTS
+MB_EDITION=oss bin/e2e-stress-test --spec path/to/spec.cy.spec.js
 ```
 
+(The stress script forwards its arguments to `bun test-cypress`, so the same `--spec` rule applies.)
+
 Set `E2E_STRESS_RUNS=N` for more iterations (default: 5). Stops on first failure and prints screenshot paths. Read those screenshots to analyze the failure.
 
 ## Analyzing failures

.claude/skills/emotion-migrate/SKILL.md

@@ -21,7 +21,7 @@ For EACH styled component, go through every CSS property and ask: "Can this be a
 
 - `display` → `display` prop
 - `color` → `c` prop (`c="core-brand"`, `c="text-primary"`)
-- `background-color` → `bg` prop (`bg="background-primary"`)
+- `background-color` → `bg` prop (`bg="background_page-primary"`)
 - `font-size` → `fz` prop (`fz="md"`)
 - `font-weight` → `fw` prop (`fw="bold"`)
 - `line-height` → `lh` prop (`lh="md"`)
@@ -57,7 +57,7 @@ For EACH styled component, go through every CSS property and ask: "Can this be a
   align="center"            /* style prop */
   gap="sm"                  /* style prop */
   p="md"                    /* style prop */
-  bg="background-primary"   /* style prop */
+  bg="background_page-primary"   /* style prop */
 >
 ```
 
@@ -171,8 +171,8 @@ Create `ComponentName.module.css` alongside the component file:
 /* Use design system tokens — NEVER raw color/spacing values */
 .root {
   border: 1px solid var(--mb-color-border-neutral);
-  border-radius: var(--mantine-radius-md);
-  background-color: var(--mb-color-background-primary);
+  border-radius: var(--mantine-radius-sm);
+  background-color: var(--mb-color-background_page-primary);
 }
 
 /* Conditional states as separate classes, combined with cx() */
@@ -182,7 +182,7 @@ Create `ComponentName.module.css` alongside the component file:
 }
 
 .disabled {
-  color: var(--mb-color-text-tertiary);
+  color: var(--mb-color-text-disabled);
   pointer-events: none;
 }
 
@@ -192,7 +192,7 @@ Create `ComponentName.module.css` alongside the component file:
 
   &:hover {
     color: var(--mb-color-core-brand);
-    background-color: var(--mb-color-background-hover);
+    background-color: var(--mb-color-background_surface-hover);
   }
 }
 
@@ -246,7 +246,8 @@ Remove the old styled file entirely. Remove all imports of it from other files.
 
 **Spacing** (`p`, `px`, `py`, `pt`, `pb`, `pl`, `pr`, `m`, `mx`, `my`, `mt`, `mb`, `ml`, `mr`):
 
-- `"xs"` = 4px, `"sm"` = 8px, `"md"` = 16px, `"lg"` = 24px, `"xl"` = 32px
+- `"xxxs"` = 0.125rem, `"xxs"` = 0.25rem, `"xs"` = 0.375rem, `"sm"` = 0.5rem, `"md"` = 0.75rem, `"lg"` = 1rem, `"xl"` = 1.5rem, `"xxl"` = 2rem, `"xxxl"` = 2.5rem
+- Use numeric `0` for zero spacing.
 - Custom: `rem(48)` for non-standard values (import `rem` from `metabase/ui`)
 
 **Dimensions** (`w`, `h`, `maw`, `mah`, `miw`, `mih`):
@@ -255,9 +256,9 @@ Remove the old styled file entirely. Remove all imports of it from other files.
 
 **Colors** (`c`, `bg`):
 
-- Text: `"text-primary"`, `"text-secondary"`, `"text-tertiary"`
-- Background: `"background-primary"`, `"background-secondary"`, `"background-hover"`
-- Brand: `"core-brand"`, `"error"`, `"success"`, `"warning"`
+- Text: `"text-primary"`, `"text-secondary"`, `"text-disabled"`
+- Background: `"background_page-primary"`, `"background_page-secondary"`, `"background_surface-hover"`
+- Brand: `"core-brand"`, `"feedback-negative"`, `"feedback-positive"`, `"feedback-warning"`
 
 **Typography** (`fz`, `fw`, `lh`, `ta`, `ff`):
 
@@ -279,21 +280,26 @@ Remove the old styled file entirely. Remove all imports of it from other files.
 
 **Colors** — `var(--mb-color-<name>)`:
 
-- `--mb-color-text-primary`, `--mb-color-text-secondary`, `--mb-color-text-tertiary`
-- `--mb-color-background-primary`, `--mb-color-background-secondary`, `--mb-color-background-hover`
-- `--mb-color-border-neutral`, `--mb-color-border-neutral-strong`, `--mb-color-border-neutral-subtle`
+- `--mb-color-text-primary`, `--mb-color-text-secondary`, `--mb-color-text-disabled`
+- `--mb-color-background_page-primary`, `--mb-color-background_page-secondary`, `--mb-color-background_surface-hover`
+- `--mb-color-border`, `--mb-color-border-strong`, `--mb-color-border-subtle`
 - `--mb-color-core-brand`, `--mb-color-core-brand-hover`
-- `--mb-color-error`, `--mb-color-success`, `--mb-color-warning`
+- `--mb-color-feedback-negative`, `--mb-color-feedback-positive`, `--mb-color-feedback-warning`
 - `--mb-color-shadow`, `--mb-color-focus`
 - `--mb-color-accent0` through `--mb-color-accent7`
 
 **Mantine spacing** — `var(--mantine-spacing-<size>)`:
 
-- `--mantine-spacing-xs` (4px), `--mantine-spacing-sm` (8px), `--mantine-spacing-md` (16px), `--mantine-spacing-lg` (24px), `--mantine-spacing-xl` (32px)
+- `--mantine-spacing-xxxs` (0.125rem), `--mantine-spacing-xxs` (0.25rem), `--mantine-spacing-xs` (0.375rem), `--mantine-spacing-sm` (0.5rem), `--mantine-spacing-md` (0.75rem), `--mantine-spacing-lg` (1rem), `--mantine-spacing-xl` (1.5rem), `--mantine-spacing-xxl` (2rem), `--mantine-spacing-xxxl` (2.5rem)
 
 **Mantine radius** — `var(--mantine-radius-<size>)`:
 
-- `--mantine-radius-xs` (4px), `--mantine-radius-sm` (6px), `--mantine-radius-md` (8px), `--mantine-radius-xl` (40px)
+- `--mantine-radius-xxxs` (0.125rem), `--mantine-radius-xxs` (0.25rem), `--mantine-radius-xs` (0.375rem), `--mantine-radius-sm` (0.5rem), `--mantine-radius-md` (0.75rem), `--mantine-radius-lg` (1rem), `--mantine-radius-xl` (1.5rem)
+
+**Mantine shadows (elevation)** — `var(--mantine-shadow-<size>)`:
+
+- `--mantine-shadow-xs`, `--mantine-shadow-xs_outline`, `--mantine-shadow-sm`, `--mantine-shadow-sm_outline`, `--mantine-shadow-lg_outline`
+- Light and dark modes use different shadow values (defined in `frontend/src/metabase/ui/theme.ts`)
 
 **Mantine font sizes** — `var(--mantine-font-size-<size>)`:
 
@@ -313,24 +319,36 @@ When migrating, **never carry over hardcoded `rem`/`px` values** from the origin
 
 **Spacing** — snap to the nearest Mantine spacing token:
 
-| Hardcoded value                   | Nearest token | Style prop   | CSS variable                   |
-| --------------------------------- | ------------- | ------------ | ------------------------------ |
-| `0.125rem` (2px)                  | `2px`         | `2` (number) | `2px` (keep literal, no token) |
-| `0.2rem` (3.2px), `0.25rem` (4px) | **xs** (4px)  | `"xs"`       | `var(--mantine-spacing-xs)`    |
-| `0.5rem` (8px)                    | **sm** (8px)  | `"sm"`       | `var(--mantine-spacing-sm)`    |
-| `0.75rem` (12px)                  | between sm/md | `rem(12)`    | `0.75rem` (no exact token)     |
-| `1rem` (16px)                     | **md** (16px) | `"md"`       | `var(--mantine-spacing-md)`    |
-| `1.5rem` (24px)                   | **lg** (24px) | `"lg"`       | `var(--mantine-spacing-lg)`    |
-| `2rem` (32px)                     | **xl** (32px) | `"xl"`       | `var(--mantine-spacing-xl)`    |
+| Hardcoded value                   | Nearest token | Style prop | CSS variable                    |
+| --------------------------------- | ------------- | ---------- | ------------------------------- |
+| `0` (0px)                         | —             | `0`        | `0`                             |
+| `0.125rem` (2px)                  | **xxxs**      | `"xxxs"`   | `var(--mantine-spacing-xxxs)`   |
+| `0.2rem` (3.2px), `0.25rem` (4px) | **xxs**       | `"xxs"`    | `var(--mantine-spacing-xxs)`    |
+| `0.375rem` (6px)                  | **xs**        | `"xs"`     | `var(--mantine-spacing-xs)`     |
+| `0.5rem` (8px)                    | **sm**        | `"sm"`     | `var(--mantine-spacing-sm)`     |
+| `0.75rem` (12px)                  | **md**        | `"md"`     | `var(--mantine-spacing-md)`     |
+| `1rem` (16px)                     | **lg**        | `"lg"`     | `var(--mantine-spacing-lg)`     |
+| `1.5rem` (24px)                   | **xl**        | `"xl"`     | `var(--mantine-spacing-xl)`     |
+| `2rem` (32px)                     | **xxl**       | `"xxl"`    | `var(--mantine-spacing-xxl)`    |
+| `2.5rem` (40px)                   | **xxxl**      | `"xxxl"`   | `var(--mantine-spacing-xxxl)`   |
+
+Values between steps: keep the literal (e.g. `rem(10)`), don't round to a token.
 
 **Border radius** — snap to the nearest Mantine radius token:
 
-| Hardcoded value  | Nearest token                 | CSS variable               |
-| ---------------- | ----------------------------- | -------------------------- |
-| `0.25rem` (4px)  | **xs** (4px)                  | `var(--mantine-radius-xs)` |
-| `0.375rem` (6px) | **sm** (6px)                  | `var(--mantine-radius-sm)` |
-| `0.5rem` (8px)   | **md** (8px)                  | `var(--mantine-radius-md)` |
-| `1rem`+ (16px+)  | **xl** (40px) or keep literal | `var(--mantine-radius-xl)` |
+| Hardcoded value  | Nearest token | CSS variable                  |
+| ---------------- | ------------- | ----------------------------- |
+| `0` (0px)        | —             | `0`                           |
+| `0.125rem` (2px) | **xxxs**      | `var(--mantine-radius-xxxs)`  |
+| `0.25rem` (4px)  | **xxs**       | `var(--mantine-radius-xxs)`   |
+| `0.375rem` (6px) | **xs**        | `var(--mantine-radius-xs)`    |
+| `0.5rem` (8px)   | **sm**        | `var(--mantine-radius-sm)`    |
+| `0.75rem` (12px) | **md**        | `var(--mantine-radius-md)`    |
+| `1rem` (16px)    | **lg**        | `var(--mantine-radius-lg)`    |
+| `1.5rem` (24px)  | **xl**        | `var(--mantine-radius-xl)`    |
+
+Fully-round pills/badges (radius ≥ half the element height): keep a literal
+such as `9999px`.
 
 **Font sizes** — snap to the nearest Mantine font size token:
 
@@ -398,7 +416,7 @@ export const Wrapper = styled.div`
 ```tsx
 export const Item = styled.div<{ isSelected: boolean; disabled: boolean }>`
   color: ${(props) =>
-    props.disabled ? color("text-tertiary") : color("text-primary")};
+    props.disabled ? color("text-disabled") : color("text-primary")};
   background-color: ${(props) =>
     props.isSelected ? color("core-brand") : "transparent"};
   cursor: ${(props) => (props.disabled ? "default" : "pointer")};
@@ -427,11 +445,11 @@ export const Item = styled.div<{ isSelected: boolean; disabled: boolean }>`
 }
 
 .disabled {
-  color: var(--mb-color-text-tertiary);
+  color: var(--mb-color-text-disabled);
   cursor: default;
 
   &:hover {
-    color: var(--mb-color-text-tertiary);
+    color: var(--mb-color-text-disabled);
   }
 }
 ```
@@ -574,7 +592,7 @@ export const Spinner = styled.div`
 | -------------------------- | ----------------------------------------------------------------- | ------------------------------------- |
 | `color("core-brand")`      | `var(--mb-color-core-brand)`                                      | `c="core-brand"` or `bg="core-brand"` |
 | `color("text-primary")`    | `var(--mb-color-text-primary)`                                    | `c="text-primary"`                    |
-| `color("border-neutral")`  | `var(--mb-color-border-neutral)`                                  | N/A (use CSS module)                  |
+| `color("border-neutral")`          | `var(--mb-color-border-neutral)`                                          | N/A (use CSS module)                  |
 | `alpha("core-brand", 0.2)` | `color-mix(in srgb, var(--mb-color-core-brand), transparent 80%)` | N/A (use CSS module)                  |
 
 ### Pattern 7: Responsive Spacing/Sizing → Responsive Style Props (NOT CSS Media Queries)

.claude/skills/fe-modularization/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: fe-modularization
+description: Deciding where frontend code lives — tier model, move mechanics, extension points, side effects, naming, and the traps. Use when moving code between modules, carving new modules, fixing boundary violations, adding a barrel or an endpoint, or reviewing module-shape decisions.
+---
+
+# Frontend modularization
+
+The module is the unit of blast radius: dependency direction, test selection,
+bundle cones, and review scope all follow module boundaries. Every decision
+here serves one goal: **make the file locations tell the truth about who owns
+what and who may depend on whom.**
+
+## Hard rules (check these before anything else)
+
+- NEVER add an `export … from` re-export at an old path, and NEVER `export *`
+  from a barrel. Move the code, codemod every call site, delete the old path,
+  all in the same PR.
+- NEVER import past a module's `index.ts` when that module has
+  `enforcePublicApi: true`, and never past `metabase/ui`'s index at all. If
+  the barrel is heavy, the fix is making the module side-effect free (below),
+  not a deep import.
+- NEVER rewrite a consumer to a lower-level idiom to make the linter pass. If
+  the fix makes the consumer worse, the plan is wrong.
+- NEVER give a new module `enforceSharedTiers: false`; new modules ship
+  enforced with `enforcePublicApi: true` and an explicit `index.ts`.
+- NEVER move code without the consumer-tier check (procedure step 2).
+- ALWAYS delete a module's `enforceSharedTiers: false` line in the PR that
+  takes it to zero violations.
+- ALWAYS measure `bun run module-boundaries` before and after, and report the
+  numbers.
+- ALWAYS import `dayjs` from `metabase/dayjs`, routing from `metabase/router`,
+  Mantine from `metabase/ui`, react-redux hooks from `metabase/redux`; the
+  raw specifiers are lint-forbidden.
+
+## Files that are ground truth
+
+| what | where |
+|---|---|
+| module elements, tiers, `enforceSharedTiers`, `enforcePublicApi` | `frontend/lint/module-boundaries.mjs` |
+| shared sub-tiers and levels, cluster rules | `frontend/lint/shared-tiers.mjs` |
+| standalone boundaries lint (all violations, incl. grandfathered) | `bun run module-boundaries` (config `eslint.config.module-boundaries.mjs`) |
+| PR lint (only enforced modules fail CI) | `bun run lint-eslint-pure` |
+| side-effect-free directories and their exceptions | `frontend/build/shared/rspack/side-effect-free-modules.js` (`SIDE_EFFECT_FREE_PATHS`, `SIDE_EFFECT_PATHS`) |
+| the lint rules that enforce that promise | `metabase/no-module-side-effects`, `metabase/no-base-api-access` in `frontend/lint/eslint-plugin-metabase/rules/` |
+| public-api enforcement | `metabase/enforce-module-public-api` rule, driven by `getPublicApiModules()` |
+
+## The model
+
+Tiers: `lib < basic < shared < feature < app`. Imports point downward, never
+sideways at feature tier (features may not import features; app and EE may
+import anything). The shared tier is subdivided in `shared-tiers.mjs` into
+shared-utils (U0…), shared-platform (P0…), and shared-domain, each ordered
+into levels. A module imports only *strictly lower* levels of its sub-tier
+plus the sub-tiers below; same-level peers are deliberately forbidden, which
+is what makes cycles structurally impossible. A domain may hold two seats
+when consumers demand it: a low core and a high surface (metabase-lib below
+questions below query_builder; viz-core below visualizations).
+
+Enforcement is per module: `enforceSharedTiers: false` on an element exempts
+it from the level rules (counted by `bun run module-boundaries`, invisible to
+PR lint). Modules with `enforcePublicApi: true` may only be imported from
+outside via `metabase/<module>`, and import relatively inside.
+
+## Deciding where code lives (apply in order; first decisive test wins)
+
+1. **Who owns the concept?** Code lives with the module that owns its
+   concept, not the module that renders or calls it. A mode encoding dashboard
+   click behaviour is dashboard code even if viz executes it. Metabot
+   conversation state is metabot state even though the store registers it.
+2. **Consumer-tier check.** The destination must sit at or below the file's
+   *lowest* consumer. A single consumer below the proposed home vetoes the
+   move; report it, don't force it.
+3. **Only four legitimate fixes** for a bad edge: move the code to its
+   terminal home; invert through a designed extension point (a prop, an
+   injected component, a contract type owned by the socket); fix the tier
+   placement when the declared level is wrong; delete a thin wrapper (a rename
+   with no derivation isn't an abstraction — deleting it *is* the migration).
+4. **A bridge lives above the lower endpoint.** Code that needs both sides of
+   a boundary belongs in or above the higher module.
+5. **"Genuinely shared" is proven by consumers.** A shared address needs two
+   or more consumers the tier rules can't serve another way. One consumer
+   pretending to be shared is a feature module at the wrong address.
+
+## Extension points
+
+The socket's owner defines the contract; every plug lives with its extender.
+Visualization owns the `mode` prop and click interfaces, each surface supplies
+its mode; the editor owns its extension contract, metabot supplies tiptap
+extensions; querying owns `TemplateTagsSidebarProps`, parameters implements
+it.
+
+- Prefer plain props/injection at composition sites. `PLUGIN_*` registries are
+  for edition gating; single-reader slots move out to their reading module;
+  slots with many readers live in the module that owns the concept (every
+  slot the whitelabel plugin fills lives in `whitelabel`), tier permitting.
+  Keep contracts type-light so implementations can load lazily.
+- Identical injection at every callsite is acceptable until a fourth consumer
+  or second slot appears; then the composition deserves its own module above
+  both parts. Don't pre-build the wrapper.
+
+## Store shape
+
+A module that has redux state owns it:
+
+- `store/` is private: reducer, plain creators/action types, and selectors,
+  typed against the module's own state (`QueryBuilderStoreState`), never the
+  global `State`. Thunks live in `actions/` and import `store/`, never the
+  reverse.
+- The barrel is the state API: selectors for reads, creators/thunks for
+  writes.
+- Store roots (`reducers-main`, `reducers-public`, the SDK store) import each
+  slice from its module barrel and derive their own state type; no slice
+  registry, no `declare module` merging.
+- Cross-module writes: a callback prop when a composition point exists;
+  otherwise dispatch the owner's exported creator; an event only when the
+  emitter must not know its listeners. Raw `dispatch({ type: "…" })` strings
+  are banned. A reducer or listener matching another module's *internal*
+  action is the coupling to remove.
+- Slices that mirror one endpoint get deleted (the RTK cache is the state); a
+  fold over many sources with one writer (the metadata store) is kept as a
+  module-private slice behind the barrel.
+
+## Endpoints
+
+Endpoints migrate to their owning module via `Api.injectEndpoints` from the
+module's `api/` file (settings, metabot, transforms precedents); `metabase/api`
+trends toward the client only. There is one `Api` object per backend because
+tag invalidation only works within one instance. Consumers reach endpoints
+only through the owner's exports (`useGetCardQuery`, `cardApi.endpoints.…`),
+never by name through the base object; `metabase/no-base-api-access` allows
+injection only in `metabase/api` and `**/api/**` / `**/api.ts`, and reaching by
+name only in `metabase/api` and test support (`invalidateTags` /
+`resetApiState` are fine anywhere). Each endpoint move carries its
+metadata-store hookup: the owner calls `entitiesFetched` from its own
+`onQueryStarted`.
+
+## Import-time side effects
+
+Directories in `SIDE_EFFECT_FREE_PATHS` are marked `sideEffects: false` for
+rspack, so importing one export from their barrel no longer drags the whole
+barrel into a bundle. The price: nothing in those directories may do work at
+import time, or production silently drops it. `metabase/no-module-side-effects`
+enforces this over every listed directory (module-scope calls, writes to
+imported objects or globals, bare imports, control flow at import; escape
+hatches are `/* #__PURE__ */` and the rule's pure-callee list). Files that
+must run at import are listed in `SIDE_EFFECT_PATHS` (files or directories).
+
+- **A library the app configures gets a facade module** owning the vendor
+  import, the registrations, and the types, with the raw specifier
+  lint-forbidden outside it: `metabase/router`, `metabase/ui`,
+  `metabase/redux`, `metabase/dayjs`. Facades are the effect, so they never
+  enter `SIDE_EFFECT_FREE_PATHS`. Never re-register a vendor plugin locally
+  (`dayjs.extend`, `echarts` `use`).
+- **A patch a component needs is an explicit registration module,
+  bare-imported by the provider that needs it** and listed in
+  `SIDE_EFFECT_PATHS` (Mantine's `Popover.Dropdown` replacement, imported by
+  `ThemeProvider`).
+- **Effects with no value to import** (global CSS, polyfills, the CSP nonce,
+  EE plugin bootstrap) live in the entry's side-effects file and nowhere else.
+- **Registries are filled from the composition root at boot**
+  (`initializePlugins`, `registerVisualizations`), never by a module
+  registering itself at import.
+- **RTK injection stays at import**; when a module with an `api/` folder is
+  declared side-effect free, list `<module>/api/` in `SIDE_EFFECT_PATHS`.
+
+## Naming
+
+The feature keeps the plain product-surface name; a shared carve is named for
+what the shared part actually is: the concept when the concept is the shared
+thing (`settings`, `current-user`, `whitelabel`, `dayjs`), or a qualified
+capability when the plain noun is taken (`search-ui`, `metrics-ui`,
+`viz-core`, `data-studio-ui`). Never two modules distinguished only by tier
+prefix; never generic `-shared` / `-feature` suffixes.
+
+## Procedure for a move
+
+1. **Enumerate consumers honestly** (hook-name greps miss the last three):
+   ```
+   grep -rn "metabase/<module>" frontend/src enterprise/frontend/src frontend/test e2e
+   grep -rn "jest.mock(\"metabase/<module>" frontend enterprise/frontend
+   grep -rn "addMatcher(.*<endpoint>" frontend/src enterprise/frontend/src
+   ```
+   plus sibling files importing the moved file relatively. Classify each by
+   module and tier from `module-boundaries.mjs` / `shared-tiers.mjs`.
+2. **Consumer-tier check**: destination at or below the lowest consumer. If
+   not, stop and report the blocking consumer.
+3. **Measure before**: `bun run module-boundaries 2>&1 | tail -1` on the base
+   (write the number down).
+4. **Move**: `git mv`; codemod every importer to `metabase/<module>` (outside)
+   or a relative path (inside); add named exports to the destination barrel
+   for every symbol an outside consumer needs (each must have a real
+   consumer). Delete the old path. If the module didn't exist: add its element
+   in `module-boundaries.mjs` (ordered before any element it's carved from,
+   first match wins), its level in `shared-tiers.mjs`, `enforcePublicApi:
+   true`, an `index.ts`. If the move empties a module's violations, delete
+   its `enforceSharedTiers: false` line. If the module has an `api/` folder
+   and is side-effect free, list `<module>/api/` in `SIDE_EFFECT_PATHS`.
+5. **Verify** (all of these, report the numbers):
+   ```
+   grep -rn "<old path>" frontend enterprise/frontend e2e        # must be empty
+   bunx eslint --no-warn-ignored <touched files>
+   bun run lint-eslint-pure                                       # enforce-module-public-api included
+   bun run type-check-pure
+   bun run test-unit-keep-cljs <touched folders' specs>
+   bun run module-boundaries 2>&1 | tail -1                       # after; no violation may name the new files
+   bun run build-release:static-viz                               # only if viz/static-viz/ui/dayjs touched; hard 3.5 MiB budget
+   ```
+6. **Report**: count before/after (state count-neutral explicitly), the edges
+   removed by file, flags/rules deleted, barrel exports added, anything you
+   skipped and why, and any consumer you found that vetoed part of the move.
+
+## Traps (each has bitten at least once)
+
+- **Late binding.** A bare function reference in a `createSelector` input
+  array, a component identity captured for comparison, a `PLUGIN_*` object
+  read at module scope: all capture at import time and dodge jest spies, EE
+  overrides, and lazy loading. Read at call time (`(_state) => fn()`), or
+  inject.
+- **Plans go stale.** Verify every recipe against current code before
+  executing; things get merged, renamed, or turn out never to have existed.
+  Skip-and-report beats force.
+- **The linter's blind spots**: `export … from` re-exports, bare-specifier
+  packages (custom-viz), pre-seeded caches that never register tags. A grep
+  for the old path is the stronger claim than a green lint run.
+- **Path-keyed baselines reset on rename**: a generated per-file ledger
+  silently loses a file's history when it moves.
+- **A heavy barrel is a bundle hazard until its module is side-effect free.**
+  One constant imported from the `metabase/ui` barrel pulled Mantine into the
+  static-viz bundle and broke its budget; the fix was `SIDE_EFFECT_FREE_PATHS`,
+  never a deep import.
+- **Type augmentation is program-wide.** `declare module "dayjs"` (and
+  similar) makes plugin types available to any file in the same tsconfig, so
+  a passing type-check never proves the setup ran; only importing the facade
+  does.
+- **Environment before diagnosis**: after a dependency-touching merge,
+  `bun install` before declaring a failure real; worktrees share staleness
+  through the node_modules symlink, and a stale `target/cljs_dev` makes
+  `type-check-pure` fail on `metabase-lib/metric/core.ts` (rebuild cljs in the
+  worktree).
+
+## PR shape
+
+One logical change per PR; the body names the specific edges removed (files,
+imports, before/after count) and gives each move's ownership reason in plain
+language a reviewer outside the effort can follow, without campaign labels.
+Stack only for semantic dependency or same-hot-file serialisation, and say
+so. Consider codeowner surface when chunking. Open as a draft until measured
+and green.

.claude/skills/metabase-ui-component-from-figma/SKILL.md

@@ -31,6 +31,11 @@ Phases 1, 2, 5 and 6 are shared. The middle two differ in **order**: update mode
    - **The component's intended API** — variants, sizes, and states the design system supports for this component. This defines the axes of your showcase (Phase 3).
 3. Decide the mode (see **Two modes** above): search for an existing component — in `metabase/ui` or as a legacy component elsewhere. Found → **update**; nothing equivalent anywhere → **create**. Confirm with the user when unsure.
 4. **Verify a Figma desktop MCP is connected before doing the work** — this skill depends on it for exact tokens in Phase 4 (and styling can't proceed accurately without it). Do a quick read against the issue's node (e.g. `get_metadata`/`get_variable_defs`); if it errors with "nothing selected" or the server isn't connected, prompt the user to enable it (Switch to Dev Mode → MCP section in the right sidebar) and select the relevant layer before continuing.
+5. **Figma Desktop MCP environments only:** open the issue's exact page with [`figma-open`](./figma-open) before MCP reads. Do not run this helper when Desktop MCP is unavailable.
+   ```bash
+   .claude/skills/metabase-ui-component-from-figma/figma-open "<figma-url-with-node-id>"
+   ```
+   A URL with `node-id` needs no token. Bare page-name and `--list` lookups require an already-configured `FIGMA_TOKEN`.
 
 ## Phase 2 — Understand the component
 
@@ -205,7 +210,7 @@ Per `docs/developers-guide/frontend.md` ("Colors"): every color must be a **sema
 
 The same discipline applies to **dimensional** values — radius, spacing/padding/gap, elevation/shadow, and typography (font size, line-height, weight). Prefer the codebase's existing scale variable over a literal: `--mantine-radius-*`, `--mantine-spacing-*`, `--mantine-shadow-*`, and the Mantine font tokens.
 
-But Figma's scales don't always line up with the codebase's. When a Figma value **has no matching step** in the corresponding scale — e.g. Figma `radius/md = 12px` while `--mantine-radius-md` is `8px`, or a Figma `xxxs` spacing step with no Mantine equivalent — **don't silently bake in a literal.** Flag it to the user the same way you flag primitive colors: name the property, the Figma value, and the nearest codebase token, so it can be resolved with design / the scale owners (align the value, or add a scale step). Only fall back to a literal if the user confirms it's an accepted one-off, and leave a short comment in the code explaining why.
+But Figma's scales don't always line up with the codebase's. When a Figma value **has no matching step** in the corresponding scale — e.g. Figma `radius/md = 16px` while `--mantine-radius-md` is `0.75rem`, or a Figma spacing step that has no Mantine equivalent — **don't silently bake in a literal.** Flag it to the user the same way you flag primitive colors: name the property, the Figma value, and the nearest codebase token, so it can be resolved with design / the scale owners (align the value, or add a scale step). Only fall back to a literal if the user confirms it's an accepted one-off, and leave a short comment in the code explaining why. The codebase scales are defined in `frontend/src/metabase/ui/theme.ts` (`SPACING_SCALE`, `RADIUS_SCALE`, `LIGHT_SHADOWS`/`DARK_SHADOWS`).
 
 ### Mantine implementation notes (reference)
 
@@ -240,5 +245,6 @@ Only after sign-off:
 - [ ] Storybook showcase matrix built from the component's full state space (theme excluded — global toggle drives light/dark), single panel, hover/pressed forced via `storybook-addon-pseudo-states`, controls scoped per story; lint + type-check pass. (Update mode: built before styling, **component styles untouched**. Create mode: built after the component is implemented in Phase 4.)
 - [ ] Figma desktop MCP available; exact tokens extracted and mapped to semantic `--mb-color-*` (NO `color-mix`, NO primitives) and to existing scale vars for radius/spacing/elevation/type — any color *or* dimensional value with no matching token/scale step flagged to the user, not baked in as a literal.
 - [ ] Component styled; stylelint + eslint(+CSS modules) + type-check pass.
+- [ ] Loki coverage registered: `storiesFilter` matches exact story display names; targeted `loki update` generated references; reference PNGs and Playwright screenshots visually inspected; targeted `loki test` passes; `.loki/reference/*.png` included in the commit.
 - [ ] Iterated with the user until satisfied.
 - [ ] Committed (when asked); call sites migrated/verified (update) or export wired (create); findings doc handed back.

.claude/skills/metabase-ui-component-from-figma/figma-open

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# figma-open — open a Figma file (or a specific page) in the Figma desktop app
+#
+# Usage:
+#   figma-open <url-or-file-key>              open the file
+#   figma-open <url-or-file-key> <node-id>    open at a node/page id (e.g. 12-3 or 12:3)
+#   figma-open <url-or-file-key> --list       list pages with their ids
+#   figma-open <url-or-file-key> "Page name"  open a page by name
+#
+# Page lookup by name/--list needs a Figma personal access token:
+#   export FIGMA_TOKEN=figd_...   or put it in ~/.config/figma/token
+set -euo pipefail
+
+arg="${1:-}"
+[[ -n "$arg" ]] || { awk 'NR==1 && /^#!/ {next} /^#/ {sub(/^# ?/,""); print; next} {exit}' "$0"; exit 1; }
+
+token="${FIGMA_TOKEN:-}"
+[[ -f "$HOME/.config/figma/token" ]] && token="$(<"$HOME/.config/figma/token")"
+
+# Extract the file key from any Figma URL form, or use the arg as a bare key.
+key="$arg"
+case "$arg" in
+  *figma.com*|figma://*)
+    key="$(printf '%s' "$arg" | sed -E 's#https?://([a-z]+\.)?figma\.com##; s#^([a-z0-9-]+\.)?figma\.com##; s#^figma://##; s#^/?(file|design|proto|board)/##; s#^/##; s#/.*##; s#\?.*##')"
+    ;;
+esac
+
+req="${2:-}"
+
+# If no page arg was given but the URL carries a node-id, use it.
+url_node="$(printf '%s' "$arg" | sed -nE 's/.*[?&]node-id=([0-9]+([-:][0-9]+)*).*/\1/p')"
+
+open_fig() { # $1 = optional node id
+  if [[ -n "${1:-}" ]]; then
+    open "figma://file/${key}?node-id=${1//:/-}"
+  else
+    open "figma://file/${key}"
+  fi
+}
+
+# No page requested — open the file (or the node the URL points at).
+[[ -z "$req" ]] && { open_fig "${url_node:-}"; exit 0; }
+
+# Explicit node id (page ids work: pages are top-level nodes).
+if [[ "$req" =~ ^[0-9]+[:-][0-9]+$ ]]; then
+  open_fig "$req"
+  exit 0
+fi
+
+# Everything else needs the REST API.
+[[ -n "$token" ]] || { echo "error: page lookup needs FIGMA_TOKEN (env or ~/.config/figma/token)" >&2; exit 1; }
+
+pages_json="$(curl -sf -H "X-Figma-Token: ${token}" "https://api.figma.com/v1/files/${key}?depth=1")" \
+  || { echo "error: could not fetch file ${key} (bad key, no access, or bad token)" >&2; exit 1; }
+
+if [[ "$req" == "--list" || "$req" == "-l" ]]; then
+  printf '%s\n' "$pages_json" | jq -r '.document.children[] | "\(.id // .guid)\t\(.name)"' | column -t -s $'\t'
+  exit 0
+fi
+
+# Page by name (case-insensitive, exact match first, then substring).
+node_id="$(printf '%s' "$pages_json" | jq -r --arg n "$req" \
+  'first(.document.children[] | select((.name // "") | ascii_downcase == ($n | ascii_downcase)) | .id // .guid) //
+   first(.document.children[] | select((.name // "") | ascii_downcase | contains($n | ascii_downcase)) | .id // .guid) //
+   empty')"
+
+[[ -n "$node_id" ]] || { echo "error: no page matching \"$req\" in file ${key}" >&2; exit 1; }
+open_fig "$node_id"

.claude/skills/typescript-review/SKILL.md

@@ -13,14 +13,14 @@ allowed-tools: Read, Grep, Bash, Glob, Skill
 
 **Primary standard: the [`typescript-write`](../typescript-write/SKILL.md) skill.** Load it first — it defines the authoring rules this review enforces, alongside `frontend/CLAUDE.md` and `docs/developers-guide/frontend.md`.
 
-Adherence to `typescript-write` is the **highest-priority** review dimension: rank any violation of its provisions above all other findings. Treat its **no-`any` hard rule** (no explicit *or* implicit `any` in new code) as **blocking**, and verify it with the LSP rather than by eye.
+Adherence to `typescript-write` is the **highest-priority** review dimension: rank any violation of its provisions above all other findings. Treat its **no-`any` hard rule** (no explicit *or* implicit `any` in new code) as **blocking**. Use TypeScript LSP tools to inspect inferred types when available; otherwise rely on type-checking and linting.
 
 Review in this priority order:
 
-1. **Violations of [`typescript-write`](../typescript-write/SKILL.md) provisions** — no-`any`, type tightening, type modeling, null/undefined handling, naming, structure, comments. Highest priority; block on the no-`any` rule.
+1. **Violations of [`typescript-write`](../typescript-write/SKILL.md) provisions** — no-`any`, type tightening, type modeling, function signatures, null/undefined handling, naming, structure, comments. Highest priority; block on the no-`any` rule. Apply conditional guidance in context: explain the unsupported type guarantee or concrete readability problem, rather than treating every preference as a blanket ban.
 2. Compliance with `frontend/CLAUDE.md`.
 3. Readability and maintainability.
-4. Appropriate test coverage.
+4. Appropriate test coverage. For internal typed callers, avoid requesting tests solely for inputs the type system excludes. External API data, deserialised values, storage and JavaScript callers can violate annotations: test runtime validation and nontrivial assumptions at those boundaries. Types do not replace behavioural, security or data-integrity tests.
 
 ## Blind spots — act as the missing reviewer
 
@@ -31,3 +31,4 @@ These rarely surface in team reviews, so this skill should raise them. They are
 - **Security.** Evaluate potential security issues in new code.
 - **Bundle size.** Flag new large dependencies, default imports from icon or util libs, and heavy modules imported at route-load time.
 - **Analytics.** User-facing flows should emit tracking events. If a PR adds a new flow (button, modal, navigation) without a tracking event, ask whether one is expected.
+- **Public API surface** (embedding SDK). Consumers should be able to use public signatures and name types they need to import. Export those types deliberately and document public behaviour, including `@deprecated` for deprecated APIs; a referenced structural type does not automatically need its own named export.

.claude/skills/typescript-write/SKILL.md

@@ -13,26 +13,34 @@ description: Write TypeScript and JavaScript code following Metabase coding stan
 
 - **New code must not introduce `any`, explicit or implicit.** No `any` annotations, no `as any` / `as unknown as`, no untyped parameters or returns that infer `any`, no implicitly-`any` destructures or array/object literals.
 - **Untyped third-party / boundary values** must be typed at the boundary (a declared type, `unknown` + type guard, or a small typed wrapper) — never let `any` propagate inward.
-- **Mandatory LSP verification.** After writing or editing any TS/TSX, inspect the changed symbols with the TypeScript Language Server (hover to read inferred types; `goToDefinition` to confirm sources) and run the project type-check.
+- **Mandatory type verification.** Before finishing a TS/TSX change, run `bun run type-check-pure`. If TypeScript LSP tools are available, also inspect changed symbols with hover and go-to-definition; otherwise skip LSP check.
 
 ## Type tightening
 
 - **Avoid type casts and loose `unknown`** — fix the signature instead.
 - **If a function only needs one field of a wide object, accept that field** — not the wide object. The cast often disappears once the signature is right.
 - **Reach for `Partial<T>`, `Pick<T, K>`, `Record<K, V>`, and generics** before reaching for a cast.
+- **Match dictionary keys to the data.** Use a finite key union when the keys are known. Open dictionaries can use an index signature, `Record<string, T>`, or `Map`; index signatures still constrain values, and changing their spelling to `Record<string, T>` does not make missing-key access safe.
 - **Prefer making props/components generic** (`<T>`) when a value flows through unchanged and the caller knows the type.
 - **Prefer `unknown` over loose typing** and narrow before use — an `unknown` value forces a guard at the point of use.
 - **`satisfies` for object literals** that must conform without widening (config objects, lookup maps, discriminated literals) — better than `: T` (widens) or `as T` (unsafe).
 - **Avoid non-null assertions (`!`)**. Prefer a guard, early return, or `?.`. Use `!` only when non-nullness is provably true and localized, with a comment.
+- **Guard indexed lookups that may miss.** Arrays and dictionaries can return `undefined` even when the inferred type omits it. Use an iteration form that preserves the key/value relationship, and only assert `keyof` when the runtime keys are known to belong to the declared type.
 - **No redundant runtime coercion** — don't wrap already-typed values in `Number()` / `String()` / `Boolean()`.
 - **Type guards belong in `frontend/src/metabase-types/guards/`**. Do not redefine them locally.
+- **A cast you can't avoid needs a real justification comment.** The `metabase/no-unjustified-type-casts` rule accepts any preceding comment — state the actual reason the cast is safe. NEVER write the legacy `// Unjustified type cast. FIXME` placeholder; it exists only on casts that predated the rule, and copying it sneaks an unjustified cast past the linter. If you can't articulate why the cast is correct, the cast is wrong — fix the types.
+- **Keep unavoidable assertions local.** Isolate a repeated or complex assertion behind a helper when that makes its invariant easier to enforce. Test nontrivial runtime assumptions that justify it; a trivial assertion does not automatically need a new helper or test. Do not weaken a public signature just to silence implementation errors.
 
 ## Type modeling
 
 - **Reuse existing types; don't re-declare them.** Use canonical IDs and domain entity types from `metabase-types/api` (`FieldId`, `TableId`, `ConcreteTableId`, `SchemaName`, …) and key data structures by them (`new Map<ConcreteTableId, …>()`). Don't duplicate generated/API types — compose or derive (`Pick`, `Omit`, indexed access `SomeType["field"]`, `ReturnType`).
-- **Use generics to allow TypeScript to infer correct types** when creating functions and components that need to be reusable and type-safe. Don't hesitate to introduce complex generics if they allow to derive types automatically instead of manual narrowing.
+- **Generics must make promises the implementation can keep.** A caller-selected `get<T>(): T` must not disguise an unchecked assertion about external data. Return `unknown` and validate, or accept a validator that establishes `T`. A factory such as `function empty<T>(): T[] { return []; }` is valid; judge the implementation, not how often `T` appears in the signature.
+- **Prefer an honest type over false precision.** Use generics when they express a real relationship. If a complex type cannot model the behaviour accurately, choose a simpler type or `unknown` with narrowing instead of asserting an unsupported guarantee.
 - **Model the actual data contract; keep types narrow.** Optional `field?: T` for a key that may be absent, `field: T | undefined` only when the key is always present but the value may be undefined, `| null` for explicit API nulls. Prefer domain unions over broad `string` / `number` / loose `Record`.
 - **Refer to API implementation** when defining or refining types to ensure they match the actual data structure. When considering a type cast, first consider if the type should be refined to match the actual data structure.
+- **Optionality must reflect absence.** Keep required fields required and optional fields optional. Normalise input when the application has a meaningful default, not merely to remove a type error. Preserve the actual wire shape in API types.
+- **Represent related absence together when modelling internal state.** If several fields exist or disappear together, consider a nullable containing object or a discriminated union. Do not reshape a raw API declaration unless the data actually has that shape.
+- **Prefer explicit special states when designing a format.** Use nullability or named union variants when sentinel values such as `-1` hide meaning. Preserve established protocol sentinel values unless the behaviour is deliberately changed, or normalise them at an explicit boundary.
 - **Discriminated unions for variant state, with exhaustive checks.** Model "one of N shapes" as a union with a literal discriminant rather than a bag of optional fields, and exhaust it with ts-pattern's `.exhaustive()` so adding a variant becomes a compile error:
   ```ts
   import { match } from "ts-pattern";
@@ -44,20 +52,30 @@ description: Write TypeScript and JavaScript code following Metabase coding stan
     .exhaustive(); // Compile-time guarantee all cases handled
   ```
 - **Derive union types from constants** (`as const` + `typeof`/`keyof`) so the type and the values can't drift.
-- **`readonly` / immutability where mutation isn't intended** — component props, shared constants, exported config. Prefer `readonly T[]` / `ReadonlyArray<T>` for inputs you don't mutate.
+- **`readonly` / immutability where mutation isn't intended** — component props, shared constants, exported config, and unmutated parameters. Prefer `readonly T[]` / `ReadonlyArray<T>` for inputs you don't mutate. Functions that mutate caller-owned data should make that behaviour explicit.
+- **Construct complete, well-typed objects where practical.** Prefer an object expression when it avoids partially initialised state or assertions. Incremental construction is fine when it is clearer and maintains the type's invariants.
+- **Treat `metabase-lib` opaque types as black boxes.** Use `metabase-lib` functions to work with types such as `Lib.Query`, rather than casting into their internal representation.
 - **Type async and error states explicitly** (a discriminated union or the data-layer's typed result) — never leave loading/error/empty implicit.
 
+## Function signatures
+
+- **Make public contracts explicit where it improves stability and clarity.** Annotate parameters and return types at shared boundaries when useful; let local values infer. Use `satisfies` or an annotation when a declaration needs an explicit shape check.
+- **Accept the inputs the operation supports and return the most precise honest result.** Narrow avoidable uncertainty inside the function, but preserve meaningful nullability and union variants in its return type.
+- **Use named options when positional arguments are easy to confuse.** Consecutive arguments with the same type are a useful warning sign, not an automatic requirement to rewrite a clear API.
+- **Use `async`/`await` when it clarifies control flow or error handling.** Returning an existing promise directly is also valid; a Promise return type alone does not require adding `async`.
+
 ## Null and undefined
 
 - **Narrow at the source**. If a value is optional only in a corner case, don't thread `undefined` through every layer — guard at the producer.
 - **Sensible defaults for optional values**. Use `?.` and `??` at the consumer.
-- **Lists should be filtered** before being used in a map or other iteration.
+- **Narrow nullable list elements when the operation requires present values.** Filter with a type guard when missing entries should be discarded; preserve them when their absence or position carries meaning.
 - **Avoid non-strict null comparisons** (`X != null`) when `X` can never be `null` — use a strict check or narrow the type. Use `checkNotNull` where necessary.
 - **Check actual nullability against API implementation**. Find the API endpoint implementation and check if the field can actually be null.
 
 ## Naming
 
 - **Names describe the entity, not the mechanism**. A name must reflect what the value holds.
+- **Use domain vocabulary and include units where useful** (`timeoutMs`, `widthPx`, `temperatureC`). Prefer a more specific name when `Info`, `Data`, or `Entity` obscures the meaning, while keeping established terminology when it is clear.
 - **Align sibling concepts**: keep verb conventions consistent across a related API.
 - **No names that encode implementation history** rather than current meaning. Suffixes like `Base`, `New`, `Old`, `Initial` need a real semantic distinction, otherwise drop them.
 - **Avoid cryptic identifiers** (`v`, `n`, `$n`) for domain values; short names are fine only in tiny conventional contexts (loop index `i`, coordinates `x`/`y`, generic params `T`/`K`/`V`).
@@ -74,10 +92,6 @@ description: Write TypeScript and JavaScript code following Metabase coding stan
 - **No comments by default**. Well-named identifiers carry the `what`.
 - **Comments should be concise**. Add a short, concise comment only when the `why` is non-obvious: a workaround, a hidden invariant, a subtle ordering constraint, a clever reduction. Never document the actual implementation, focus on the intent and the why.
 
-## TypeScript Migration
-
-**When touching existing JavaScript files, propose to convert them to TypeScript first**. Create a separate PR for the conversion, then implement the changes.
-
 ## Verify before done
 
 - **Run the project type-check** when finished (see the shared TypeScript commands above).

.clj-kondo/config.edn

@@ -7,7 +7,6 @@
 
   :aliased-namespace-symbol     {:level :warning}
   :case-symbol-test             {:level :warning}
-  :condition-always-true        {:level :warning}
   :def-fn                       {:level :warning}
   :dynamic-var-not-earmuffed    {:level :warning}
   :equals-expected-position     {:level :warning, :only-in-test-assertion true}
@@ -50,9 +49,11 @@
   ;; disabled linters
   ;;
 
+  :constant-condition {:level :off} ; TODO (sashko): too confused by defenterprises, some hook/config is needed
   :redundant-ignore {:level :off} ; lots of false positives, see https://github.com/clj-kondo/clj-kondo/issues/2414
   :unexpected-recur {:level :off} ; TODO (cam): I think we just need to tell it how to handle MBQL match and we can enable this?
   :redundant-primitive-coercion {:level :off} ; there are many defensive boolean coercions, kondo looks too much into it
+  :type-mismatch {:level :off} ; Still quite raw, can sometimes give useful insights, but sometimes is just confused
 
   ;;
   ;; globally-enabled custom linters
@@ -71,6 +72,7 @@
   :metabase/namespace-name                                   {:level :warning}
   :metabase/no-jsqlparser-imports                            {:level :warning}
   :metabase/prefer-with-dynamic-fn-redefs                    {:level :warning}
+  :metabase/t2-query-namespace                               {:level :warning}
   :metabase/toucan-model-ns                                  {:level :warning}
   :metabase/require-shape-checker                            {:level :warning}
   :metabase/tests-must-live-in-known-modules                 {:level :warning}
@@ -179,14 +181,30 @@
      clojure.core.async/take!
      clojure.core.async/to-chan!
      clojure.core.async/to-chan!!
+     ;; writes the ratchet files from a :once fixture that finishes before the parallel tests
+     dev.kondo-ratchet/fix!
+     metabase.ai-tracing.core/record!
      metabase.api.macros.defendpoint.tools-manifest/assert-optional-fields-nullable!
      metabase.channel.core/send!
+     metabase.channel.render.pdf/draw-too-large!
+     metabase.channel.render.pdf/draw-no-results!
+     metabase.channel.render.pdf/render-card-cell!
+     metabase.channel.render.pdf.font/load-fonts!
      metabase.warehouses.models.database/assert-not-h2!
      metabase.driver.sql-jdbc.execute/execute-prepared-statement!
+     ;; only inspects a details map and throws; the `!` is for the throw, not for a mutation
+     metabase.driver/validate-db-details!
+     metabase.mcp.usage/record-mcp-session!
+     metabase.mcp.usage/record-mcp-session-end!
+     metabase.mcp.usage/record-mcp-tool-call!
      metabase.notification.models/create-notification!
      metabase.oauth-server.core/reset-provider!
      metabase.pulse.send/send-pulse!
      metabase-enterprise.transforms-python.python-runner-test/execute!
+     ;; MCP usage tests isolate their rows by unique keys (session id / tool name / duration /
+     ;; client version) and clean up only those, so these deletes are safe in parallel.
+     metabase-enterprise.mcp.usage-test/cleanup!
+     metabase-enterprise.mcp.usage-test/cleanup-calls!
      ;; Workspace isolation functions are safe in parallel tests because they operate on
      ;; isolated, test-specific workspaces and databases that don't affect other tests
      metabase-enterprise.workspaces.isolation/destroy-workspace-isolation!
@@ -248,9 +266,6 @@
   ;; misc config for built-in linters
   ;;
 
-  :invalid-arity       {:skip-args [metabase.util.match/match-one
-                                    metabase.util.match/match-many
-                                    metabase.util.match/replace]}                    ; TODO (cam): can we fix these?
   :refer-all           {:level :warning, :exclude [clojure.test]}
   :unused-referred-var {:exclude {compojure.core [GET DELETE POST PUT]}}
 
@@ -289,7 +304,10 @@
     metabase.query-processor.util/normalize-token                {:namespaces ["metabase.*"]}}}
 
   :discouraged-var
-  {clojure.core/print                                 {:message "Use metabase.util.log instead of clojure.core/print"}
+  {metabase-enterprise.entity-retrieval.core/search-unfiltered {:message "Permission bypass risk: library-index hits are unfiltered — resolve each entity and drop what the current user can't read"}
+   metabase.entity-retrieval.core/search-unfiltered            {:message "Permission bypass risk: library-index hits are unfiltered — resolve each entity and drop what the current user can't read"}
+   metabase.entity-retrieval.mirror/search-unfiltered          {:message "Permission bypass risk: library-index hits are unfiltered — resolve each entity and drop what the current user can't read"}
+   clojure.core/print                                 {:message "Use metabase.util.log instead of clojure.core/print"}
    clojure.core/println                               {:message "Use metabase.util.log instead of clojure.core/println"}
    clojure.core/printf                                {:message "Use metabase.util.log instead of clojure.core/printf"}
    clojure.core/prn                                   {:message "Use metabase.util.log instead of clojure.core/prn"}
@@ -388,6 +406,7 @@
     metabase.channel.render.core              channel.render
     metabase.cloud-migration.core             cloud-migration
     metabase.eid-translation.core             eid-translation
+    metabase.llm.test-util                    llm.tu
     metabase.login-history.core               login-history
     metabase.model-persistence.core           model-persistence
     metabase.notification.core                notification
@@ -444,15 +463,21 @@
   instaparse.core/defparser                                                             clojure.core/def
   metabase-enterprise.action-v2.test-util/with-test-tables!                             clojure.core/let
   metabase-enterprise.content-translation.routes-test/with-new-secret-key!              clojure.core/fn
-  metabase-enterprise.curated-search.reconcile-test/with-isolated-mirror                clojure.core/fn
+  metabase-enterprise.entity-retrieval.reconcile-test/with-isolated-index                 clojure.core/fn
+  metabase-enterprise.mfa.enrollment-flow-test/with-fresh-user-session!                  clojure.core/fn
+  metabase-enterprise.mfa.login-flow-test/with-enrolled-rasta!                           clojure.core/fn
+  metabase-enterprise.mfa.recovery-codes-test/with-confirmed-enrollment!                 clojure.core/fn
   metabase-enterprise.serialization.metadata-file-import.wire-format-test/with-tiny-fixture! clojure.core/fn
   metabase-enterprise.serialization.test-util/with-dbs                                  clojure.core/fn
   metabase-enterprise.serialization.test-util/with-random-dump-dir                      clojure.core/let
+  metabase-enterprise.tenants.pulse-api-test/with-tenant-pulse-fixture!                 clojure.core/fn
   metabase-enterprise.workspaces.test-util/with-resources!                              clojure.core/let
   metabase-enterprise.workspaces.test-util/with-workspaces!                             clojure.core/let
   metabase.actions.test-util/with-actions                                               clojure.core/let
   metabase.transforms.test-util/with-transform-cleanup!                                 clojure.core/let
   metabase.api.common/let-404                                                           clojure.core/let
+  metabase.app-db.connection/with-unshared-connection                                   clojure.core/fn
+  metabase.app-db.core/with-unshared-connection                                         clojure.core/fn
   metabase.app-db.custom-migrations.util/with-temp-scheduler!                           clojure.core/fn
   metabase.app-db.custom-migrations/define-migration                                    clj-kondo.lint-as/def-catch-all
   metabase.app-db.custom-migrations/define-reversible-migration                         clj-kondo.lint-as/def-catch-all
@@ -461,7 +486,7 @@
   metabase.channel.impl.http-test/with-captured-http-requests                           clojure.core/fn
   metabase.channel.impl.http-test/with-server                                           clojure.core/let
   metabase.collections.models.collection-test/with-collection-in-location               clojure.core/let
-  metabase.curated-search.api-test/with-test-entry                                      clojure.core/let
+  metabase.collections.test-utils/with-library                                          clojure.core/fn
   metabase.driver.mongo.connection/with-mongo-client                                    clojure.core/let
   metabase.driver.mongo.connection/with-mongo-database                                  clojure.core/let
   metabase.driver.mongo.query-processor/mongo-let                                       clojure.core/let
@@ -475,6 +500,8 @@
   metabase.notification.test-util/with-card-notification                                clojure.core/let
   metabase.notification.test-util/with-system-event-notification!                       clojure.core/let
   metabase.notification.test-util/with-temp-notification                                clojure.core/let
+  metabase.oauth-server.test-util/with-oauth-client                                     clojure.core/fn
+  metabase.osi.ai-context.api-test/with-test-entry                                      clojure.core/let
   metabase.premium-features.core/defenterprise-schema                                   clj-kondo.lint-as/def-catch-all
   metabase.premium-features.defenterprise/defenterprise-schema                          clj-kondo.lint-as/def-catch-all
   metabase.premium-features.settings/define-premium-feature                             clojure.core/def
@@ -483,7 +510,9 @@
   metabase.query-processor.pipeline-queries-test/mbql5-query                            clojure.core/->
   metabase.query-processor.pipeline-queries-test/run-mbql5-query                        clojure.core/->
   metabase.query-processor.error-type/deferror                                          clojure.core/def
+  metabase.query-processor.core/with-reducible-deserialized-results                     clojure.core/let
   metabase.query-processor.middleware.cache.impl/with-reducible-deserialized-results    clojure.core/let
+  metabase.query-processor.result-serialization/with-reducible-deserialized-results     clojure.core/let
   metabase.query-processor.middleware.process-userland-query-test/with-query-execution! clojure.core/let
   metabase.query-processor.setup/with-qp-setup                                          clojure.core/let
   metabase.search.api-test/do-test-users                                                clojure.core/let
@@ -500,7 +529,6 @@
   metabase.test.data.interface/defdataset                                               clojure.core/def
   metabase.test.data.interface/defdataset-edn                                           clojure.core/def
   metabase.test.embedded-postgres.core/with-system                                      clojure.core/let
-  metabase.test.gentest/defgentest                                                      clojure.test/deftest
   metabase.test/defdataset                                                              clojure.core/def
   metabase.test/let-url                                                                 clojure.core/let
   metabase.test/with-actions                                                            clojure.core/let
@@ -511,6 +539,7 @@
   metabase.test/with-temp-empty-app-db                                                  clojure.core/let
   metabase.test/with-temp-file                                                          clojure.core/let
   metabase.test/with-user-in-groups                                                     clojure.core/let
+  metabase.transforms-rest.api.transform-runs-test/with-runs-fixture!                   clojure.core/fn
   metabase.upload.impl-test/with-upload-table!                                          clojure.core/let
   metabase.util/for-map                                                                 clojure.core/for
   metabase.util.files/with-open-path-to-resource                                        clojure.core/let
@@ -576,7 +605,7 @@
    metabase.api.common.internal-test/with-jetty-server                                                                       hooks.common/with-one-binding
    metabase.api.macros/defendpoint                                                                                           hooks.metabase.api.macros/defendpoint
    metabase.app-db.schema-migrations-test.impl/test-migrations                                                               hooks.metabase.app-db.schema-migrations-test.impl/test-migrations
-   metabase.channel.render.js.svg/with-static-viz-context                                                                    hooks.common/with-one-top-level-binding
+   metabase.channel.render.js.pool/with-static-viz-context                                                                   hooks.common/with-one-top-level-binding
    metabase.channel.template.handlebars-helper/defhelper                                                                     hooks.metabase.channel.template.handlebars-helper/defhelper
    metabase.channel.template.handlebars-test/with-temp-template!                                                             hooks.common/with-vec-first-binding
    metabase.classloader.core/require                                                                                         hooks.clojure.core.require/lint-require
@@ -605,13 +634,56 @@
    metabase.lib.schema.mbql-clause/define-tuple-mbql-clause                                                                  hooks.metabase.lib.schema.mbql-clause/define-mbql-clause
    methodical.core/defmethod                                                                                                 hooks.metabase.toucan.table-name/lint-defmethod
    methodical.macros/defmethod                                                                                               hooks.metabase.toucan.table-name/lint-defmethod
+   metabase.app-db.core/query                                                                                                hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.core/streaming-reducible-query                                                                            hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.core/select-or-insert!                                                                                    hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.core/update-or-insert!                                                                                    hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.core/current-timestamp-string                                                                             hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.query/query                                                                                               hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.query/streaming-reducible-query                                                                           hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.query/select-or-insert!                                                                                   hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.query/update-or-insert!                                                                                   hooks.metabase.toucan.db-ns/lint-query-call
+   metabase.app-db.query/current-timestamp-string                                                                            hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/count                                                                                                        hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/delete!                                                                                                      hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/exists?                                                                                                      hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/insert!                                                                                                      hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/insert-returning-instance!                                                                                   hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/insert-returning-instances!                                                                                  hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/insert-returning-pk!                                                                                         hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/insert-returning-pks!                                                                                        hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/query                                                                                                        hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/query-one                                                                                                    hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/reducible-query                                                                                              hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/reducible-select                                                                                             hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/reducible-update                                                                                             hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/reducible-update-returning-pks                                                                               hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/save!                                                                                                        hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select                                                                                                       hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-fn->fn                                                                                                hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-fn->pk                                                                                                hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-fn-reducible                                                                                          hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-fn-set                                                                                                hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-fn-vec                                                                                                hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-one                                                                                                   hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-one-fn                                                                                                hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-one-pk                                                                                                hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-pk->fn                                                                                                hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-pks-set                                                                                               hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/select-pks-vec                                                                                               hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/update!                                                                                                      hooks.metabase.toucan.db-ns/lint-query-call
+   toucan2.core/update-returning-pks!                                                                                        hooks.metabase.toucan.db-ns/lint-query-call
    metabase.lib.test-util.macros/$ids                                                                                        hooks.metabase.test.data/$ids
    metabase.lib.test-util.macros/mbql-query                                                                                  hooks.metabase.test.data/mbql-query
    metabase.lib.test-util.macros/mbql-5-query                                                                                hooks.metabase.test.data/mbql-query
    metabase.lib.test-util.macros/with-testing-against-standard-queries                                                       hooks.metabase.lib.test-util.macros/with-testing-against-standard-queries
+   metabase.metrics.api-dimension-test/with-seeded-metric                                                                    hooks.common/with-one-binding
    metabase.model-persistence.api-test/with-persistence-setup!                                                               hooks.common/with-one-top-level-binding
    metabase.model-persistence.api-test/with-setup!                                                                           hooks.common/with-one-top-level-binding
    metabase.model-persistence.test-util/with-persistence-enabled!                                                            hooks.metabase.model-persistence.test-util/with-persistence-enabled!
+   metabase.mq.core/with-queue                                                                                               hooks.common/let-second
+   metabase.mq.test-util/with-test-mq                                                                                        hooks.common/with-one-binding
+   metabase.mq.core/def-listener!                                                                                            hooks.metabase.mq.impl/def-listener
    metabase.models.interface/define-batched-hydration-method                                                                 hooks.metabase.models.interface/define-hydration-method
    metabase.models.interface/define-simple-hydration-method                                                                  hooks.metabase.models.interface/define-hydration-method
    metabase.permissions.core/allow-changing-all-users-group-members                                                          hooks.common/do*
@@ -654,7 +726,6 @@
    metabase.test.data/dataset                                                                                                hooks.metabase.test.data/dataset
    metabase.test.data/mbql-query                                                                                             hooks.metabase.test.data/mbql-query
    metabase.test.data/run-mbql-query                                                                                         hooks.metabase.test.data/mbql-query
-   metabase.test.gentest/iterate                                                                                             hooks.metabase.test.gentest/iterate*
    metabase.test.util.async/with-open-channels                                                                               hooks.common/let-with-optional-value-for-last-binding
    metabase.test.util.generators.jvm/with-random-cards                                                                       hooks.metabase.test.util.generators.jvm/with-random-cards
    metabase.test.util.log/with-log-level                                                                                     hooks.common/with-ignored-first-arg
@@ -703,6 +774,10 @@
    metabase.util.log/warn                                                                                                    hooks.metabase.util.log/info
    metabase.util.log/warnf                                                                                                   hooks.metabase.util.log/infof
    metabase.util.malli.registry/def                                                                                          hooks.metabase.util.malli.registry/def
+   metabase.util.match/match-one                                                                                             hooks.metabase.util.match/match-one
+   metabase.util.match/match-many                                                                                            hooks.metabase.util.match/match-many
+   metabase.util.match/replace                                                                                               hooks.metabase.util.match/replace
+   metabase.util.match/replace-in                                                                                            hooks.metabase.util.match/replace-in
    metabase.util/case-enum                                                                                                   hooks.metabase.util/case-enum
    metabase.util/format-color                                                                                                hooks.metabase.util/format-color
    metabase.xrays.api.automagic-dashboards-test/with-indexed-model!                                                          hooks.metabase.xrays.api.automagic-dashboards-test/with-indexed-model!
@@ -716,6 +791,7 @@
    clojurewerkz.quartzite.schedule.simple/schedule                                              macros.quartz/simple-schedule
    clojurewerkz.quartzite.triggers/build                                                        macros.quartz/build-trigger
    metabase-enterprise.database-routing.e2e-test/with-temp-dbs!                                 macros.metabase-enterprise.database-routing.e2e-test/with-temp-dbs!
+   metabase-enterprise.database-routing.e2e-test/with-routing-setup!                            macros.metabase-enterprise.database-routing.e2e-test/with-routing-setup!
    metabase-enterprise.impersonation.util-test/with-impersonations!                             macros.metabase-enterprise.impersonation.util-test/with-impersonations!
    metabase-enterprise.query-reference-validation.api-test/with-test-setup!                     macros.metabase-enterprise.query-reference-validation.api-test/with-test-setup!
    metabase-enterprise.sandbox.test-util/with-gtaps!                                            macros.metabase-enterprise.sandbox.test-util/with-gtaps!
@@ -746,6 +822,7 @@
    metabase.test/with-temporary-raw-setting-values                                              macros.metabase.test.util/with-temporary-raw-setting-values
    metabase.users.models.user-test/with-groups!                                                 macros.metabase.users.models.user-test/with-groups!
    metabase.util.namespaces/import-fn                                                           macros.metabase.util.namespaces/import-fn
+   metabase.util.namespaces/import-macro                                                        macros.metabase.util.namespaces/import-macro
    metabase.xrays.related-test/with-world                                                       macros.metabase.xrays.related-test/with-world}}
 
  :config-in-comment
@@ -767,7 +844,7 @@
    :name    test-namespaces}
   {:pattern "^(?!.*-test(?:\\..*)?$)(?!.*test-util)(?!^metabase\\.test.*).*$"
    :name    source-namespaces}
-  {:pattern "(?:(?:^metabase\\.cmd.*)|(?:^build.*)|(?:^metabuild-common.*)|(?:^release.*)|(?:^i18n.*)|(?:^lint-migrations-file$))|(?:^mage.*)"
+  {:pattern "(?:(?:^metabase\\.cmd.*)|(?:^build.*)|(?:^metabuild-common.*)|(?:^release.*)|(?:^i18n.*)|(?:^lint-migrations-file$))|(?:^mage.*)|(?:^load-namespaces.*)|(?:^dev\\..*)"
    :name    printable-namespaces}
   {:pattern "^metabase\\.(?:(?:lib)|(?:legacy-mbql))\\..*"
    :name    metabase-lib}
@@ -803,9 +880,14 @@
   ;;
   {:pattern "^metabase(?:((?:-enterprise\\.sandbox)?\\.query-processor)|(?:\\.driver\\.sql(?!server)(?!ite))).*-test$"
    :name    general-qp-and-driver-test-namespaces}
-
   {:pattern "(?:^mage.*)"
-   :name    mage-namespaces}]
+   :name    mage-namespaces}
+  ;;
+  ;; the app-db module is the application database layer itself (connections, migrations, encryption), so it gets to
+  ;; run Toucan 2 queries anywhere.
+  ;;
+  {:pattern "^metabase\\.app-db\\..*"
+   :name    app-db-namespaces}]
 
  :config-in-ns
  {test-namespaces
@@ -815,6 +897,7 @@
     :private-call                                        {:level :off}
     :metabase/defsetting-must-specify-export             {:level :off}
     :metabase/defsetting-namespace                       {:level :off}
+    :metabase/t2-query-namespace                         {:level :off}
     :metabase/test-helpers-use-non-thread-safe-functions {:level :warning} ; more config in `.clj-kondo/config/test-helpers/config.edn`
 
     :discouraged-var
@@ -822,6 +905,9 @@
      metabase.lib.convert/->legacy-MBQL {:level :off}
      metabase.lib.core/->legacy-MBQL    {:level :off}}}}
 
+  app-db-namespaces
+  {:linters {:metabase/t2-query-namespace {:level :off}}}
+
   ;; .cljc tests run in both Clojure and ClojureScript — `with-dynamic-fn-redefs` is JVM-only,
   ;; so leave these alone.
   metabase.lib.aggregation-test
@@ -829,6 +915,11 @@
   metabase.util.time-test
   {:linters {:metabase/prefer-with-dynamic-fn-redefs {:level :off}}}
 
+  ;; classloader sits below `util` in the module graph, so it can't use `metabase.util.log` without creating
+  ;; a cycle; it gets to use tools.logging directly.
+  metabase.classloader.impl
+  {:linters {:discouraged-namespace {clojure.tools.logging {:level :off}}}}
+
   source-namespaces
   {:linters
    {:metabase/discourage-millis-duration               {:level :warning}

.clj-kondo/config/modules/ratchets.edn

@@ -0,0 +1,6 @@
+;; Budgets for escape hatches in config.edn. Counts may fall but not exceed these values.
+;; Leave reductions to the post-merge shrink workflow; explain increases in the PR.
+{:api-any              1
+ :friend-edges         22
+ :model-imports-bypass 2
+ :uses-any             4}

.clj-kondo/config/test-helpers/config.edn

@@ -36,6 +36,9 @@
      ;; Definitely thread safe
      metabase.test.util.dynamic-redefs/patch-vars!
 
+     ;; test-only cleanup of in-memory throttle state (atom resets)
+     metabase.session.api/reset-throttlers-for-testing!
+
      ;; TODO: most of these symbols shouldn't be here, we should go through them and
      ;; find the functions/macros that use them and make sure their names end with !
      ;; best way to do this is try remove each of these and rely on kondo output to find places where it's used
@@ -55,6 +58,7 @@
      metabase.app-db.core/finish-db-setup!
      metabase.app-db.core/migrate!
      metabase.app-db.core/setup-db!
+     metabase.app-db.encryption-test-util/do-with-encrypted-app-db!
      metabase.app-db.schema-migrations-test.impl/run-migrations-in-range!
      metabase.app-db.setup/migrate!
      metabase.app-db.setup/setup-db!

.clj-kondo/macros/metabase/util/namespaces.clj

@@ -6,3 +6,8 @@
    `(def ~(-> sym name symbol) "docstring" ~sym))
   ([sym name]
    `(def ~name "docstring" ~sym)))
+
+(defmacro import-macro
+  "Kondo macro replacement for [[metabase.util.namespaces/import-macro]]."
+  [sym]
+  `(def ~(-> sym name symbol) "docstring" ~sym))

.clj-kondo/macros/metabase_enterprise/database_routing/e2e_test.clj

@@ -3,3 +3,8 @@
 (defmacro with-temp-dbs! [bindings & body]
   `(let [~@(interleave bindings (repeat nil))]
      ~@body))
+
+(defmacro with-routing-setup! [[router-binding destinations] & body]
+  `(let [~router-binding nil
+         ~@(interleave (map first destinations) (repeat nil))]
+     ~@body))

.clj-kondo/ratchets.edn

@@ -0,0 +1,81 @@
+;; Budgets for kondo suppressions: inline `:clj-kondo/ignore` forms per linter (:ignore-counts), and
+;; config-level waivers in .clj-kondo/config.edn (:config-counts -- :off switches and :exclude entries).
+;; Each :ignore-counts value is a non-negative integer budget, or :unlimited for no ceiling.
+;; Checks fail when a count exceeds its numeric budget; unused budget is allowed.
+;; Any ignore outside :comment-exempt needs an explanatory comment directly above or trailing on its line.
+;; `./bin/mage kondo-ratchets-shrink` lowers budgets unless `--seed` explicitly adds or raises one.
+;; The workflow runs it on master, so feature branches do not need to record reductions.
+;; Raising or adding a budget (`--seed` for inline ignores, a manual edit otherwise) or widening the
+;; exemptions must be explained in the PR.
+;; :all is the vector-less ignore form, which suppresses every linter on the next form.
+{:ignore-counts  {:aliased-namespace-symbol                                            3
+                  :case-symbol-test                                                    1
+                  :clojure-lsp/unused-public-var                                       9
+                  :consistent-alias                                                    2
+                  :def-fn                                                              1
+                  :deprecated-namespace                                                95
+                  :deprecated-var                                                      86
+                  :discouraged-java-method                                             4
+                  :discouraged-namespace                                               71
+                  :discouraged-var                                                     130
+                  :duplicate-require                                                   1
+                  :equals-true                                                         1
+                  :main-without-gen-class                                              1
+                  :metabase/defsetting-namespace                                       1
+                  :metabase/disallow-hardcoded-driver-names-in-tests                   34
+                  :metabase/discourage-millis-duration                                 1
+                  :metabase/i-like-making-cams-eyes-bleed-with-horrifically-long-tests 13
+                  :metabase/modules                                                    23
+                  :metabase/namespace-name                                             4
+                  :metabase/prefer-with-dynamic-fn-redefs                              28
+                  :metabase/test-helpers-use-non-thread-safe-functions                 18
+                  :metabase/validate-defendpoint-has-response-schema                   427
+                  :metabase/validate-defendpoint-query-params-use-kebab-case           48
+                  :metabase/validate-defendpoint-route-uses-kebab-case                 44
+                  :metabase/validate-deftest                                           10
+                  :missing-docstring                                                   12
+                  :missing-protocol-method                                             3
+                  :non-arg-vec-return-type-hint                                        1
+                  :reduce-without-init                                                 3
+                  :redundant-do                                                        1
+                  :syntax                                                              2
+                  :type-mismatch                                                       8
+                  :uninitialized-var                                                   1
+                  :unquote-not-syntax-quoted                                           1
+                  :unresolved-namespace                                                3
+                  :unresolved-symbol                                                   11
+                  :unsorted-required-namespaces                                        :unlimited
+                  :unused-alias                                                        2
+                  :unused-binding                                                      9
+                  :unused-excluded-var                                                 2
+                  :unused-namespace                                                    2
+                  :unused-private-var                                                  8
+                  :unused-value                                                        1}
+ :config-counts  {:constant-condition                      1
+                  :deprecated-namespace                    7
+                  :deprecated-var                          16
+                  :discouraged-namespace                   14
+                  :discouraged-var                         14
+                  :inline-def                              1
+                  :main-without-gen-class                  1
+                  :metabase/defsetting-must-specify-export 1
+                  :metabase/defsetting-namespace           1
+                  :metabase/prefer-with-dynamic-fn-redefs  3
+                  :metabase/t2-query-namespace             2
+                  :missing-docstring                       1
+                  :private-call                            1
+                  :redundant-ignore                        1
+                  :redundant-primitive-coercion            1
+                  :refer-all                               1
+                  :type-mismatch                           1
+                  :unexpected-recur                        1
+                  :unresolved-symbol                       19
+                  :unresolved-var                          1
+                  :unused-referred-var                     4}
+ :comment-exempt #{:deprecated-namespace
+                   :discouraged-namespace
+                   :discouraged-var
+                   :metabase/modules
+                   :metabase/validate-defendpoint-has-response-schema
+                   :metabase/validate-defendpoint-query-params-use-kebab-case
+                   :metabase/validate-defendpoint-route-uses-kebab-case}}

.clj-kondo/src/hooks/clojure/core/ns.clj

@@ -71,10 +71,28 @@
   (some-> (ns-form-node->ns-symb-node ns-form-node)
           hooks/sexpr))
 
+(defn- lint-test-parallel-metadata [ns-form-node]
+  (when-let [ns-symb-node (ns-form-node->ns-symb-node ns-form-node)]
+    (let [ns-metadata (meta (hooks/sexpr ns-symb-node))]
+      (cond
+        (:synchronous ns-metadata)
+        (hooks/reg-finding!
+         (assoc (meta ns-symb-node)
+                :message (str "Use `^:synchronized` to mark this namespace explicitly non-parallel; "
+                              "`^:synchronous` is ignored by Hawk. [:metabase/validate-deftest]")
+                :type :metabase/validate-deftest))
+
+        (and (contains? ns-metadata :parallel)
+             (false? (:parallel ns-metadata)))
+        (hooks/reg-finding!
+         (assoc (meta ns-symb-node)
+                :message "Use `^:synchronized` instead of `^{:parallel false}`. [:metabase/validate-deftest]"
+                :type :metabase/validate-deftest))))))
+
 (defn- lint-modules [ns-form-node config]
   (let [ns-symb (ns-form-node->ns-symb ns-form-node)]
     (when-not (modules/ignored-namespace? config ns-symb)
-      (when-let [current-module (modules/module ns-symb)]
+      (when-let [current-module (modules/module config ns-symb)]
         (let [required-namespace-symb-nodes (-> ns-form-node
                                                 ns-form-node->require-node
                                                 require-node->namespace-symb-nodes)]
@@ -140,6 +158,7 @@
     lint-requires-on-new-lines
     (lint-modules (modules/config x))
     lint-namespace-name
+    lint-test-parallel-metadata
     lint-jsqlparser-imports)
   x)
 

.clj-kondo/src/hooks/clojure/core/require.clj

@@ -11,15 +11,32 @@
          (every? simple-symbol? required-namespaces)]}
   (when-not (modules/ignored-namespace? config current-ns)
     ;; ignore namespaces outside of the module system
-    (when-let [current-module (modules/module current-ns)]
+    (when-let [current-module (modules/module config current-ns)]
       (doseq [required-namespace required-namespaces]
         ;; ignore namespaces outside of the module system.
-        (when (modules/module required-namespace)
+        (when (modules/module config required-namespace)
           (when-let [error (modules/usage-error config current-module required-namespace)]
             (hooks/reg-finding! (assoc (meta node)
                                        :message error
                                        :type    :metabase/modules))))))))
 
+(defn- lint-dynamic-require* [node current-ns config]
+  (when (and (not (modules/ignored-namespace? config current-ns))
+             (modules/module config current-ns))
+    (hooks/reg-finding! (assoc (meta node)
+                               :message "Module dependency cannot be statically determined from a dynamic require"
+                               :type    :metabase/modules))))
+
+(defn- quoted-require? [node]
+  (or (= (hooks/tag node) :quote)
+      (and (= (hooks/tag node) :list)
+           (let [[x] (:children node)]
+             (and (hooks/token-node? x)
+                  (= (hooks/sexpr x) 'quote))))))
+
+(defn- keyword-node? [node]
+  (keyword? (hooks/sexpr node)))
+
 (defn- unwrap-require [node]
   (case (hooks/tag node)
     ;; some.namespace of some.namespace/some-var
@@ -42,7 +59,11 @@
 
     ;; something like [some.namespace :as whatever]
     :vector
-    (recur (first (:children node)))))
+    (recur (first (:children node)))
+
+    ;; anything else -- e.g. a runtime expression like `(requiring-resolve (:failing-test-var opts))` --
+    ;; has no statically-known namespace
+    nil))
 
 (comment
   (unwrap-require (-> "(requiring-resolve 'metabase.notification.payload.execute/execute-dashboard)"
@@ -51,20 +72,24 @@
                       second)))
 
 (defn- lint-require* [node current-ns config]
-  (let [[_require & args]   (:children node)
-        required-namespaces (->> (keep unwrap-require args)
-                                 ;; `require` runs through `cc/load-libs` which allows
-                                 ;; #{:as :reload :reload-all :require :use :verbose :refer :as-alias}
-                                 ;; as args. If you use a REPL tool that applies clj-kondo linting (e.g., Clojure MCP)
-                                 ;; you may wish to `:reload` or `:reload-all` a namespace. So we shouldn't assume all
-                                 ;; args are keywords:
-                                 (remove keyword?))]
-    (lint* node current-ns config required-namespaces)))
+  (let [[_require & args]    (:children node)
+        ;; Keywords such as `:reload` and `:reload-all` are options, not namespace dependencies.
+        namespace-nodes     (remove keyword-node? args)
+        static-nodes        (filter quoted-require? namespace-nodes)
+        required-namespaces (->> (keep unwrap-require static-nodes)
+                                 (filter simple-symbol?))]
+    (lint* node current-ns config required-namespaces)
+    (when (or (not= (count static-nodes) (count namespace-nodes))
+              (not= (count required-namespaces) (count static-nodes)))
+      (lint-dynamic-require* node current-ns config))))
 
 (defn- lint-requiring-resolve* [node current-ns config]
   (let [[_requiring-resolve symb-node] (:children node)
         required-namespace             (unwrap-require symb-node)]
-    (lint* node current-ns config [required-namespace])))
+    (if (and (quoted-require? symb-node)
+             (simple-symbol? required-namespace))
+      (lint* node current-ns config [required-namespace])
+      (lint-dynamic-require* node current-ns config))))
 
 (defn lint-require [x]
   (lint-require* (:node x) (:ns x) (modules/config x))

.clj-kondo/src/hooks/clojure/test.clj

@@ -28,11 +28,11 @@
     (walk form)))
 
 (defn- deftest-check-parallel
-  "1. Check if test is marked ^:parallel / ^:synchronized correctly.
+  "1. Check if test is marked `^:parallel` / `^:synchronized` correctly.
    2. Make sure disallowed forms are not used in ^:parallel tests.
-   3. Disallow ^:parallel tests in namespaces marked ^:synchronous -- the
-      ns marker is the author's blanket promise that nothing inside runs
-      in parallel, so an individual ^:parallel deftest contradicts it."
+   3. Disallow `^:parallel` tests in namespaces marked `^:synchronized` --
+      the ns marker is the author's blanket promise that nothing inside runs
+      in parallel, so an individual `^:parallel` deftest contradicts it."
   [{[_ test-name & body] :children, :as _node} ns-sym config]
   (let [test-metadata     (:meta test-name)
         metadata-sexprs   (map hooks/sexpr test-metadata)
@@ -44,28 +44,48 @@
                            (completing merge)
                            {}
                            metadata-sexprs)
-        parallel?     (:parallel combined-metadata)
-        synchronized? (:synchronized combined-metadata)
-        ns-synchronous? (boolean (:synchronous (meta ns-sym)))]
+        parallel?                  (true? (:parallel combined-metadata))
+        synchronized?              (true? (:synchronized combined-metadata))
+        explicitly-nonparallel?    (or synchronized?
+                                       (and (contains? combined-metadata :parallel)
+                                            (false? (:parallel combined-metadata))))
+        ns-metadata                (meta ns-sym)
+        ns-explicitly-nonparallel? (or (true? (:synchronized ns-metadata))
+                                       (and (contains? ns-metadata :parallel)
+                                            (false? (:parallel ns-metadata))))]
+    (when (and (contains? combined-metadata :parallel)
+               (false? (:parallel combined-metadata)))
+      (hooks/reg-finding! (assoc (meta test-name)
+                                 :message (str "Use `^:synchronized` instead of `^{:parallel false}`. "
+                                               "[:metabase/validate-deftest]")
+                                 :type :metabase/validate-deftest)))
+    (when (:sequential combined-metadata)
+      (hooks/reg-finding! (assoc (meta test-name)
+                                 :message (str "Use `^:synchronized` to mark this test explicitly non-parallel; "
+                                               "`^:sequential` is ignored by Hawk. "
+                                               "[:metabase/validate-deftest]")
+                                 :type :metabase/validate-deftest)))
     (when (and parallel? synchronized?)
       (hooks/reg-finding! (assoc (meta test-name)
-                                 :message "Test should not be marked both ^:parallel and ^:synchronized"
+                                 :message "Test should not be marked both `^:parallel` and `^:synchronized`"
                                  :type :metabase/validate-deftest)))
-    (when (and parallel? ns-synchronous?)
+    (when (and parallel? ns-explicitly-nonparallel?)
       (hooks/reg-finding!
        (assoc (meta test-name)
-              :message (str "Test should not be marked ^:parallel in a namespace marked ^:synchronous -- "
+              :message (str "Test should not be marked `^:parallel` in a namespace marked "
+                            "`^:synchronized` -- "
                             "the ns marker promises no parallel execution. "
-                            "Drop ^:parallel from the deftest, or drop ^:synchronous from the ns. "
+                            "Drop `^:parallel` from the deftest, or drop `^:synchronized` from the ns. "
                             "[:metabase/validate-deftest]")
               :type :metabase/validate-deftest)))
-    ;; only when the custom `:metabase/deftest-not-marked-parallel-or-synchronized` is enabled: complain if tests are
-    ;; not explicitly marked `^:parallel` or `^:synchronized`. This is mostly to encourage people to mark everything
-    ;; `^:parallel` in places like `metabase.lib` tests unless there is a really good reason not to.
-    (when-not (or parallel? synchronized?)
+    ;; Only when the custom `:metabase/deftest-not-marked-parallel-or-synchronized` is enabled:
+    ;; complain if tests are not explicitly marked `^:parallel` or `^:synchronized`. This is
+    ;; mostly to encourage people to mark everything `^:parallel` in places like `metabase.lib`
+    ;; tests unless there is a really good reason not to.
+    (when-not (or parallel? explicitly-nonparallel?)
       (hooks/reg-finding!
        (assoc (meta test-name)
-              :message "Test should be marked either ^:parallel or ^:synchronized"
+              :message "Test should be marked either `^:parallel` or `^:synchronized`"
               :type :metabase/deftest-not-marked-parallel-or-synchronized)))
     (when parallel?
       (doseq [form body]
@@ -151,8 +171,11 @@
           (str/starts-with? (name ns-symb) prefix))
         ["build-drivers."
          "build."
+         "hooks." ; clj-kondo hook tests, outside the module system
          "i18n." ; bin/i18n
          "lint-migrations-file-test"
+         "load-namespaces." ; bin/load-namespaces
+         "mage."
          "main-test" ; bin/release-list
          "metabase.deps-edn-test"
          "metabase.driver."
@@ -171,7 +194,7 @@
                (not (contains? @warned-namespaces ns-symb)))
       (swap! warned-namespaces conj ns-symb)
       (let [known-modules  (set (keys (:metabase/modules (modules/config input))))
-            current-module (modules/module ns-symb)]
+            current-module (modules/module (modules/config input) ns-symb)]
         (when (or (not current-module)
                   (not (contains? known-modules current-module)))
           (hooks/reg-finding! (assoc (meta node)
@@ -231,18 +254,20 @@
 
 (defn use-fixtures
   "Flag `:parallel/unsafe` forms inside fixtures. Skipped when the surrounding
-  namespace is marked `^:synchronous` -- the ns marker is the author's
+  namespace is marked `^:synchronized` -- the ns marker is the author's
   explicit opt-in to a single-threaded test ns where destructive setup is
   safe. Without that opt-in, kondo can't know whether sibling deftests will
   be `^:parallel`, so the conservative default is to flag.
 
   Sister to [[deftest-check-parallel]]: the deftest hook rejects `^:parallel`
-  tests inside a `^:synchronous` ns, so the two checks together form a
-  coherent opt-in: either the whole ns is synchronous (fixtures can be
+  tests inside a `^:synchronized` ns, so the two checks together form a
+  coherent opt-in: either the whole ns is explicitly non-parallel (fixtures can be
   anything; no parallel tests allowed) or it isn't (fixtures must be
   parallel-safe)."
   [{:keys [node config], ns-sym :ns, :as input}]
-  (when-not (:synchronous (meta ns-sym))
+  (when-not (or (true? (:synchronized (meta ns-sym)))
+                (and (contains? (meta ns-sym) :parallel)
+                     (false? (:parallel (meta ns-sym)))))
     (let [linter-config (get-in config [:linters :metabase/validate-deftest])]
       (doseq [form (rest (:children node))]
         (warn-about-disallowed-parallel-forms form linter-config))))

.clj-kondo/src/hooks/common/modules.clj

@@ -1,4 +1,8 @@
 (ns hooks.common.modules
+  "Resolves namespaces to modules and enforces module boundaries.
+
+  The Kondo linter, config generator, and CI tooling share this namespace so
+  they apply the same rules."
   (:require
    [clojure.string :as str]))
 
@@ -12,25 +16,130 @@
   (merge (get-in config [:linters :metabase/modules])
          (select-keys config [:metabase/modules])))
 
-(defn module
+;;;; Module tree. These functions take the `:metabase/modules` map, or the prefix map built from it.
+;;;;
+;;;; Dots express nesting: `lib.schema` is a child of `lib`. A declared
+;;;; `enterprise/X` module is also a child of OSS module `X`. A namespace
+;;;; belongs to the module with the most specific matching `:ns-prefix`.
+
+(defn default-ns-prefix
+  "Namespace prefix a module owns unless it sets `:ns-prefix`: `metabase.lib.schema` for `lib.schema`,
+  `metabase-enterprise.foo` for `enterprise/foo`."
+  [module]
+  (str (if (= "enterprise" (namespace module)) "metabase-enterprise." "metabase.") (name module)))
+
+(defn module-ns-prefix
+  "Namespace prefix `module` owns: its `:ns-prefix`, else [[default-ns-prefix]]."
+  [modules module]
+  (or (get-in modules [module :ns-prefix])
+      (default-ns-prefix module)))
+
+(defn build-prefix->module
+  "Map each declared namespace prefix to its module, for [[declared-module]]."
+  [modules]
+  (into {}
+        (map (fn [module] [(module-ns-prefix modules module) module]))
+        (keys modules)))
+
+(defn declared-module
+  "Resolve `ns-symb` to its declared module, or `nil`.
+
+  Chooses the most specific dotted prefix and ignores a trailing `-test`."
+  [prefix->module ns-symb]
+  (loop [candidate (str/replace (str ns-symb) #"-test$" "")]
+    (or (get prefix->module candidate)
+        (when-let [dot (str/last-index-of candidate ".")]
+          (recur (subs candidate 0 dot))))))
+
+(defn resolve-module
   "E.g.
 
-    (module 'metabase.qp.middleware.wow) => 'qp
-    (module 'metabase-enterprise.whatever.core) => enterprise/whatever"
-  [ns-symb]
+    (resolve-module prefix->module 'metabase.qp.middleware.wow) => 'qp
+    (resolve-module prefix->module 'metabase-enterprise.whatever.core) => enterprise/whatever
+
+  An unmatched Metabase namespace resolves to its first segment so the linter can report an undeclared module."
+  [prefix->module ns-symb]
   {:pre [(simple-symbol? ns-symb)]}
   ;; treat something like `metabase.driver-test` (for a module that hasn't fully been updated to use `.core`
   ;; namespaces) as being in the `driver` module
   (let [ns-symb (if (str/ends-with? (name ns-symb) "-test")
                   (symbol (str/replace (name ns-symb) #"-test$" ""))
                   ns-symb)]
-    (or (some->> (re-find #"^metabase-enterprise\.([^.]+)" (str ns-symb))
+    (or (declared-module prefix->module ns-symb)
+        (some->> (re-find #"^metabase-enterprise\.([^.]+)" (str ns-symb))
                  second
                  (symbol "enterprise"))
         (some-> (re-find #"^metabase\.([^.]+)" (str ns-symb))
                 second
                 symbol))))
 
+(defn parent-module
+  "The direct parent of `module`, or `nil` when it is top-level."
+  [modules module]
+  (let [module-name (name module)]
+    (if-let [dot (str/last-index-of module-name ".")]
+      (symbol (namespace module) (subs module-name 0 dot))
+      (when (= "enterprise" (namespace module))
+        (let [oss (symbol module-name)]
+          (when (contains? modules oss)
+            oss))))))
+
+(defn descendant-of?
+  "Whether `module` is `ancestor` or one of its descendants."
+  [modules module ancestor]
+  (boolean (some #{ancestor} (take-while some? (iterate #(parent-module modules %) module)))))
+
+(defn- exports-child?
+  [modules parent child]
+  (or (contains? (set (get-in modules [parent :module-exports])) child)
+      ;; OSS module `X` implicitly exports its `enterprise/X` companion.
+      (and (not= (namespace parent) (namespace child))
+           (contains? modules child))))
+
+(defn- blocking-export
+  "The first missing export from `module` toward the root.
+
+  Returns `{:ancestor parent, :child child}`, or `nil` when every link is
+  exported."
+  [modules module]
+  (loop [child module]
+    (when-let [ancestor (parent-module modules child)]
+      (if (exports-child? modules ancestor child)
+        (recur ancestor)
+        {:ancestor ancestor, :child child}))))
+
+(defn namability-error
+  "Explain why `caller` may not refer to `target` in `:uses`, or return `nil` if it may.
+
+  A nested module is private to the nearest ancestor with a missing export.
+  Exporting every link makes it public."
+  [modules caller target]
+  (when-let [{:keys [ancestor child]} (blocking-export modules target)]
+    (when-not (descendant-of? modules caller ancestor)
+      (format (str "Module %s is nested and not exported by its ancestors; %s may not use it. Add %s to %s's "
+                   ":module-exports, or move the caller into the %s subtree. [:metabase/modules %s :module-exports]")
+              target caller child ancestor ancestor ancestor))))
+
+;;;; Lint rules. These functions take the full linter config.
+
+(defonce ^:private prefix->module-cache
+  (atom nil))
+
+(defn- prefix->module
+  "[[build-prefix->module]] for `config`, cached because Kondo hands every hook call the same `:metabase/modules` map."
+  [config]
+  (let [modules (:metabase/modules config)
+        cached  @prefix->module-cache]
+    (if (identical? modules (:modules cached))
+      (:prefix->module cached)
+      (:prefix->module (reset! prefix->module-cache {:modules        modules
+                                                     :prefix->module (build-prefix->module modules)})))))
+
+(defn module
+  "Resolve `ns-symb` to its module under `config`; see [[resolve-module]]."
+  [config ns-symb]
+  (resolve-module (prefix->module config) ns-symb))
+
 (defn- module-api-namespaces
   "Set of API namespace symbols for a given module. `:any` means you can use anything, there are no API namespaces for
   this module (yet). If unspecified, the default is just the `<module>.core` namespace."
@@ -44,9 +153,7 @@
       module-config
 
       :else
-      (let [ns-prefix (if (= (namespace module) "enterprise")
-                        (str "metabase-enterprise." (name module))
-                        (name module))]
+      (let [ns-prefix (module-ns-prefix (:metabase/modules config) module)]
         #{(symbol (str ns-prefix ".api"))
           (symbol (str ns-prefix ".core"))
           (symbol (str ns-prefix ".init"))}))))
@@ -68,15 +175,17 @@
         (contains? (set allowed-modules) required-module))))
 
 (defn- allowed-module-namespace? [config current-module ns-symb]
-  (let [module                (module ns-symb)
+  (let [module                (module config ns-symb)
         module-api-namespaces (module-api-namespaces config module)
         module-friends        (module-friends config module)]
-    (or (empty? module-api-namespaces)
+    (or (nil? module-api-namespaces)
         (contains? module-api-namespaces ns-symb)
-        (contains? module-friends current-module))))
+        (contains? module-friends current-module)
+        ;; a child may use its ancestors' internals; a parent still goes through its child's `:api`
+        (descendant-of? (:metabase/modules config) current-module module))))
 
 (defn- rest-module? [module]
-  (str/ends-with? module "-rest"))
+  (re-find #"[.-]rest$" (str module)))
 
 (defn- routes-module? [module]
   (str/ends-with? module "-routes"))
@@ -89,7 +198,7 @@
   error type if there is one, otherwise `nil` if there are no errors."
   [config current-module required-namespace]
   ;; ignore stuff not in a module i.e. non-Metabase stuff.
-  (when-let [required-module (module required-namespace)]
+  (when-let [required-module (module config required-namespace)]
     (when-not (= current-module required-module)
       (cond
         (not (allowed-module? config current-module required-module))
@@ -113,4 +222,8 @@
                 required-module
                 current-module
                 required-module
-                (symbol (str/replace required-module #"-rest$" "")))))))
+                (symbol (str/replace required-module #"[.-]rest$" "")))
+
+        ;; Config tests check explicit `:uses`; wildcard callers are checked here.
+        (= :any (allowed-modules config current-module))
+        (namability-error (:metabase/modules config) current-module required-module)))))

.clj-kondo/src/hooks/metabase/mq/impl.clj

@@ -0,0 +1,18 @@
+(ns hooks.metabase.mq.impl
+  (:require
+   [clj-kondo.hooks-api :as hooks]))
+
+(defn def-listener
+  "Kondo hook for `mq/def-listener`. Rewrites to a `fn` form so kondo can analyze bindings.
+
+   Form:
+     (mq/def-listener! :queue/bar [msgs] body...)"
+  [{:keys [node]}]
+  (let [[_ _channel-name bindings & body] (:children node)
+        ;; rewrite as: (fn [bindings...] body...)
+        new-node (hooks/list-node
+                  (list*
+                   (hooks/token-node 'fn)
+                   bindings
+                   body))]
+    {:node new-node}))

.clj-kondo/src/hooks/metabase/settings/models/setting.clj

@@ -4,9 +4,9 @@
    [hooks.common :as common]))
 
 (defn lint-defsetting-namespace [node context]
-  (when-not (re-matches #"^metabase(?:-enterprise)?\.[^\.]+\.settings$" (name (:ns context)))
+  (when-not (re-matches #"^metabase(?:-enterprise)?\.([^\.]+\.)+settings$" (name (:ns context)))
     (hooks/reg-finding! (assoc (meta node)
-                               :message "All defsettings should live in metabase[-enterprise].<module>.settings namespaces"
+                               :message "All defsettings should live in a namespace ending in .settings under metabase[-enterprise]"
                                :type :metabase/defsetting-namespace))))
 
 ;;; TODO -- move this into a Kondo config file in `.clj-kondo/config/`
@@ -286,6 +286,7 @@
     (update context :node update-node)))
 
 (comment
+  (require '[clojure.pprint])
   (defn- defsetting* [form]
     (hooks/sexpr
      (:node
@@ -293,7 +294,6 @@
         {:node
          (hooks/parse-string
           (with-out-str
-            #_{:clj-kondo/ignore [:unresolved-namespace]}
             (clojure.pprint/pprint
              form)))}))))
 

.clj-kondo/src/hooks/metabase/test/gentest.clj

@@ -1,14 +0,0 @@
-(ns hooks.metabase.test.gentest
-  (:require
-   [clj-kondo.hooks-api :as hooks]))
-
-(defn iterate*
-  "(iterate {:as limit-spec} [s1 val1 & more] body-form body-form...)"
-  [{{:keys [children] :as node} :node :as orig}]
-  (let [[token limit-spec bindings & body-nodes] children
-        node* (-> (hooks/list-node
-                   (list token limit-spec
-                         (hooks/list-node (list* (hooks/token-node 'let) bindings
-                                                 body-nodes))))
-                  (with-meta (meta node)))]
-    (assoc orig :node node*)))

.clj-kondo/src/hooks/metabase/toucan/db_ns.clj

@@ -0,0 +1,45 @@
+(ns hooks.metabase.toucan.db-ns
+  "Lint that application database query calls -- Toucan 2's `t2/select`, `t2/query`, `t2/insert!`, `t2/update!`,
+  `t2/delete!` and friends, plus the `metabase.app-db.core` wrappers around them such as `mdb/query` and
+  `mdb/update-or-insert!` -- live in a module's `db` namespace, i.e. `metabase[-enterprise].<module>.db` (or `metabase.driver.<driver>.db` for
+  driver modules). Every other namespace in a module goes through those functions instead of talking to the
+  application database directly.
+
+  Registered as an `:analyze-call` hook on each of those functions in `.clj-kondo/config.edn`. The hook
+  returns its input unchanged so Kondo's normal analysis of the call (arity, var usage) still runs."
+  (:require
+   [clj-kondo.hooks-api :as hooks]
+   [hooks.common.modules :as modules]))
+
+(def ^:private driver-db-namespace
+  "Matches `metabase.driver.<driver>.db`; individual drivers are not modules."
+  #"^metabase\.driver\.[^.]+\.db$")
+
+(defn- db-namespace? [config ns-sym]
+  (let [ns-str (name ns-sym)]
+    (boolean
+     ;; Resolve ownership first: a nested `.db` name alone does not make a module.
+     (or (when-let [module (modules/module config ns-sym)]
+           (= ns-str (str (modules/module-ns-prefix (:metabase/modules config) module) ".db")))
+         (re-matches driver-db-namespace ns-str)))))
+
+(defn- test-file?
+  "Whether `filename` is in a test source tree. Test namespaces are exempt through the `test-namespaces` group in
+  `config.edn`, but helper namespaces like `metabase.sso.test-helpers` don't match that group's pattern."
+  [filename]
+  (boolean (and filename (re-find #"(?:^|/)test/" filename))))
+
+(defn lint-query-call
+  "Register a `:metabase/t2-query-namespace` finding when a Toucan 2 query call appears outside a `<module>.db`
+  namespace."
+  [{:keys [node ns filename] :as input}]
+  (when (and ns
+             (not (db-namespace? (modules/config input) ns))
+             (not (test-file? filename)))
+    (let [fn-node (first (:children node))]
+      (hooks/reg-finding!
+       (assoc (meta fn-node)
+              :message (format "Application database query calls like `%s` must live in metabase[-enterprise].<module>.db (or metabase.driver.<driver>.db) namespaces"
+                               (hooks/sexpr fn-node))
+              :type :metabase/t2-query-namespace))))
+  input)

.clj-kondo/src/hooks/metabase/util/match.clj

@@ -0,0 +1,132 @@
+(ns hooks.metabase.util.match
+  (:require [clj-kondo.hooks-api :as api]))
+
+(defn- token-node? [node token-name]
+  (and (api/token-node? node)
+       (= (str (:value node)) token-name)))
+
+(defn- keyword-node? [node k]
+  (and (api/keyword-node? node)
+       (= (:k node) k)))
+
+(defn- binding-symbol?
+  "True when the token is a plain symbol that should be treated as a binding
+  (not a keyword, not a boolean literal, not nil, not a number, not `_`)."
+  [node]
+  (and (api/token-node? node)
+       (let [v (:value node)]
+         (and (symbol? v)
+              (not (contains? '#{_ nil true false} v))))))
+
+;; To establish fake let bindings, we need to bind them to something. This "something" has to be vague enough to trick
+;; kondo into not looking too much into it. E.g., if we bind everything to `nil`, Kondo linters will get fired up.
+(def opaque-node (api/list-node (list (api/token-node 'rand-nth) (api/list-node []))))
+
+(defn collect-bindings
+  "Return a list of token nodes (symbols) introduced as bindings by `pattern`."
+  [pattern]
+  (cond
+    (binding-symbol? pattern)
+    [[pattern opaque-node]]
+
+    ;; Lists: (:or ...), (:and ...), (sym :guard pred ...), or a quoted symbol.
+    (api/list-node? pattern)
+    (let [[head & rst] (:children pattern)]
+      (cond (or (keyword-node? head :or)
+                (keyword-node? head :and))
+            (mapcat collect-bindings rst)
+
+            (api/token-node? head)
+            (cond-> []
+              (binding-symbol? head) (conj [head opaque-node])
+              (keyword-node? (first rst) :guard) (conj [(api/token-node '_) (second rst)]))
+
+            ;; anything else (e.g. a function call used as predicate) — no bindings
+            :else []))
+
+    (api/vector-node? pattern)
+    (mapcat (fn [node]
+              (when-not (token-node? node "&")
+                (collect-bindings node)))
+            (:children pattern))
+
+    ;; Maps: keys are literal selectors, values are sub-patterns.
+    ;; Special value-symbols &truthy and _ are NOT user bindings.
+    (api/map-node? pattern)
+    (let [children (:children pattern)
+          pairs    (partition 2 children)]
+      (mapcat (fn [[_k v]]
+                (when-not (or (token-node? v "&truthy")
+                              (token-node? v "_"))
+                  (collect-bindings v)))
+              pairs))
+
+    ;; For sets, make sure to use them because they may reference some of the outer local bindings, so if we don't
+    ;; include them, Kondo will complain about those bindings being unused.
+    (api/set-node? pattern)
+    [[(api/token-node '_) pattern]]
+
+    ;; Anything else — no bindings.
+    :else []))
+
+(defn- dedupe-bindings
+  "Prevent Kondo complaining that we have multiple fake bindings."
+  [pairs]
+  (loop [[[sym v] & r] pairs, seen #{}, result []]
+    (cond (nil? sym) result
+          (and (seen sym) (not (token-node? sym "_"))) (recur r seen result)
+          :else (recur r (conj seen sym) (conj result sym v)))))
+
+(defn match-one
+  "clj-kondo :analyze-call hook for match-one.
+
+  Rewrites
+
+    (match-one value
+      pat1 ret1
+      pat2 ret2
+      ...)
+
+  into a `let` form that declares all binding symbols introduced by the patterns, so clj-kondo knows they are
+  legitimate and won't warn about unresolved/unused symbols:
+
+    (let [<all-bindings> (rand-nth []) ...]
+      (or ret1 ret2 ...))"
+  [{:keys [node]}]
+  (let [[_ value & clauses] (:children node)]
+    (when (odd? (count clauses))
+      (api/reg-finding!
+       {:message  "match-one/match-many/replace requires an even number of pattern/result pairs"
+        :type     :metabase/match-odd-clauses
+        :row      (:row node)
+        :col      (:col node)
+        :filename (-> node meta :filename)}))
+    (let [pairs (partition 2 clauses)
+          all-bindings (->> pairs
+                            (mapcat (fn [[pat _ret]] (collect-bindings pat)))
+                            dedupe-bindings)
+          special-bindings [(api/token-node '_)        value
+                            (api/token-node '&match)   opaque-node
+                            (api/token-node '&parents) opaque-node
+                            (api/token-node '&recur)   opaque-node
+                            ;; Pretend to use &match, &parents, and &recur so that Kondo doesn't complain about them
+                            ;; if they are not used by the user code.
+                            (api/token-node '_) (api/token-node '&match)
+                            (api/token-node '_) (api/token-node '&parents)
+                            (api/token-node '_) (api/token-node '&recur)]
+          binding-nodes (into special-bindings all-bindings)
+          result-exprs (map second pairs)
+          new-node (api/list-node
+                    (list
+                     (api/token-node 'let)
+                     (api/vector-node binding-nodes)
+                     (api/list-node
+                      (concat [(api/token-node 'clojure.core/or)] result-exprs [opaque-node]))))]
+      {:node new-node})))
+
+(def match-many match-one)
+(def replace match-one)
+
+(defn replace-in [context]
+  ;; Everything is the same as in match-one, just drop the middle argument.
+  (match-one (update-in context [:node :children] (fn [[sym value path & clauses]] (list* sym value clauses)))))

.clj-kondo/test/hooks/clojure/core/ns_test.clj

@@ -19,6 +19,19 @@
 (defn- lint-modules [form config]
   (lint-ns form (assoc-in config [:linters :metabase/modules :level] :warning)))
 
+(deftest ^:parallel explicit-nonparallel-namespace-metadata-test
+  (let [config {:linters {:metabase/validate-deftest {:level :warning}}}]
+    (testing "Hawk's supported namespace marker passes"
+      (is (empty? (lint-ns '(ns ^:synchronized example.test) config))))
+    (testing "the verbose Hawk spelling is not accepted as Metabase style"
+      (is (=? [{:type    :metabase/validate-deftest
+                :message #(re-find #"Use `\^:synchronized` instead" %)}]
+              (lint-ns '(ns ^{:parallel false} example.test) config))))
+    (testing "the legacy marker explains that Hawk ignores it"
+      (is (=? [{:type    :metabase/validate-deftest
+                :message #(re-find #"`\^:synchronous` is ignored by Hawk" %)}]
+              (lint-ns '(ns ^:synchronous example.test) config))))))
+
 (deftest ^:parallel module-checker-allowed-modules-test
   (are [task-namespace] (=? [{:message "Module task should not be used in the api module. [:metabase/modules api :uses]"
                               :type :metabase/modules}]
@@ -43,6 +56,16 @@
            '{:metabase/modules {api    {:uses #{search}}
                                 search {:api  #{metabase.search.core}}}}))))
 
+(deftest ^:parallel module-checker-empty-api-test
+  (is (=? [{:message "Namespace metabase.embeddings.core is not an allowed external API namespace for the embeddings module. [:metabase/modules embeddings :api]"
+            :type :metabase/modules}]
+          (lint-modules
+           '(ns metabase.metabot.core
+              (:require
+               [metabase.embeddings.core :as embeddings]))
+           '{:metabase/modules {metabot   {:uses #{embeddings}}
+                                embeddings {:api #{}}}}))))
+
 (deftest ^:parallel module-checker-friends-test
   (is (= []
          (lint-modules

.clj-kondo/test/hooks/clojure/core/require_test.clj

@@ -0,0 +1,65 @@
+(ns hooks.clojure.core.require-test
+  (:require
+   [clj-kondo.hooks-api :as hooks]
+   [clj-kondo.impl.utils]
+   [clojure.test :refer :all]
+   [hooks.clojure.core.require]))
+
+(def ^:private config
+  '{:linters          {:metabase/modules {:level :warning}}
+    :metabase/modules {search {:uses #{}}
+                       task   {:api #{metabase.task.core}}}})
+
+(defn- lint [hook form current-ns]
+  (binding [clj-kondo.impl.utils/*ctx* {:config     config
+                                        :ignores    (atom nil)
+                                        :findings   (atom [])
+                                        :namespaces (atom {})}]
+    (hook {:node   (hooks/parse-string (pr-str form))
+           :ns     current-ns
+           :config config})
+    @(:findings clj-kondo.impl.utils/*ctx*)))
+
+(defn- lint-require [form current-ns]
+  (lint hooks.clojure.core.require/lint-require form current-ns))
+
+(defn- lint-requiring-resolve [form current-ns]
+  (lint hooks.clojure.core.require/lint-requiring-resolve form current-ns))
+
+(def ^:private dynamic-require-finding
+  {:message "Module dependency cannot be statically determined from a dynamic require"
+   :type    :metabase/modules})
+
+(def ^:private cross-module-finding
+  {:message "Module task should not be used in the search module. [:metabase/modules search :uses]"
+   :type    :metabase/modules})
+
+(deftest ^:parallel dynamic-requiring-resolve-test
+  (testing "outside the module system"
+    (is (= [] (lint-requiring-resolve '(requiring-resolve (:failing-test-var opts)) 'dev))))
+  (testing "inside a module"
+    (are [form] (=? [dynamic-require-finding]
+                    (lint-requiring-resolve form 'metabase.search.core))
+      '(requiring-resolve (:failing-test-var opts))
+      '(requiring-resolve @some-atom)
+      '(requiring-resolve some-local)
+      '(requiring-resolve "not-a-symbol"))))
+
+(deftest ^:parallel dynamic-require-test
+  (testing "outside the module system"
+    (is (= [] (lint-require '(require some-local) 'dev))))
+  (testing "inside a module"
+    (is (=? [dynamic-require-finding]
+            (lint-require '(require some-local) 'metabase.search.core)))))
+
+(deftest ^:parallel static-requiring-resolve-still-linted-test
+  (is (=? [cross-module-finding]
+          (lint-requiring-resolve '(requiring-resolve 'metabase.task.impl/go)
+                                  'metabase.search.core))
+      "a statically-known cross-module violation is still reported"))
+
+(deftest ^:parallel static-require-still-linted-test
+  (is (=? [cross-module-finding]
+          (lint-require '(require 'metabase.task.impl :reload)
+                        'metabase.search.core))
+      "a statically-known cross-module violation is still reported while keyword flags are ignored"))

.clj-kondo/test/hooks/clojure/test_test.clj

@@ -21,6 +21,54 @@
                                             #{:athena}}}}})
     (mapv :message @(:findings clj-kondo.impl.utils/*ctx*))))
 
+(defn- parallel-metadata-findings
+  ([form]
+   (parallel-metadata-findings form 'example.test))
+  ([form ns-sym]
+   (let [linters {:metabase/deftest-not-marked-parallel-or-synchronized {:level :warning}
+                  :metabase/validate-deftest                             {:level :warning}}]
+     (binding [clj-kondo.impl.utils/*ctx* {:config     {:linters linters}
+                                           :ignores    (atom nil)
+                                           :findings   (atom [])
+                                           :namespaces (atom {})}]
+       (hooks.clojure.test/deftest {:node   (api/parse-string form)
+                                    :lang   :clj
+                                    :ns     ns-sym
+                                    :config {:linters {:metabase/validate-deftest {}}}})
+       @(:findings clj-kondo.impl.utils/*ctx*)))))
+
+(deftest ^:parallel explicit-nonparallel-metadata-test
+  (testing "Hawk's supported test markers satisfy the explicit metadata linter"
+    (are [metadata] (empty? (parallel-metadata-findings
+                             (format "(deftest %s example-test (is true))" metadata)))
+      "^:parallel"
+      "^:synchronized"))
+  (testing "an unmarked test still gets the opt-in linter's guidance"
+    (is (=? [{:type    :metabase/deftest-not-marked-parallel-or-synchronized
+              :message "Test should be marked either `^:parallel` or `^:synchronized`"}]
+            (parallel-metadata-findings "(deftest example-test (is true))"))))
+  (testing "the unsupported marker explains that Hawk ignores it"
+    (is (some #(and (= (:type %) :metabase/validate-deftest)
+                    (re-find #"ignored by Hawk" (:message %)))
+              (parallel-metadata-findings
+               "(deftest ^:sequential example-test (is true))"))))
+  (testing "the verbose Hawk spelling is not accepted as Metabase style"
+    (is (some #(and (= (:type %) :metabase/validate-deftest)
+                    (re-find #"Use `\^:synchronized` instead" (:message %)))
+              (parallel-metadata-findings
+               "(deftest ^{:parallel false} example-test (is true))"))))
+  (testing "a test cannot request both execution modes"
+    (is (some #(and (= (:type %) :metabase/validate-deftest)
+                    (re-find #"both `\^:parallel` and `\^:synchronized`" (:message %)))
+              (parallel-metadata-findings
+               "(deftest ^:parallel ^:synchronized example-test (is true))"))))
+  (testing "a namespace-level non-parallel promise rejects parallel tests"
+    (is (=? [{:type    :metabase/validate-deftest
+              :message #(re-find #"namespace marked.*`\^:synchronized`" %)}]
+            (parallel-metadata-findings
+             "(deftest ^:parallel example-test (is true))"
+             (with-meta 'example.test {:synchronized true}))))))
+
 (deftest ^:parallel disallow-hardcoded-driver-names-in-tests-test
   (is (= []
          (deftest-warnings

.clj-kondo/test/hooks/common/modules_test.clj

@@ -5,6 +5,6 @@
 
 (deftest ^:parallel module-test
   (are [symb expected] (= expected
-                          (hooks.common.modules/module symb))
+                          (hooks.common.modules/module {} symb))
     'metabase.qp.middleware.wow        'qp
     'metabase-enterprise.whatever.core 'enterprise/whatever))

.clj-kondo/test/hooks/metabase/toucan/db_ns_test.clj

@@ -0,0 +1,73 @@
+(ns hooks.metabase.toucan.db-ns-test
+  (:require
+   [clj-kondo.hooks-api :as hooks]
+   [clj-kondo.impl.utils]
+   [clojure.test :refer :all]
+   [hooks.metabase.toucan.db-ns :as toucan.db-ns]))
+
+(defn- lint-query-call [form ns-sym & [filename modules]]
+  (binding [clj-kondo.impl.utils/*ctx* {:config     {:linters {:metabase/t2-query-namespace {:level :warning}}}
+                                        :ignores    (atom nil)
+                                        :findings   (atom [])
+                                        :namespaces (atom {})}]
+    (let [input  {:node     (hooks/parse-string (pr-str form))
+                  :ns       ns-sym
+                  :filename (or filename "src/metabase/foo/bar.clj")
+                  :config   {:metabase/modules modules}}
+          output (toucan.db-ns/lint-query-call input)]
+      (is (identical? (:node input) (:node output))
+          "the hook must return the node unchanged so Kondo's normal analysis still runs")
+      @(:findings clj-kondo.impl.utils/*ctx*))))
+
+(deftest ^:parallel t2-query-must-live-in-db-namespace-test
+  (testing "a query call outside a db namespace is flagged"
+    (is (=? [{:type    :metabase/t2-query-namespace
+              :message #".*`t2/select-one`.*"}]
+            (lint-query-call '(t2/select-one :model/Card :id 1) 'metabase.queries.models.card))))
+  (testing "metabase.<module>.db is allowed"
+    (is (empty? (lint-query-call '(t2/select-one :model/Card :id 1) 'metabase.queries.db))))
+  (testing "metabase-enterprise.<module>.db is allowed"
+    (is (empty? (lint-query-call '(t2/select-one :model/Card :id 1) 'metabase-enterprise.sandbox.db))))
+  (testing "metabase.driver.<driver>.db is allowed for driver modules"
+    (is (empty? (lint-query-call '(t2/select-one :model/Database :id 1) 'metabase.driver.bigquery-cloud-sdk.db))))
+  (testing "a nested db namespace is not a module db namespace"
+    (is (=? [{:type :metabase/t2-query-namespace}]
+            (lint-query-call '(t2/query {:select [:*]}) 'metabase.queries.models.db))))
+  (testing "a namespace merely ending in db is not a module db namespace"
+    (is (=? [{:type :metabase/t2-query-namespace}]
+            (lint-query-call '(t2/delete! :model/Card :id 1) 'metabase.queries.dashboards-db))))
+  (testing "files in a test source tree are exempt even when the namespace name doesn't look like a test"
+    (is (empty? (lint-query-call '(t2/update! :model/User 1 {:sso_source nil}) 'metabase.sso.test-helpers
+                                 "test/metabase/sso/test_helpers.clj")))
+    (is (empty? (lint-query-call '(t2/select :model/Card) 'metabase-enterprise.remote-sync.test-helpers
+                                 "/repo/enterprise/backend/test/metabase_enterprise/remote_sync/test_helpers.clj"))))
+  (testing "app-db wrappers around Toucan 2 are reported the same way"
+    (is (=? [{:type    :metabase/t2-query-namespace
+              :message #".*`mdb/update-or-insert!`.*"}]
+            (lint-query-call '(mdb/update-or-insert! :model/Foo {:id 1}) 'metabase.foo.models.foo))))
+  (testing "fully-qualified calls are reported by their written name"
+    (is (=? [{:type    :metabase/t2-query-namespace
+              :message #".*`toucan2.core/insert!`.*"}]
+            (lint-query-call '(toucan2.core/insert! :model/Card {}) 'metabase.queries.models.card)))))
+
+(deftest ^:parallel t2-query-namespace-follows-the-module-tree-test
+  (let [modules '{queries            {}
+                  metabot            {}
+                  metabot.llm        {}
+                  lib.be             {:ns-prefix "metabase.lib-be"}
+                  enterprise/sandbox {}}]
+    (testing "a nested module owns its own db namespace"
+      (is (empty? (lint-query-call '(t2/select :model/Card) 'metabase.metabot.llm.db nil modules))))
+    (testing "the parent's db namespace stays its own"
+      (is (empty? (lint-query-call '(t2/select :model/Card) 'metabase.metabot.db nil modules))))
+    (testing "a module with an explicit :ns-prefix is resolved through it, not its dotted name"
+      (is (empty? (lint-query-call '(t2/select :model/Card) 'metabase.lib-be.db nil modules)))
+      (is (=? [{:type :metabase/t2-query-namespace}]
+              (lint-query-call '(t2/select :model/Card) 'metabase.lib.be.db nil modules))))
+    (testing "a db namespace under a directory naming no module is still a finding"
+      (is (=? [{:type :metabase/t2-query-namespace}]
+              (lint-query-call '(t2/query {:select [:*]}) 'metabase.queries.models.db nil modules)))
+      (is (=? [{:type :metabase/t2-query-namespace}]
+              (lint-query-call '(t2/query {:select [:*]}) 'metabase.metabot.llm.models.db nil modules))))
+    (testing "enterprise modules resolve through the metabase-enterprise root"
+      (is (empty? (lint-query-call '(t2/select :model/Card) 'metabase-enterprise.sandbox.db nil modules))))))

.clj-kondo/test/hooks/metabase/util/match_test.clj

@@ -0,0 +1,59 @@
+(ns hooks.metabase.util.match-test
+  (:require
+   [clj-kondo.hooks-api :as hooks]
+   [clj-kondo.impl.utils]
+   [clojure.test :refer :all]
+   [hooks.metabase.util.match :as sut]))
+
+(defn- expand [src]
+  (-> (sut/match-one {:node (hooks/parse-string (pr-str src))})
+      :node
+      hooks/sexpr))
+
+(defn- lint [src]
+  (binding [clj-kondo.impl.utils/*ctx* {:config     {:linters {:metabase/match-odd-clauses {:level :warning}}}
+                                        :ignores    (atom nil)
+                                        :findings   (atom [])
+                                        :namespaces (atom {})}]
+    (expand src)
+    @(:findings clj-kondo.impl.utils/*ctx*)))
+
+(deftest odd-clauses-triggers-warning-test
+  (is (=? [{:type :metabase/match-odd-clauses}]
+          (lint '(metabase.util.match/match-one [] [a b c])))))
+
+(deftest expansion-test
+  (testing "simple expansion example"
+    (is (= '(let [_ []
+                  &match (rand-nth ())
+                  &parents (rand-nth ())
+                  &recur (rand-nth ())
+                  _ &match
+                  _ &parents
+                  _ &recur
+                  a (rand-nth ())
+                  b (rand-nth ())
+                  c (rand-nth ())]
+              (clojure.core/or (+ a b) (rand-nth ())))
+           (expand '(match-one [] [a b c] (+ a b))))))
+  (testing "complicated expansion example that uses most match-one macro features, and also binding deduplication by the rewriter"
+    (is (= '(let [_ []
+                  &match (rand-nth ())
+                  &parents (rand-nth ())
+                  &recur (rand-nth ())
+                  _ &match
+                  _ &parents
+                  _ &recur
+                  val1 (rand-nth ())
+                  a (rand-nth ())
+                  _ #{maybe important}
+                  rst (rand-nth ())
+                  x (rand-nth ())
+                  _ (= x 3)
+                  b (rand-nth ())]
+              (clojure.core/or (+ a val1) (rand-nth ())))
+           (expand '(match-one []
+                               (:or [{:key1 val1, :key2 &truthy, :key3 _} _ a #{maybe important} & rst]
+                                    (:and (x :guard (= x 3))
+                                          [a b]))
+                               (+ a val1)))))))

.cljfmt.edn

@@ -12,6 +12,7 @@
   "enterprise/backend"
   "bin/build"
   "bin/lint-migrations-file"
+  "bin/load-namespaces"
   "bin/release-list"
   #_"mage/src"
   #_"mage/test"

.coderabbit.yaml

@@ -0,0 +1,28 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+reviews:
+  high_level_summary: false
+  review_status: false
+
+  auto_review:
+    enabled: false
+    drafts: true
+    labels:
+      - "coderabbit"
+
+  path_filters:
+    - "!**/*.snap"
+    - "!**/*.po"
+    - "!**/bun.lock"
+    - "!**/package-lock.json"
+
+  tools:
+    eslint:
+      enabled: false
+
+knowledge_base:
+  code_guidelines:
+    filePatterns:
+      - ".claude/skills/clojure-review/SKILL.md"
+      - ".claude/skills/typescript-review/SKILL.md"
+      - ".claude/skills/e2e-test-review/SKILL.md"
+      - ".claude/skills/docs-review/SKILL.md"

.codespellrc

@@ -16,7 +16,7 @@ skip =
     frontend/src/metabase/querying/expressions/tokenizer/lezer.js,
     frontend/src/metabase/query_builder/components/NativeQueryEditor/CodeMirrorEditor/language.ts,
     frontend/src/metabase/static-viz/constants/char-sizes.ts,
-    frontend/src/metabase/visualizations/lib/mapping_codes.ts,
+    frontend/src/metabase/viz-core/lib/mapping_codes.ts,
     frontend/*/mocks/*,
     modules/drivers/mongo/src/metabase/driver/mongo/operators.clj,
     src/metabase/analyze/classifiers/name.clj,

.dependency-cruiser.cjs

@@ -0,0 +1,32 @@
+// dependency-cruiser config for the actual frontend import graph (what's
+// imported, vs the *allowed* edges in module-boundaries.mjs). Consumed by
+// .github/scripts/create-test-plan.ts.
+//
+//   bunx depcruise frontend/src enterprise/frontend/src \
+//     --config .dependency-cruiser.cjs --output-type json > dependency-graph.json
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  options: {
+    // Keep only edges between our own source files (drops node_modules etc.),
+    // which keeps the JSON small.
+    includeOnly: "^(frontend/src|enterprise/frontend/src)/",
+
+    doNotFollow: { path: "node_modules" },
+
+    // Resolve the `"*": ["./frontend/src/*", ...]` aliases so bare imports like
+    // `metabase/lib/foo` map back to a real file.
+    tsConfig: { fileName: "tsconfig.json" },
+
+    // Keep type-only imports: a type-only dependent still breaks on a type change.
+    tsPreCompilationDeps: true,
+
+    moduleSystems: ["es6", "cjs", "tsd"],
+
+    enhancedResolveOptions: {
+      exportsFields: ["exports"],
+      conditionNames: ["import", "require", "node", "default", "types"],
+      extensions: [".js", ".jsx", ".ts", ".tsx", ".json"],
+    },
+  },
+};

.devcontainer/Dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/vscode/devcontainers/java:21
+FROM mcr.microsoft.com/vscode/devcontainers/java:25
 
 # Set up nodesource, install node, bun, fontconfig for static viz, rlwrap for dev ergonomics
 

.dockerignore

@@ -1,5 +1,6 @@
+.git
 .babel_cache
-target/*
+target
 .circleci
 .cpcache
 .devcontainer
@@ -15,6 +16,7 @@ test_config/*
 test_modules/*
 test_resources/*
 node_modules
+**/node_modules
 **metabase.jar
 
 *.db

.gitattributes

@@ -7,3 +7,9 @@
 #
 # TODO (Bryan 12/12/25) -- reenable this when we can completely verify correctness
 # resources/migrations/*_update_migrations.yaml merge=yaml-migrations
+
+# Generated API documentation/specs — regenerated by the "Auto-update documentation for master"
+# CI automation, not edited by hand. Mark generated so tools/humans don't review or diff them as source.
+docs/api.json                  linguist-generated
+docs/api.html                  linguist-generated
+resources/openapi/openapi.json linguist-generated

.github/CODEOWNERS

@@ -10,15 +10,30 @@ src/metabase/query_processor @metabase/core-backend-querying-platform
 src/metabase/graph @metabase/graphy
 enterprise/backend/src/metabase_enterprise/dependencies @metabase/graphy
 enterprise/frontend/src/metabase-enterprise/dependencies @metabase/graphy
+enterprise/frontend/src/metabase-enterprise/monitor/dependency-diagnostics @metabase/graphy
 
 # @metabase/embedding
-enterprise/frontend/src/embedding-sdk-package @metabase/embedding
-enterprise/frontend/src/embedding-sdk-bundle @metabase/embedding
-enterprise/frontend/src/embedding-sdk-shared @metabase/embedding
+
+frontend/src/metabase/embedding @metabase/embedding
 frontend/src/metabase/embedding-sdk @metabase/embedding
+frontend/src/embedding-sdk-bundle @metabase/embedding
+frontend/src/embedding-sdk-shared @metabase/embedding
 frontend/src/metabase/public/containers/PublicOrEmbeddedQuestion @metabase/embedding
 frontend/src/metabase/public/containers/PublicOrEmbeddedDashboard @metabase/embedding
 
+enterprise/frontend/src/embedding @metabase/embedding
+enterprise/frontend/src/embedding-sdk-ee @metabase/embedding
+enterprise/frontend/src/embedding-sdk-package @metabase/embedding
+
+enterprise/frontend/src/metabase-enterprise/embedding @metabase/embedding
+enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk @metabase/embedding
+enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk_setup @metabase/embedding
+enterprise/frontend/src/metabase-enterprise/embedding-sdk @metabase/embedding
+
+e2e/test-component @metabase/embedding
+e2e/test/scenarios/embedding @metabase/embedding
+e2e/embedding-sdk-host-apps @metabase/embedding
+
 # @metabase/tech-writers
 docs @metabase/tech-writers
 docs/developers-guide # exclude from tech-writer ownership
@@ -27,6 +42,9 @@ docs/api.json # auto-generated
 docs/configuring-metabase/environment-variables.md # auto-generated
 docs/configuring-metabase/config-template.md # auto-generated
 docs/installation-and-operation/commands.md # auto-generated
+docs/ai/providers.md # auto-generated
+docs/embedding/sdk/api # auto-generated
+docs/embedding/eajs/snippets # auto-generated
 
 # @metabase/devexp
 .github @metabase/devexp
@@ -35,5 +53,17 @@ docs/installation-and-operation/commands.md # auto-generated
 src/metabase/analytics/prometheus.clj @metabase/cloud-ops
 
 # @metabase/metabot-frontend
-enterprise/frontend/src/metabase-enterprise/metabot @metabase/metabot-frontend 
+enterprise/frontend/src/metabase-enterprise/metabot @metabase/metabot-frontend
 frontend/src/metabase/metabot @metabase/metabot-frontend
+
+# @metabase/core-frontend-gadget
+bin/custom-viz @metabase/core-frontend-gadget
+docs/developers-guide/custom-visualizations.md @metabase/core-frontend-gadget
+enterprise/frontend/src/custom-viz @metabase/core-frontend-gadget
+enterprise/frontend/src/metabase-enterprise/api/custom-viz-plugin.ts @metabase/core-frontend-gadget
+enterprise/frontend/src/metabase-enterprise/custom_viz @metabase/core-frontend-gadget
+frontend/src/metabase-types/api/custom-viz-plugin.ts @metabase/core-frontend-gadget
+frontend/src/metabase/plugins/oss/custom-viz.ts @metabase/core-frontend-gadget
+frontend/src/metabase/visualizations/custom-visualizations @metabase/core-frontend-gadget
+frontend/test/__support__/custom-viz-fixtures @metabase/core-frontend-gadget
+.github/workflows/release-custom-viz.yml @metabase/devexp @metabase/core-frontend-gadget

.github/actionlint.yaml

@@ -0,0 +1,19 @@
+self-hosted-runner:
+  # Custom runner labels that actionlint cannot know about. Everything else is
+  # selected through `vars.DEFAULT_RUNNER_KEY` and is not checked.
+  labels:
+    - arm-ubuntu-24-2core
+
+paths:
+  # GitHub added parallel steps (`parallel`, `background`, `wait`, `wait-all`,
+  # `cancel`) in June 2026, and actionlint 1.7.12 does not know the schema yet:
+  # https://github.blog/changelog/2026-06-25-actions-steps-can-now-be-run-in-parallel/
+  .github/workflows/backend.yml:
+    ignore:
+      - 'step must run script with "run" section or run action with "uses" section'
+  .github/workflows/lint.yml:
+    ignore:
+      - 'step must run script with "run" section or run action with "uses" section'
+  .github/workflows/pr.checks.yml:
+    ignore:
+      - 'step must run script with "run" section or run action with "uses" section'

.github/actions/bundle-size-check/action.yml

@@ -0,0 +1,136 @@
+name: Bundle Size Check
+description: |
+  Measures app + embedding SDK bundle sizes from the current and base-ref
+  uberjars (reusing the builds that already ran) plus their bundle-stats
+  artifacts, and flags gzipped size changes beyond the threshold for the main
+  app's initial bundle and the chunked SDK's reachable total. The base ref is
+  read back off the current uberjar so that both sides differ only by the PR.
+  Skips when the base-ref artifacts aren't available rather than rebuilding from
+  source (which would compare across pipelines).
+
+inputs:
+  edition:
+    description: 'Metabase edition (ee or oss)'
+    required: true
+  threshold-percent:
+    description: 'Percent threshold for bundle size change'
+    required: true
+
+outputs:
+  app_status:
+    description: "App initial bundle status: increased, decreased, or stable"
+    value: ${{ steps.compare.outputs.app_initial_status }}
+  app_size_change_percent:
+    description: "App initial bundle size change percent (positive = increase, negative = decrease)"
+    value: ${{ steps.compare.outputs.app_initial_size_change_percent }}
+  sdk_status:
+    description: "Chunked SDK bundle status: increased, decreased, or stable"
+    value: ${{ steps.compare.outputs.embedding_sdk_chunked_total_status }}
+  sdk_size_change_percent:
+    description: "Chunked SDK bundle size change percent (positive = increase, negative = decrease)"
+    value: ${{ steps.compare.outputs.embedding_sdk_chunked_total_size_change_percent }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Download current uberjar
+      uses: ./.github/actions/fetch-artifact
+      with:
+        commit: ${{ github.event.pull_request.head.sha || github.sha }}
+        edition: ${{ inputs.edition }}
+        extract-path: temp/current-uberjar
+    - name: Resolve the base ref the current uberjar was built against
+      id: base-ref
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        set -uo pipefail
+
+        # The uberjar job checks out refs/pull/<n>/merge (the PR head already
+        # merged into the base branch tip) but names its artifact after head.sha,
+        # so the comparable base ref is that merge's first parent. Reading it back
+        # off the jar describes the artifact actually being measured. Using
+        # pull_request.base.sha instead compares against a stale snapshot of the
+        # base branch, reporting everything that landed in between as this PR's
+        # own bundle delta.
+        unzip -o -j temp/current-uberjar/metabase.jar version.properties -d temp/current-version >/dev/null
+        built=$(sed -n 's/^hash=//p' temp/current-version/version.properties)
+        base=$(gh api "/repos/${GITHUB_REPOSITORY}/commits/${built}" \
+          --jq 'if (.parents | length) == 2 then .parents[0].sha else empty end' 2>/dev/null) || base=""
+
+        echo "sha=${base}" >> "$GITHUB_OUTPUT"
+        echo "The current uberjar was built from ${built}; its base ref is ${base:-unknown}"
+    - name: Download base-ref uberjar
+      id: base-jar
+      if: steps.base-ref.outputs.sha != ''
+      continue-on-error: true
+      uses: ./.github/actions/fetch-artifact
+      with:
+        commit: ${{ steps.base-ref.outputs.sha }}
+        edition: ${{ inputs.edition }}
+        extract-path: temp/base-uberjar
+    - name: Measure and compare bundle sizes
+      id: compare
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        EDITION: ${{ inputs.edition }}
+        HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        BASE_SHA: ${{ steps.base-ref.outputs.sha }}
+        THRESHOLD: ${{ inputs.threshold-percent }}
+        MEASURE_BUNDLES: app,embedding-sdk-legacy,embedding-sdk-chunked
+        # The gated bundles, as "<bundle>/<kind>". Each one's step outputs are
+        # named after its key (see outputPrefix in compare.js), which is what the
+        # action outputs above read.
+        GATES: app/initial,embedding-sdk-chunked/total
+      run: |
+        set -uo pipefail
+
+        skip() {
+          echo "::notice::Bundle-size check skipped: $1"
+          for gate in ${GATES//,/ }; do
+            prefix=$(printf '%s' "$gate" | tr -c 'a-zA-Z0-9' '_')
+            echo "${prefix}_status=stable" >> "$GITHUB_OUTPUT"
+            echo "${prefix}_size_change_percent=0" >> "$GITHUB_OUTPUT"
+          done
+          exit 0
+        }
+
+        # The base ref needs an already-built uberjar. Rebuilding it from source
+        # would compare across two build pipelines (the bug this check used to
+        # have), so skip instead when it — or its stats — isn't available.
+        [ -n "${BASE_SHA}" ] || skip "no comparable base ref for the current uberjar"
+        [ -f temp/base-uberjar/metabase.jar ] || skip "base-ref uberjar not found for ${BASE_SHA}"
+
+        extract_js() { # $1=jar  $2=dest-root
+          mkdir -p "$2/resources"
+          unzip -o "$1" \
+            "frontend_client/app/dist/*" \
+            "frontend_client/app/embed.js" \
+            "frontend_client/app/embedding-sdk/*" \
+            -d "$2/resources" >/dev/null || true
+        }
+
+        fetch_stats() { # $1=sha  $2=dest-dir
+          local name="metabase-bundle-stats-${EDITION}-$1"
+          local id
+          id=$(gh api "/repos/${GITHUB_REPOSITORY}/actions/artifacts?name=${name}" --jq '.artifacts[0].id // empty' 2>/dev/null)
+          [ -n "${id}" ] || return 1
+          mkdir -p "$2"
+          gh api "/repos/${GITHUB_REPOSITORY}/actions/artifacts/${id}/zip" > "$2.zip" 2>/dev/null || return 1
+          unzip -o "$2.zip" -d "$2" >/dev/null || return 1
+        }
+
+        extract_js temp/current-uberjar/metabase.jar temp/current
+        extract_js temp/base-uberjar/metabase.jar temp/base
+
+        fetch_stats "${HEAD_SHA}" temp/current/artifacts || skip "bundle stats not found for current ${HEAD_SHA}"
+        fetch_stats "${BASE_SHA}" temp/base/artifacts || skip "bundle stats not found for base ${BASE_SHA}"
+
+        MEASURE_ROOT=temp/current node ./.github/scripts/measure-bundle-sizes.js > temp/current-sizes.json \
+          || { echo "::error::Failed to measure current bundle sizes"; exit 1; }
+        MEASURE_ROOT=temp/base node ./.github/scripts/measure-bundle-sizes.js > temp/base-sizes.json \
+          || { echo "::error::Failed to measure base bundle sizes"; exit 1; }
+
+        node ./.github/actions/bundle-size-check/compare.js temp/current-sizes.json temp/base-sizes.json

.github/actions/bundle-size-check/compare.js

@@ -0,0 +1,133 @@
+/* eslint-disable import/no-commonjs */
+// Diffs the bundle sizes produced by measure-bundle-sizes.js for the current
+// build and the base ref. Every (bundle, kind) is compared strictly against the
+// same (bundle, kind) — never one bundle type against another — using gzipped
+// (served) bytes.
+//
+// The report covers every measured bundle; the gates are the subset that drives
+// PR comments, named as "<bundle>/<kind>" (e.g. "app/initial",
+// "embedding-sdk-chunked/total").
+//
+// compareBundles is pure (data in, data out) so it can be unit-tested; main()
+// is the thin I/O wrapper that reads the size files, prints the report and sets
+// the step outputs / exit code.
+const fs = require("fs");
+
+const pick = (rows, bundle, kind) => rows.find(row => row.bundle === bundle && row.kind === kind);
+const keyOf = row => `${row.bundle}/${row.kind}`;
+const mb = bytes => (bytes / 1024 / 1024).toFixed(2);
+const percentOf = (currentBytes, baseBytes) =>
+  baseBytes ? Math.trunc(((currentBytes - baseBytes) * 100) / baseBytes) : 0;
+
+// Output names are derived from the gate key, so the workflow reads
+// `app_initial_status`, `embedding_sdk_chunked_total_status`, and so on.
+const outputPrefix = gateKey => gateKey.replace(/[^a-zA-Z0-9]+/g, "_");
+
+/**
+ * Evaluate one gate. Returns the key plus exactly one of:
+ *  - `status` / `percent`: the bundle moved by `percent`.
+ *  - `skip`  reason: the gate is non-actionable (reported stable, no comment).
+ *  - `error` reason: the gate inputs are missing (hard failure).
+ */
+function evaluateGate({ current, base, threshold, gateKey }) {
+  const [bundle, kind] = gateKey.split("/");
+  const gateCurrent = pick(current, bundle, kind);
+  const gateBase = pick(base, bundle, kind);
+  if (!gateCurrent || !gateBase || !gateBase.gzipBytes) {
+    return { gateKey, error: `Could not find ${bundle} ${kind} (gzip) in both builds` };
+  }
+
+  // Both sides must measure the bundle the same way. A base ref built before the
+  // reachableAssets enrichment collapses its total to the initial set, so
+  // comparing it against the current reachable total reports a phantom jump
+  // (~30%). Skip until the base ref also carries reachable stats.
+  if (Boolean(gateCurrent.reachable) !== Boolean(gateBase.reachable)) {
+    return {
+      gateKey,
+      skip:
+        `"${gateKey}" measured differently on each side ` +
+        `(current reachable=${Boolean(gateCurrent.reachable)}, base reachable=${Boolean(gateBase.reachable)}); ` +
+        `the base ref predates the reachable-chunk stats. Resolves once this change is on the base ref.`,
+    };
+  }
+
+  const percent = percentOf(gateCurrent.gzipBytes, gateBase.gzipBytes);
+  const status = percent > threshold ? "increased" : percent < -threshold ? "decreased" : "stable";
+  return { gateKey, status, percent };
+}
+
+/**
+ * Compare two measurement sets and evaluate every gate. Returns a
+ * human-readable `report` over all measured bundles plus one entry per gate.
+ */
+function compareBundles({ current, base, threshold, gateKeys }) {
+  const report = ["=== Bundle sizes (gzipped, current vs base) ==="];
+  const keys = [...new Set([...current, ...base].map(keyOf))].sort();
+  for (const key of keys) {
+    const [bundle, kind] = key.split("/");
+    const currentRow = pick(current, bundle, kind);
+    const baseRow = pick(base, bundle, kind);
+    if (!currentRow || !baseRow) {
+      report.push(`${key}: present only in ${currentRow ? "current" : "base"} build`);
+      continue;
+    }
+    const diff = currentRow.gzipBytes - baseRow.gzipBytes;
+    const percent = percentOf(currentRow.gzipBytes, baseRow.gzipBytes);
+    report.push(`${key}: ${mb(currentRow.gzipBytes)}MB vs ${mb(baseRow.gzipBytes)}MB (${percent}%, ${diff} bytes)`);
+  }
+
+  return { report, gates: gateKeys.map(gateKey => evaluateGate({ current, base, threshold, gateKey })) };
+}
+
+module.exports = { compareBundles, outputPrefix };
+
+const setOutput = (name, value) => {
+  if (process.env.GITHUB_OUTPUT) {
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${value}\n`);
+  }
+};
+
+function main() {
+  const [, , currentPath, basePath] = process.argv;
+  const threshold = Number(process.env.THRESHOLD ?? 2);
+  const gateKeys = (process.env.GATES ?? "embedding-sdk-chunked/total").split(",").map(key => key.trim());
+
+  const current = JSON.parse(fs.readFileSync(currentPath, "utf8"));
+  const base = JSON.parse(fs.readFileSync(basePath, "utf8"));
+
+  const { report, gates } = compareBundles({ current, base, threshold, gateKeys });
+  console.log(report.join("\n"));
+  console.log("");
+
+  for (const gate of gates) {
+    const prefix = outputPrefix(gate.gateKey);
+
+    if (gate.error) {
+      // One broken gate must not hide the others, so report them all and fail
+      // the step at the end.
+      console.error(`::error::${gate.error}`);
+      continue;
+    }
+
+    if (gate.skip) {
+      // Treat the gate as non-actionable: report stable so no regression comment
+      // is posted, mirroring the shell skip() for missing artifacts.
+      console.log(`::notice::Bundle-size gate skipped: ${gate.skip}`);
+      setOutput(`${prefix}_status`, "stable");
+      setOutput(`${prefix}_size_change_percent`, "0");
+      continue;
+    }
+
+    console.log(`Gate: ${gate.gateKey} ${gate.percent}% (threshold ${threshold}%) → ${gate.status}`);
+    setOutput(`${prefix}_status`, gate.status);
+    setOutput(`${prefix}_size_change_percent`, gate.percent);
+  }
+
+  if (gates.some(gate => gate.error)) {
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}

.github/actions/bundle-size-check/compare.unit.spec.js

@@ -0,0 +1,84 @@
+const { compareBundles, outputPrefix } = require("./compare");
+
+const SDK_GATE = "embedding-sdk-chunked/total";
+const APP_GATE = "app/initial";
+
+const total = (gzipBytes, over = {}) => ({
+  bundle: "embedding-sdk-chunked",
+  kind: "total",
+  gzipBytes,
+  reachable: true,
+  ...over,
+});
+
+const appInitial = gzipBytes => ({ bundle: "app", kind: "initial", gzipBytes });
+
+const compare = ({ current, base, threshold = 2, gateKeys = [SDK_GATE] }) =>
+  compareBundles({ current, base, threshold, gateKeys });
+
+describe("outputPrefix", () => {
+  it("turns a gate key into a step-output prefix", () => {
+    expect(outputPrefix(APP_GATE)).toBe("app_initial");
+    expect(outputPrefix(SDK_GATE)).toBe("embedding_sdk_chunked_total");
+  });
+});
+
+describe("compareBundles", () => {
+  it("gates on the chunked SDK total and flags an increase past the threshold", () => {
+    const { gates, report } = compare({ current: [total(110)], base: [total(100)] });
+
+    expect(gates).toEqual([{ gateKey: SDK_GATE, status: "increased", percent: 10 }]);
+    expect(report[0]).toContain("current vs base");
+  });
+
+  it("flags a decrease and stays stable within the threshold", () => {
+    expect(compare({ current: [total(90)], base: [total(100)] }).gates[0]).toMatchObject({
+      status: "decreased",
+      percent: -10,
+    });
+    expect(compare({ current: [total(101)], base: [total(100)] }).gates[0]).toMatchObject({
+      status: "stable",
+      percent: 1,
+    });
+  });
+
+  it("evaluates each gate against its own bundle", () => {
+    const { gates } = compare({
+      current: [total(100), appInitial(110)],
+      base: [total(100), appInitial(100)],
+      gateKeys: [APP_GATE, SDK_GATE],
+    });
+
+    expect(gates).toEqual([
+      { gateKey: APP_GATE, status: "increased", percent: 10 },
+      { gateKey: SDK_GATE, status: "stable", percent: 0 },
+    ]);
+  });
+
+  it("skips when the two sides measured a gate differently (reachable mismatch)", () => {
+    const { gates } = compare({
+      current: [total(130, { reachable: true })],
+      base: [total(100, { reachable: false })],
+    });
+
+    expect(gates[0].status).toBeUndefined();
+    expect(gates[0].skip).toContain("predates the reachable-chunk stats");
+  });
+
+  it("errors when a gate bundle is missing on either side, without hiding the others", () => {
+    const { gates } = compare({
+      current: [appInitial(100)],
+      base: [appInitial(100)],
+      gateKeys: [APP_GATE, SDK_GATE],
+    });
+
+    expect(gates[0]).toEqual({ gateKey: APP_GATE, status: "stable", percent: 0 });
+    expect(gates[1].error).toContain("embedding-sdk-chunked total");
+  });
+
+  it("reports a bundle/kind present on only one side without erroring", () => {
+    const { report } = compare({ current: [total(100), appInitial(50)], base: [total(100)] });
+
+    expect(report.some(line => line.includes("present only in current build"))).toBe(true);
+  });
+});

.github/actions/collect-profile/action.yml

@@ -0,0 +1,61 @@
+name: Collect profile
+description: >-
+  Attach a flamegraph and per-test wall times to a job whose tests ran under clj-async-profiler.
+  Does nothing when the run was not profiled.
+
+inputs:
+  profiled:
+    required: true
+    description: >-
+      "true" when the test step ran under the profiler. Passed in rather than read from the
+      environment so the decision stays recorded by the step that made it.
+  artifact-name:
+    required: true
+    description: Name for the uploaded artifact. Must be unique across the jobs of one run.
+
+runs:
+  using: "composite"
+  steps:
+    # Unlike a JUnit failure report, these run on a green build too — a suite that passes slowly is
+    # exactly what profiling is for.
+    #
+    # `awk 'NR<=25'` rather than `head -25`: the runner ignores SIGPIPE, so `head` exiting early
+    # leaves `sort` with an EPIPE write error and `pipefail` fails the step. `|| true` covers `grep`
+    # finding no junit files.
+    - name: Summarize test wall times
+      if: ${{ inputs.profiled == 'true' }}
+      continue-on-error: true
+      shell: bash
+      run: |
+        {
+          echo "### Slowest test namespaces (seconds)"
+          echo '```'
+          grep -h '<testsuite' target/junit/*.xml 2>/dev/null \
+            | sed -E 's|.*<testsuite name="([^"]*)" time="([^"]*)".*|\2 \1|' \
+            | sort -rn | awk 'NR<=25' || true
+          echo '```'
+          echo "### Slowest tests (seconds)"
+          echo '```'
+          grep -h '<testcase' target/junit/*.xml 2>/dev/null \
+            | sed -E 's|.*classname="([^"]*)" name="([^"]*)" time="([^"]*)".*|\3 \1/\2|' \
+            | sort -rn | awk 'NR<=25' || true
+          echo '```'
+        } >> "$GITHUB_STEP_SUMMARY"
+
+    # Only the rendered flamegraph is kept: the raw collapsed stacks it was built from run to
+    # hundreds of MB on a long suite, and are reproducible locally from the same test selection.
+    #
+    # The info-level test log rides along on a green profiled run too. The failure-only log artifact
+    # the test jobs upload is not written when nothing failed, which is exactly the run being profiled.
+    - name: Upload profile
+      if: ${{ inputs.profiled == 'true' }}
+      continue-on-error: true
+      uses: actions/upload-artifact@v7
+      with:
+        name: ${{ inputs.artifact-name }}
+        path: |
+          target/clj-async-profiler/results/*flamegraph.html
+          target/junit/*.xml
+          logs/test-log.json
+        retention-days: 14
+        if-no-files-found: warn

.github/actions/create-backport/action.yml

@@ -1,4 +1,5 @@
 name: Create Backport PR
+description: Cherry-picks a commit onto a release branch and opens the backport pull request.
 
 inputs:
   target-version: # major version number like 34 or 86
@@ -24,6 +25,8 @@ runs:
         COMMIT: ${{ inputs.backport-commit }}
       shell: bash
       run: | # bash
+        source "${{ github.action_path }}/kondo-ratchets.sh"
+
         git config --global user.email "metabase-bot@metabase.com"
         git config --global user.name "Metabase bot"
 
@@ -33,7 +36,7 @@ runs:
         git checkout ${TARGET_BRANCH}
         git fetch --all
         git checkout -b ${BACKPORT_BRANCH}
-        git cherry-pick ${COMMIT} || true
+        cherry_pick_backport "${COMMIT}"
 
         CONFLICT_LIST=$(git ls-files -u)
 
@@ -42,13 +45,10 @@ runs:
           git cherry-pick --abort
 
           echo "Could not cherry pick because of a conflict"
-          echo "has-conflicts=true" >> $GITHUB_OUTPUT
+          echo "has-conflicts=true" >> "$GITHUB_OUTPUT"
 
           # Add a shell script for resolving conflicts
-          echo "git reset HEAD~1" > ./backport.sh
-          echo "rm ./backport.sh" >> ./backport.sh
-          echo "git cherry-pick ${COMMIT}" >> ./backport.sh
-          echo "echo 'Resolve conflicts and force push this branch.\n\nTo backport translations run: bin/i18n/merge-translations <release-branch>'" >> ./backport.sh
+          write_backport_script "${COMMIT}"
           chmod +x ./backport.sh
           git add ./backport.sh
           git commit -m "Add backport resolution script"
@@ -57,44 +57,43 @@ runs:
           #${ORIGINAL_PULL_REQUEST_NUMBER}
           > [!IMPORTANT]
           > Manual conflict resolution is required.
-          > Checkout the branch and run \`./backport.sh\` script. Force push your changes after cherry-picking. Check the box below when done.
+          > Checkout the branch and run \`./backport.sh\` script. Force push your changes after cherry-picking. Mark the PR as ready for review once conflicts have been addressed.
 
           Conflicts:
           \`\`\`shell
           ${CONFLICT_LIST}
           \`\`\`
-
-          - [ ] Conflicts resolved
         END
           )
         else
-          echo "has-conflicts=false" >> $GITHUB_OUTPUT
+          echo "has-conflicts=false" >> "$GITHUB_OUTPUT"
           PR_BODY="#${ORIGINAL_PULL_REQUEST_NUMBER}"
         fi
 
         git push -u origin ${BACKPORT_BRANCH}
 
-        BACKPORT_PR_URL=$(gh pr create --base "${TARGET_BRANCH}" --head "${BACKPORT_BRANCH}" --label "was-backported" --assignee "${{ github.event.pull_request.user.login }}" --title "🤖 backported \"${ORIGINAL_TITLE}\"" --body "${PR_BODY}")
+        PR_ARGS=(--base "${TARGET_BRANCH}" --head "${BACKPORT_BRANCH}" --label "was-backported" --assignee "${{ github.event.pull_request.user.login }}" --title "🤖 v${TARGET_VERSION} backported \"${ORIGINAL_TITLE}\"" --body "${PR_BODY}")
+        if [ "$CONFLICTS" -gt 0 ]; then
+          PR_ARGS+=(--draft)
+        fi
+
+        BACKPORT_PR_URL=$(gh pr create "${PR_ARGS[@]}")
         BACKPORT_PR_NUMBER=${BACKPORT_PR_URL##*/}
 
-        echo "backport_pr_number=$BACKPORT_PR_NUMBER" >> $GITHUB_OUTPUT
+        echo "backport_pr_number=$BACKPORT_PR_NUMBER" >> "$GITHUB_OUTPUT"
         echo "New PR has been created: #${BACKPORT_PR_NUMBER}"
 
         git checkout ${{ github.sha }}
 
-    - name: Auto approve backport PR
+    - name: Approve and Merge the PR
       if: ${{ steps.create_backport_pull_request.outputs.has-conflicts == 'false' }}
-      uses: juliangruber/approve-pull-request-action@68fcc9a5a73b5641cadf757cf99d73720dcb05d0 # v2.1.0
-      with:
-        github-token: ${{ inputs.github-token-2 }}
-        number: ${{ steps.create_backport_pull_request.outputs.backport_pr_number }}
-
-    - name: Enable Pull Request Automerge
-      if: ${{ steps.create_backport_pull_request.outputs.has-conflicts == 'false' }}
-      run: gh pr merge --squash --auto "$PR_NUMBER"
+      run: |
+        gh pr review --approve "$PR_NUMBER"
+        gh pr merge --squash --auto "$PR_NUMBER"
       shell: bash
       env:
-        GH_TOKEN: ${{ inputs.github-token }}
+        # uses a different token than the token that created the PR so we can approve and merge it
+        GH_TOKEN: ${{ inputs.github-token-2 }}
         PR_NUMBER: ${{ steps.create_backport_pull_request.outputs.backport_pr_number }}
 
     - uses: ./.github/actions/notify-pull-request

.github/actions/create-backport/create-backport-test.sh

@@ -0,0 +1,375 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+action_dir=$(cd "$(dirname "$0")" && pwd)
+cut_release_workflow="$action_dir/../../workflows/cut-release-branch.yml"
+
+# shellcheck source=.github/actions/create-backport/kondo-ratchets.sh
+source "$action_dir/kondo-ratchets.sh"
+
+# Any editor launch fails the run, so a continuation that waits on an editor cannot pass.
+export GIT_EDITOR=false
+
+test_root=
+trap '[ -z "$test_root" ] || rm -rf -- "$test_root"' EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+test_root=$(mktemp -d)
+
+active_ratchets='{:ignore-counts {:example 1}}'
+disabled_ratchets=';; Kondo ignore ratchets apply only to master; this release branch opts out.
+;; The test and fixer recognize this explicit opt-out.
+{:disabled true}'
+
+# Coverage:
+#
+# Target state       Incoming change       Other conflict   Expected result
+# -----------------  --------------------  ---------------  ------------------------------------------
+# active ratchets    unrelated file        none             leave ratchets unchanged
+# active ratchets    ratchets              none             install the release opt-out
+# disabled ratchets  ratchets              none             keep the opt-out; finish with an empty commit
+# divergent ratchets ratchets              none             resolve ratchets and finish the cherry-pick
+# divergent ratchets ratchets (on a pty)   none             finish without opening an editor
+# active ratchets    unrelated file        app.txt          leave the conflict for manual resolution
+# divergent ratchets ratchets + app.txt    app.txt          resolve only ratchets
+# release cut        ratchets              none             cut and backport commit the same opt-out
+# n/a                cut-release workflow  n/a              the workflow calls the shared writer
+# any                invalid commit        n/a              propagate the cherry-pick failure
+# divergent ratchets generated backport.sh app.txt          resolve only ratchets through the manual script
+#
+# Known gaps: an older target with no ratchets file, and an incoming commit that
+# deletes the ratchets file.
+
+test_unrelated_backport_preserves_target_ratchets() (
+  local repo="$test_root/unrelated"
+  init_repo "$repo"
+  local commit
+  commit=$(feature_commit "$repo" change_app)
+  git -C "$repo" checkout -q release
+
+  cd "$repo"
+  cherry_pick_backport "$commit"
+
+  assert_eq feature "$(cat app.txt)" "the unrelated change was not cherry-picked"
+  assert_ratchets "$active_ratchets"
+  assert_cherry_pick_completed
+  assert_worktree_clean
+)
+
+test_clean_ratchet_backport_installs_release_opt_out() (
+  local repo="$test_root/clean-ratchet"
+  init_repo "$repo"
+  local commit
+  commit=$(feature_commit "$repo" change_ratchets)
+  git -C "$repo" checkout -q release
+
+  cd "$repo"
+  cherry_pick_backport "$commit"
+
+  assert_ratchets_disabled
+  assert_cherry_pick_completed
+  assert_worktree_clean
+)
+
+test_disabled_release_absorbs_ratchet_only_backport() (
+  local repo="$test_root/disabled-release"
+  init_repo "$repo"
+  local commit
+  commit=$(feature_commit "$repo" change_ratchets)
+  git -C "$repo" checkout -q release
+  commit_release_change "$repo" disable_release_ratchets "Disable release ratchets"
+
+  cd "$repo"
+  cherry_pick_backport "$commit"
+
+  assert_ratchets_disabled
+  assert_cherry_pick_completed
+  assert_empty_commit
+  assert_worktree_clean
+)
+
+test_ratchet_only_conflict_is_resolved() (
+  local repo="$test_root/ratchet-conflict"
+  init_repo "$repo"
+  local commit
+  commit=$(conflicting_ratchet_commit "$repo")
+
+  cd "$repo"
+  cherry_pick_backport "$commit"
+
+  assert_ratchets_disabled
+  assert_cherry_pick_completed
+  assert_worktree_clean
+)
+
+test_continuation_never_opens_an_editor() (
+  local repo="$test_root/editor"
+  init_repo "$repo"
+  local commit
+  commit=$(conflicting_ratchet_commit "$repo")
+
+  cd "$repo"
+  # Git only opens an editor for the continuation when stdin is a terminal, so run it on a pty. The
+  # exported GIT_EDITOR=false turns any editor launch into a failure. The single quotes are deliberate:
+  # $1 and $2 are for the inner bash, not this shell.
+  # shellcheck disable=SC2016
+  python3 -c 'import os, pty, sys; sys.exit(os.waitstatus_to_exitcode(pty.spawn(sys.argv[1:])))' \
+    bash -c 'source "$1/kondo-ratchets.sh" && cherry_pick_backport "$2"' bash "$action_dir" "$commit" >/dev/null ||
+    fail "the cherry-pick continuation opened an editor"
+
+  assert_ratchets_disabled
+  assert_cherry_pick_completed
+)
+
+test_non_ratchet_conflict_remains_manual() (
+  local repo="$test_root/non-ratchet-conflict"
+  init_repo "$repo"
+  local commit
+  commit=$(feature_commit "$repo" change_app)
+  git -C "$repo" checkout -q release
+  commit_release_change "$repo" change_release_app "Change release app"
+
+  cd "$repo"
+  cherry_pick_backport "$commit"
+
+  assert_ratchets "$active_ratchets"
+  assert_only_conflicts app.txt
+  assert_cherry_pick_pending
+)
+
+test_mixed_conflict_resolves_only_ratchets() (
+  local repo="$test_root/mixed-conflict"
+  init_repo "$repo"
+  local commit
+  commit=$(feature_commit "$repo" change_app_and_ratchets)
+  git -C "$repo" checkout -q release
+  commit_release_change "$repo" change_release_app_and_ratchets "Change release app and ratchets"
+
+  cd "$repo"
+  cherry_pick_backport "$commit"
+
+  assert_ratchets_disabled
+  assert_only_conflicts app.txt
+  assert_cherry_pick_pending
+)
+
+test_release_cut_and_backport_commit_the_same_opt_out() (
+  local cut_repo="$test_root/release-cut"
+  init_repo "$cut_repo"
+  cd "$cut_repo"
+  git checkout -qb release-x.99.x
+  write_disabled_ratchets
+  git add --sparse .clj-kondo/ratchets.edn
+  git commit -q --allow-empty --no-verify -m "Cut release-x.99.x branch"
+  git show HEAD:.clj-kondo/ratchets.edn > "$test_root/release-cut.edn"
+
+  local backport_repo="$test_root/release-cut-backport"
+  init_repo "$backport_repo"
+  local commit
+  commit=$(feature_commit "$backport_repo" change_ratchets)
+  git -C "$backport_repo" checkout -q release
+  cd "$backport_repo"
+  cherry_pick_backport "$commit"
+  git show HEAD:.clj-kondo/ratchets.edn > "$test_root/backport.edn"
+
+  cmp -s "$test_root/release-cut.edn" "$test_root/backport.edn" ||
+    fail "the release cut and the backport committed different opt-out files"
+  assert_eq "$disabled_ratchets" "$(cat "$test_root/release-cut.edn")" \
+    "the release cut did not install the expected opt-out"
+)
+
+test_cut_release_workflow_uses_the_shared_writer() (
+  grep -Fq 'source .github/actions/create-backport/kondo-ratchets.sh' "$cut_release_workflow" ||
+    fail "the cut-release workflow does not source kondo-ratchets.sh"
+  grep -Fq 'write_disabled_ratchets' "$cut_release_workflow" ||
+    fail "the cut-release workflow does not call write_disabled_ratchets"
+  ! grep -Fq ':disabled' "$cut_release_workflow" ||
+    fail "the cut-release workflow carries its own copy of the opt-out"
+)
+
+test_invalid_commit_failure_is_propagated() (
+  local repo="$test_root/invalid"
+  init_repo "$repo"
+  cd "$repo"
+
+  if cherry_pick_backport deadbeef; then
+    fail "an invalid commit succeeded"
+  fi
+)
+
+test_generated_script_resolves_ratchets_end_to_end() (
+  local repo="$test_root/generated-script"
+  init_repo "$repo"
+  local commit
+  commit=$(feature_commit "$repo" change_app_and_ratchets)
+  git -C "$repo" checkout -q release
+  commit_release_change "$repo" change_release_app_and_ratchets "Change release app and ratchets"
+
+  cd "$repo"
+  cherry_pick_backport "$commit"
+  git cherry-pick --abort
+
+  local release_commit
+  release_commit=$(git rev-parse HEAD)
+  write_backport_script "$commit"
+  chmod +x backport.sh
+  git add backport.sh
+  git commit -qm "Add manual backport script"
+
+  bash -n backport.sh
+  grep -Fq 'write_disabled_ratchets ()' backport.sh || fail "the generated script omitted write_disabled_ratchets"
+  ./backport.sh
+
+  assert_ratchets_disabled
+  assert_only_conflicts app.txt
+  assert_cherry_pick_pending
+  assert_eq "$release_commit" "$(git rev-parse HEAD)" "the generated script did not return HEAD to the release commit"
+  [ ! -e backport.sh ] || fail "the generated script did not remove itself"
+  ! git ls-files --error-unmatch backport.sh >/dev/null 2>&1 || fail "the generated script is still tracked"
+  ! git status --porcelain | grep -q backport.sh || fail "the generated script left a status entry"
+)
+
+# Test harness
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+assert_eq() {
+  local expected=$1
+  local actual=$2
+  local message=$3
+  [ "$expected" = "$actual" ] || fail "$message (expected '$expected', got '$actual')"
+}
+
+assert_ratchets() {
+  assert_eq "$1" "$(cat .clj-kondo/ratchets.edn)" "unexpected ratchet state"
+}
+
+assert_ratchets_disabled() {
+  assert_ratchets "$disabled_ratchets"
+}
+
+assert_cherry_pick_completed() {
+  ! git rev-parse -q --verify CHERRY_PICK_HEAD >/dev/null || fail "the cherry-pick is still pending"
+}
+
+assert_cherry_pick_pending() {
+  git rev-parse -q --verify CHERRY_PICK_HEAD >/dev/null || fail "the cherry-pick state was lost"
+}
+
+assert_only_conflicts() {
+  local expected
+  local actual
+  expected=$(printf '%s\n' "$@" | sort)
+  actual=$(git diff --name-only --diff-filter=U | sort)
+  assert_eq "$expected" "$actual" "unexpected unresolved files"
+}
+
+assert_empty_commit() {
+  git diff --quiet HEAD^ HEAD || fail "the backport commit was not empty"
+}
+
+assert_worktree_clean() {
+  [ -z "$(git status --porcelain)" ] || fail "the backport left worktree changes"
+}
+
+init_repo() {
+  local repo=$1
+  git init -q -b release "$repo"
+  git -C "$repo" config user.email test@example.com
+  git -C "$repo" config user.name "Backport test"
+  printf 'base\n' > "$repo/app.txt"
+  mkdir -p "$repo/.clj-kondo"
+  printf '%s\n' "$active_ratchets" > "$repo/.clj-kondo/ratchets.edn"
+  git -C "$repo" add .
+  git -C "$repo" commit -qm "Base"
+}
+
+feature_commit() {
+  local repo=$1
+  shift
+  git -C "$repo" checkout -qb feature
+  "$@" "$repo"
+  git -C "$repo" add .
+  git -C "$repo" commit -qm "Feature"
+  git -C "$repo" rev-parse HEAD
+}
+
+# Sets up a release branch whose ratchets conflict with the feature commit, and prints that commit.
+conflicting_ratchet_commit() {
+  local repo=$1
+  local commit
+  commit=$(feature_commit "$repo" change_ratchets)
+  git -C "$repo" checkout -q release
+  commit_release_change "$repo" change_release_ratchets "Change release ratchets"
+  echo "$commit"
+}
+
+change_app() {
+  printf 'feature\n' > "$1/app.txt"
+}
+
+change_ratchets() {
+  printf '{:ignore-counts {:example 2}}\n' > "$1/.clj-kondo/ratchets.edn"
+}
+
+change_app_and_ratchets() {
+  change_app "$1"
+  change_ratchets "$1"
+}
+
+change_release_app() {
+  printf 'release\n' > "$1/app.txt"
+}
+
+change_release_ratchets() {
+  printf '{:ignore-counts {:release 1}}\n' > "$1/.clj-kondo/ratchets.edn"
+}
+
+change_release_app_and_ratchets() {
+  change_release_app "$1"
+  change_release_ratchets "$1"
+}
+
+# Setup writes the opt-out through the shared writer; the only copy is the expected text at the top.
+disable_release_ratchets() {
+  (cd "$1" && write_disabled_ratchets)
+}
+
+commit_release_change() {
+  local repo=$1
+  local change=$2
+  local message=$3
+  "$change" "$repo"
+  git -C "$repo" add .
+  git -C "$repo" commit -qm "$message"
+}
+
+run_test() {
+  local description=$1
+  local test=${description// /_}
+  test=${test//-/_}
+  test="test_$test"
+
+  declare -F "$test" >/dev/null || fail "missing test function: $test"
+
+  printf 'TEST: %s\n' "$description"
+  "$test"
+  printf 'PASS: %s\n' "$description"
+}
+
+run_test "unrelated backport preserves target ratchets"
+run_test "clean ratchet backport installs release opt-out"
+run_test "disabled release absorbs ratchet-only backport"
+run_test "ratchet-only conflict is resolved"
+run_test "continuation never opens an editor"
+run_test "non-ratchet conflict remains manual"
+run_test "mixed conflict resolves only ratchets"
+run_test "release cut and backport commit the same opt-out"
+run_test "cut-release workflow uses the shared writer"
+run_test "invalid commit failure is propagated"
+run_test "generated script resolves ratchets end-to-end"

.github/actions/create-backport/kondo-ratchets.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# The only place that knows what a release branch's opt-out looks like. The cut-release workflow, the
+# backport helper, and the tests all go through this function.
+write_disabled_ratchets() {
+  mkdir -p .clj-kondo
+  printf '%s\n' \
+    ';; Kondo ignore ratchets apply only to master; this release branch opts out.' \
+    ';; The test and fixer recognize this explicit opt-out.' \
+    '{:disabled true}' \
+    > .clj-kondo/ratchets.edn
+}
+
+disable_ratchets() {
+  local commit=$1
+  local file=.clj-kondo/ratchets.edn
+  [ -n "$(git diff-tree --root --no-commit-id --name-only -r "$commit" -- "$file")" ] || return 0
+
+  echo "$file: disabling kondo ratchets on the release branch"
+  write_disabled_ratchets
+  git add -- "$file"
+
+  if ! git rev-parse -q --verify CHERRY_PICK_HEAD >/dev/null; then
+    if ! git diff --cached --quiet HEAD; then
+      git commit --amend --no-edit
+    fi
+    return 0
+  fi
+
+  if [ -z "$(git ls-files -u)" ]; then
+    echo "$file was the only conflict, finishing the cherry-pick"
+    if git diff --cached --quiet HEAD; then
+      echo "nothing left to apply, committing the backport empty"
+      git commit --allow-empty --no-edit
+    else
+      # GIT_EDITOR outranks core.editor, VISUAL, and EDITOR, so the continuation can never wait on
+      # an editor; the repository's own editor configuration is left alone.
+      GIT_EDITOR=true git cherry-pick --continue
+    fi
+  fi
+}
+
+cherry_pick_backport() {
+  local commit=$1
+  local status=0
+  git cherry-pick "$commit" || status=$?
+  if [ "$status" -ne 0 ] && ! git rev-parse -q --verify CHERRY_PICK_HEAD >/dev/null; then
+    echo "cherry-pick failed without entering a resolvable conflict state" >&2
+    return "$status"
+  fi
+
+  disable_ratchets "$commit"
+  if [ "$status" -ne 0 ] &&
+     git rev-parse -q --verify CHERRY_PICK_HEAD >/dev/null &&
+     [ -z "$(git ls-files -u)" ]; then
+    echo "cherry-pick stopped without a file conflict to resolve" >&2
+    return "$status"
+  fi
+}
+
+write_backport_script() {
+  local commit=$1
+  {
+    echo "#!/usr/bin/env bash"
+    echo "set -euo pipefail"
+    echo "git reset HEAD~1"
+    echo "rm ./backport.sh"
+    declare -f write_disabled_ratchets disable_ratchets cherry_pick_backport
+    printf 'cherry_pick_backport %q\n' "$commit"
+    printf '%s\n' "printf 'Resolve conflicts and force push this branch.\\n\\nTo backport translations run: bin/i18n/merge-translations <release-branch>\\n'"
+  } > ./backport.sh
+}

.github/actions/create-test-plan/action.yml

@@ -0,0 +1,131 @@
+name: Create test plan
+description: Cruise the frontend import graph and compute the affected-tests plan.
+
+inputs:
+  changed-files:
+    description: All changed files (CSV).
+    required: true
+  fe-changed-files:
+    description: Changed frontend_sources files (CSV).
+    required: true
+  be-changed-files:
+    description: Changed backend_sources files (CSV).
+    required: true
+  unit-infra-touched:
+    description: Whether FE unit infra changed.
+    required: true
+  loki-infra-touched:
+    description: Whether Loki infra changed.
+    required: true
+  e2e-infra-touched:
+    description: Whether e2e harness/support code changed.
+    required: true
+  shared-sources-touched:
+    description: Whether cljc/cljs/package.json changed.
+    required: true
+
+outputs:
+  stats:
+    description: FE Affected Tests stats row (JSON).
+    value: ${{ steps.compute.outputs.stats }}
+  fe_unit_specs_to_run:
+    description: Unit specs to run (JSON array).
+    value: ${{ steps.compute.outputs.fe_unit_specs_to_run }}
+  loki_stories_to_run:
+    description: Loki stories to run (JSON array).
+    value: ${{ steps.compute.outputs.loki_stories_to_run }}
+  e2e_specs_to_run:
+    description: E2E specs to run (JSON array).
+    value: ${{ steps.compute.outputs.e2e_specs_to_run }}
+
+runs:
+  using: composite
+  steps:
+    - name: Prepare Node + Bun
+      uses: ./.github/actions/prepare-node-bun
+    - name: Resolve closest-ancestor e2e coverage manifest
+      id: manifest
+      uses: actions/github-script@v9
+      with:
+        script: | # js
+          const { pathToFileURL } = require("url");
+          const { resolveCoverageManifest } = await import(
+            pathToFileURL(
+              `${process.env.GITHUB_WORKSPACE}/.github/scripts/resolve-coverage-manifest.mjs`,
+            ).href,
+          );
+          const result = await resolveCoverageManifest({
+            github,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            headSha: context.payload.pull_request?.head?.sha ?? context.sha,
+          });
+          core.setOutput("path", result?.path ?? "");
+    - name: Build dependency graph
+      shell: bash
+      run: |
+        # Quiet on success; surface output only if install fails.
+        bun install --frozen-lockfile > /tmp/bun-install.log 2>&1 \
+          || { echo "bun install issues (continuing):"; tail -20 /tmp/bun-install.log; }
+        bunx depcruise frontend/src enterprise/frontend/src \
+          --config .dependency-cruiser.cjs \
+          --output-type json > dependency-graph.json || true
+
+    - name: Create test plan
+      id: compute
+      shell: bash
+      env:
+        CHANGED_FILES: ${{ inputs.changed-files }}
+        FE_CHANGED_FILES: ${{ inputs.fe-changed-files }}
+        BE_CHANGED_FILES: ${{ inputs.be-changed-files }}
+        UNIT_INFRA_TOUCHED: ${{ inputs.unit-infra-touched }}
+        LOKI_INFRA_TOUCHED: ${{ inputs.loki-infra-touched }}
+        E2E_INFRA_TOUCHED: ${{ inputs.e2e-infra-touched }}
+        SHARED_SOURCES_TOUCHED: ${{ inputs.shared-sources-touched }}
+        DEP_GRAPH_JSON: dependency-graph.json
+        E2E_SPEC_MANIFEST: ${{ steps.manifest.outputs.path }}
+      run: |
+        # stdout is the plan JSON; the planner's own info logs go to stderr.
+        bun .github/scripts/create-test-plan.ts > test-plan.json
+        echo "stats=$(jq -c '.stats' test-plan.json)" >> "$GITHUB_OUTPUT"
+        echo "fe_unit_specs_to_run=$(jq -c '.fe_unit_specs_to_run' test-plan.json)" >> "$GITHUB_OUTPUT"
+        echo "loki_stories_to_run=$(jq -c '.loki_stories_to_run' test-plan.json)" >> "$GITHUB_OUTPUT"
+        echo "e2e_specs_to_run=$(jq -c '.e2e_specs_to_run' test-plan.json)" >> "$GITHUB_OUTPUT"
+
+    - name: Report test plan
+      shell: bash
+      run: |
+        plan=test-plan.json
+        row() { # name, selected, total
+          if [ "$2" -eq "$3" ]; then echo "| $1 | all ($3) | $3 |"; else echo "| $1 | $2 | $3 |"; fi
+        }
+        {
+          echo "## Affected test plan"
+          echo
+          echo "| Suite | Selected | Total |"
+          echo "|---|---:|---:|"
+          row "Unit" "$(jq '.stats.unit_specs_to_run_usage' "$plan")" "$(jq '.stats.unit_specs_all' "$plan")"
+          row "Loki" "$(jq '.stats.loki_stories_to_run_usage' "$plan")" "$(jq '.stats.loki_stories_all' "$plan")"
+          row "E2E"  "$(jq '.stats.e2e_specs_to_run_usage' "$plan")"  "$(jq '.stats.e2e_specs_all' "$plan")"
+          echo
+          echo "Changed: $(jq '.stats.fe_files_changed' "$plan") FE / $(jq '.stats.be_files_changed' "$plan") BE file(s) · $(jq '.stats.fe_modules_affected_usage' "$plan") FE module(s) affected"
+          echo
+          e2e_run=$(jq '.stats.e2e_specs_to_run_usage' "$plan")
+          e2e_all=$(jq '.stats.e2e_specs_all' "$plan")
+          if [ "$e2e_run" -eq "$e2e_all" ]; then
+            echo "**E2E: full run** — no manifest, or a change the coverage manifest can't scope (backend, e2e infra, cljc/cljs)."
+          else
+            echo "<details><summary><b>E2E specs to run ($e2e_run)</b></summary>"
+            echo
+            jq -r '.e2e_specs_to_run[]' "$plan" | sed 's/^/- /'
+            echo
+            echo "</details>"
+          fi
+          echo
+          echo "<details><summary>Full stats (rules vs usage graph)</summary>"
+          echo
+          echo '```json'
+          jq '.stats' "$plan"
+          echo '```'
+          echo "</details>"
+        } | tee -a "${GITHUB_STEP_SUMMARY:-/dev/null}"

.github/actions/cross-branch-migration-test/action.yml

@@ -1,4 +1,7 @@
 name: Cross-branch migration test
+description: >-
+  Boot Metabase on the base branch to migrate the app db, then boot the PR branch against the
+  same db, verifying the PR's migrations apply cleanly on top of the base branch's schema.
 
 inputs:
   base-ref: ## Base branch PR came from

.github/actions/e2e-prepare-containers/action.yml

@@ -93,8 +93,8 @@ runs:
 
         if ${{ inputs.maildev }}; then
           echo -e "${Y}checking maildev container..." &&
-          while ! nc -z localhost 1080; do sleep 1; done &&
-          while ! nc -z localhost 1025; do sleep 1; done &&
+          while ! nc -z localhost 1180; do sleep 1; done &&
+          while ! nc -z localhost 1125; do sleep 1; done &&
           echo -e "${G}Maildev is up and running!"
 
           echo -e "${Y}checking maildev-ssl container..." &&

.github/actions/fetch-artifact/action.yml

@@ -20,6 +20,15 @@ inputs:
     description: Directory path where the jar should be extracted (defaults to current directory)
     required: false
     default: "."
+  download:
+    description: Default is true. Set to false to only look the artifact up and report `fetch-hit`.
+    required: false
+    default: "true"
+
+outputs:
+  fetch-hit:
+    description: Boolean indicating if an artifact was successfully found and downloaded.
+    value: ${{ steps.find_release_artifact.outputs.fetch-hit }}
 
 runs:
   using: "composite"
@@ -28,11 +37,12 @@ runs:
       id: find_release_artifact
       uses: actions/github-script@v9
       with:
-        result-encoding: string
         script: | # js
           const fs = require('fs');
 
           const isRelease = "${{ inputs.release }}" === "true";
+          const failOnMiss = "${{ inputs.fail-on-fetch-miss }}" !== "false";
+          const shouldDownload = "${{ inputs.download }}" !== "false";
           const prefix = isRelease ? "metabase-release" : "metabase";
           const artifactName = `${prefix}-${{ inputs.edition }}-${{ inputs.commit }}-uberjar`;
           console.log(`Looking for artifact: ${artifactName}`);
@@ -44,12 +54,18 @@ runs:
             per_page: 1,
           });
 
-          if (!artifacts.data?.artifacts?.[0]?.id) {
-            core.setFailed(`No artifacts found for ${artifactName}`);
-            return;
+          const artifact_id = artifacts.data?.artifacts?.[0]?.id;
+
+          if (!artifact_id) {
+            core.setOutput('fetch-hit', 'false');
+          } else {
+            core.setOutput('fetch-hit', 'true');
           }
 
-          const artifact_id = artifacts.data.artifacts[0].id;
+          if (!shouldDownload) {
+            console.log(`skipping download (download: false)`);
+            return;
+          }
 
           let download;
           const maxAttempts = 3;
@@ -74,6 +90,7 @@ runs:
           fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/mb.zip`, Buffer.from(download.data));
 
     - name: Extract and rename JAR
+      if: ${{ steps.find_release_artifact.outputs.fetch-hit == 'true' && inputs.download != 'false' }}
       shell: bash
       run: | # bash
         OUTPUT_NAME="${{ inputs.output-name }}"
@@ -113,18 +130,20 @@ runs:
 
         # Set the JAR_PATH environment variable
         if [ "$EXTRACT_PATH" == "." ]; then
-          echo "JAR_PATH=$OUTPUT_NAME" >> $GITHUB_ENV
+          echo "JAR_PATH=$OUTPUT_NAME" >> "$GITHUB_ENV"
         else
-          echo "JAR_PATH=$EXTRACT_PATH/$OUTPUT_NAME" >> $GITHUB_ENV
+          echo "JAR_PATH=$EXTRACT_PATH/$OUTPUT_NAME" >> "$GITHUB_ENV"
         fi
 
     - name: Verify that this is a valid JAR file
+      if: ${{ steps.find_release_artifact.outputs.fetch-hit == 'true' && inputs.download != 'false' }}
       shell: bash
       run: |
         echo "Verifying JAR at: $JAR_PATH"
         file --mime-type "$JAR_PATH"
 
     - name: Reveal its version.properties
+      if: ${{ steps.find_release_artifact.outputs.fetch-hit == 'true' && inputs.download != 'false' }}
       shell: bash
       run: |
         echo "Extracting version.properties from: $JAR_PATH"

.github/actions/find-squashed-commit/action.yml

@@ -22,7 +22,7 @@ runs:
         COMMIT=$(env -i git log $BASE_REF --grep="(#$PULL_REQUEST_NUMBER)" --format="%H")
         echo "commit SHA $COMMIT"
 
-        echo "commit=$COMMIT" >> $GITHUB_OUTPUT
+        echo "commit=$COMMIT" >> "$GITHUB_OUTPUT"
       id: find-squashed-commit
       shell: bash
       env:

.github/actions/get-cache-keys/action.yml

@@ -1,45 +0,0 @@
-name: Get cache keys
-description: |
-  Get deterministic cache keys for Maven and Node.js caches based on the centrally controlled cache prefix,
-  and the suffix based on the runner OS and the current week of the year.
-
-outputs:
-  m2-cache-key:
-    description: "The cache key for the Maven cache."
-    value: ${{ steps.keys-factory.outputs.m2-cache-key }}
-  m2-restore-key:
-    description: "The fallback restore key prefix for the Maven cache."
-    value: ${{ steps.keys-factory.outputs.m2-restore-key }}
-  node-cache-key:
-    description: "The cache key for the Node.js cache."
-    value: ${{ steps.keys-factory.outputs.node-cache-key }}
-  node-restore-key:
-    description: "The fallback restore key prefix for the Node.js cache."
-    value: ${{ steps.keys-factory.outputs.node-restore-key }}
-  eslint-cache-key:
-    description: "The cache key for Eslint cache"
-    value: ${{ steps.keys-factory.outputs.eslint-cache-key }}
-  cypress-cache-key:
-    description: "The cache key for Cypress cache"
-    value: ${{ steps.keys-factory.outputs.cypress-cache-key }}
-
-runs:
-  using: "composite"
-  steps:
-    - name: Generate and output cache keys
-      id: keys-factory
-      run: |
-        M2_CACHE_PREFIX='M2'
-        NODE_CACHE_PREFIX='node-modules'
-        ESLINT_CACHE_PREFIX='eslint'
-        CYPRESS_CACHE_PREFIX='cypress'
-        WEEK_OF_YEAR=$(/bin/date "+%G-%V")
-        CACHE_SUFFIX="${{ runner.os }}-$WEEK_OF_YEAR"
-
-        echo "m2-cache-key=$M2_CACHE_PREFIX-$CACHE_SUFFIX" >> $GITHUB_OUTPUT
-        echo "m2-restore-key=$M2_CACHE_PREFIX-" >> $GITHUB_OUTPUT
-        echo "node-cache-key=$NODE_CACHE_PREFIX-$CACHE_SUFFIX" >> $GITHUB_OUTPUT
-        echo "node-restore-key=$NODE_CACHE_PREFIX-" >> $GITHUB_OUTPUT
-        echo "eslint-cache-key=$ESLINT_CACHE_PREFIX-$CACHE_SUFFIX" >> $GITHUB_OUTPUT
-        echo "cypress-cache-key=$CYPRESS_CACHE_PREFIX-$CACHE_SUFFIX" >> $GITHUB_OUTPUT
-      shell: bash

.github/actions/get-docker-info/action.yml

@@ -1,7 +1,15 @@
 name: Get Docker Info
-description: Determines Docker repository and tag based on branch and edition
+description: Determines the registry, repository, and tag a container image is pushed to.
 
 inputs:
+  repo:
+    description: Registry and repo, e.g. "metabase/metabase". Overrides branch derived repo.
+    required: false
+    default: ''
+  tag:
+    description: Docker tag, e.g. v1.87.2. Overrides a branch derived tag.
+    required: false
+    default: ''
   branch:
     description: Branch name (defaults to current branch)
     required: false
@@ -25,9 +33,6 @@ outputs:
   full_image:
     description: Full Docker image name (repo:tag)
     value: ${{ steps.docker-info.outputs.full_image }}
-  editions:
-    description: JSON array of editions to build
-    value: ${{ steps.docker-info.outputs.editions }}
 
 runs:
   using: "composite"
@@ -41,34 +46,22 @@ runs:
           const edition = '${{ inputs.edition }}';
           const owner = '${{ inputs.owner }}';
 
-          console.log(`Determining Docker info for branch: ${branch}, edition: ${edition}`);
-
-          let repo, tag, editions;
-
-          if (branch === 'master') {
-            // Master builds both editions with specific repos
-            editions = ['ee', 'oss'];
-            tag = 'latest';
-
-            if (edition === 'ee') {
-              repo = `${owner}/metabase-enterprise-head`;
-            } else {
-              repo = `${owner}/metabase-head`;
-            }
-          } else {
-            // All other branches only build EE to metabase-dev
-            editions = ['ee'];
-            tag = branch.replaceAll('/', '-'); // slashes make docker sad
-            repo = `${owner}/metabase-dev`;
+          let tag = '${{ inputs.tag}}';
+          if (!tag) {
+            tag = branch === 'master' ? 'latest' : `${branch.replaceAll('/', '-')}-${edition}`;
           }
 
-          const fullImage = `${repo}:${tag}`;
+          let repo = '${{ inputs.repo }}';
+          if (!repo) {
+            if (branch === 'master') {
+              repo = edition === 'ee' ? `${owner}/metabase-enterprise-head` : `${owner}/metabase-head`;
+            } else {
+              repo = `${owner}/metabase-dev`;
+            }
+          }
 
-          // Set outputs
           core.setOutput('repo', repo);
           core.setOutput('tag', tag);
-          core.setOutput('full_image', fullImage);
-          core.setOutput('editions', JSON.stringify(editions));
+          core.setOutput('full_image', `${repo}:${tag}`);
 
-          console.log(`Docker image: ${fullImage}`);
-          console.log(`Editions: ${JSON.stringify(editions)}`);
+          console.log(`Resolved: repo = ${repo}, tag = ${tag}`);

.github/actions/notify-pull-request/action.yml

@@ -1,12 +1,11 @@
 name: Notify Pull Request
+description: Post a comment on the pull request, optionally replacing the previous one with the same message.
 inputs:
   remove-previous-comment:
     required: false
-    type: boolean
     default: false
   add-new-comment:
     required: false
-    type: boolean
     default: true
   message:
     required: true

.github/actions/prepare-backend/action.yml

@@ -4,10 +4,7 @@ description: |
 inputs:
   java-version:
     required: true
-    default: "21"
-  clojure-version:
-    required: true
-    default: "1.12.0.1488"
+    default: "25"
 
 runs:
   using: "composite"
@@ -17,12 +14,40 @@ runs:
       with:
         java-version: ${{ inputs.java-version }}
         distribution: "temurin"
+    - name: Cache spec
+      id: cache-spec
+      shell: bash
+      run: .github/scripts/cache-keys.sh | tee -a "$GITHUB_OUTPUT"
+
+    - name: Restore Clojure CLI
+      uses: actions/cache/restore@v5
+      with:
+        path: ${{ steps.cache-spec.outputs.clojure-path }}
+        key: ${{ steps.cache-spec.outputs.clojure-key }}
+
     - name: Install Clojure CLI
       shell: bash
+      env:
+        CLOJURE_PREFIX: ${{ steps.cache-spec.outputs.clojure-path }}
+        CLOJURE_VERSION: ${{ steps.cache-spec.outputs.clojure-version }}
       run: |
+        set -uo pipefail
+        echo "$CLOJURE_PREFIX/bin" >> "$GITHUB_PATH"
+        export PATH="$CLOJURE_PREFIX/bin:$PATH"
+
+        # Whether the prefix already holds the right install is decided by running it, not by the
+        # cache-hit flag. The installer bakes the prefix into the clj/clojure shims, so a tree restored
+        # under a different $HOME points at a directory that is not there; and on a runner that is not
+        # ephemeral, a previous version's prefix outlives the cache entry that stopped matching it.
+        if clojure --version | grep -qF "$CLOJURE_VERSION"; then
+          clojure --version
+          exit 0
+        fi
+
+        cd "$RUNNER_TEMP"
         for attempt in 1 2 3; do
-          curl --retry 3 --retry-delay 5 --fail -O https://download.clojure.org/install/linux-install-${{ inputs.clojure-version }}.sh \
-            && sudo bash ./linux-install-${{ inputs.clojure-version }}.sh \
+          curl --retry 3 --retry-delay 5 --fail -O "https://download.clojure.org/install/linux-install-$CLOJURE_VERSION.sh" \
+            && bash "./linux-install-$CLOJURE_VERSION.sh" --prefix "$CLOJURE_PREFIX" \
             && break
           echo "::warning::Clojure install attempt $attempt failed, retrying in 10s..."
           sleep 10
@@ -32,10 +57,6 @@ runs:
           exit 1
         fi
 
-    - name: Get M2 cache key
-      uses: ./.github/actions/get-cache-keys
-      id: get-cache-keys
-
     - name: Install uv (for Python package installation)
       uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
       with:
@@ -46,9 +67,6 @@ runs:
     - name: Restore M2 cache
       uses: actions/cache/restore@v5
       with:
-        path: |
-          ~/.m2
-          ~/.gitlibs
-        key: ${{ steps.get-cache-keys.outputs.m2-cache-key }}
-        restore-keys: |
-          ${{ steps.get-cache-keys.outputs.m2-restore-key }}
+        path: ${{ steps.cache-spec.outputs.m2-path }}
+        key: ${{ steps.cache-spec.outputs.m2-key }}
+        restore-keys: ${{ steps.cache-spec.outputs.m2-restore-key }}

.github/actions/prepare-ci-conductor/action.yml

@@ -0,0 +1,52 @@
+name: Prepare CI Conductor
+description: >-
+  Make the ci-conductor sources runnable in the workspace.
+  Unless the checkout is headed for master, they are overlaid from master, so every
+  branch runs the latest scripts while its workflow wiring stays branch-historical.
+
+runs:
+  using: composite
+  steps:
+    - name: Detect bun
+      id: bun
+      shell: bash
+      run: |
+        if command -v bun >/dev/null; then
+          echo "present=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "present=false" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Install bun
+      if: steps.bun.outputs.present != 'true'
+      uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+      with:
+        bun-version-file: "package.json"
+        token: ${{ github.token }}
+
+    # Anything headed for master runs master's own sources, so a PR can test its own changes.
+    - name: Fetch ci-conductor sources from master
+      if: ${{ github.base_ref != 'master' && github.ref_name != 'master' }}
+      uses: actions/checkout@v6
+      with:
+        repository: metabase/metabase
+        ref: master
+        path: .ci-conductor-master
+        persist-credentials: false
+        sparse-checkout-cone-mode: false
+        sparse-checkout: |
+          release/ci-conductor
+          e2e/support/ci_conductor.ts
+
+    # e2e/support/config.js and e2e/support/ci_conductor.ts resolve these by relative
+    # path at bundle time, so the sources have to land where the branch expects them.
+    - name: Overlay ci-conductor sources from master
+      if: ${{ github.base_ref != 'master' && github.ref_name != 'master' }}
+      shell: bash
+      run: |
+        set -euo pipefail
+        rm -rf release/ci-conductor
+        mv .ci-conductor-master/release/ci-conductor release/ci-conductor
+        mv .ci-conductor-master/e2e/support/ci_conductor.ts e2e/support/ci_conductor.ts
+        rm -rf .ci-conductor-master
+        echo "Overlaid ci-conductor sources from master."

.github/actions/prepare-cypress/action.yml

@@ -15,21 +15,27 @@ outputs:
 runs:
   using: "composite"
   steps:
+    # e2e/support/config.js imports the reporter, so it has to be in place before Cypress bundles.
+    - name: Prepare CI Conductor
+      uses: ./.github/actions/prepare-ci-conductor
+
     - name: Install Chrome v144
       uses: browser-actions/setup-chrome@2e1d749697dd1612b833dba4a722266286fbefcd # v2.1.2
       with:
         chrome-version: 144
       id: setup-chrome
 
-    - name: Get cache keys
-      uses: ./.github/actions/get-cache-keys
-      id: get-cache-keys
+    - name: Cache spec
+      id: cache-spec
+      shell: bash
+      run: .github/scripts/cache-keys.sh | tee -a "$GITHUB_OUTPUT"
 
-    - name: Get Cypress cache
+    - name: Restore Cypress binary
       uses: actions/cache/restore@v5
       with:
-        path: ~/.cache/Cypress
-        key: ${{ steps.get-cache-keys.outputs.cypress-cache-key }}
+        path: ${{ steps.cache-spec.outputs.cypress-path }}
+        key: ${{ steps.cache-spec.outputs.cypress-key }}
+        restore-keys: ${{ steps.cache-spec.outputs.cypress-restore-key }}
 
     - name: Ensure that Cypress executable is ready
       run: |

.github/actions/prepare-frontend/action.yml

@@ -16,43 +16,37 @@ runs:
       with:
         node-version: ${{ inputs.node-version }}
 
-    - name: Get cache keys
-      uses: ./.github/actions/get-cache-keys
-      id: get-cache-keys
-
-    - name: Restore M2 cache
-      uses: actions/cache/restore@v5
-      with:
-        path: |
-          ~/.m2
-          ~/.gitlibs
-        key: ${{ steps.get-cache-keys.outputs.m2-cache-key }}
-        restore-keys: |
-          ${{ steps.get-cache-keys.outputs.m2-restore-key }}
-
-    - name: Get bun cache directory
-      id: bun-cache
-      run: |
-        BUN_CACHE_DIR=$(bun pm cache)
-        echo "Bun cache directory: $BUN_CACHE_DIR"
-        echo "dir=$BUN_CACHE_DIR" >> $GITHUB_OUTPUT
+    - name: Cache spec
+      id: cache-spec
       shell: bash
+      run: .github/scripts/cache-keys.sh | tee -a "$GITHUB_OUTPUT"
 
-    - name: Restore node_modules cache
+    # The spec names the store path rather than discovering it, so that a job can restore the cache
+    # before bun exists. Exported job-wide rather than per-step because every later bun invocation has
+    # to resolve against the same store. Confirm bun agreed: if the variable stopped taking effect, bun
+    # would fill its default directory and the cache would silently save an empty tree.
+    - name: Point bun at the cached store
+      shell: bash
+      env:
+        STORE: ${{ steps.cache-spec.outputs.bun-store-path }}
+      run: |
+        echo "BUN_INSTALL_CACHE_DIR=$STORE" >> "$GITHUB_ENV"
+        ACTUAL=$(BUN_INSTALL_CACHE_DIR="$STORE" bun pm cache)
+        if [ "$ACTUAL" != "$STORE" ]; then
+          echo "::error::bun reports its store at $ACTUAL, not $STORE; BUN_INSTALL_CACHE_DIR is not taking effect"
+          exit 1
+        fi
+
+    - name: Restore bun store
       uses: actions/cache/restore@v5
-      id: node-modules-cache
       with:
-        path: |
-          ${{ steps.bun-cache.outputs.dir }}
-          node_modules
-        key: ${{ steps.get-cache-keys.outputs.node-cache-key }}
-        restore-keys: |
-          ${{ steps.get-cache-keys.outputs.node-restore-key }}
+        path: ${{ steps.cache-spec.outputs.bun-store-path }}
+        key: ${{ steps.cache-spec.outputs.bun-store-key }}
+        restore-keys: ${{ steps.cache-spec.outputs.bun-store-restore-key }}
 
     # postinstall lifecycle hook can be dangerous in CI so we only run it locally (see package.json)
     # If a job wants to patch packages, it does so explicitly in the CI. This setting is opt-out.
-    # For example, we never want to cache node_modules with patches already applied so cache-generator.yml skips that step.
-    - name: Clean install
+    - name: Install front-end dependencies
       run: bun install --frozen-lockfile
       shell: bash
     - name: Patch frontend dependencies

.github/actions/prepare-node-bun/action.yml

@@ -16,5 +16,5 @@ runs:
     - name: Install bun
       uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
       with:
-        bun-version: "1.3.14"
+        bun-version-file: 'package.json'
         token: ${{ github.token }}

.github/actions/prepare-release-scripts/action.yml

@@ -6,7 +6,7 @@ runs:
   steps:
     - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
       with:
-        bun-version: "1.3.14"
+        bun-version-file: 'package.json'
         token: ${{ github.token }}
 
     - name: Build release scripts

.github/actions/prepare-shoppy-e2e/action.yml

@@ -14,21 +14,6 @@ inputs:
   staging-mb-all-features-token:
     description: "Staging MB all features token"
     required: true
-  shoppy-iam-role:
-    description: "Shoppy IAM role for AWS credentials"
-    required: true
-  shoppy-metabase-app-db-s3-bucket:
-    description: "S3 bucket for Shoppy app DB dump"
-    required: true
-  shoppy-metabase-app-db-s3-key:
-    description: "S3 key for Shoppy app DB dump"
-    required: true
-  shoppy-metabase-app-db-user:
-    description: "Shoppy Metabase app DB user"
-    required: true
-  shoppy-metabase-app-db-database:
-    description: "Shoppy Metabase app DB database"
-    required: true
   metastore-dev-server-url:
     description: "Metastore dev server URL"
     required: true
@@ -88,25 +73,11 @@ runs:
         REPO_URL="https://github.com/metabase/shoppy.git"
         echo "Checking if branch '${SAMPLE_APP_BRANCH_NAME}' exists in ${REPO_URL}..."
         if git ls-remote --exit-code --heads "$REPO_URL" "${SAMPLE_APP_BRANCH_NAME}"; then
-          echo "sample_app_branch_exists=true" >> $GITHUB_OUTPUT
+          echo "sample_app_branch_exists=true" >> "$GITHUB_OUTPUT"
         else
-          echo "sample_app_branch_exists=false" >> $GITHUB_OUTPUT
+          echo "sample_app_branch_exists=false" >> "$GITHUB_OUTPUT"
         fi
 
-    - name: Configure AWS credentials
-      if: ${{ steps.check-sample-app-branch.outputs.sample_app_branch_exists == 'true' }}
-      uses: aws-actions/configure-aws-credentials@d979d5b3a71173a29b74b5b88418bfda9437d885
-      with:
-        role-to-assume: ${{ inputs.shoppy-iam-role }}
-        role-session-name: GitHub_to_AWS_via_FederatedOIDC
-        aws-region: us-east-1
-
-    - name: Download Shoppy's App DB PostgreSQL dump from S3
-      if: ${{ steps.check-sample-app-branch.outputs.sample_app_branch_exists == 'true' }}
-      shell: bash
-      run: |
-        aws s3 cp s3://${{ inputs.shoppy-metabase-app-db-s3-bucket }}/${{ inputs.shoppy-metabase-app-db-s3-key }} ./e2e/tmp/db_dumps/shoppy_metabase_app_db_dump.sql
-
     - name: Prepare and launch Shoppy containers
       if: ${{ steps.check-sample-app-branch.outputs.sample_app_branch_exists == 'true' }}
       shell: bash
@@ -115,8 +86,6 @@ runs:
         SAMPLE_APP_ENVIRONMENT: ${{ inputs.sample-app-environment }}
         CYPRESS_MB_ALL_FEATURES_TOKEN: ${{ inputs.staging-mb-all-features-token }}
         METASTORE_DEV_SERVER_URL: ${{ inputs.metastore-dev-server-url }}
-        METABASE_APP_DB_USER: ${{ inputs.shoppy-metabase-app-db-user }}
-        METABASE_APP_DB: ${{ inputs.shoppy-metabase-app-db-database }}
         SHOPPY_DATADOG_APPLICATION_ID: ${{ inputs.shoppy-datadog-application-id }}
         SHOPPY_DATADOG_CLIENT_TOKEN: ${{ inputs.shoppy-datadog-client-token }}
         SHOPPY_DATADOG_SITE: "us5.datadoghq.com"

.github/actions/prepare-uberjar-artifact/action.yml

@@ -1,26 +0,0 @@
-name: Prepare Uberjar Artifact
-description: Prepare and upload Metabase JAR as a GitHub artifact.
-
-inputs:
-  edition:
-    required: false
-    default: "ee"
-    description: Metabase edition (ee or oss)
-
-runs:
-  using: "composite"
-  steps:
-    - name: Mark with the commit hash
-      run: git rev-parse --short HEAD > COMMIT-ID
-      shell: bash
-    - name: Calculate SHA256 checksum
-      run: sha256sum ./target/uberjar/metabase.jar > SHA256.sum
-      shell: bash
-    - name: Upload JARs as artifact
-      uses: actions/upload-artifact@v7
-      with:
-        name: metabase-${{ inputs.edition }}-${{ github.event.pull_request.head.sha || github.sha }}-uberjar
-        path: |
-          ./target/uberjar/metabase.jar
-          ./COMMIT-ID
-          ./SHA256.sum

.github/actions/quarantine-gate/action.yml

@@ -0,0 +1,38 @@
+name: CI Conductor quarantine gate
+description: >-
+  Check this job's test failures against ci-conductor's quarantine list.
+  Either enforces the quarantine or only prints a verdict (dry run).
+  Fails closed when enforcing but the `CI_CONDUCTOR_BASE_URL` is missing or unreachable.
+
+inputs:
+  adapter:
+    description: Which gate to run — one of `backend`, `frontend`, `e2e`.
+    required: true
+  test-suite:
+    description: >-
+      Suite label to gate (CI_CONDUCTOR_TEST_SUITE). MUST match the label this
+      job reports under, or the gate checks the wrong quarantine list.
+    required: true
+  enforce-quarantine:
+    description: >-
+      Whether the gate actually gates the job. When "false", it only prints a verdict.
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - name: Prepare CI Conductor
+      uses: ./.github/actions/prepare-ci-conductor
+    - name: Check failures against the quarantine list
+      shell: bash
+      env:
+        CI_CONDUCTOR_TEST_SUITE: ${{ inputs.test-suite }}
+        ADAPTER: ${{ inputs.adapter }}
+        QUARANTINE_DRY_RUN: ${{ inputs.enforce-quarantine != 'true' }}
+      run: |
+        case "$ADAPTER" in
+          backend|frontend|e2e) ;;
+          *) echo "::error::quarantine-gate: unknown adapter '$ADAPTER' (expected backend|frontend|e2e)"; exit 1 ;;
+        esac
+        bun "release/ci-conductor/src/check-${ADAPTER}-quarantine.ts"

.github/actions/report-failures-to-ci-conductor/action.yml

@@ -0,0 +1,35 @@
+name: Report failures to CI Conductor
+description: >-
+  Report this job's test failures to ci-conductor. Best-effort; no-ops unless
+  CI_CONDUCTOR_BASE_URL is set. Gate it at the call site with continue-on-error
+  and an `if:` on the test step's outcome.
+
+inputs:
+  test-suite:
+    description: Per-job identity label (CI_CONDUCTOR_TEST_SUITE); unique per job/leg.
+    required: true
+  adapter:
+    description: Which reporter to run; resolves to report-<adapter>.ts. backend or frontend.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Prepare CI Conductor
+      uses: ./.github/actions/prepare-ci-conductor
+    - name: Report failed tests to ci-conductor
+      shell: bash
+      env:
+        REPO_ID: ${{ github.event.repository.id }}
+        COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        TARGET_BRANCH: ${{ github.event.pull_request.base.ref || github.ref_name }}
+        CI_CONDUCTOR_TEST_SUITE: ${{ inputs.test-suite }}
+        ADAPTER: ${{ inputs.adapter }}
+        IS_RERUN: ${{ github.run_attempt != '1' }}
+      # Keep the path constrained to known entrypoints.
+      run: |
+        case "$ADAPTER" in
+          backend|frontend) ;;
+          *) echo "::error::Unknown ci-conductor adapter '$ADAPTER'"; exit 1 ;;
+        esac
+        bun "release/ci-conductor/src/report-${ADAPTER}.ts"

.github/actions/sdk-bundle-size-check/action.yml

@@ -1,76 +0,0 @@
-name: Embedding SDK Bundle Size Check
-description: |
-  Downloads the current branch's uberjar and builds the base ref's
-  embedding-sdk.js from source, compares their sizes,
-  and sets output if the size change exceeds the threshold.
-
-inputs:
-  edition:
-    description: 'Metabase edition (ee or oss)'
-    required: true
-  base-ref-commit:
-    description: 'Commit SHA of the base ref (e.g. merge base).'
-    required: true
-  threshold-percent:
-    description: 'Percent threshold for bundle size change'
-    required: true
-
-outputs:
-  status:
-    description: "Bundle size status: increased, decreased, or stable"
-    value: ${{ steps.compare.outputs.status }}
-  size_change_percent:
-    description: "size change percent (positive = increase, negative = decrease)"
-    value: ${{ steps.compare.outputs.size_change_percent }}
-
-runs:
-  using: "composite"
-  steps:
-    - name: Prepare backend
-      uses: ./.github/actions/prepare-backend
-    - name: Prepare frontend
-      uses: ./.github/actions/prepare-frontend
-    - name: Download current uberjar
-      uses: ./.github/actions/fetch-artifact
-      with:
-        commit: ${{ github.event.pull_request.head.sha || github.sha }}
-        edition: ${{ inputs.edition }}
-        extract-path: temp/current-uberjar
-    - name: Extract embedding-sdk bundles from current uberjar
-      shell: bash
-      run: |
-        # Extract preserving the jar's internal paths under resources/ so the
-        # shared measure script sees the same layout as a source build. Both the
-        # new (embedding-sdk/legacy + chunks) and old (embedding-sdk.js) layouts
-        # are pulled; whichever exists is what gets measured.
-        mkdir -p temp/current/resources
-        unzip -o temp/current-uberjar/metabase.jar \
-          "frontend_client/app/embedding-sdk/*" \
-          -d temp/current/resources 2>/dev/null || true
-        unzip -o temp/current-uberjar/metabase.jar \
-          "frontend_client/app/embedding-sdk.js" \
-          -d temp/current/resources 2>/dev/null || true
-    - name: Checkout base ref
-      uses: actions/checkout@v6
-      with:
-        ref: ${{ inputs.base-ref-commit }}
-        path: temp/base-ref-src
-    - name: Build base-ref embedding-sdk.js
-      shell: bash
-      run: |
-        cd temp/base-ref-src
-        bun install
-        MB_EDITION=${{ inputs.edition }} bun run build-release
-    - name: Measure current and base bundle sizes
-      shell: bash
-      env:
-        MEASURE_BUNDLES: embedding-sdk-legacy,embedding-sdk-chunked
-      run: |
-        MEASURE_ROOT=temp/current node ./.github/scripts/measure-bundle-sizes.js > temp/current-sizes.json
-        MEASURE_ROOT=temp/base-ref-src node ./.github/scripts/measure-bundle-sizes.js > temp/base-sizes.json
-    - name: Compare sizes and set output
-      id: compare
-      shell: bash
-      env:
-        THRESHOLD: ${{ inputs.threshold-percent }}
-      run: node ./.github/actions/sdk-bundle-size-check/compare.js temp/current-sizes.json temp/base-sizes.json

.github/actions/sdk-bundle-size-check/compare.js

@@ -1,54 +0,0 @@
-/* eslint-disable import/no-commonjs */
-// Diffs the embedding SDK bundle sizes produced by measure-bundle-sizes.js for
-// the current build and the base ref. The gate is driven by the legacy
-// (monolithic) bundle's raw bytes; the chunked delivery is reported for context.
-const fs = require("fs");
-
-const [, , currentPath, basePath] = process.argv;
-const threshold = Number(process.env.THRESHOLD ?? 2);
-
-const current = JSON.parse(fs.readFileSync(currentPath, "utf8"));
-const base = JSON.parse(fs.readFileSync(basePath, "utf8"));
-
-const pick = (rows, bundle, kind) => rows.find(row => row.bundle === bundle && row.kind === kind);
-
-const setOutput = (name, value) => {
-  if (process.env.GITHUB_OUTPUT) {
-    fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${value}\n`);
-  }
-};
-
-const mb = bytes => (bytes / 1024 / 1024).toFixed(2);
-
-const legacyCurrent = pick(current, "embedding-sdk-legacy", "total");
-const legacyBase = pick(base, "embedding-sdk-legacy", "total");
-
-if (!legacyCurrent || !legacyBase || !legacyBase.rawBytes) {
-  console.error("::error::Could not find embedding-sdk-legacy size in both builds");
-  process.exit(1);
-}
-
-const diff = legacyCurrent.rawBytes - legacyBase.rawBytes;
-const percent = Math.trunc((diff * 100) / legacyBase.rawBytes);
-
-const status = percent > threshold ? "increased" : percent < -threshold ? "decreased" : "stable";
-
-console.log("=== Embedding SDK legacy (monolithic) bundle ===");
-console.log(`Current:  ${legacyCurrent.rawBytes} bytes raw / ${mb(legacyCurrent.gzipBytes)}MB gzip`);
-console.log(`Base ref: ${legacyBase.rawBytes} bytes raw / ${mb(legacyBase.gzipBytes)}MB gzip`);
-console.log(`Difference: ${diff} bytes (${percent}%), threshold ${threshold}%`);
-console.log(`Status: ${status}`);
-
-const chunkedCurrent = pick(current, "embedding-sdk-chunked", "total");
-const chunkedBase = pick(base, "embedding-sdk-chunked", "total");
-if (chunkedCurrent && chunkedBase) {
-  const chunkedDiff = chunkedCurrent.rawBytes - chunkedBase.rawBytes;
-  console.log("");
-  console.log("=== Embedding SDK chunked (informational) ===");
-  console.log(`Current:  ${chunkedCurrent.rawBytes} bytes raw / ${mb(chunkedCurrent.gzipBytes)}MB gzip`);
-  console.log(`Base ref: ${chunkedBase.rawBytes} bytes raw / ${mb(chunkedBase.gzipBytes)}MB gzip`);
-  console.log(`Difference: ${chunkedDiff} bytes`);
-}
-
-setOutput("status", status);
-setOutput("size_change_percent", percent);

.github/actions/test-driver/action.yml

@@ -9,13 +9,48 @@ inputs:
   build-static-viz:
     required: true
     default: false
-  logs-artifact-suffix:
+  artifact-suffix:
     required: false
-    description: Suffix to append to the test logs artifact name to avoid conflicts in matrix jobs
+    description: >-
+      Discriminator appended to this job's artifact names (test logs, granular-rerun failed
+      tests). A job whose matrix runs several concurrent legs MUST set a per-leg-unique value,
+      or the legs collide on one artifact — for the rerun artifact that means a leg restores
+      another leg's failed set. Must be stable across attempts of the same job.
   edition:
     required: false
-    default: 'ee'
+    default: "ee"
     description: Edition to test (oss or ee)
+  runner-index:
+    required: false
+    description: >-
+      The index of this runner among those sharing a partitioned suite. See
+      `be-tests-bigquery-cloud-sdk-ee` in `.github/workflows/drivers.yml` for an example.
+  runner-count:
+    required: false
+    description: >-
+      How many runners share the suite. Recommended to set to `strategy.job-total` rather
+      than a literal so that it doesn't need updating if the `runner-index` matrix changes.
+  jvms-per-runner:
+    required: false
+    default: "1"
+    description: >-
+      Concurrent JVMs per runner. Recommended to raise above 1 for drivers whose tests
+      spend a lot of time waiting on a remote warehouse.
+  heap-per-jvm:
+    required: false
+    default: "4g"
+    description: >-
+      `-Xmx` per JVM, applied only when `jvms-per-runner` is more than 1 (otherwise the
+      the `:ci` alias's `-Xmx12g` is used). To size it: reserve ~1G for the OS and ~2G
+      of non-heap per JVM, then divide what's left. On a 16G runner that's ~4G each for
+      two JVMs.
+  granular-rerun:
+    required: false
+    default: "true"
+    description: >-
+      When "true" (default), a re-run of a failed job runs only the tests that failed on the
+      previous attempt (hawk `:only`). Stress workflows set this to "false": they intentionally
+      run a fixed test set `:times N`, and narrowing to failures would drop that repetition.
 
 outputs:
   test-outcome:
@@ -27,6 +62,10 @@ runs:
   steps:
     - name: Prepare back-end environment
       uses: ./.github/actions/prepare-backend
+    - name: Resolve current job id
+      # Resolve JOB_ID early (before the long test step) so the ci-conductor
+      # reporter below can link failures to this exact job. Best-effort.
+      uses: ./.github/actions/resolve-job-id
     - name: Prepare front-end environment
       if: ${{ inputs.build-static-viz == 'true' }}
       uses: ./.github/actions/prepare-frontend
@@ -35,15 +74,129 @@ runs:
       run: bun run build-static-viz
       shell: bash
       env:
-        MB_EDITION: ee
+        MB_EDITION: ${{ inputs.edition }}
+
+    # Granular rerun: on a re-run of a failed job, restore the list
+    # of tests that failed on the previous attempt (uploaded below) so the test
+    # step can target only those instead of the whole suite. Best-effort: a
+    # missing/empty artifact leaves no file and the run falls back to the full
+    # suite. First attempts skip this entirely.
+    #
+    # Scoped to the IMMEDIATELY preceding attempt: an attempt that passed, or
+    # that failed with nothing attributable to a var, uploads no artifact, and a
+    # narrow set must not outlive it. Reading `attempt - 1` means "only what the
+    # last attempt actually recorded" — anything else falls back to the full suite.
+    # Workflow expressions have no arithmetic, so the shell computes it.
+    #
+    # run-tests.yml calls app-db.yml, backend.yml, drivers.yml and semantic-search.yml
+    # as part of ONE run, so all four share an artifact namespace. `junit-name` alone is not
+    # unique there — app-db.yml and drivers.yml both derive `be-tests-postgres-ee` — so
+    # `artifact-suffix` carries the rest of the discriminator.
+    - name: Resolve rerun artifact names
+      if: ${{ inputs.granular-rerun == 'true' }}
+      shell: bash
+      env:
+        RERUN_ARTIFACT_BASE: ${{ format('failed-tests-{0}{1}', inputs.junit-name, inputs.artifact-suffix && format('-{0}', inputs.artifact-suffix) || '') }}
+      run: |
+        echo "RERUN_ARTIFACT=$RERUN_ARTIFACT_BASE-attempt-$GITHUB_RUN_ATTEMPT" >> "$GITHUB_ENV"
+        echo "RERUN_PREV_ARTIFACT=$RERUN_ARTIFACT_BASE-attempt-$((GITHUB_RUN_ATTEMPT - 1))" >> "$GITHUB_ENV"
+
+    # `pattern` (not `name`) because the artifact is legitimately absent whenever the
+    # previous attempt recorded nothing: `name` treats that as an error, `pattern`
+    # downloads nothing and moves on. The value is a literal — no glob metacharacters —
+    # so it matches exactly one artifact, which lands at `target/failed-tests`. A pattern
+    # that ever matched two would nest them under their artifact names instead, leaving
+    # the file absent and falling back to the full suite.
+    - name: Restore previously-failed tests
+      if: ${{ inputs.granular-rerun == 'true' && github.run_attempt != '1' }}
+      continue-on-error: true
+      uses: actions/download-artifact@v8
+      with:
+        pattern: ${{ env.RERUN_PREV_ARTIFACT }}
+        path: target
+
     - name: Test database driver
-      run: clojure -X:dev:ci:${{ inputs.edition }}:${{ inputs.edition }}-dev:drivers:drivers-dev:test ${{ inputs.test-args }}
+      # On a rerun with a non-empty failed-tests file, target only those vars via
+      # hawk `:only` (a var-level selector bypasses `:only-tags`, which is fine —
+      # every listed var already passed that filter on the first attempt).
+      # Otherwise run exactly as before. Quote the file so the whole `[ns/var ...]`
+      # vector reaches clojure -X as a single argument.
+      run: |
+        ALIASES="dev:ci:${{ inputs.edition }}:${{ inputs.edition }}-dev:drivers:drivers-dev:test"
+        BASE="clojure -X:dev:ci:${{ inputs.edition }}:${{ inputs.edition }}-dev:drivers:drivers-dev:test"
+        # `:profile-tests` overrides `:test`'s exec-fn, so it has to come last. See dev.profile-tests.
+        # The `profiled` output is what the collection steps below key off, so that the decision is
+        # recorded by the step that acts on it rather than re-derived from the environment.
+        if [ "$PROFILE_TESTS" = "true" ]; then
+          echo "Profiling this run; a flamegraph will be attached to the job."
+          echo "profiled=true" >> "$GITHUB_OUTPUT"
+          BASE="$BASE:profile-tests"
+        fi
+        # An explicit selection wins over the rerun narrowing below: it was asked for by hand, on this
+        # attempt. Names may be separated by commas or spaces; hawk wants them as one vector argument.
+        if [ -n "$ONLY_TESTS" ]; then
+          ONLY="[$(echo "$ONLY_TESTS" | tr ',' ' ')]"
+          echo "Running only: $ONLY"
+          $BASE :only "$ONLY"
+        elif [ "${{ inputs.granular-rerun }}" = "true" ] && [ "${{ github.run_attempt }}" != "1" ] && [ -s target/failed-tests ]; then
+          echo "Granular rerun of previously-failed tests: $(cat target/failed-tests)"
+          clojure -X:"$ALIASES" :only "$(cat target/failed-tests)"
+        elif [ -n "$TEST_RUNNER_INDEX" ]; then
+          CLOJURE_ALIASES="$ALIASES" ./.github/scripts/run-backend-test-jvms.sh ${{ inputs.test-args }}
+        else
+          clojure -X:"$ALIASES" ${{ inputs.test-args }}
+        fi
       shell: bash
       id: run-test
-      # Trunk Quarantine controls the final state of the run in the CI!
-      # Even if this step fails we let it pass, and then `trunk-io/analytics-uploader` determines
-      # whether to fail or to pass the whole job, based on the quarantine list.
+      env:
+        TEST_RUNNER_INDEX: ${{ inputs.runner-index }}
+        TEST_RUNNER_COUNT: ${{ inputs.runner-count }}
+        TEST_JVMS_PER_RUNNER: ${{ inputs.jvms-per-runner }}
+        TEST_HEAP_PER_JVM: ${{ inputs.heap-per-jvm }}
+      # Keep this step continue-on-error because the quarantine gate below controls whether it
+      # ultimately fails.
       continue-on-error: true
+
+    - name: Collect profile
+      if: ${{ !cancelled() }}
+      uses: ./.github/actions/collect-profile
+      with:
+        profiled: ${{ steps.run-test.outputs.profiled }}
+        artifact-name: ${{ format('profile-{0}{1}', inputs.junit-name, inputs.artifact-suffix && format('-{0}', inputs.artifact-suffix) || '') }}
+
+    - name: Report failed tests to ci-conductor
+      if: ${{ !cancelled() && ( steps.run-test.outcome == 'failure' || github.run_attempt != '1' ) }}
+      # This step should NEVER fail the job!
+      continue-on-error: true
+      uses: ./.github/actions/report-failures-to-ci-conductor
+      with:
+        test-suite: ${{ inputs.junit-name }}
+        adapter: backend
+
+    # Granular rerun: record which tests failed so a re-run of this
+    # job targets only those (restored above). Reuses the backend JUnit adapter
+    # from the ci-conductor sources the report step just prepared. Best-effort:
+    # writes nothing unless every failure is attributable to a var, so an
+    # unattributable failure falls back to a full rerun.
+    - name: Collect failed tests for rerun
+      if: ${{ inputs.granular-rerun == 'true' && !cancelled() && steps.run-test.outcome == 'failure' }}
+      continue-on-error: true
+      shell: bash
+      # Clear the restored set first, so a collector that dies before deciding
+      # can't leave the previous attempt's file to be uploaded as this one's.
+      run: |
+        rm -f target/failed-tests
+        bun release/ci-conductor/src/collect-failed-backend.ts
+
+    - name: Upload failed tests for rerun
+      if: ${{ inputs.granular-rerun == 'true' && !cancelled() && steps.run-test.outcome == 'failure' }}
+      continue-on-error: true
+      uses: actions/upload-artifact@v7
+      with:
+        name: ${{ env.RERUN_ARTIFACT }}
+        path: target/failed-tests
+        if-no-files-found: ignore
+
     - name: Publish Test Report (JUnit)
       uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
       # As per the documentation: https://docs.github.com/en/actions/reference/workflows-and-actions/contexts#steps-context
@@ -57,12 +210,25 @@ runs:
         list-suites: failed
         list-tests: failed
         fail-on-error: false
+
     - name: Upload Logs on Failure
       if: always() && steps.run-test.outcome != 'success'
       uses: actions/upload-artifact@v7
       with:
-        name: ${{ format('test-logs-{0}{1}', github.job, inputs.logs-artifact-suffix && format('-{0}', inputs.logs-artifact-suffix) || '') }}
-        path: logs/test-log.json
+        name: ${{ format('test-logs-{0}{1}', github.job, inputs.artifact-suffix && format('-{0}', inputs.artifact-suffix) || '') }}
+        # Glob: a single-JVM run writes `logs/test-log.json`; a multi-JVM run merges one
+        # `logs/test-log-p<index>.json` per JVM.
+        path: logs/test-log*.json
         retention-days: 1
       # Failing to upload the artifact should never affect the outcome of the whole test run.
       continue-on-error: true
+
+    # Last, because this is the only step allowed to fail the job: everything above it reports the
+    # failure (JUnit report, logs, ci-conductor) and must run regardless of the verdict below.
+    - name: Quarantine gate
+      if: ${{ !cancelled() && steps.run-test.outcome == 'failure' }}
+      uses: ./.github/actions/quarantine-gate
+      with:
+        adapter: backend
+        test-suite: ${{ inputs.junit-name }}
+        enforce-quarantine: "true"

.github/actions/update-cache/action.yml

@@ -1,41 +0,0 @@
-name: Update cache
-description: |
-  Update a GitHub Actions cache based on a provided path and key.
-  If a cache entry already exists for the given key, it is first removed.
-  This ensures immutability of cache entries, and prevents runtime errors.
-
-inputs:
-  path:
-    description: "The path(s) to cache, separated by newlines."
-    required: true
-  key:
-    description: "The cache key to use."
-    required: true
-
-runs:
-  using: "composite"
-  steps:
-    - name: Check if the cache entry exists
-      id: cache-lookup
-      uses: actions/cache/restore@v5
-      with:
-        path: ${{ inputs.path }}
-        key: ${{ inputs.key }}
-        lookup-only: true # Important bit: the action will not fetch anything, just check for the cache existence.
-    - name: Delete the cache entry if it exists
-      if: ${{ steps.cache-lookup.outputs.cache-hit == 'true' }}
-      run: |
-        echo "Cache entry found for key '${{ inputs.key }}'. Deleting it to ensure immutability."
-        gh api \
-          --method DELETE \
-          -H "Accept: application/vnd.github+json" \
-          -H "X-GitHub-Api-Version: 2022-11-28" \
-          /repos/${{ github.repository }}/actions/caches?key=${{ inputs.key }}
-      env:
-        GH_TOKEN: ${{ github.token }}
-      shell: bash
-    - name: Save the new cache entry
-      uses: actions/cache/save@v5
-      with:
-        path: ${{ inputs.path }}
-        key: ${{ inputs.key }}

.github/actions/upgrade-backend-deps/action.yml

@@ -1,4 +1,5 @@
 name: Create Backend Dep Bump PRs
+description: Opens a pull request for each backend dependency that has a newer version available.
 
 inputs:
   github-token:

.github/actions/upload-test-results/action.yml

@@ -1,182 +0,0 @@
-name: Upload Test Results to s3
-description: Uploads test results files to s3
-
-inputs:
-  input-path:
-    required: true
-  output-name:
-    required: true
-    default: test
-  role-to-assume:
-    required: true
-  aws-region:
-    required: true
-    default: us-east-1
-  bucket:
-    required: true
-  trunk-api-token:
-    required: true
-  variant:
-    required: false
-    default: ""
-  previous-step-outcome:
-    required: true
-  driver-status:
-    required: false
-    default: ""
-    description: >-
-      Configured status for this driver ("info", "skip", "required", or empty). When
-      "info", the job is reported as passing regardless of the real test outcome, and
-      that outcome is surfaced via a job summary and (on PRs) a comment instead.
-  report-variant:
-    required: false
-    default: ""
-    description: >-
-      Optional label disambiguating matrix legs of the same job, so the info-driver
-      job summary and PR comment stay distinct per leg.
-
-runs:
-  using: "composite"
-  steps:
-    - name: Configure AWS credentials
-      uses: aws-actions/configure-aws-credentials@d979d5b3a71173a29b74b5b88418bfda9437d885
-      with:
-        role-to-assume: ${{ inputs.role-to-assume }}
-        aws-region: ${{ inputs.aws-region }}
-    - name: zip test results
-      env:
-        INPUT_DIR: ${{ inputs.input-path }}
-        OUTPUT_FILE: ${{ inputs.output-name }}
-      shell: bash
-      run: | # sh
-        zip ${OUTPUT_FILE}.zip $INPUT_DIR/*.xml
-    - name: Upload test results to S3
-      env:
-        BUCKET: ${{ inputs.bucket }}
-        OUTPUT_FILE: ${{ inputs.output-name }}
-      shell: bash
-      run: | # sh
-        DATE=$(date '+%Y-%m-%d')
-        aws s3 cp ${OUTPUT_FILE}.zip s3://$BUCKET/$DATE/$GITHUB_RUN_ID/$GITHUB_RUN_ATTEMPT/
-
-    - name: Upload results to Trunk
-      # Important!
-      # 1. This step must always run because it controls job's exit code.
-      # 2. There's no point in running this outside the organization
-      # 3. For "info" drivers our own status takes precedence: we let this step pass so
-      #    the job is reported as passing regardless of the real outcome (still uploaded).
-      if: always() && github.repository_owner == 'metabase'
-      continue-on-error: ${{ inputs.driver-status == 'info' }}
-      uses: trunk-io/analytics-uploader@1198efcc0976501147b10a7e343c3fa069527526 # v2.0.9
-      env:
-        TRUNK_REPO_URL: git@github.com:metabase/metabase.git
-      with:
-        junit-paths: ${{ inputs.input-path }}
-        variant: ${{ inputs.variant || inputs.output-name }}
-        org-slug: metabase
-        dry-run: ${{ (github.event_name == 'pull_request' && github.event.pull_request.draft == true) || github.repository != 'metabase/metabase' }} # quarantine, but do not upload results
-        token: ${{ inputs.trunk-api-token }}
-        use-cache: true
-        previous-step-outcome: ${{ inputs.previous-step-outcome }}
-
-    # For "info" drivers the job is forced green above, so surface the real outcome here —
-    # but only when it did NOT pass, to avoid spamming summaries/comments for healthy runs.
-    # Never include logs or stack traces — only the real status and a link to the run.
-    - name: Report info-level driver result (job summary)
-      if: ${{ always() && inputs.driver-status == 'info' && inputs.previous-step-outcome == 'failure' }}
-      shell: bash
-      env:
-        OUTCOME: ${{ inputs.previous-step-outcome }}
-        LABEL: ${{ inputs.output-name }}
-        VARIANT: ${{ inputs.report-variant }}
-      run: | # sh
-        if [ "$OUTCOME" = "success" ]; then EMOJI="✅"; else EMOJI="❌"; fi
-        TITLE="$LABEL"
-        [ -n "$VARIANT" ] && TITLE="$LABEL ($VARIANT)"
-        RUN_URL="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
-        {
-          echo "### ℹ️ Info-level driver: $TITLE"
-          echo ""
-          echo "Reported as passing (non-blocking). Real result: $EMOJI \`$OUTCOME\`"
-          echo ""
-          echo "[View run]($RUN_URL)"
-        } >> "$GITHUB_STEP_SUMMARY"
-
-    # Maintain ONE PR comment per commit for all info drivers. Each leg upserts its own line
-    # (keyed by a hidden tag); a passing leg removes its line, and the comment is deleted once
-    # no failing legs remain. Comments from older commits are cleaned up. Runs on pass and fail
-    # so recoveries self-heal. Never includes logs or stack traces — only status and a run link.
-    - name: Sync info-level driver result into the PR comment
-      if: ${{ always() && inputs.driver-status == 'info' && github.event_name == 'pull_request' }}
-      uses: actions/github-script@v9
-      continue-on-error: true
-      env:
-        OUTCOME: ${{ inputs.previous-step-outcome }}
-        LABEL: ${{ inputs.output-name }}
-        VARIANT: ${{ inputs.report-variant }}
-      with:
-        script: | # js
-          const { OUTCOME, LABEL, VARIANT, GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID } = process.env;
-          const pr = context.payload.pull_request;
-          if (!pr) return;
-          const { owner, repo } = context.repo;
-          const sha = pr.head.sha;
-          // PREFIX matches the current per-commit marker AND the older per-leg one, so legacy
-          // comments from a previous version get cleaned up on the next sync.
-          const PREFIX = "<!-- info-driver-result";
-          const marker = `<!-- info-driver-results:${sha} -->`;
-          const header = `${marker}\nℹ️ **Info-level drivers** failed (non-blocking) on \`${sha.slice(0, 7)}\` — these do not gate:`;
-          const lineKey = `${LABEL}:${VARIANT}`;
-          const title = VARIANT ? `${LABEL} (${VARIANT})` : LABEL;
-          const runUrl = `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}`;
-          // Only real failures are reported; cancelled/skipped/success remove this leg's line.
-          // List-item line with the hidden key tag at the END so markdown (links) renders.
-          const ourLine = OUTCOME === "failure"
-            ? `- **${title}** — ❌ \`${OUTCOME}\` ([Logs](${runUrl})) <!--l:${lineKey}-->`
-            : null;
-          const linesOf = (body) => body.split("\n").filter((l) => l.includes("<!--l:"));
-
-          const sync = async () => {
-            const { data: comments } = await github.rest.issues.listComments({
-              owner, repo, issue_number: pr.number, per_page: 100,
-            });
-            const tagged = comments.filter((c) => c.body.includes(PREFIX));
-            // Drop comments left over from older commits.
-            for (const c of tagged.filter((c) => !c.body.includes(marker))) {
-              await github.rest.issues.deleteComment({ owner, repo, comment_id: c.id }).catch(() => {});
-            }
-            const mine = tagged
-              .filter((c) => c.body.includes(marker))
-              .sort((a, b) => new Date(a.created_at) - new Date(b.created_at));
-            // Merge any duplicates raced into existence; latest write of each line wins.
-            const byKey = new Map();
-            for (const c of mine) {
-              for (const l of linesOf(c.body)) {
-                const m = l.match(/<!--l:(.*?)-->/);
-                if (m) byKey.set(m[1], l);
-              }
-            }
-            if (ourLine) byKey.set(lineKey, ourLine);
-            else byKey.delete(lineKey);
-            const lines = [...byKey.values()].sort();
-            const target = mine[0];
-            for (const c of mine.slice(1)) {
-              await github.rest.issues.deleteComment({ owner, repo, comment_id: c.id }).catch(() => {});
-            }
-            if (lines.length === 0) {
-              if (target) await github.rest.issues.deleteComment({ owner, repo, comment_id: target.id }).catch(() => {});
-              return;
-            }
-            const body = [header, "", ...lines].join("\n");
-            if (target) {
-              await github.rest.issues.updateComment({ owner, repo, comment_id: target.id, body });
-            } else {
-              await github.rest.issues.createComment({ owner, repo, issue_number: pr.number, body });
-            }
-          };
-
-          // Retry to shrink the window where parallel legs clobber each other's update.
-          for (let i = 0; i < 4; i++) {
-            try { await sync(); break; }
-            catch (e) { if (i === 3) throw e; await new Promise((r) => setTimeout(r, 400 * (i + 1))); }
-          }

.github/actions/verify-membership/action.yml

@@ -1,22 +0,0 @@
-name: 'Verify Organization Membership'
-description: 'Check if a user is a member of a GitHub organization'
-inputs:
-  github_token:
-    description: 'Token with access to the organization'
-    required: true
-  organization_name:
-    description: 'Organization name'
-    required: true
-  username:
-    description: 'Username'
-    required: true
-outputs:
-  is_member:
-    value: ${{ steps.verify-membership.outputs.is_member }}
-    description: "Is the user a member of the organization"
-runs:
-  using: "composite"
-  steps:
-    - run: bash ${{ github.action_path }}/verify_membership.sh ${{ inputs.github_token }} ${{ inputs.organization_name }} ${{ inputs.username }}
-      id: verify-membership
-      shell: bash

.github/actions/verify-membership/verify_membership.sh

@@ -1,25 +0,0 @@
-#!/bin/bash
-
-TOKEN=$1
-ORG_NAME=$2
-USERNAME=$3
-
-response=$(curl -L -o /dev/null -w "%{http_code}" \
-  -H "Accept: application/vnd.github+json" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "X-GitHub-Api-Version: 2022-11-28" \
-  "https://api.github.com/orgs/$ORG_NAME/members/$USERNAME")
-
-# Github returns an empty response with 204 status if user is a member and 404 status otherwise
-# See: https://docs.github.com/en/rest/orgs/members?apiVersion=2022-11-28#check-organization-membership-for-a-user
-if [ "$response" == "204" ]; then
-    echo "The user $USERNAME is a member of $ORG_NAME"
-    echo "is_member=true" >> $GITHUB_OUTPUT
-elif [ "$response" == "404" ]; then
-    echo "The user $USERNAME is not a member of $ORG_NAME"
-    echo "is_member=false" >> $GITHUB_OUTPUT
-else
-    echo "Failed to determine the membership status for $USERNAME in $ORG_NAME"
-    echo "is_member=false" >> $GITHUB_OUTPUT
-    exit 1
-fi

.github/file-paths.yaml

@@ -7,6 +7,9 @@ default: &default
   - "locales/**"
   - "bin/**/!(*.md)"
 
+workflows:
+  - added|modified: ".github/workflows/*.{yml,yaml}"
+
 shared_sources: &shared_sources
   - "src/**/*.cljc"
   - "src/**/*.cljs"
@@ -50,11 +53,6 @@ frontend_sources: &frontend_sources
   - "enterprise/frontend/!(test)**/**/{!(*.spec),}.{js,jsx,ts,tsx,css}"
   - "frontend/!(test)**/**/{!(*.spec),}.{js,jsx,ts,tsx,css}"
 
-# Used only in .github/workflows/conventional-commit-pr-title-reminder.yml
-frontend_embedding_sources:
-  - "enterprise/frontend/src/{embedding,embedding-*}/**/{!(*.spec),}.{js,jsx,ts,tsx,css}"
-  - "enterprise/frontend/src/metabase-enterprise/{embedding,embedding-*}**/{!(*.spec),}.{js,jsx,ts,tsx,css}"
-
 # Used only in .github/workflows/embedding-sdk-labels-reminder.yml
 frontend_embedding_sdk_package_sources:
   - "enterprise/frontend/src/embedding-sdk-package/**/!(*.spec).{js,jsx,ts,tsx,css}"
@@ -66,6 +64,9 @@ frontend_specs: &frontend_specs
   - "frontend/**/*.unit.*"
   - "enterprise/frontend/**/*.unit.*"
   - ".github/**/*.unit.spec.*"
+  # file-paths.unit.spec.ts asserts what this file's own patterns match, so a change to it has to
+  # run the specs that guard it.
+  - ".github/file-paths.yaml"
   - "jest.config.js"
   - "jest.tz.unit.conf.json"
 
@@ -95,19 +96,18 @@ frontend_loki_infra: &frontend_loki_infra
   - *shared_ci
   - *frontend_loki_ci
 
+# e2e harness/support code (commands, support file, runner). Not in the
+# instrumented bundle, so it maps to no covered module — a change here forces a
+# full e2e run (see create-test-plan / e2eInfraTouched).
+e2e_infra: &e2e_infra
+  - *shared_e2e
+
 backend_ci: &backend_ci
   - *shared_ci
   - ".github/actions/test-driver/**"
   - ".github/workflows/backend.yml"
   - ".github/workflows/drivers.yml"
 
-backend_presto_kerberos:
-  - "**/presto_jdbc/**"
-  - "**/presto-jdbc/**" # the driver module has a hyphen. underscores are classpaths
-  - "**/presto_jdbc.clj"
-  - "**/presto_jdbc_test.clj"
-  - ".github/workflows/presto-kerberos-integration-test.yml"
-
 backend_sources: &backend_sources
   - *shared_sources
   - "**deps.edn"
@@ -115,11 +115,15 @@ backend_sources: &backend_sources
   - "src/**"
   - "modules/drivers/{*,*/{*,!(test)/**}}"
   - "resources/**"
-  - ".clj-kondo/**"
+  # Ratchet files drive project_ratchet_checks alone, so automation PRs that lower budgets
+  # run the Project tests job by themselves. Patterns are OR-ed, so a separate "!..." entry would match
+  # every other path instead of excluding this one.
+  - ".clj-kondo/**/!(ratchets.edn)"
 
 backend_specs: &backend_specs
   - *shared_specs
   - "test/**"
+  - "dev/test/**"
   - "enterprise/backend/test/**"
   - "test_modules/**"
   - "modules/drivers/*/test/**"
@@ -132,6 +136,48 @@ backend_all: &backend_all
   - *backend_sources
   - *backend_specs
 
+# Project checks have narrower triggers than the backend matrix.
+# Changes to their shared CI entry points exercise every suite; otherwise each
+# suite follows only the files that can affect its result.
+project_tests_infra: &project_tests_infra
+  - ".github/actions/prepare-backend/**"
+  - ".github/file-paths.yaml"
+  - ".github/workflows/backend.yml"
+  - ".github/workflows/run-tests.yml"
+  - "bb.edn"
+  - "bin/mage"
+  - "bin/mage.bb"
+  - "mage/src/mage/color.clj"
+  - "mage/src/mage/project_tests.clj"
+  - "mage/src/mage/shell.clj"
+  - "mage/src/mage/util.clj"
+
+project_backend_checks:
+  - *project_tests_infra
+  - "{src,test,enterprise,dev,bin,mage}/**/*.{clj,cljc,cljs}"
+  - "modules/**/*.clj"
+  - "modules/**/*.cljc"
+  - "modules/**/*.cljs"
+  - "**deps.edn"
+  - ".clj-kondo/{src,test}/**/*.{clj,cljc,cljs}"
+  - "{resources,test_resources,test_config}/**/*.{clj,cljc,cljs}"
+  - ".clj-kondo/config.edn"
+  - ".clj-kondo/config/modules/config.edn"
+  - ".github/team.json"
+  - "dev/resources/dev/modules_config_test/**"
+
+# Only the ratchet check reads the budgets, so a diff that touches nothing else runs that suite alone.
+project_ratchet_checks:
+  - ".clj-kondo/ratchets.edn"
+  - ".clj-kondo/config/modules/ratchets.edn"
+
+project_migration_checks:
+  - *project_tests_infra
+  - "bin/lint-migrations-file/**"
+  - "resources/migrations/**/*.{yaml,yml}"
+  - "src/metabase/app_db/custom_migrations.clj"
+  - "src/metabase/app_db/custom_migrations/**"
+
 sources: &sources
   - *shared_sources
   - *frontend_sources
@@ -145,7 +191,7 @@ custom_viz_all:
 
 e2e_ci: &e2e_ci
   - *shared_ci
-  - ".github/actions/prepare-uberjar-artifact/**"
+  - ".github/workflows/uberjar.yml"
   - ".github/actions/fetch-artifact/action.yml"
   - ".github/actions/e2e-prepare-containers/**"
   - ".github/actions/prepare-cypress/**"
@@ -156,7 +202,7 @@ e2e_specs: &e2e_specs
 
 embedding_sdk_ci: &embedding_sdk_ci
   - *shared_ci
-  - ".github/actions/prepare-uberjar-artifact/**"
+  - ".github/workflows/uberjar.yml"
   - ".github/actions/fetch-artifact/action.yml"
   - ".github/actions/prepare-cypress/**"
   - ".github/workflows/embedding-sdk*.yml"
@@ -178,7 +224,7 @@ embedding_sdk_host_sample_apps:
   - "e2e/test-host-app/**/*.cy.*.{js,ts}"
 
 snowplow: &snowplow
-  - ".github/workflows/snowplow.yml"
+  - ".github/workflows/lint.yml"
   - "snowplow/**"
   - "bin/lint-snowplow-schemas.bb"
   - "bin/lint-snowplow-schemas-test.bb"
@@ -207,7 +253,7 @@ yaml:
   - "**/*.yaml"
 
 codeql:
-  - ".github/workflows/codeql.yml"
+  - ".github/workflows/lint.yml"
   - "frontend/src/**"
   - "enterprise/frontend/src/**"
 
@@ -215,26 +261,43 @@ i18n:
   - *default
   - ".github/actions/prepare-frontend/**"
   - ".github/actions/prepare-backend/**"
-  - ".github/workflows/i18n.yml"
+  - ".github/workflows/lint.yml"
   - *sources
 
-visualizations:
-  - "frontend/src/metabase/visualizations/**"
-  - "frontend/src/metabase/static-viz/**"
-  - "src/metabase/pulse/**"
-
 cljs:
   - *shared_sources
   - *shared_specs
   - ".github/workflows/cljs.yml"
   - "shadow-cljs.edn"
 
+embedder_plugin:
+  - ".github/actions/prepare-backend/**"
+  - ".github/file-paths.yaml"
+  - ".github/workflows/build-scripts.yml"
+  - "bin/build-embedder-plugin.sh"
+  - "bin/build/src/build/embedder_model.clj"
+  - "bin/build/src/build/plugin_uberjar.clj"
+  - "bin/build/src/build_embedder_plugin.clj"
+  - "deps.edn"
+  - "modules/embedder/**"
+  - "enterprise/backend/src/metabase_enterprise/data_complexity_score/complexity_embedders.clj"
+  - "enterprise/backend/src/metabase_enterprise/data_complexity_score/settings.clj"
+  - "enterprise/backend/src/metabase_enterprise/data_complexity_score/synonym_source.clj"
+  - "enterprise/backend/src/metabase_enterprise/semantic_search/embedding.clj"
+  - "enterprise/backend/src/metabase_enterprise/semantic_search/settings.clj"
+  - "enterprise/backend/test/metabase_enterprise/semantic_search/appdb_pgvector_mode_test.clj"
+  - "enterprise/backend/test/metabase_enterprise/semantic_search/embedding_test.clj"
+  - "src/metabase/embeddings/provider.clj"
+  - "src/metabase/embeddings/startup.clj"
+  - "src/metabase/plugins/**"
+  - "test/metabase/embeddings/embedder_plugin_artifact_test.clj"
+
 serialization_baseline:
   - ".github/workflows/serialization.yml"
   - "test_resources/serialization_baseline/**"
 
 openapi:
-  - ".github/workflows/openapi.yml"
+  - ".github/workflows/lint.yml"
   - "src/metabase/api/**"
   - "src/metabase/api_routes/**"
   - "src/metabase/*_rest/api.clj"

.github/instructions/e2e.instructions.md

@@ -0,0 +1,12 @@
+---
+applyTo: "e2e/**/*.cy.spec.{js,ts}"
+---
+
+# Cypress E2E Spec Review
+
+When reviewing Cypress E2E specs, apply the guidelines in these files:
+
+- `.claude/skills/_shared/cypress-conventions.md`
+- `.claude/skills/e2e-test-review/SKILL.md`
+
+These are in addition to the TypeScript/JavaScript instructions, which also match these files.

.github/scripts/affected-modules.ts

@@ -1,32 +1,196 @@
-export type ModuleDef = { type: string; pattern: string };
-export type Rule = { from: string[]; allow: string[] };
+import micromatch from "micromatch";
 
-type ModuleNode = { type: string; regex: RegExp };
+export type ModuleDef = { type: string; pattern: string };
+
+export type Rule = {
+  from: string[];
+  allow?: string[];
+  disallow?: string[];
+};
+
+export type ModuleNode = { type: string; regex: RegExp };
+
+export type FileDependency = { source: string; dependencies: string[] };
+
+/** First match wins, so element order matters for nested patterns. */
+export function buildNodes(elements: ModuleDef[]): ModuleNode[] {
+  return elements.map((el) => ({
+    type: el.type,
+    // dot:true so files in dot-directories (e.g. .storybook) still match.
+    regex: micromatch.makeRe(el.pattern, { dot: true }),
+  }));
+}
+
+export function mapFileToModule(
+  nodes: ModuleNode[],
+  path: string,
+): string | null {
+  for (const node of nodes) {
+    if (node.regex.test(path)) {
+      return node.type;
+    }
+  }
+  return null;
+}
+
+export function getChangedModules(
+  nodes: ModuleNode[],
+  changedFiles: string[],
+): Set<string> {
+  const direct = new Set<string>();
+  for (const file of changedFiles) {
+    const module = mapFileToModule(nodes, file);
+    if (module) {
+      direct.add(module);
+    }
+  }
+  return direct;
+}
+
+export type FileGraph = {
+  nodes: ModuleNode[];
+  fileDependents: Map<string, Set<string>>;
+};
+
+/** Drops unresolvable imports (e.g. ambient types) that point at no real file. */
+export function parseCruiseModules(
+  modules: Array<{
+    source: string;
+    dependencies?: Array<{ resolved: string; couldNotResolve?: boolean }>;
+  }>,
+): FileDependency[] {
+  return modules.map((module) => ({
+    source: module.source,
+    dependencies: (module.dependencies ?? [])
+      .filter((dep) => !dep.couldNotResolve)
+      .map((dep) => dep.resolved),
+  }));
+}
+
+/** Inverts the import edges into the `fileDependents` reverse graph. */
+export function buildFileGraph(
+  elements: ModuleDef[],
+  fileDependencies: FileDependency[],
+): FileGraph {
+  const fileDependents = new Map<string, Set<string>>();
+  for (const { source, dependencies } of fileDependencies) {
+    for (const target of dependencies) {
+      let importers = fileDependents.get(target);
+      if (!importers) {
+        importers = new Set();
+        fileDependents.set(target, importers);
+      }
+      importers.add(source);
+    }
+  }
+  return { nodes: buildNodes(elements), fileDependents };
+}
+
+/** Changed files plus every file that transitively imports them. */
+export function getAffectedFiles(
+  fileGraph: FileGraph,
+  changedFiles: string[],
+): Set<string> {
+  const affected = new Set(changedFiles);
+  const queue = [...changedFiles];
+  while (queue.length > 0) {
+    const file = queue.shift()!;
+    for (const importer of fileGraph.fileDependents.get(file) ?? []) {
+      if (!affected.has(importer)) {
+        affected.add(importer);
+        queue.push(importer);
+      }
+    }
+  }
+  return affected;
+}
 
 export type ModuleGraph = {
   nodes: ModuleNode[];
+  /**
+   * dependents.get(M) is every module affected when M changes — the full
+   * transitive closure, so getAffectedModules only needs a single hop.
+   */
   dependents: Map<string, Set<string>>;
 };
 
+/** Expands a direct-dependents map into its transitive closure. */
+function transitiveClosure(
+  direct: Map<string, Set<string>>,
+): Map<string, Set<string>> {
+  const closure = new Map<string, Set<string>>();
+  for (const start of direct.keys()) {
+    const reached = new Set<string>();
+    const queue = [...(direct.get(start) ?? [])];
+    while (queue.length > 0) {
+      const node = queue.shift()!;
+      if (reached.has(node)) {
+        continue;
+      }
+      reached.add(node);
+      for (const next of direct.get(node) ?? []) {
+        queue.push(next);
+      }
+    }
+    reached.delete(start);
+    closure.set(start, reached);
+  }
+  return closure;
+}
+
 /**
- * Compiles a glob pattern to an anchored RegExp.
+ * Builds a module graph from the actual import graph. Reachability is computed
+ * per module at the file level and then collapsed to modules.
  */
-export function globToRegex(glob: string): RegExp {
-  const escapeSegment = (seg: string) =>
-    seg.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
-  const body = glob.split("**").map(escapeSegment).join(".*");
-  return new RegExp(`^${body}$`);
+export function buildUsageModuleGraph(
+  elements: ModuleDef[],
+  fileDependencies: FileDependency[],
+): ModuleGraph {
+  const nodes = buildNodes(elements);
+  const fileGraph = buildFileGraph(elements, fileDependencies);
+
+  const filesByModule = new Map<string, string[]>();
+  const allFiles = new Set<string>();
+  for (const { source, dependencies } of fileDependencies) {
+    allFiles.add(source);
+    for (const target of dependencies) {
+      allFiles.add(target);
+    }
+  }
+  for (const file of allFiles) {
+    const module = mapFileToModule(nodes, file);
+    if (module) {
+      const files = filesByModule.get(module);
+      if (files) {
+        files.push(file);
+      } else {
+        filesByModule.set(module, [file]);
+      }
+    }
+  }
+
+  const dependents = new Map<string, Set<string>>(
+    elements.map((el) => [el.type, new Set()]),
+  );
+  for (const [module, files] of filesByModule) {
+    const affected = new Set<string>();
+    for (const file of getAffectedFiles(fileGraph, files)) {
+      const owner = mapFileToModule(nodes, file);
+      if (owner && owner !== module) {
+        affected.add(owner);
+      }
+    }
+    dependents.set(module, affected);
+  }
+
+  return { nodes, dependents };
 }
 
 export function buildModuleGraph(
   elements: ModuleDef[],
   rules: Rule[],
 ): ModuleGraph {
-  const nodes = elements.map((el) => ({
-    type: el.type,
-    regex: globToRegex(el.pattern),
-  }));
-
+  const nodes = buildNodes(elements);
   const allTypes = elements.map((e) => e.type);
 
   function expandPattern(pattern: string): string[] {
@@ -40,57 +204,25 @@ export function buildModuleGraph(
     return allTypes.includes(pattern) ? [pattern] : [];
   }
 
-  // dependents.get(M) is the set of modules that depend on M
-  // i.e. modules that are affected when M changes
-  const dependents = new Map<string, Set<string>>(
+  const directDependents = new Map<string, Set<string>>(
     allTypes.map((type) => [type, new Set()]),
   );
   for (const rule of rules) {
+    // Grandfathered imports that break the disallow rules still exist in the code,
+    // and selection must cover every import that actually exists.
+    // So disallow rules are ignored, at the cost of a looser graph.
     const fromTypes = rule.from.flatMap(expandPattern);
-    const allowTypes = rule.allow.flatMap(expandPattern);
+    const allowTypes = (rule.allow ?? []).flatMap(expandPattern);
     for (const target of allowTypes) {
       for (const importer of fromTypes) {
         if (importer !== target) {
-          dependents.get(target)?.add(importer);
+          directDependents.get(target)?.add(importer);
         }
       }
     }
   }
 
-  return { nodes, dependents };
-}
-
-/**
- * Returns the module type that owns the given file.
- * First match wins, so element ordering matters for nested patterns.
- */
-export function mapFileToModule(
-  moduleGraph: ModuleGraph,
-  path: string,
-): string | null {
-  for (const el of moduleGraph.nodes) {
-    if (el.regex.test(path)) {
-      return el.type;
-    }
-  }
-  return null;
-}
-
-/**
- * Returns the set of module types containing any of the changed files.
- */
-export function getChangedModules(
-  moduleGraph: ModuleGraph,
-  changedFiles: string[],
-): Set<string> {
-  const direct = new Set<string>();
-  for (const file of changedFiles) {
-    const module = mapFileToModule(moduleGraph, file);
-    if (module) {
-      direct.add(module);
-    }
-  }
-  return direct;
+  return { nodes, dependents: transitiveClosure(directDependents) };
 }
 
 /**
@@ -100,16 +232,10 @@ export function getAffectedModules(
   moduleGraph: ModuleGraph,
   changedFiles: string[],
 ): Set<string> {
-  const direct = getChangedModules(moduleGraph, changedFiles);
-  const affected = new Set(direct);
-  const queue = [...direct];
-  while (queue.length > 0) {
-    const module = queue.shift()!;
+  const affected = getChangedModules(moduleGraph.nodes, changedFiles);
+  for (const module of [...affected]) {
     for (const dep of moduleGraph.dependents.get(module) ?? []) {
-      if (!affected.has(dep)) {
-        affected.add(dep);
-        queue.push(dep);
-      }
+      affected.add(dep);
     }
   }
   return affected;

.github/scripts/affected-modules.unit.spec.ts

@@ -1,8 +1,13 @@
 import {
+  buildFileGraph,
   buildModuleGraph,
+  buildNodes,
+  buildUsageModuleGraph,
+  getAffectedFiles,
   getAffectedModules,
   getChangedModules,
   mapFileToModule,
+  parseCruiseModules,
 } from "./affected-modules";
 
 const ELEMENTS = [
@@ -31,6 +36,7 @@ const RULES = [
   { from: ["app/*"], allow: ["lib/*", "feature/*", "app/*"] },
 ];
 
+const nodes = buildNodes(ELEMENTS);
 const graph = buildModuleGraph(ELEMENTS, RULES);
 
 describe("affected modules", () => {
@@ -49,19 +55,19 @@ describe("affected modules", () => {
       ["external/lib/foo.ts", "feature/external"],
       ["src/embed.tsx", "app/main"],
     ])("should map %s to %s", (path, expected) => {
-      expect(mapFileToModule(graph, path)).toBe(expected);
+      expect(mapFileToModule(nodes, path)).toBe(expected);
     });
 
     it("should return null for files outside any pattern", () => {
-      expect(mapFileToModule(graph, "docs/foo.md")).toBe(null);
-      expect(mapFileToModule(graph, "README.md")).toBe(null);
-      expect(mapFileToModule(graph, "external/notlib/foo.ts")).toBe(null);
+      expect(mapFileToModule(nodes, "docs/foo.md")).toBe(null);
+      expect(mapFileToModule(nodes, "README.md")).toBe(null);
+      expect(mapFileToModule(nodes, "external/notlib/foo.ts")).toBe(null);
     });
   });
 
   describe("getChangedModules", () => {
     it("should return the unique set of modules whose files changed", () => {
-      const result = getChangedModules(graph, [
+      const result = getChangedModules(nodes, [
         "src/utils/colors.ts",
         "src/foo/x.ts",
         "src/foo/y.ts",
@@ -71,11 +77,81 @@ describe("affected modules", () => {
     });
 
     it("should return an empty set when no file maps to a module", () => {
-      expect(getChangedModules(graph, ["docs/foo.md"]).size).toBe(0);
+      expect(getChangedModules(nodes, ["docs/foo.md"]).size).toBe(0);
     });
   });
 
-  describe("getAffectedModules", () => {
+  describe("parseCruiseModules", () => {
+    it("should flatten to source + resolved-paths and drop unresolved deps", () => {
+      expect(
+        parseCruiseModules([
+          {
+            source: "src/foo/foo.tsx",
+            dependencies: [
+              { resolved: "src/utils/colors.ts" },
+              { resolved: "ambient/types", couldNotResolve: true },
+            ],
+          },
+          { source: "src/bar/bar.tsx" }, // no dependencies key
+        ]),
+      ).toEqual([
+        { source: "src/foo/foo.tsx", dependencies: ["src/utils/colors.ts"] },
+        { source: "src/bar/bar.tsx", dependencies: [] },
+      ]);
+    });
+  });
+
+  const FILE_DEPS = [
+    { source: "src/app.js", dependencies: ["src/foo/foo.tsx"] },
+    { source: "src/bar/bar.tsx", dependencies: ["src/embed.tsx"] },
+    { source: "src/foo/foo.tsx", dependencies: ["src/utils/colors.ts"] },
+  ];
+  const fileGraph = buildFileGraph(ELEMENTS, FILE_DEPS);
+
+  describe("getAffectedFiles", () => {
+    it("should return the changed file and everything that imports it", () => {
+      expect(
+        [...getAffectedFiles(fileGraph, ["src/utils/colors.ts"])].sort(),
+      ).toEqual(["src/app.js", "src/foo/foo.tsx", "src/utils/colors.ts"]);
+    });
+
+    it("should include a changed file with no importers (itself only)", () => {
+      // Nothing imports the app.js entry point.
+      expect([...getAffectedFiles(fileGraph, ["src/app.js"])]).toEqual([
+        "src/app.js",
+      ]);
+    });
+  });
+
+  describe("buildUsageModuleGraph + getAffectedModules", () => {
+    const usageGraph = buildUsageModuleGraph(ELEMENTS, FILE_DEPS);
+
+    it("should expand a changed module to its file-level affected modules", () => {
+      expect(
+        [...getAffectedModules(usageGraph, ["src/utils/colors.ts"])].sort(),
+      ).toEqual(["app/main", "feature/foo", "lib/utils"]);
+    });
+
+    it("should NOT pull in feature/bar via the app/main hub", () => {
+      const affected = getAffectedModules(usageGraph, ["src/foo/foo.tsx"]);
+      expect([...affected].sort()).toEqual(["app/main", "feature/foo"]);
+      expect(affected.has("feature/bar")).toBe(false);
+    });
+
+    it("should treat the whole changed module as changed", () => {
+      // app.js itself has no importers, but app/main also owns embed.tsx, which
+      // feature/bar imports so changing any app/main file flags feature/bar.
+      expect(
+        [...getAffectedModules(usageGraph, ["src/app.js"])].sort(),
+      ).toEqual(["app/main", "feature/bar"]);
+    });
+
+    it("should return empty when no file maps to a module", () => {
+      expect(getAffectedModules(usageGraph, ["docs/foo.md"]).size).toBe(0);
+    });
+  });
+
+  describe("getAffectedModules (rules graph)", () => {
     it("should affect feature/super and app/main but not feature/bar when feature/foo changes", () => {
       const result = getAffectedModules(graph, ["src/foo/x.ts"]);
       expect([...result].sort()).toEqual([

.github/scripts/affected-tests.ts

@@ -1,36 +1,40 @@
-// Per-suite affected-tests logic: combines module-affected closure with
-// per-suite "infra-touched" booleans (computed by dorny/paths-filter against
-// the `frontend_unit_infra` / `frontend_loki_infra` anchors in file-paths.yaml).
-// When infra files change, the whole suite runs in full.
+// Builds the affected-tests plan from raw inputs: computes the rules and usage
+// affected-module sets and selects, per suite, which specs to run under each.
+import { getFeatureModules } from "../../frontend/lint/module-boundaries.mjs";
 
 import {
+  type FileDependency,
   type ModuleDef,
-  type ModuleGraph,
+  type ModuleNode,
   type Rule,
   buildModuleGraph,
+  buildUsageModuleGraph,
   getAffectedModules,
   getChangedModules,
   mapFileToModule,
 } from "./affected-modules";
 
-export type TestSuiteDef = {
-  statsPrefix: string;
-  runAllTests?: boolean;
-};
-
 export type TestPlanStats = {
-  modules_changed: number;
-  modules_affected: number;
-  modules_affected_list: string[];
-  fe_unit_specs_total: number;
-  fe_unit_specs_run: number;
-  fe_unit_specs_skipped: number;
-  loki_stories_total: number;
-  loki_stories_run: number;
-  loki_stories_skipped: number;
-  e2e_specs_total: number;
-  e2e_specs_run: number;
-  e2e_specs_skipped: number;
+  fe_files_changed: number;
+  fe_files_total: number;
+  be_files_changed: number;
+  be_files_total: number;
+  unit_infra_touched: boolean;
+  loki_infra_touched: boolean;
+  shared_sources_touched: boolean;
+  fe_modules_total: number;
+  fe_modules_changed: number;
+  fe_modules_affected_rules: number;
+  fe_modules_affected_usage: number;
+  unit_specs_all: number;
+  unit_specs_to_run_rules: number;
+  unit_specs_to_run_usage: number;
+  loki_stories_all: number;
+  loki_stories_to_run_rules: number;
+  loki_stories_to_run_usage: number;
+  e2e_specs_all: number;
+  e2e_specs_to_run_rules: number;
+  e2e_specs_to_run_usage: number;
 };
 
 export type TestPlan = {
@@ -40,101 +44,187 @@ export type TestPlan = {
   e2e_specs_to_run: string[];
 };
 
-export const TEST_SUITES = {
-  unit: {
-    statsPrefix: "fe_unit_specs",
-  },
-  loki: {
-    statsPrefix: "loki_stories",
-  },
-  e2e: {
-    statsPrefix: "e2e_specs",
-    // We don't map changed files to e2e tests yet, so for now just run them all
-    runAllTests: true,
-  },
-} satisfies Record<string, TestSuiteDef>;
-
-export function createTestPlan({
-  elements,
-  rules,
-  testSuites,
-  changedFiles,
-  testFilesBySuite,
-  infraTouchedBySuite,
-}: {
+export type CreateTestPlanInput = {
   elements: ModuleDef[];
   rules: Rule[];
-  testSuites: Record<string, TestSuiteDef>;
   changedFiles: string[];
-  testFilesBySuite: Record<string, string[]>;
-  infraTouchedBySuite: Record<string, boolean>;
-}): TestPlan {
-  const moduleGraph = buildModuleGraph(elements, rules);
+  // Parsed dependency-cruiser edges, or null to fall back to the rules graph.
+  fileDependencies: FileDependency[] | null;
+  testFilesBySuite: { unit: string[]; loki: string[]; e2e: string[] };
+  e2eSpecFiles: Record<string, string[]> | null;
+  unitInfraTouched: boolean;
+  lokiInfraTouched: boolean;
+  e2eInfraTouched: boolean;
+  sharedSourcesTouched: boolean;
+  feFilesChanged: number;
+  beFilesChanged: number;
+  feFilesTotal: number;
+  beFilesTotal: number;
+};
 
-  const changedModules = getChangedModules(moduleGraph, changedFiles);
-  const modulesAffected = getAffectedModules(moduleGraph, changedFiles);
-  const modulesAffectedList = [...modulesAffected].sort();
-
-  const specsToRun: Record<string, string[]> = {};
-  const stats: Record<string, number | string[]> = {
-    modules_changed: changedModules.size,
-    modules_affected: modulesAffected.size,
-    modules_affected_list: modulesAffectedList,
-  };
-
-  for (const [name, testSuite] of Object.entries(testSuites)) {
-    const files = testFilesBySuite[name] ?? [];
-    const tests = createTestPlanForSuite(
-      moduleGraph,
-      testSuite,
-      infraTouchedBySuite[name] ?? false,
-      changedFiles,
-      files,
-    );
-    specsToRun[name] = tests;
-    stats[`${testSuite.statsPrefix}_total`] = files.length;
-    stats[`${testSuite.statsPrefix}_run`] = tests.length;
-    stats[`${testSuite.statsPrefix}_skipped`] = files.length - tests.length;
-  }
-
-  return {
-    stats: stats as TestPlanStats,
-    fe_unit_specs_to_run: specsToRun.unit ?? [],
-    loki_stories_to_run: specsToRun.loki ?? [],
-    e2e_specs_to_run: specsToRun.e2e ?? [],
-  };
-}
-
-/**
- * Computes the test plan for one test suite
- *
- * Runs the full suite when `runAllTests` is set or `infraTouched` is true,
- * otherwise runs the tests based on affected-modules.
- */
-export function createTestPlanForSuite(
-  moduleGraph: ModuleGraph,
-  testSuite: TestSuiteDef,
-  infraTouched: boolean,
-  changedFiles: string[],
-  allTestFiles: string[],
-): string[] {
-  if (testSuite.runAllTests || infraTouched) {
-    return allTestFiles;
-  }
-  const affected = getAffectedModules(moduleGraph, changedFiles);
-  return filterAffectedTests(moduleGraph, affected, allTestFiles);
-}
-
-/**
- * Filters the test-file list down to tests whose owning module is affected.
- */
+// Tests whose owning module is affected.
 export function filterAffectedTests(
-  moduleGraph: ModuleGraph,
+  nodes: ModuleNode[],
   affected: Set<string>,
   testFiles: string[],
 ): string[] {
   return testFiles.filter((file) => {
-    const module = mapFileToModule(moduleGraph, file);
+    const module = mapFileToModule(nodes, file);
     return module !== null && affected.has(module);
   });
 }
+
+// Collapse each spec's covered files to the *feature* modules it exercises,
+// once, for reuse across the rules/usage selects. Non-feature tiers
+// (shared/lib/...) are intentionally dropped: the manifest is a stale nightly
+// artifact, so its coupling to the module graph stays minimal ("does this spec
+// touch feature X?"). Accuracy comes from the fresh `affected` set, which
+// already expands a shared/infra change into the feature modules that depend on
+// it.
+export function specFeatureModules(
+  nodes: ModuleNode[],
+  featureModules: Set<string>,
+  specFiles: Record<string, string[]>,
+): Map<string, Set<string>> {
+  const moduleCache = new Map<string, string | null>();
+  const moduleOf = (file: string): string | null => {
+    let module = moduleCache.get(file);
+    if (module === undefined) {
+      module = mapFileToModule(nodes, file);
+      moduleCache.set(file, module);
+    }
+    return module;
+  };
+
+  const result = new Map<string, Set<string>>();
+  for (const [spec, files] of Object.entries(specFiles)) {
+    const features = new Set<string>();
+    for (const file of files) {
+      const module = moduleOf(file);
+      if (module !== null && featureModules.has(module)) {
+        features.add(module);
+      }
+    }
+    result.set(spec, features);
+  }
+  return result;
+}
+
+// A spec runs if any feature module it covers is affected.
+// A spec doesn't map to any feature module always runs because its scope is unknown
+export function filterAffectedE2eSpecs(
+  specFeatures: Map<string, Set<string>>,
+  affected: Set<string>,
+  e2eSpecs: string[],
+): string[] {
+  return e2eSpecs.filter((spec) => {
+    const features = specFeatures.get(spec);
+    if (!features || features.size === 0) {
+      return true;
+    }
+    return [...features].some((module) => affected.has(module));
+  });
+}
+
+export function createTestPlan({
+  elements,
+  rules,
+  changedFiles,
+  fileDependencies,
+  testFilesBySuite,
+  e2eSpecFiles,
+  unitInfraTouched,
+  lokiInfraTouched,
+  e2eInfraTouched,
+  sharedSourcesTouched,
+  feFilesChanged,
+  beFilesChanged,
+  feFilesTotal,
+  beFilesTotal,
+}: CreateTestPlanInput): TestPlan {
+  const rulesGraph = buildModuleGraph(elements, rules);
+  const usageGraph = fileDependencies
+    ? buildUsageModuleGraph(elements, fileDependencies)
+    : rulesGraph;
+
+  const nodes = rulesGraph.nodes;
+  // Distinct module types (an element type can span several patterns).
+  const totalModules = new Set(elements.map((el) => el.type)).size;
+  const changedModules = getChangedModules(nodes, changedFiles);
+  const rulesAffected = getAffectedModules(rulesGraph, changedFiles);
+  const usageAffected = getAffectedModules(usageGraph, changedFiles);
+
+  // The coarse "feature" tier is the only set the e2e manifest is ever
+  // collapsed to (see filterAffectedE2eSpecs).
+  const featureModules = new Set(getFeatureModules(elements));
+
+  // cljc/cljs compile into the FE bundle, so they force a full run that module
+  // selection can't narrow — same effect as a suite's own infra changing.
+  const unitForceAll = unitInfraTouched || sharedSourcesTouched;
+  const lokiForceAll = lokiInfraTouched || sharedSourcesTouched;
+  // e2e is integration-level, so anything the FE-coverage manifest can't see
+  // forces a full run: cljc/cljs in the bundle (sharedSourcesTouched), a backend
+  // change that can break the UI (beFilesChanged), an e2e harness/support change
+  // (e2eInfraTouched), or no manifest at all.
+  const e2eForceAll =
+    sharedSourcesTouched ||
+    e2eInfraTouched ||
+    beFilesChanged > 0 ||
+    e2eSpecFiles === null;
+
+  const select = (forceAll: boolean, affected: Set<string>, files: string[]) =>
+    forceAll ? files : filterAffectedTests(nodes, affected, files);
+
+  const { unit, loki, e2e } = testFilesBySuite;
+  const unitRules = select(unitForceAll, rulesAffected, unit);
+  const unitUsage = select(unitForceAll, usageAffected, unit);
+  const lokiRules = select(lokiForceAll, rulesAffected, loki);
+  const lokiUsage = select(lokiForceAll, usageAffected, loki);
+
+  // Precompute spec -> feature modules once (null when e2e runs in full).
+  const specFeatures =
+    e2eForceAll || e2eSpecFiles === null
+      ? null
+      : specFeatureModules(nodes, featureModules, e2eSpecFiles);
+  // A spec that was itself edited always runs, even when no app module changed.
+  const changedSet = new Set(changedFiles);
+  const selectE2e = (affected: Set<string>): string[] => {
+    if (specFeatures === null) {
+      return e2e;
+    }
+    const narrowed = new Set(
+      filterAffectedE2eSpecs(specFeatures, affected, e2e),
+    );
+    return e2e.filter((spec) => narrowed.has(spec) || changedSet.has(spec));
+  };
+  const e2eRules = selectE2e(rulesAffected);
+  const e2eUsage = selectE2e(usageAffected);
+
+  return {
+    stats: {
+      fe_files_changed: feFilesChanged,
+      fe_files_total: feFilesTotal,
+      be_files_changed: beFilesChanged,
+      be_files_total: beFilesTotal,
+      unit_infra_touched: unitInfraTouched,
+      loki_infra_touched: lokiInfraTouched,
+      shared_sources_touched: sharedSourcesTouched,
+      fe_modules_total: totalModules,
+      fe_modules_changed: changedModules.size,
+      fe_modules_affected_rules: rulesAffected.size,
+      fe_modules_affected_usage: usageAffected.size,
+      unit_specs_all: unit.length,
+      unit_specs_to_run_rules: unitRules.length,
+      unit_specs_to_run_usage: unitUsage.length,
+      loki_stories_all: loki.length,
+      loki_stories_to_run_rules: lokiRules.length,
+      loki_stories_to_run_usage: lokiUsage.length,
+      e2e_specs_all: e2e.length,
+      e2e_specs_to_run_rules: e2eRules.length,
+      e2e_specs_to_run_usage: e2eUsage.length,
+    },
+    fe_unit_specs_to_run: unitUsage,
+    loki_stories_to_run: lokiUsage,
+    e2e_specs_to_run: e2eUsage,
+  };
+}

.github/scripts/affected-tests.unit.spec.ts

@@ -1,9 +1,5 @@
-import { buildModuleGraph } from "./affected-modules";
-import {
-  createTestPlan,
-  createTestPlanForSuite,
-  filterAffectedTests,
-} from "./affected-tests";
+import { buildNodes } from "./affected-modules";
+import { createTestPlan, filterAffectedTests } from "./affected-tests";
 
 const ELEMENTS = [
   { type: "lib/utils", pattern: "src/utils/**" },
@@ -18,12 +14,6 @@ const RULES = [
   { from: ["feature/*"], allow: ["lib/*"] },
 ];
 
-const TEST_SUITE_DEFS = {
-  unit: { statsPrefix: "fe_unit_specs" },
-  loki: { statsPrefix: "loki_stories" },
-  e2e: { statsPrefix: "e2e_specs", runAllTests: true },
-};
-
 const UNIT_FILES = [
   "src/foo/foo.unit.spec.ts",
   "src/foo/bar.unit.spec.ts",
@@ -33,158 +23,227 @@ const UNIT_FILES = [
 const LOKI_FILES = ["src/foo/Foo.stories.tsx", "src/bar/Bar.stories.tsx"];
 const E2E_FILES = ["e2e/test/scenarios/a.cy.spec.ts"];
 
-const moduleGraph = buildModuleGraph(ELEMENTS, RULES);
+const baseInput = {
+  elements: ELEMENTS,
+  rules: RULES,
+  fileDependencies: null,
+  testFilesBySuite: { unit: UNIT_FILES, loki: LOKI_FILES, e2e: E2E_FILES },
+  e2eSpecFiles: null,
+  unitInfraTouched: false,
+  lokiInfraTouched: false,
+  e2eInfraTouched: false,
+  sharedSourcesTouched: false,
+  feFilesChanged: 0,
+  beFilesChanged: 0,
+  feFilesTotal: 0,
+  beFilesTotal: 0,
+};
 
-describe("affected tests", () => {
-  describe("createTestPlanForSuite", () => {
-    it("should run all tests when infra is touched", () => {
-      const result = createTestPlanForSuite(
-        moduleGraph,
-        TEST_SUITE_DEFS.unit,
-        true, // infraTouched
-        ["src/foo/x.ts"],
-        UNIT_FILES,
-      );
-      expect(result).toEqual(UNIT_FILES);
-    });
+describe("createTestPlan", () => {
+  it("runs only specs in affected modules (rules graph)", () => {
+    const plan = createTestPlan({ ...baseInput, changedFiles: ["src/foo/x.ts"] });
 
-    it("should fall back to affected-tests filtering when infra not touched", () => {
-      const result = createTestPlanForSuite(
-        moduleGraph,
-        TEST_SUITE_DEFS.unit,
-        false, // infraTouched
-        ["src/foo/x.ts"],
-        UNIT_FILES,
-      );
-      expect(result.sort()).toEqual([
-        "src/foo/bar.unit.spec.ts",
-        "src/foo/foo.unit.spec.ts",
-      ]);
-    });
-
-    it("should return nothing when infra not touched and no file maps to a module", () => {
-      const result = createTestPlanForSuite(
-        moduleGraph,
-        TEST_SUITE_DEFS.unit,
-        false,
-        ["docs/foo.md"],
-        UNIT_FILES,
-      );
-      expect(result).toEqual([]);
-    });
-
-    it("should run all tests for runAllTests suites regardless of inputs", () => {
-      expect(
-        createTestPlanForSuite(
-          moduleGraph,
-          TEST_SUITE_DEFS.e2e,
-          false,
-          ["docs/foo.md"],
-          E2E_FILES,
-        ),
-      ).toEqual(E2E_FILES);
-      expect(
-        createTestPlanForSuite(
-          moduleGraph,
-          TEST_SUITE_DEFS.e2e,
-          false,
-          ["src/foo/x.ts"],
-          E2E_FILES,
-        ),
-      ).toEqual(E2E_FILES);
-    });
+    expect(plan.stats.fe_modules_changed).toBe(1);
+    expect(plan.stats.fe_modules_affected_rules).toBe(1);
+    expect(plan.fe_unit_specs_to_run.sort()).toEqual([
+      "src/foo/bar.unit.spec.ts",
+      "src/foo/foo.unit.spec.ts",
+    ]);
+    expect(plan.stats.unit_specs_to_run_rules).toBe(2);
+    expect(plan.stats.loki_stories_to_run_rules).toBe(1);
+    // With no file deps, usage falls back to rules.
+    expect(plan.stats.unit_specs_to_run_usage).toBe(2);
   });
 
-  describe("createTestPlan", () => {
-    it("should return run lists and stats together", () => {
-      const result = createTestPlan({
-        elements: ELEMENTS,
-        rules: RULES,
-        testSuites: TEST_SUITE_DEFS,
-        changedFiles: ["src/foo/x.ts"],
-        testFilesBySuite: {
-          unit: UNIT_FILES,
-          loki: LOKI_FILES,
-          e2e: E2E_FILES,
-        },
-        infraTouchedBySuite: { unit: false, loki: false, e2e: false },
-      });
-
-      expect(result.fe_unit_specs_to_run.sort()).toEqual([
-        "src/foo/bar.unit.spec.ts",
-        "src/foo/foo.unit.spec.ts",
-      ]);
-      expect(result.loki_stories_to_run).toEqual(["src/foo/Foo.stories.tsx"]);
-      expect(result.e2e_specs_to_run).toEqual(E2E_FILES);
-
-      expect(result.stats).toEqual({
-        modules_changed: 1,
-        modules_affected: 1,
-        modules_affected_list: ["feature/foo"],
-        fe_unit_specs_total: 4,
-        fe_unit_specs_run: 2,
-        fe_unit_specs_skipped: 2,
-        loki_stories_total: 2,
-        loki_stories_run: 1,
-        loki_stories_skipped: 1,
-        e2e_specs_total: 1,
-        e2e_specs_run: 1,
-        e2e_specs_skipped: 0,
-      });
+  it("narrows further with the usage graph than the rules graph", () => {
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["src/utils/colors.ts"],
+      // Only feature/foo actually imports lib/utils.
+      fileDependencies: [
+        { source: "src/foo/foo.tsx", dependencies: ["src/utils/colors.ts"] },
+      ],
     });
 
-    it("should run all unit specs when unit infra is touched", () => {
-      const result = createTestPlan({
-        elements: ELEMENTS,
-        rules: RULES,
-        testSuites: TEST_SUITE_DEFS,
-        changedFiles: ["docs/foo.md"],
-        testFilesBySuite: {
-          unit: UNIT_FILES,
-          loki: LOKI_FILES,
-          e2e: E2E_FILES,
-        },
-        infraTouchedBySuite: { unit: true, loki: false, e2e: false },
-      });
-      expect(result.stats.fe_unit_specs_run).toBe(UNIT_FILES.length);
-      expect(result.stats.fe_unit_specs_skipped).toBe(0);
-      // Only the unit suite was triggered.
-      expect(result.stats.loki_stories_run).toBe(0);
-    });
-
-    it("should not run anything when no infra is touched and no modules affected", () => {
-      const result = createTestPlan({
-        elements: ELEMENTS,
-        rules: RULES,
-        testSuites: TEST_SUITE_DEFS,
-        changedFiles: ["docs/foo.md"],
-        testFilesBySuite: {
-          unit: UNIT_FILES,
-          loki: LOKI_FILES,
-          e2e: E2E_FILES,
-        },
-        infraTouchedBySuite: { unit: false, loki: false, e2e: false },
-      });
-      expect(result.stats.fe_unit_specs_run).toBe(0);
-      expect(result.stats.loki_stories_run).toBe(0);
-      // e2e is runAllTests, so it still reports run = total.
-      expect(result.stats.e2e_specs_run).toBe(E2E_FILES.length);
-    });
+    // Rules allow both features to import lib/utils, so both are "affected".
+    expect(plan.stats.fe_modules_affected_rules).toBe(3);
+    // Usage sees only feature/foo + lib/utils.
+    expect(plan.stats.fe_modules_affected_usage).toBe(2);
+    expect(plan.stats.unit_specs_to_run_rules).toBe(4);
+    expect(plan.stats.unit_specs_to_run_usage).toBe(3);
   });
 
-  describe("filterAffectedTests", () => {
-    it("should keep only tests inside affected modules", () => {
-      const affected = new Set(["feature/foo", "lib/utils"]);
-      const tests = [
-        "src/foo/foo.unit.spec.ts",
-        "src/utils/colors.unit.spec.ts",
-        "src/bar/bar.unit.spec.ts",
-        "docs/unrelated.unit.spec.ts",
-      ];
-      expect(filterAffectedTests(moduleGraph, affected, tests)).toEqual([
-        "src/foo/foo.unit.spec.ts",
-        "src/utils/colors.unit.spec.ts",
-      ]);
+  it("forces a full FE run on a shared-sources (cljc) change with no affected modules", () => {
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["docs/readme.md"],
+      sharedSourcesTouched: true,
     });
+
+    expect(plan.stats.fe_modules_affected_rules).toBe(0);
+    expect(plan.stats.unit_specs_to_run_rules).toBe(UNIT_FILES.length);
+    expect(plan.stats.unit_specs_to_run_usage).toBe(UNIT_FILES.length);
+    expect(plan.stats.loki_stories_to_run_rules).toBe(LOKI_FILES.length);
+  });
+
+  it("forces only the suite whose infra changed", () => {
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["docs/readme.md"],
+      unitInfraTouched: true,
+    });
+
+    expect(plan.stats.unit_specs_to_run_rules).toBe(UNIT_FILES.length);
+    expect(plan.stats.loki_stories_to_run_rules).toBe(0);
+  });
+
+  it("runs the full e2e suite when no coverage manifest is available", () => {
+    const plan = createTestPlan({ ...baseInput, changedFiles: ["src/foo/x.ts"] });
+
+    expect(plan.stats.e2e_specs_to_run_rules).toBe(E2E_FILES.length);
+    expect(plan.stats.e2e_specs_to_run_usage).toBe(E2E_FILES.length);
+    expect(plan.e2e_specs_to_run).toEqual(E2E_FILES);
+  });
+
+  it("narrows e2e to specs covering affected feature modules", () => {
+    const e2e = [
+      "e2e/test/scenarios/foo.cy.spec.ts",
+      "e2e/test/scenarios/bar.cy.spec.ts",
+      "e2e/test/scenarios/new.cy.spec.ts",
+    ];
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["src/foo/x.ts"], // affects feature/foo only
+      testFilesBySuite: { unit: UNIT_FILES, loki: LOKI_FILES, e2e },
+      e2eSpecFiles: {
+        "e2e/test/scenarios/foo.cy.spec.ts": ["src/foo/a.ts"], // feature/foo
+        "e2e/test/scenarios/bar.cy.spec.ts": ["src/bar/b.ts"], // feature/bar
+        // new.cy.spec.ts intentionally absent from the manifest
+      },
+    });
+
+    // foo's feature module is affected; bar's is not; the unmapped new spec
+    // always runs.
+    expect(plan.e2e_specs_to_run.sort()).toEqual([
+      "e2e/test/scenarios/foo.cy.spec.ts",
+      "e2e/test/scenarios/new.cy.spec.ts",
+    ]);
+    expect(plan.stats.e2e_specs_all).toBe(3);
+  });
+
+  it("runs a spec that maps to no feature module (unknown scope)", () => {
+    const e2e = ["e2e/test/scenarios/lib-only.cy.spec.ts"];
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["src/foo/x.ts"], // affects feature/foo, NOT lib/utils
+      testFilesBySuite: { unit: UNIT_FILES, loki: LOKI_FILES, e2e },
+      e2eSpecFiles: {
+        // Covers only a non-feature module (e.g. a home/auth spec whose feature
+        // the baseline subtracted), so its feature scope is unknown.
+        "e2e/test/scenarios/lib-only.cy.spec.ts": ["src/utils/colors.ts"],
+      },
+    });
+
+    // No feature module to gate on -> can't bound scope -> always runs.
+    expect(plan.e2e_specs_to_run).toEqual(e2e);
+  });
+
+  it("force-runs all e2e on a backend change (invisible to FE coverage)", () => {
+    const e2e = ["e2e/test/scenarios/foo.cy.spec.ts"];
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["src/metabase/api/card.clj"],
+      beFilesChanged: 1,
+      testFilesBySuite: { unit: UNIT_FILES, loki: LOKI_FILES, e2e },
+      e2eSpecFiles: { "e2e/test/scenarios/bar.cy.spec.ts": ["src/bar/b.ts"] },
+    });
+
+    expect(plan.e2e_specs_to_run).toEqual(e2e);
+  });
+
+  it("force-runs all e2e when e2e infra (support/runner) changes", () => {
+    const e2e = ["e2e/test/scenarios/foo.cy.spec.ts"];
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["e2e/support/commands/api/createQuestion.js"],
+      e2eInfraTouched: true,
+      testFilesBySuite: { unit: UNIT_FILES, loki: LOKI_FILES, e2e },
+      e2eSpecFiles: { "e2e/test/scenarios/bar.cy.spec.ts": ["src/bar/b.ts"] },
+    });
+
+    expect(plan.e2e_specs_to_run).toEqual(e2e);
+  });
+
+  it("runs an edited spec even when no app module changed", () => {
+    const spec = "e2e/test/scenarios/foo.cy.spec.ts";
+    const e2e = [spec, "e2e/test/scenarios/bar.cy.spec.ts"];
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: [spec], // only the spec itself changed
+      testFilesBySuite: { unit: UNIT_FILES, loki: LOKI_FILES, e2e },
+      e2eSpecFiles: {
+        [spec]: ["src/bar/b.ts"], // covers feature/bar, which is NOT affected
+        "e2e/test/scenarios/bar.cy.spec.ts": ["src/bar/b.ts"],
+      },
+    });
+
+    // No module is affected, but the edited spec must still run.
+    expect(plan.e2e_specs_to_run).toEqual([spec]);
+  });
+
+  it("runs a spec whose coverage was fully baseline-subtracted (empty files)", () => {
+    const e2e = ["e2e/test/scenarios/empty.cy.spec.ts"];
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["src/foo/x.ts"], // affects feature/foo
+      testFilesBySuite: { unit: UNIT_FILES, loki: LOKI_FILES, e2e },
+      e2eSpecFiles: { "e2e/test/scenarios/empty.cy.spec.ts": [] },
+    });
+
+    // Empty coverage means unknown scope, so the spec runs.
+    expect(plan.e2e_specs_to_run).toEqual(e2e);
+  });
+
+  it("forces a full e2e run when shared (cljc) sources change", () => {
+    const e2e = ["e2e/test/scenarios/foo.cy.spec.ts"];
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: ["src/foo/x.ts"],
+      sharedSourcesTouched: true,
+      testFilesBySuite: { unit: UNIT_FILES, loki: LOKI_FILES, e2e },
+      e2eSpecFiles: { "e2e/test/scenarios/bar.cy.spec.ts": ["src/bar/b.ts"] },
+    });
+
+    // Manifest is present but cljc is invisible to JS coverage, so run all.
+    expect(plan.e2e_specs_to_run).toEqual(e2e);
+  });
+
+  it("passes the FE/BE file counts through to stats", () => {
+    const plan = createTestPlan({
+      ...baseInput,
+      changedFiles: [],
+      feFilesChanged: 5,
+      beFilesChanged: 3,
+    });
+
+    expect(plan.stats.fe_files_changed).toBe(5);
+    expect(plan.stats.be_files_changed).toBe(3);
+  });
+});
+
+describe("filterAffectedTests", () => {
+  it("keeps only tests inside affected modules", () => {
+    const nodes = buildNodes(ELEMENTS);
+    const affected = new Set(["feature/foo", "lib/utils"]);
+    const tests = [
+      "src/foo/foo.unit.spec.ts",
+      "src/utils/colors.unit.spec.ts",
+      "src/bar/bar.unit.spec.ts",
+      "docs/unrelated.unit.spec.ts",
+    ];
+    expect(filterAffectedTests(nodes, affected, tests)).toEqual([
+      "src/foo/foo.unit.spec.ts",
+      "src/utils/colors.unit.spec.ts",
+    ]);
   });
 });

.github/scripts/bundle-size-stats-prepare.ts

@@ -0,0 +1,225 @@
+// Prepares the rows the bundle-size stats logger imports into eng-stats-importer.
+//
+// For each measured (bundle, kind) it computes the delta — raw, gzipped and
+// brotli (as-served) bytes plus percent — against the previously *plotted* data
+// point (restored from a rolling cache), so the deltas can be charted directly.
+// It also decides whether this commit is worth recording at all: a point is kept
+// when the as-served size moved by at least MIN_DELTA_PERCENT, or when a new
+// bundle/kind appears. Only master builds run through here — releases form
+// non-linear lines whose deltas are meaningless, so they're not recorded (their
+// historical sizes are backfilled separately).
+//
+// buildStatsRows is pure (data in, data out) so it can be unit-tested; main()
+// is the thin I/O wrapper that reads env/files and writes the rows, cache and
+// step outputs.
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+/** One measurement emitted by measure-bundle-sizes. */
+export interface Measurement {
+  bundle: string;
+  kind: "initial" | "total";
+  rawBytes: number;
+  gzipBytes: number;
+  brotliBytes: number;
+  fileCount: number;
+}
+
+/**
+ * The slim row cached between runs, holding the last *plotted* point.
+ * `brotliBytes` is optional because a point cached before brotli logging
+ * landed does not carry it — see buildStatsRows' per-row gzip fallback.
+ */
+export type CacheRow = Pick<Measurement, "bundle" | "kind" | "rawBytes" | "gzipBytes"> & {
+  brotliBytes?: number;
+};
+
+export interface BuildStatsRowsInput {
+  measurements: Measurement[];
+  previous: CacheRow[];
+  threshold: number;
+  date: string;
+  commit: string;
+  commitMessage: string;
+  version: string;
+}
+
+/** An upload row, keyed by the importer's column display names. */
+export type StatsRow = Record<string, string | number | null>;
+
+export interface BuildStatsRowsResult {
+  rows: StatsRow[];
+  cacheRows: CacheRow[];
+  significant: boolean;
+  reason: string;
+  maxServedDeltaPercent: number;
+  firstPoint: boolean;
+  hasNewSeries: boolean;
+}
+
+// null, not "", for an absent delta: the stats importer coerces values
+// strictly and rejects "" for a numeric column.
+const deltaPercent = (current: number, base: number | undefined | null): number | null =>
+  base ? Math.round(((current - base) * 10000) / base) / 100 : null;
+
+/**
+ * Turn the current measurements + the last plotted point into upload rows, the
+ * slim cache rows for the next diff, and the keep/skip decision.
+ *
+ * The significance threshold tracks the as-served size: brotli where the build
+ * ships a precompressed .br, otherwise gzip. Current measurements always carry
+ * brotliBytes (estimated when no .br shipped), but a cached base point recorded
+ * before brotli logging may not, so the delta still falls back to gzip per row.
+ */
+export function buildStatsRows({
+  measurements,
+  previous,
+  threshold,
+  date,
+  commit,
+  commitMessage,
+  version,
+}: BuildStatsRowsInput): BuildStatsRowsResult {
+  const previousOf = (bundle: string, kind: string) =>
+    previous.find((row) => row.bundle === bundle && row.kind === kind);
+
+  let maxServedDeltaPercent = 0;
+  let hasNewSeries = false;
+
+  const rows = measurements.map((measurement): StatsRow => {
+    const base = previousOf(measurement.bundle, measurement.kind);
+    // Non-null only when BOTH sides carry brotli: a point cached before brotli
+    // logging landed has none, and that row falls back to the gzip delta.
+    const baseBrotli =
+      measurement.brotliBytes != null && base?.brotliBytes != null ? base.brotliBytes : null;
+    const gzipDeltaPercent = deltaPercent(measurement.gzipBytes, base?.gzipBytes);
+    const brotliDeltaPercent =
+      baseBrotli != null ? deltaPercent(measurement.brotliBytes, baseBrotli) : null;
+    if (!base) {
+      hasNewSeries = true;
+    } else {
+      const servedDeltaPercent = baseBrotli != null ? brotliDeltaPercent : gzipDeltaPercent;
+      maxServedDeltaPercent = Math.max(maxServedDeltaPercent, Math.abs(servedDeltaPercent ?? 0));
+    }
+    return {
+      Date: date,
+      Version: version,
+      Commit: commit,
+      Bundle: measurement.bundle,
+      Kind: measurement.kind, // "initial" or "total"
+      // The stats table carries a free-text Description column. Populate it
+      // with the commit subject so the chart's points are self-describing.
+      Description: commitMessage,
+      "Raw bytes": measurement.rawBytes,
+      "Gzip bytes": measurement.gzipBytes,
+      "Brotli bytes": measurement.brotliBytes, // as-served (shipped .br, else estimated)
+      "File count": measurement.fileCount,
+      "Raw bytes delta": base ? measurement.rawBytes - base.rawBytes : null,
+      "Gzip bytes delta": base ? measurement.gzipBytes - base.gzipBytes : null,
+      "Brotli bytes delta": baseBrotli != null ? measurement.brotliBytes - baseBrotli : null,
+      "Raw delta %": deltaPercent(measurement.rawBytes, base?.rawBytes),
+      "Gzip delta %": gzipDeltaPercent,
+      "Brotli delta %": brotliDeltaPercent,
+    };
+  });
+
+  const firstPoint = previous.length === 0;
+  const significant = firstPoint || hasNewSeries || maxServedDeltaPercent >= threshold;
+
+  // Slim rows the next run diffs against. The workflow only persists this to the
+  // cache when we actually push, so the cached reference always stays the last
+  // *plotted* point (cumulative drift is caught).
+  const cacheRows = measurements.map(
+    ({ bundle, kind, rawBytes, gzipBytes, brotliBytes }): CacheRow => ({
+      bundle,
+      kind,
+      rawBytes,
+      gzipBytes,
+      brotliBytes,
+    }),
+  );
+
+  const reason = firstPoint
+    ? "first point"
+    : hasNewSeries
+      ? "new bundle/kind series"
+      : `max served Δ ${maxServedDeltaPercent.toFixed(2)}% (threshold ${threshold}%)`;
+
+  return {
+    rows,
+    cacheRows,
+    significant,
+    reason,
+    maxServedDeltaPercent,
+    firstPoint,
+    hasNewSeries,
+  };
+}
+
+const readJson = <T,>(filePath: string | undefined): T | null =>
+  filePath && existsSync(filePath) ? (JSON.parse(readFileSync(filePath, "utf8")) as T) : null;
+
+const writeJson = (filePath: string, value: unknown) => {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(value));
+};
+
+const setOutput = (name: string, value: string) => {
+  if (process.env.GITHUB_OUTPUT) {
+    appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${value}\n`);
+  }
+};
+
+// version.properties (extracted from the uberjar) carries the build's tag.
+// Non-release (master) builds report tag=vUNKNOWN, so leave Version empty there.
+function readVersion(versionPropsPath: string | undefined): string {
+  const raw =
+    versionPropsPath && existsSync(versionPropsPath)
+      ? (readFileSync(versionPropsPath, "utf8").match(/^tag=(.*)$/m)?.[1]?.trim() ?? "")
+      : "";
+  return raw === "vUNKNOWN" ? "" : raw;
+}
+
+export function main() {
+  const env = process.env;
+
+  const measurements = readJson<Measurement[]>(env.CURRENT);
+  if (!Array.isArray(measurements) || measurements.length === 0) {
+    console.error(`::error::No bundle measurements found at ${env.CURRENT}`);
+    process.exit(1);
+  }
+
+  const result = buildStatsRows({
+    measurements,
+    // The last plotted point, as slim rows: [{ bundle, kind, rawBytes, gzipBytes, brotliBytes }].
+    previous: readJson<CacheRow[]>(env.LAST) || [],
+    threshold: Number(env.MIN_DELTA_PERCENT ?? 1),
+    date: new Date().toISOString().slice(0, 10), // YYYY-MM-DD
+    commit: (env.HEAD_SHA || "").slice(0, 12),
+    commitMessage: (env.COMMIT_MESSAGE || "").split("\n")[0], // subject line only
+    version: readVersion(env.VERSION_PROPS),
+  });
+
+  writeJson(env.ROWS_OUT!, result.rows);
+  writeJson(env.CACHE_OUT!, result.cacheRows);
+
+  console.log(`${result.significant ? "RECORD" : "SKIP"} — ${result.reason}`);
+
+  setOutput("significant", result.significant ? "true" : "false");
+  setOutput(
+    "max_delta_percent",
+    result.firstPoint || result.hasNewSeries ? "" : result.maxServedDeltaPercent.toFixed(2),
+  );
+}
+
+// Only run the I/O wrapper when invoked directly, so importing buildStatsRows
+// (from the spec) has no side effects.
+if ((import.meta as ImportMeta & { main?: boolean }).main) {
+  main();
+}

.github/scripts/bundle-size-stats-prepare.unit.spec.ts

@@ -0,0 +1,105 @@
+import {
+  buildStatsRows,
+  type CacheRow,
+  type Measurement,
+} from "./bundle-size-stats-prepare";
+
+const meta = {
+  date: "2026-06-30",
+  commit: "abc123",
+  commitMessage: "Fix the thing (#123)",
+  version: "",
+};
+const measurement = (over: Partial<Measurement> = {}): Measurement => ({
+  bundle: "embedding-sdk-chunked",
+  kind: "total",
+  rawBytes: 1000,
+  gzipBytes: 400,
+  brotliBytes: 300,
+  fileCount: 3,
+  ...over,
+});
+
+describe("buildStatsRows", () => {
+  it("records the first point and leaves every delta empty", () => {
+    const result = buildStatsRows({
+      ...meta,
+      measurements: [measurement()],
+      previous: [],
+      threshold: 1,
+    });
+
+    expect(result.firstPoint).toBe(true);
+    expect(result.significant).toBe(true);
+    expect(result.reason).toBe("first point");
+    expect(result.rows[0]["Gzip bytes delta"]).toBeNull();
+    expect(result.rows[0]["Brotli delta %"]).toBeNull();
+    expect(result.rows[0]["Description"]).toBe("Fix the thing (#123)");
+    expect(result.cacheRows[0]).toEqual({
+      bundle: "embedding-sdk-chunked",
+      kind: "total",
+      rawBytes: 1000,
+      gzipBytes: 400,
+      brotliBytes: 300,
+    });
+  });
+
+  it("records a never-seen bundle/kind as a new series", () => {
+    const result = buildStatsRows({
+      ...meta,
+      measurements: [measurement({ bundle: "app", kind: "initial" })],
+      previous: [{ bundle: "app", kind: "total", rawBytes: 1, gzipBytes: 1, brotliBytes: 1 }],
+      threshold: 99,
+    });
+
+    expect(result.hasNewSeries).toBe(true);
+    expect(result.significant).toBe(true);
+    expect(result.reason).toBe("new bundle/kind series");
+  });
+
+  it("gates significance on the brotli (as-served) delta when both sides have it", () => {
+    const previous: CacheRow[] = [
+      {
+        bundle: "embedding-sdk-chunked",
+        kind: "total",
+        rawBytes: 1000,
+        gzipBytes: 400,
+        brotliBytes: 300,
+      },
+    ];
+
+    const big = buildStatsRows({
+      ...meta,
+      measurements: [measurement({ brotliBytes: 315, gzipBytes: 400 })], // brotli +5%, gzip 0%
+      previous,
+      threshold: 1,
+    });
+    expect(big.maxServedDeltaPercent).toBeCloseTo(5);
+    expect(big.significant).toBe(true);
+    expect(big.rows[0]["Brotli delta %"]).toBeCloseTo(5);
+
+    const small = buildStatsRows({
+      ...meta,
+      measurements: [measurement({ brotliBytes: 301, gzipBytes: 999 })], // brotli +0.33%, gzip ignored
+      previous,
+      threshold: 1,
+    });
+    expect(small.significant).toBe(false);
+    expect(small.reason).toContain("threshold 1%");
+  });
+
+  it("falls back to the gzip delta when the cached base predates brotli logging", () => {
+    const result = buildStatsRows({
+      ...meta,
+      measurements: [measurement({ gzipBytes: 440, brotliBytes: 300 })], // gzip +10%
+      // No brotliBytes: this point was cached before brotli logging landed.
+      previous: [{ bundle: "embedding-sdk-chunked", kind: "total", rawBytes: 1000, gzipBytes: 400 }],
+      threshold: 1,
+    });
+
+    expect(result.maxServedDeltaPercent).toBeCloseTo(10);
+    expect(result.significant).toBe(true);
+    expect(result.rows[0]["Brotli bytes delta"]).toBeNull(); // no base brotli to diff against
+    expect(result.rows[0]["Gzip delta %"]).toBeCloseTo(10);
+  });
+});

.github/scripts/cache-keys.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Single definition of every CI dependency cache: what it holds, what identifies it, what it falls back to.
+#
+# A GitHub cache entry is identified by its key, a hash of the declared path list, and the ref that saved
+# it. A step declaring a different path list than the one a cache was saved with computes a different
+# identity and can never match it, whatever its key says. So paths and keys are emitted together here and
+# every cache step takes both from this script.
+#
+# Emits `name=value` lines in $GITHUB_OUTPUT format:
+#
+#   .github/scripts/cache-keys.sh >> "$GITHUB_OUTPUT"
+#
+# Run it with no redirect to see the whole scheme, or pass one name to print a single value:
+#
+#   .github/scripts/cache-keys.sh
+#   .github/scripts/cache-keys.sh m2-key
+#
+# Hashes are computed here rather than with GitHub's hashFiles() so that a local run and a CI run of the
+# same commit produce the same keys, and so that an empty match can fail loudly - a hashFiles() call that
+# matches nothing silently yields "", collapsing the key onto its own restore prefix and pointing every
+# dependency set at one entry.
+
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)"
+
+OS="${RUNNER_OS:-$(uname -s)}"
+[ "$OS" = "Darwin" ] && OS="macOS"
+
+sha256() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | cut -d' ' -f1
+  else
+    shasum -a 256 | cut -d' ' -f1
+  fi
+}
+
+# Digest of a set of files: hash each one, then hash the concatenation, so the result depends on every
+# file's contents and on which files exist.
+digest() {
+  local f
+  if [ "$#" -eq 0 ]; then
+    echo "::error::cache-keys.sh: no files matched; refusing to emit a key that would collide across dependency sets" >&2
+    exit 1
+  fi
+  for f in "$@"; do
+    [ -f "$f" ] || { echo "::error::cache-keys.sh: $f does not exist" >&2; exit 1; }
+    sha256 < "$f"
+  done | sha256
+}
+
+shopt -s nullglob
+DEPS_FILES=(deps.edn
+            bin/lint-migrations-file/deps.edn
+            bin/load-namespaces/deps.edn
+            modules/drivers/deps.edn
+            modules/drivers/*/deps.edn)
+shopt -u nullglob
+
+DEPS_HASH="$(digest "${DEPS_FILES[@]}")"
+LOCK_HASH="$(digest bun.lock)"
+
+# The Cypress binary depends on the Cypress version alone, so keying it on the whole lockfile would
+# throw away a 200MB download every time any frontend dependency moved.
+#
+# Reading a version out of a lockfile with a regex is only safe while exactly one line matches. Insist
+# on that rather than taking the first of several: a second match means the format moved under us, and
+# picking one at random would key the binary under a version it is not.
+CYPRESS_VERSIONS="$(sed -n 's/.*"cypress": \["cypress@\([^"]*\)".*/\1/p' bun.lock)"
+CYPRESS_MATCHES="$(printf '%s\n' "$CYPRESS_VERSIONS" | grep -c . || true)"
+if [ "$CYPRESS_MATCHES" != "1" ]; then
+  echo "::error::cache-keys.sh: expected exactly one resolved cypress version in bun.lock, found $CYPRESS_MATCHES" >&2
+  exit 1
+fi
+CYPRESS_VERSION="$CYPRESS_VERSIONS"
+
+# The Clojure CLI version CI installs. It lives here rather than in prepare-backend so that the version
+# and the key that identifies its cache entry cannot drift apart.
+CLOJURE_VERSION="1.12.0.1488"
+
+# An incremental lint cache is only ever an accelerator, so it keys on the commit and always falls back
+# to the newest entry on the prefix. The exact key never pre-exists, which keeps the entry current.
+ESLINT_SHA="${GITHUB_SHA:-$(git rev-parse HEAD)}"
+
+emit_multiline() {
+  local name="$1"; shift
+  printf '%s<<CACHE_KEYS_EOF\n' "$name"
+  printf '%s\n' "$@"
+  printf 'CACHE_KEYS_EOF\n'
+}
+
+# Paths under the home directory are emitted absolute rather than as `~/...`. actions/cache would expand
+# a tilde, but a shell assigning one of these to a variable would not, and would go on to create a
+# directory named `~`. Paths inside the checkout stay relative; actions/cache resolves those against the
+# workspace.
+spec() {
+  emit_multiline m2-path "$HOME/.m2" "$HOME/.gitlibs" "$HOME/.deps.clj" 'bin/bb'
+  echo "m2-key=M2-$OS-$DEPS_HASH"
+  echo "m2-restore-key=M2-$OS-"
+
+  # Pinned rather than discovered via `bun pm cache` so that the path is known before bun is installed;
+  # prepare-frontend exports BUN_INSTALL_CACHE_DIR to match and fails if bun disagrees.
+  echo "bun-store-path=$HOME/.bun/install/cache"
+  echo "bun-store-key=bun-store-$OS-$LOCK_HASH"
+  echo "bun-store-restore-key=bun-store-$OS-"
+
+  # No restore-key: an entry from another version installs a working `clojure` of the wrong version, and
+  # the freshness check in prepare-backend - running the binary - would accept it.
+  #
+  # The installer bakes this prefix into the clj/clojure shims, so the tree only works when restored to
+  # the same absolute path it was built at; prepare-backend reinstalls when it is not.
+  echo "clojure-path=$HOME/.clojure-cli"
+  echo "clojure-key=clojure-cli-$OS-$CLOJURE_VERSION"
+  echo "clojure-version=$CLOJURE_VERSION"
+
+  echo "cypress-path=$HOME/.cache/Cypress"
+  echo "cypress-key=cypress-$OS-$CYPRESS_VERSION"
+  echo "cypress-restore-key=cypress-$OS-"
+
+  echo "eslint-path=.eslintcache"
+  echo "eslint-key=eslint-$OS-$ESLINT_SHA"
+  echo "eslint-restore-key=eslint-$OS-"
+}
+
+# Print one output's value, including the multiline form, and fail on a name that does not exist. A
+# caller that silently received "" would go on to build a key with a hole in it.
+query() {
+  local want="$1" line delim found=0 in_block=0
+  while IFS= read -r line; do
+    if [ "$in_block" = 1 ]; then
+      if [ "$line" = "$delim" ]; then
+        in_block=0
+      else
+        printf '%s\n' "$line"
+      fi
+      continue
+    fi
+    case "$line" in
+      "$want="*)
+        printf '%s\n' "${line#*=}"
+        found=1
+        ;;
+      "$want<<"*)
+        delim="${line#*<<}"
+        in_block=1
+        found=1
+        ;;
+    esac
+  done <<EOF
+$(spec)
+EOF
+  if [ "$found" = 0 ]; then
+    echo "::error::cache-keys.sh: no output named '$want'" >&2
+    exit 1
+  fi
+}
+
+if [ "$#" -eq 0 ]; then
+  spec
+else
+  query "$1"
+fi

.github/scripts/cache-keys.unit.spec.ts

@@ -0,0 +1,80 @@
+import { execFileSync } from "child_process";
+import { join } from "path";
+
+const SCRIPT = join(__dirname, "cache-keys.sh");
+
+const CACHES = ["m2", "bun-store", "cypress", "eslint"];
+
+// stderr is inherited by default, so the deliberate-failure case below would print a literal
+// `::error::` line - which GitHub Actions reads as an annotation directive, making a passing run
+// annotate itself with an error.
+const run = (args: string[] = [], env: NodeJS.ProcessEnv = {}, quiet = false) =>
+  execFileSync(SCRIPT, args, {
+    encoding: "utf8",
+    stdio: quiet ? ["ignore", "pipe", "ignore"] : "pipe",
+    env: { ...process.env, RUNNER_OS: "Linux", GITHUB_SHA: "abc123", ...env },
+  });
+
+const get = (name: string, env: NodeJS.ProcessEnv = {}) =>
+  run([name], env).trimEnd();
+
+describe("cache-keys.sh", () => {
+  it("is deterministic for a given tree", () => {
+    expect(run()).toEqual(run());
+  });
+
+  it("emits every cache's path, key and restore key", () => {
+    for (const cache of CACHES) {
+      expect(get(`${cache}-path`)).not.toEqual("");
+      expect(get(`${cache}-key`)).not.toEqual("");
+      expect(get(`${cache}-restore-key`)).not.toEqual("");
+    }
+  });
+
+  // Silently returning "" for a name that does not exist is how a caller ends up building a key with a
+  // hole in it.
+  it("fails on an unknown output name", () => {
+    expect(() => run(["no-such-output"], {}, true)).toThrow();
+  });
+
+  // A key equal to its own restore prefix points every dependency set at one entry, and nothing reports
+  // it. This is the failure the script exists to prevent.
+  it("never emits a key equal to its own restore prefix", () => {
+    for (const cache of CACHES) {
+      const key = get(`${cache}-key`);
+      const prefix = get(`${cache}-restore-key`);
+      expect(key.startsWith(prefix)).toBe(true);
+      expect(key.length).toBeGreaterThan(prefix.length);
+    }
+  });
+
+  it("scopes every key to the runner OS", () => {
+    for (const cache of CACHES) {
+      expect(get(`${cache}-key`, { RUNNER_OS: "Linux" })).not.toEqual(
+        get(`${cache}-key`, { RUNNER_OS: "macOS" }),
+      );
+    }
+  });
+
+  // Home paths must be absolute: actions/cache expands a tilde but a shell assigning one to a variable
+  // does not, and would create a directory literally named `~`.
+  it("emits absolute paths for home directory locations", () => {
+    expect(get("bun-store-path").startsWith("/")).toBe(true);
+    expect(get("cypress-path").startsWith("/")).toBe(true);
+    for (const line of get("m2-path").split("\n")) {
+      expect(line.startsWith("~")).toBe(false);
+    }
+  });
+
+  // The Cypress binary depends on the Cypress version alone, so an unrelated dependency bump must not
+  // invalidate a 200MB download.
+  it("keys the Cypress binary on the resolved version, not the lockfile", () => {
+    expect(get("cypress-key")).toMatch(/^cypress-Linux-\d+\.\d+\.\d+/);
+  });
+
+  it("keys the ESLint cache on the commit", () => {
+    expect(get("eslint-key", { GITHUB_SHA: "deadbeef" })).toEqual(
+      "eslint-Linux-deadbeef",
+    );
+  });
+});

.github/scripts/check-job-timeouts.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Fails when a job in .github/workflows/ does not set `timeout-minutes`.
+#
+# Without it a job inherits GitHub's 6-hour default, so a hung job burns six hours of runner time -
+# and holds up everything queued behind it - before anyone notices. actionlint cannot check this: its
+# rule set is compiled in and .github/actionlint.yaml only takes `self-hosted-runner`,
+# `config-variables`, and `paths` (which suppresses findings rather than adding them). Hence this
+# script.
+#
+# The rule is per job: a `timeout-minutes` on a step does not satisfy it, and steps are not required
+# to carry one of their own.
+#
+# Jobs that call a reusable workflow (`uses:` at the job level) are skipped - GitHub rejects
+# `timeout-minutes` there. The called workflow's own jobs are checked when it lives in this repo.
+#
+#   .github/scripts/check-job-timeouts.sh [workflow-file ...]
+#
+# With no arguments it checks every workflow; CI passes the files that changed, like actionlint does.
+
+set -euo pipefail
+
+# Arguments are used as given, so the paths in the annotations match what the caller passed. Without
+# them the full scan has to run from the repo root.
+if [ $# -gt 0 ]; then
+  workflows=("$@")
+else
+  cd "$(git rev-parse --show-toplevel)"
+
+  shopt -s nullglob
+  workflows=(.github/workflows/*.yml .github/workflows/*.yaml)
+
+  if [ ${#workflows[@]} -eq 0 ]; then
+    echo "::error::check-job-timeouts.sh: no workflow files found under .github/workflows/" >&2
+    exit 1
+  fi
+fi
+
+status=0
+
+for file in "${workflows[@]}"; do
+  # `awk NF` drops the blank line yq emits when a file has nothing to report.
+  missing="$(
+    # --header-preprocess=false: yq otherwise slurps any leading comment block before parsing, which
+    # shifts every line number it reports by the size of that block.
+    yq --header-preprocess=false '
+      .jobs
+      | to_entries
+      | .[]
+      | select(((.value | has("timeout-minutes")) or (.value | has("uses"))) | not)
+      | [(.key | line), .key]
+      | @tsv
+    ' "$file" | awk NF
+  )"
+
+  [ -n "$missing" ] || continue
+
+  while IFS=$'\t' read -r line job; do
+    echo "::error file=${file},line=${line}::Job \"${job}\" does not set a job-level timeout-minutes" >&2
+  done <<< "$missing"
+
+  status=1
+done
+
+if [ "$status" -ne 0 ]; then
+  echo >&2
+  echo "Every job must set an explicit timeout-minutes; without one it inherits GitHub's 6-hour default." >&2
+  echo "Pick a value with headroom over the job's normal runtime." >&2
+  exit 1
+fi
+
+echo "All jobs in the ${#workflows[@]} workflow file(s) checked set timeout-minutes."

.github/scripts/check-preresolve-aliases.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# Fails when a Clojure classpath used by CI is not pre-resolved by cache-warm.
+#
+# tools.deps selects dependency versions globally per classpath, so two alias combinations can resolve
+# the same transitive library to different versions. A combination the warm job never resolved is
+# therefore not merely absent from the cache - the cache holds *a* version of those libraries, just not
+# the one this classpath wants, and the job fetches its delta straight from Maven Central on every run.
+# That is the intermittent-403 failure of DEV-2094, and it is invisible: the build still passes.
+#
+# Nothing about a missing combination shows up at runtime, so this check is the only thing standing
+# between a newly added alias combination and a permanently half-cold cache.
+#
+#   .github/scripts/check-preresolve-aliases.sh
+
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)"
+
+WARM=.github/workflows/cache-warm.yml
+
+# Invocations deliberately left out of the warm job. Each needs a reason, because the default answer is
+# to add the combination to the list instead.
+WAIVED="$(
+  cat <<'EOF'
+:deps
+:outdated
+EOF
+)"
+# :deps      - tools.deps built-in used by write-poms.sh; contributes no dependencies of its own.
+# :outdated  - scheduled dependency-bump workflow only; a cold resolve there costs nothing anyone waits on.
+
+# Dependency roots and alias combinations the warm job pre-resolves.
+declared="$({
+  sed -n '/^[[:space:]]*combos=(/,/^ *)/p' "$WARM" \
+    | grep -oE '":[^"]*"' \
+    | tr -d '"' \
+    | sed 's#^#.|#'
+  sed -n '/^[[:space:]]*nested_combos=(/,/^ *)/p' "$WARM" \
+    | grep -oE '"[^"]+\|:[^"]+"' \
+    | tr -d '"'
+} | sort -u)"
+if [ -z "$declared" ]; then
+  echo "::error::check-preresolve-aliases.sh: found no pre-resolved classpaths in $WARM" >&2
+  exit 1
+fi
+
+# Expressions we know how to expand. An unrecognised one has to stop the check rather than be skipped:
+# silently ignoring it is how a whole matrix of combinations would go unchecked.
+unknown="$(grep -rhoE '\$\{\{[^}]*\}\}' --include='*' \
+             --exclude='*.png' --exclude='*.jpg' .github/ 2>/dev/null \
+           | sort -u | grep -v 'edition' || true)"
+
+scan() { # scan <edition>: dependency root and aliases used by .github Clojure invocations
+  grep -rhE 'clojure[[:space:]]+(-P[[:space:]]+)?-[XMATP]?:' \
+       --include='*' --exclude='*.png' --exclude='*.jpg' .github/ 2>/dev/null \
+    | sed "s/\\\${{[^}]*edition[^}]*}}/$1/g" \
+    | grep -oE 'clojure[[:space:]]+(-P[[:space:]]+)?-[XMATP]?:[A-Za-z0-9:_./-]+' \
+    | grep -oE ':[A-Za-z0-9:_./-]+' \
+    | sed -e 's/:$//' -e 's#^#.|#'
+}
+
+scan_project_tests() { # scan_project_tests <function> <dependency-root>
+  # Mage shell commands are vectors split across lines, so flatten each function body before
+  # extracting its alias.
+  sed -n "/(defn- $1 /,/^(defn/p" mage/src/mage/project_tests.clj \
+    | tr '\n' ' ' \
+    | grep -oE '"clojure"[[:space:]]+("-P"[[:space:]]+)?"-[XMATP]?:[A-Za-z0-9:_./-]+' \
+    | grep -oE ':[A-Za-z0-9:_./-]+' \
+    | sed -e 's/:$//' -e "s#^#$2|#"
+}
+
+# Check each scan separately. One scan still finding commands would otherwise conceal that another has
+# stopped matching, which silently drops everything it used to cover.
+require_scan() { # require_scan <what> <result>
+  [ -n "$2" ] && return
+  echo "::error::check-preresolve-aliases.sh: found no Clojure invocation in $1; the scan pattern no longer matches" >&2
+  exit 1
+}
+workflow_checks=$( { scan ee; scan oss; } || true)
+clojure_checks=$(scan_project_tests run-clojure-checks! . || true)
+migration_checks=$(scan_project_tests run-migration-checks! bin/lint-migrations-file || true)
+require_scan ".github/" "$workflow_checks"
+require_scan "run-clojure-checks! (mage/src/mage/project_tests.clj)" "$clojure_checks"
+require_scan "run-migration-checks! (mage/src/mage/project_tests.clj)" "$migration_checks"
+
+scanned="$(printf '%s\n' "$workflow_checks" "$clojure_checks" "$migration_checks" | sort -u)"
+
+found="$( {
+  printf '%s\n' "$scanned"
+  # build-scripts.yml runs this classpath from its own dependency root.
+  printf '%s\n' 'bin/load-namespaces|:test'
+} | sort -u )"
+
+covered="$( {
+  printf '%s\n' "$declared"
+  printf '%s\n' "$WAIVED" | sed 's#^#.|#'
+} | sort -u)"
+missing="$(comm -23 <(printf '%s\n' "$found") <(printf '%s\n' "$covered") || true)"
+
+if [ -n "$missing" ]; then
+  echo "::error::Clojure classpaths used by CI that cache-warm does not pre-resolve:" >&2
+  printf '%s\n' "$missing" | sed 's/^/  /' >&2
+  echo >&2
+  echo "Add each to the matching root or nested combo list in $WARM, or waive it here with a reason." >&2
+  echo "Leaving it uncovered means those jobs re-fetch their version deltas from Maven on every run." >&2
+  exit 1
+fi
+
+echo "All $(printf '%s\n' "$found" | grep -c .) Clojure classpaths used by CI are pre-resolved."

.github/scripts/conventional-commit-pr-title-reminder/utils.js

@@ -1,109 +0,0 @@
-const TYPES = new Set([
-  "feat",
-  "fix",
-  "perf",
-  "docs",
-  "style",
-  "refactor",
-  "test",
-  "build",
-  "ci",
-]);
-
-/**
- * @param title {string}
- */
-function isConventionalTitle(title) {
-  const match = /^(?<type>\w+)\((?<rawScopes>[^)]+)\):/.exec(title);
-
-  if (!match) {
-    return false;
-  }
-
-  const [, type, rawScopes] = match;
-  const scopes = rawScopes
-    .split(",")
-    .map((scope) => scope.trim())
-    .filter(Boolean);
-
-  return TYPES.has(type) && scopes.length > 0;
-}
-
-/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */
-async function updateCommentForEmbedding({ github, context }) {
-  const githubUsername = context.payload.sender.login;
-
-  const comment = `${CONVENTIONAL_COMMENT_IDENTIFIER}
-@${githubUsername} You have modified embedding code. Please make sure the PR title follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) style.
-Here are all the supported types:
-- \`feat\`
-- \`fix\`
-- \`perf\`
-- \`docs\`
-- \`style\`
-- \`refactor\`
-- \`test\`
-- \`build\`
-- \`ci\`
-
-Please also make sure to include a scope.
-
-For example, these are valid PR titles:
-- \`feat(sdk-bundle): Add interactive dashboard component\`
-- \`fix(sdk-package): Fixed MetabaseProviderPropsStore logic\`
-- \`fix(sdk-package, embed-js): Fix API\``;
-
-  return updateComment(comment, { github, context });
-}
-
-/**
- * @param comment {string}
- * @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments
- */
-async function updateComment(comment, { github, context }) {
-  const owner = context.repo.owner;
-  const repo = context.repo.repo;
-  const pullRequestNumber = context.issue.number;
-  const comments = await github.rest.issues.listComments({
-    owner,
-    repo,
-    issue_number: pullRequestNumber,
-  });
-
-  const existingComment = getExistingConventionalCommitReminderComment(
-    comments.data,
-  );
-
-  if (existingComment) {
-    return await github.rest.issues.updateComment({
-      owner,
-      repo,
-      comment_id: existingComment.id,
-      body: comment,
-    });
-  } else {
-    return await github.rest.issues.createComment({
-      owner,
-      repo,
-      issue_number: pullRequestNumber,
-      body: comment,
-    });
-  }
-}
-
-const CONVENTIONAL_COMMENT_IDENTIFIER =
-  "<!---conventional comment identifier-->";
-
-/**
- * @param comments {{body: string}[]}
- */
-function getExistingConventionalCommitReminderComment(comments) {
-  for (const comment of comments) {
-    if (comment.body.startsWith(CONVENTIONAL_COMMENT_IDENTIFIER)) {
-      return comment;
-    }
-  }
-}
-
-exports.isConventionalTitle = isConventionalTitle;
-exports.updateCommentForEmbedding = updateCommentForEmbedding;

.github/scripts/conventional-commit-pr-title-reminder/utils.unit.spec.js

@@ -1,45 +0,0 @@
-const { isConventionalTitle } = require("./utils");
-
-describe("isConventionalTitle", () => {
-  it("returns true for a simple conventional commit", () => {
-    expect(isConventionalTitle("feat: add new feature")).toBe(false);
-  });
-
-  it("returns true for a commit with a scope", () => {
-    expect(isConventionalTitle("fix(api): correct API bug")).toBe(true);
-  });
-
-  it("returns true for a commit with multiple scopes, comma separated", () => {
-    expect(isConventionalTitle("feat(build,deps): update dependencies")).toBe(
-      true,
-    );
-  });
-
-  it("returns true for a commit with multiple scopes, comma separated with space", () => {
-    expect(isConventionalTitle("feat(build, deps): update dependencies")).toBe(
-      true,
-    );
-  });
-
-  it("returns false for a commit with round brackets in a message", () => {
-    expect(isConventionalTitle("feat: (something) update dependencies")).toBe(
-      false,
-    );
-  });
-
-  it("returns false for missing colon", () => {
-    expect(isConventionalTitle("feat add feature")).toBe(false);
-  });
-
-  it("returns false for invalid type", () => {
-    expect(isConventionalTitle("invalidType: some message")).toBe(false);
-  });
-
-  it("returns false for empty message", () => {
-    expect(isConventionalTitle("feat:")).toBe(false);
-  });
-
-  it("returns false for empty input", () => {
-    expect(isConventionalTitle("")).toBe(false);
-  });
-});

.github/scripts/create-test-plan.ts

@@ -1,67 +1,118 @@
-// Changed files come from dorny/paths-filter's `all_changed_files` output
+// I/O entrypoint: gather inputs (env vars, the cruise graph, the test-file
+// lists) and hand them to createTestPlan, which does the computing.
 
 import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+
+import micromatch from "micromatch";
 
 import { elements, rules } from "../../frontend/lint/module-boundaries.mjs";
 
-import { TEST_SUITES, createTestPlan } from "./affected-tests";
+import { type FileDependency, parseCruiseModules } from "./affected-modules";
+import { createTestPlan } from "./affected-tests";
+import { listSpecFiles } from "./e2e-spec-globs.mjs";
 
+const UNIT_ROOTS = ["frontend/src", "enterprise/frontend/src"];
 const UNIT_GLOBS = [
-  "frontend/src/**/*.unit.spec.js",
-  "frontend/src/**/*.unit.spec.jsx",
-  "frontend/src/**/*.unit.spec.ts",
-  "frontend/src/**/*.unit.spec.tsx",
-  "enterprise/frontend/src/**/*.unit.spec.js",
-  "enterprise/frontend/src/**/*.unit.spec.jsx",
-  "enterprise/frontend/src/**/*.unit.spec.ts",
-  "enterprise/frontend/src/**/*.unit.spec.tsx",
+  "frontend/src/**/*.unit.spec.{js,jsx,ts,tsx}",
+  "enterprise/frontend/src/**/*.unit.spec.{js,jsx,ts,tsx}",
 ];
 
+const STORY_ROOTS = ["frontend", "enterprise/frontend"];
 const STORY_GLOBS = [
-  "frontend/**/*.stories.js",
-  "frontend/**/*.stories.jsx",
-  "frontend/**/*.stories.ts",
-  "frontend/**/*.stories.tsx",
-  "enterprise/frontend/**/*.stories.js",
-  "enterprise/frontend/**/*.stories.jsx",
-  "enterprise/frontend/**/*.stories.ts",
-  "enterprise/frontend/**/*.stories.tsx",
+  "frontend/**/*.stories.{js,jsx,ts,tsx}",
+  "enterprise/frontend/**/*.stories.{js,jsx,ts,tsx}",
 ];
 
-const E2E_GLOBS = [
-  "e2e/test/scenarios/**/*.cy.spec.js",
-  "e2e/test/scenarios/**/*.cy.spec.jsx",
-  "e2e/test/scenarios/**/*.cy.spec.ts",
-  "e2e/test/scenarios/**/*.cy.spec.tsx",
-];
+// `git ls-files -- frontend enterprise/frontend` already prints just over a
+// megabyte of paths, and node's default maxBuffer is exactly 1 MiB: past that
+// the spawn dies with ENOBUFS. Give the listings room to grow.
+const LS_FILES_MAX_BUFFER = 64 * 1024 * 1024;
 
-function listFiles(globs: string[]): string[] {
-  return execFileSync("git", ["ls-files", "--", ...globs], { encoding: "utf8" })
+// Returns the tracked files under `roots` that match `globs`. The `dot: true`
+// option means files inside dot-directories such as `.storybook` are included.
+function listFiles(roots: string[], globs: string[]): string[] {
+  const tracked = execFileSync("git", ["ls-files", "--", ...roots], {
+    encoding: "utf8",
+    maxBuffer: LS_FILES_MAX_BUFFER,
+  })
     .split("\n")
     .map((line) => line.trim())
     .filter(Boolean);
+  return micromatch(tracked, globs, { dot: true });
 }
 
-const changedFiles = (process.env.CHANGED_FILES ?? "")
-  .split(",")
-  .map((s) => s.trim())
-  .filter(Boolean);
+// dorny outputs comma-separated lists; CHANGED_FILES is `all_changed_files`.
+const csvToList = (csv: string | undefined) =>
+  (csv ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+// Reads the dependency-cruiser graph (DEP_GRAPH_JSON). Null falls back to the
+// rules graph, so a missing or unparseable file never breaks the plan.
+function readFileDependencies(): FileDependency[] | null {
+  const path = process.env.DEP_GRAPH_JSON;
+  if (path && existsSync(path)) {
+    try {
+      const { modules } = JSON.parse(readFileSync(path, "utf8"));
+      process.stderr.write(`Using usage graph from ${path}.\n`);
+      return parseCruiseModules(modules);
+    } catch (error) {
+      process.stderr.write(
+        `Failed to read ${path}; falling back to rules graph: ${error}\n`,
+      );
+    }
+  } else {
+    process.stderr.write(
+      "No DEP_GRAPH_JSON found; falling back to rules graph.\n",
+    );
+  }
+  return null;
+}
+
+// Reads the nightly coverage manifest (E2E_SPEC_MANIFEST): { builtAt, specs:
+// { spec -> files } }. Returns the specs map, or null so e2e falls back to a
+// full run when the manifest is missing/unparseable.
+function readE2eSpecFiles(): Record<string, string[]> | null {
+  const path = process.env.E2E_SPEC_MANIFEST;
+  if (path && existsSync(path)) {
+    try {
+      const { specs } = JSON.parse(readFileSync(path, "utf8"));
+      if (specs && typeof specs === "object") {
+        process.stderr.write(`Using e2e coverage manifest from ${path}.\n`);
+        return specs;
+      }
+    } catch (error) {
+      process.stderr.write(
+        `Failed to read ${path}; e2e will run in full: ${error}\n`,
+      );
+    }
+  } else {
+    process.stderr.write("No E2E_SPEC_MANIFEST found; e2e will run in full.\n");
+  }
+  return null;
+}
 
 const testPlan = createTestPlan({
   elements,
   rules,
-  testSuites: TEST_SUITES,
-  changedFiles,
+  changedFiles: csvToList(process.env.CHANGED_FILES),
+  fileDependencies: readFileDependencies(),
   testFilesBySuite: {
-    unit: listFiles(UNIT_GLOBS),
-    loki: listFiles(STORY_GLOBS),
-    e2e: listFiles(E2E_GLOBS),
-  },
-  infraTouchedBySuite: {
-    unit: process.env.UNIT_INFRA_TOUCHED === "true",
-    loki: process.env.LOKI_INFRA_TOUCHED === "true",
-    e2e: false,
+    unit: listFiles(UNIT_ROOTS, UNIT_GLOBS),
+    loki: listFiles(STORY_ROOTS, STORY_GLOBS),
+    e2e: listSpecFiles(),
   },
+  e2eSpecFiles: readE2eSpecFiles(),
+  unitInfraTouched: process.env.UNIT_INFRA_TOUCHED === "true",
+  lokiInfraTouched: process.env.LOKI_INFRA_TOUCHED === "true",
+  e2eInfraTouched: process.env.E2E_INFRA_TOUCHED === "true",
+  sharedSourcesTouched: process.env.SHARED_SOURCES_TOUCHED === "true",
+  feFilesChanged: csvToList(process.env.FE_CHANGED_FILES).length,
+  beFilesChanged: csvToList(process.env.BE_CHANGED_FILES).length,
+  feFilesTotal: listFiles(["frontend", "enterprise/frontend"], ["**"]).length,
+  beFilesTotal: listFiles(["src", "enterprise/backend"], ["**"]).length,
 });
 
 process.stdout.write(JSON.stringify(testPlan) + "\n");

.github/scripts/csv-to-mb.js

@@ -1,41 +0,0 @@
-/**
- * jsonData must be in the format:
- * [
- *   { column1: value1, column2: value2, ... },
- *   { column1: value3, column2: value4, ... },
- *   ...
- * ]
- */
-function jsonToCsvFormData(jsonData) {
-  const formData = new FormData();
-  const csvHeader = Object.keys(jsonData[0]).join(',') + '\n';
-  const csvContent = jsonData.map(row =>
-    Object.values(row).map(value => `"${String(value).replace(/"/g, '""')}"`).join(',')
-  ).join('\n');
-
-  const blob = new Blob([csvHeader + csvContent], { type: 'text/csv' });
-  formData.append('file', blob, 'data.csv');
-
-  return formData;
-}
-
-async function uploadCsvToMb({ baseUrl, tableId, jsonData, mode = 'append' }) {
-  const formData = jsonToCsvFormData(jsonData);
-  const operation = mode === 'replace' ? 'replace-csv' : 'append-csv';
-
-  const response = await fetch(`${baseUrl}/api/table/${tableId}/${operation}`, {
-    method: 'POST',
-    headers: {
-      "x-api-key": process.env.API_KEY
-    },
-    body: formData
-  });
-
-  if (!response.ok) {
-    const body = await response.text().catch(() => '');
-    throw new Error(`Upload failed: ${response.status} ${response.statusText} ${body}`.trim());
-  }
-  return { success: true };
-}
-
-module.exports = { uploadCsvToMb };

.github/scripts/e2e-spec-globs.mjs

@@ -0,0 +1,32 @@
+import { execFileSync } from "node:child_process";
+
+import micromatch from "micromatch";
+
+const SPEC_DIR = "e2e/test/scenarios";
+
+// This is the nightly-only baseline helper that runs in the instrumented pass to
+// capture boot-time coverage. It is not a product spec, so it is excluded from
+// the test plan universe and from the manifest backfill reconciliation.
+export const BASELINE_SPEC = `${SPEC_DIR}/coverage-baseline.cy.spec.js`;
+
+// This glob set defines the spec "universe". The test planner
+// (create-test-plan.ts) selects which specs to run from it, and the coverage
+// manifest builder (build-coverage-manifest.mjs) reconciles against it when
+// backfilling specs that did not run.
+export const E2E_SPEC_GLOBS = [`${SPEC_DIR}/**/*.cy.spec.{js,jsx,ts,tsx}`];
+
+// Returns the tracked e2e specs as repo-relative paths, excluding the baseline
+// helper.
+export function listSpecFiles(cwd = process.cwd()) {
+  const tracked = execFileSync("git", ["ls-files", "--", SPEC_DIR], {
+    cwd,
+    encoding: "utf8",
+  })
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return micromatch(tracked, E2E_SPEC_GLOBS, {
+    ignore: [BASELINE_SPEC],
+    dot: true,
+  });
+}

.github/scripts/file-paths.unit.spec.ts

@@ -0,0 +1,66 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+
+import { load } from "js-yaml";
+import { isMatch } from "micromatch";
+
+const FILTERS = join(__dirname, "..", "file-paths.yaml");
+
+type Filter = string | Filter[] | { [changeType: string]: Filter };
+
+// A filter is a list of patterns, and an entry may name the change types it applies to as
+// { "added|modified": pattern }. Either way the patterns are what matters here.
+const patterns = (value: Filter): string[] => {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.flatMap(patterns);
+  return Object.values(value).flatMap(patterns);
+};
+
+describe("file-paths.yaml", () => {
+  const filters = load(readFileSync(FILTERS, "utf8")) as Record<string, Filter>;
+
+  // dorny/paths-filter matches with picomatch, which micromatch wraps, so this asks the same
+  // question CI asks of a changed path.
+  const matches = (name: string, path: string) =>
+    patterns(filters[name]).some((pattern) =>
+      isMatch(path, pattern, { dot: true }),
+    );
+
+  // dorny/paths-filter ORs the patterns in a filter, so a "!..." entry does not subtract from the
+  // other entries - it matches every path they don't, turning the filter permanently on. Excluding
+  // a path means writing the exclusion inside one pattern, the way backend_sources keeps
+  // ratchet files out with ".clj-kondo/**/!(ratchets.edn)".
+  it("never excludes a path with a standalone negation", () => {
+    const negated = Object.entries(filters).flatMap(([name, filter]) =>
+      patterns(filter)
+        .filter((pattern) => pattern.startsWith("!"))
+        .map((pattern) => `${name}: ${pattern}`),
+    );
+
+    expect(negated).toEqual([]);
+  });
+
+  it.each(["backend_sources", "backend_all"])(
+    "%s skips a ratchets-only change and still follows the rest of .clj-kondo",
+    (name) => {
+      expect(matches(name, ".clj-kondo/ratchets.edn")).toBe(false);
+      expect(
+        matches(name, ".clj-kondo/config/modules/ratchets.edn"),
+      ).toBe(false);
+      expect(matches(name, ".clj-kondo/config.edn")).toBe(true);
+      expect(matches(name, ".clj-kondo/config/modules/config.edn")).toBe(true);
+    },
+  );
+
+  it("runs the ratchet check on the ratchets file", () => {
+    expect(matches("project_ratchet_checks", ".clj-kondo/ratchets.edn")).toBe(
+      true,
+    );
+    expect(
+      matches(
+        "project_ratchet_checks",
+        ".clj-kondo/config/modules/ratchets.edn",
+      ),
+    ).toBe(true);
+  });
+});

.github/scripts/find-linear-issue.js

@@ -1,40 +0,0 @@
-async function findLinearIssue({ githubIssueUrl, linearApiKey }) {
-  const response = await fetch("https://api.linear.app/graphql", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: linearApiKey,
-    },
-    body: JSON.stringify({
-      query: `
-        query {
-          attachmentsForURL(url: "${githubIssueUrl}") {
-            nodes {
-              issue { identifier }
-            }
-          }
-        }
-      `,
-    }),
-  });
-
-  const data = await response.json();
-
-  if (!response.ok) {
-    return { success: false, message: `Linear API error: ${response.status}` };
-  }
-
-  if (!data.data?.attachmentsForURL?.nodes?.length) {
-    return {
-      success: false,
-      message: `No Linear issue linked to ${githubIssueUrl}`,
-    };
-  }
-
-  return {
-    success: true,
-    issue: data.data.attachmentsForURL.nodes[0].issue.identifier,
-  };
-}
-
-module.exports = { findLinearIssue };

.github/scripts/fix-yarn-lock-aliases.ts

@@ -0,0 +1,66 @@
+/**
+ * Renames aliased dependency keys in a bun-generated yarn.lock.
+ *
+ * Yarn names an alias entry after the alias, for example
+ * `"typescript7@npm:typescript@7.0.2"`. Bun names it after the aliased package
+ * instead, for example `"typescript@npm:typescript@7.0.2"`. Snyk follows the
+ * yarn convention and fails to resolve the dependency.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+
+async function main() {
+  const packageJsonPath = `${process.cwd()}/package.json`;
+  const lockPath = `${process.cwd()}/yarn.lock`;
+
+  const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+
+  const dependencies = Object.entries<string>(
+    Object.assign(
+      {},
+      packageJson.dependencies,
+      packageJson.devDependencies,
+      packageJson.optionalDependencies,
+    ),
+  );
+
+  let lock = await readFile(lockPath, "utf8");
+  const renamedKeys: string[] = [];
+
+  for (const [alias, specifier] of dependencies) {
+    if (!specifier.startsWith("npm:")) {
+      continue;
+    }
+
+    const aliasedPackage = specifier
+      .slice("npm:".length)
+      .replace(/@[^@]*$/, "");
+
+    if (aliasedPackage === alias) {
+      continue;
+    }
+
+    const bunKey = `"${aliasedPackage}@${specifier}"`;
+    const yarnKey = `"${alias}@${specifier}"`;
+
+    if (lock.includes(bunKey)) {
+      lock = lock.replaceAll(bunKey, yarnKey);
+      renamedKeys.push(`${bunKey} -> ${yarnKey}`);
+    }
+  }
+
+  if (renamedKeys.length > 0) {
+    await writeFile(lockPath, lock);
+  }
+
+  process.stdout.write(
+    renamedKeys.length > 0
+      ? `Renamed alias keys in yarn.lock:\n${renamedKeys.join("\n")}\n`
+      : "No alias keys to rename in yarn.lock\n",
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`Failed to rename alias keys in yarn.lock: ${error}\n`);
+  process.exit(1);
+});