Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

feat(console): editable backend dashboards — panel schema + first-launch seeding + CRUD gaps

xerj-org7dc184c8df1c
diff --git a/engine/crates/xerj-console-api/src/bootstrap.rs b/engine/crates/xerj-console-api/src/bootstrap.rs
index 9e57d43d0..ab632efd5 100644
--- a/engine/crates/xerj-console-api/src/bootstrap.rs
+++ b/engine/crates/xerj-console-api/src/bootstrap.rs
@@ -52,6 +52,12 @@ pub async fn run(
indices::ensure_all(engine)?;
+ // Materialise the built-in dashboards as editable backend data. Idempotent
+ // and safe on every boot: creates any missing default, never clobbers an
+ // operator's edits, and only re-syncs untouched defaults when the shipped
+ // seed revision is bumped. See `crate::seed`.
+ crate::seed::seed_default_dashboards(engine).await?;
+
let magic_link = if has_any_active_user(engine).await? {
None
} else {
diff --git a/engine/crates/xerj-console-api/src/dashboards.rs b/engine/crates/xerj-console-api/src/dashboards.rs
index 6d7457aa7..c5fea87a1 100644
--- a/engine/crates/xerj-console-api/src/dashboards.rs
+++ b/engine/crates/xerj-console-api/src/dashboards.rs
@@ -34,6 +34,44 @@ use crate::response::{created, no_content, ok};
use crate::state::ConsoleState;
use crate::time::now_iso;
+/// A durable dashboard.
+///
+/// # Panel schema (convention inside `panels[]`)
+///
+/// The engine stores `panels` **opaquely** — it is a `Vec<Value>` here and an
+/// untyped array in the mapping (deliberately *not* typed in
+/// [`crate::indices`]). The frontend panel-builder and the seeding module
+/// ([`crate::seed`]) agree on this shape, and it round-trips through
+/// create/replace/patch byte-for-byte:
+///
+/// ```jsonc
+/// {
+/// "id": "queries", // stable & unique within the dashboard
+/// "type": "metric|line|topn|heatmap|table|events|markdown|ribbon3d|…",
+/// "title": "LLM QUERIES", // supersedes the old `eyebrow`
+/// "layout": { "x": 0, "y": 0, "w": 4, "h": 2 },
+/// // FREE-FORM grid: x/w in 12-col units, y/h in row units. Subsumes
+/// // the old bare `cols` (== w) and enables drag / move / resize /
+/// // height.
+/// "query": { // null for static panels (markdown)
+/// "index": "logs-*",
+/// "time_field": "@timestamp",
+/// "dsl": { /* ES query DSL — reuses the ES-compat search port */ },
+/// "aggs": { /* ES aggs */ }
+/// },
+/// "viz": { "unit": "queries", "value_field": "…", "spark": true, … },
+/// // type-specific display config
+/// "drilldown": { "to": "<dashId>", "filter_field": "intent" } | null,
+/// "builtin": "ai-overview/queries" | null
+/// // provenance key for seeded panels still resolved through the
+/// // shipped mock renderer; null for user-authored data-driven panels.
+/// }
+/// ```
+///
+/// Per-panel geometry, query, and viz all live here; the dashboard-level time
+/// / filter context lives in the top-level `time_default` + `filters_default`.
+/// There is intentionally **no per-panel PATCH**: `panels` replaces wholesale
+/// (dashboards are small — the frontend sends the full array on save).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Dashboard {
pub id: String,
@@ -42,8 +80,16 @@ pub struct Dashboard {
pub org_id: String,
/// `private` (only owner sees / writes), `shared` (every user in
/// the org reads, only `editor` and up writes), `default` (engine-
- /// provisioned read-only built-in dashboards).
+ /// provisioned built-in dashboards — editable by admin/owner, never
+ /// deletable; see `managed`).
pub visibility: String,
+ /// `true` for engine-seeded built-in dashboards ([`crate::seed`]). A
+ /// managed doc is editable by admin/owner (so layout/title/panel edits
+ /// persist) but cannot be deleted, and re-seed leaves it alone once it has
+ /// been edited (`version > 1`). User-authored dashboards are always
+ /// `managed: false` — clients cannot mint a managed doc through `create`.
+ #[serde(default)]
+ pub managed: bool,
pub name: String,
#[serde(default)]
pub section: Option<String>,
@@ -107,6 +153,11 @@ pub struct PatchBody {
pub filters_default: Option<Value>,
#[serde(default)]
pub time_default: Option<String>,
+ /// Accepted for a full-object round-trip, but only applied when the caller
+ /// is admin/owner (see `apply_managed`). `owner` / `org_id` / `created_at`
+ /// are intentionally absent — they are create-only and never patchable.
+ #[serde(default)]
+ pub managed: Option<bool>,
}
// ─────────────────────────────────────────────────────────────────────────────
@@ -171,7 +222,7 @@ pub async fn create(
sess: AuthSession,
Json(body): Json<CreateBody>,
) -> ConsoleResult<Response> {
- enforce_can_write_visibility(&sess, &body.visibility)?;
+ enforce_can_set_visibility(&sess, &body.visibility, None)?;
let id = uuid::Uuid::new_v4().to_string();
let now = now_iso();
let dash = Dashboard {
@@ -179,6 +230,9 @@ pub async fn create(
owner: sess.user.id.clone(),
org_id: default_org(),
visibility: body.visibility,
+ // Clients never mint managed docs — only the seeder (and the
+ // admin/owner-only `_bulk` path) can set `managed: true`.
+ managed: false,
name: body.name,
section: body.section,
group: body.group,
@@ -215,6 +269,21 @@ pub struct ReplaceBody {
pub filters_default: Value,
#[serde(default)]
pub time_default: Option<String>,
+ /// See [`PatchBody::managed`] — applied only for admin/owner; create-only
+ /// fields (`owner`/`org_id`/`created_at`) are never accepted here.
+ #[serde(default)]
+ pub managed: Option<bool>,
+}
+
+/// Body for `POST /dashboards/_bulk` — whole-set save + uniform seeding path.
+#[derive(Debug, Deserialize, Default)]
+pub struct BulkBody {
+ /// Full dashboard objects (each MUST carry an `id`); upserted in place.
+ #[serde(default)]
+ pub upserts: Vec<Value>,
+ /// Ids to soft-delete.
+ #[serde(default)]
+ pub deletes: Vec<String>,
}
pub async fn replace(
@@ -227,7 +296,7 @@ pub async fn replace(
let mut dash = read_required(&state, &id).await?;
enforce_write(&sess, &dash)?;
enforce_etag(&headers, dash.version)?;
- enforce_can_write_visibility(&sess, &body.visibility)?;
+ enforce_can_set_visibility(&sess, &body.visibility, Some(&dash.visibility))?;
dash.name = body.name;
dash.visibility = body.visibility;
@@ -236,6 +305,7 @@ pub async fn replace(
dash.panels = body.panels;
dash.filters_default = body.filters_default;
dash.time_default = body.time_default;
+ apply_managed(&sess, &mut dash, body.managed);
dash.version += 1;
dash.updated_at = now_iso();
@@ -263,7 +333,7 @@ pub async fn patch(
dash.name = name;
}
if let Some(visibility) = body.visibility {
- enforce_can_write_visibility(&sess, &visibility)?;
+ enforce_can_set_visibility(&sess, &visibility, Some(&dash.visibility))?;
dash.visibility = visibility;
}
if let Some(section) = body.section {
@@ -281,6 +351,7 @@ pub async fn patch(
if let Some(td) = body.time_default {
dash.time_default = Some(td);
}
+ apply_managed(&sess, &mut dash, body.managed);
dash.version += 1;
dash.updated_at = now_iso();
@@ -300,6 +371,14 @@ pub async fn delete(
Path(id): Path<String>,
) -> ConsoleResult<Response> {
let mut dash = read_required(&state, &id).await?;
+ // Seeded / managed defaults are editable but not deletable, so a re-seed
+ // always has a canonical row to keep in sync and an operator can't nuke a
+ // shipped dashboard by accident.
+ if dash.managed || dash.visibility == "default" {
+ return Err(ConsoleApiError::Forbidden(
+ "managed default dashboards cannot be deleted".into(),
+ ));
+ }
enforce_write(&sess, &dash)?;
dash.deleted_at = Some(now_iso());
dash.version += 1;
@@ -307,6 +386,70 @@ pub async fn delete(
Ok(no_content())
}
+// ─────────────────────────────────────────────────────────────────────────────
+// BULK (whole-set save + uniform seeding path)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// `POST /dashboards/_bulk` — upsert a set of full dashboards and/or
+/// soft-delete a set of ids in one call. This is a **privileged** operation
+/// (it can set `owner` / `managed` / `visibility` freely), so it is limited to
+/// admin/owner roles. The frontend uses it for a whole-set save; seeding uses
+/// the same shape server-side.
+pub async fn bulk(
+ State(state): State<ConsoleState>,
+ sess: AuthSession,
+ Json(body): Json<BulkBody>,
+) -> ConsoleResult<Response> {
+ match sess.user.role.as_str() {
+ "admin" | "owner" => require_active(&sess)?,
+ _ => {
+ return Err(ConsoleApiError::Forbidden(
+ "bulk dashboard write requires admin or owner".into(),
+ ))
+ }
+ }
+
+ let now = now_iso();
+ let mut upserted: Vec<String> = Vec::with_capacity(body.upserts.len());
+ for raw in body.upserts {
+ let mut dash: Dashboard = serde_json::from_value(raw).map_err(|e| {
+ ConsoleApiError::BadRequest(format!("invalid dashboard in upsert: {e}"))
+ })?;
+ if dash.id.trim().is_empty() {
+ return Err(ConsoleApiError::BadRequest(
+ "upsert entry missing id".into(),
+ ));
+ }
+ validate_visibility_value(&dash.visibility)?;
+ if dash.org_id.trim().is_empty() {
+ dash.org_id = default_org();
+ }
+ if dash.created_at.trim().is_empty() {
+ dash.created_at = now.clone();
+ }
+ dash.version = dash.version.max(1);
+ dash.updated_at = now.clone();
+ write_doc(&state, &dash).await?;
+ upserted.push(dash.id);
+ }
+
+ let mut deleted: Vec<String> = Vec::with_capacity(body.deletes.len());
+ for id in body.deletes {
+ // Ignore ids that are already gone (idempotent).
+ if let Ok(mut dash) = read_required(&state, &id).await {
+ dash.deleted_at = Some(now.clone());
+ dash.version += 1;
+ write_doc(&state, &dash).await?;
+ deleted.push(id);
+ }
+ }
+
+ Ok(ok(
+ json!({ "upserted": upserted, "deleted": deleted }),
+ None,
+ ))
+}
+
// ─────────────────────────────────────────────────────────────────────────────
// helpers
// ─────────────────────────────────────────────────────────────────────────────
@@ -334,8 +477,10 @@ async fn read_required(state: &ConsoleState, id: &str) -> ConsoleResult<Dashboar
async fn write_doc(state: &ConsoleState, dash: &Dashboard) -> ConsoleResult<()> {
let idx = state.engine.get_index(indices::DASHBOARDS)?;
- let _ = idx.delete_document(&dash.id).await;
- idx.create_document(dash.id.clone(), serde_json::to_value(dash)?)
+ // Single in-place upsert (one WAL append) instead of delete-then-create,
+ // so a crash between the two operations can never leave the id missing
+ // (durability, design C.2). `index_document` overwrites an existing id.
+ idx.index_document(Some(dash.id.clone()), serde_json::to_value(dash)?)
.await?;
Ok(())
}
@@ -351,10 +496,18 @@ fn enforce_read(sess: &AuthSession, dash: &Dashboard) -> ConsoleResult<()> {
}
fn enforce_write(sess: &AuthSession, dash: &Dashboard) -> ConsoleResult<()> {
- if dash.visibility == "default" {
- return Err(ConsoleApiError::Forbidden(
- "default dashboards are read-only".into(),
- ));
+ // Managed / default-visibility dashboards used to be flatly read-only.
+ // They are now *editable* by admin/owner so the seeded defaults are true
+ // editable data — layout, title, and panel edits persist. Lower roles
+ // still can't touch them, and DELETE is blocked for everyone (see
+ // `delete`). Re-seed leaves any edited default alone (version > 1).
+ if dash.managed || dash.visibility == "default" {
+ return match sess.user.role.as_str() {
+ "admin" | "owner" => require_active(sess),
+ _ => Err(ConsoleApiError::Forbidden(
+ "managed dashboards are editable only by admin or owner".into(),
+ )),
+ };
}
if dash.owner == sess.user.id {
return require_active(sess);
@@ -368,25 +521,49 @@ fn enforce_write(sess: &AuthSession, dash: &Dashboard) -> ConsoleResult<()> {
Err(ConsoleApiError::Forbidden("not your dashboard".into()))
}
-fn enforce_can_write_visibility(sess: &AuthSession, visibility: &str) -> ConsoleResult<()> {
- if visibility == "default" {
- // Only the owner can mint default-visibility dashboards. (For
- // v1.0 this prevents an editor from sneaking up an unkillable
- // dashboard; in practice we don't surface a UI for it yet.)
- if sess.user.role != "owner" {
- return Err(ConsoleApiError::Forbidden(
- "only owner can create default-visibility dashboards".into(),
- ));
- }
+/// Reject an unknown visibility string (used on every write path).
+fn validate_visibility_value(visibility: &str) -> ConsoleResult<()> {
+ match visibility {
+ "private" | "shared" | "default" => Ok(()),
+ other => Err(ConsoleApiError::BadRequest(format!(
+ "unknown visibility '{other}'"
+ ))),
}
- if visibility != "private" && visibility != "shared" && visibility != "default" {
- return Err(ConsoleApiError::BadRequest(format!(
- "unknown visibility '{visibility}'"
- )));
+}
+
+/// Validate the requested visibility and guard *escalation* to `default` by a
+/// non-owner. The escalation guard fires only when the new visibility is
+/// `default` **and differs** from the doc's current visibility — so an admin
+/// editing an already-`default` seeded dashboard isn't blocked from keeping it
+/// default; only minting a fresh unkillable default is owner-only. Pass
+/// `current = None` on create.
+fn enforce_can_set_visibility(
+ sess: &AuthSession,
+ new_visibility: &str,
+ current: Option<&str>,
+) -> ConsoleResult<()> {
+ validate_visibility_value(new_visibility)?;
+ if new_visibility == "default" && current != Some("default") && sess.user.role != "owner" {
+ return Err(ConsoleApiError::Forbidden(
+ "only owner can create default-visibility dashboards".into(),
+ ));
}
Ok(())
}
+/// Apply a requested `managed` flag change. `managed` is a privileged
+/// provenance marker: only admin/owner may change it (this prevents an editor
+/// from making a shared dashboard un-deletable). Any other caller's value is
+/// ignored and the existing flag is preserved, so a full-object round-trip
+/// from a normal user is safe.
+fn apply_managed(sess: &AuthSession, dash: &mut Dashboard, requested: Option<bool>) {
+ if let Some(m) = requested {
+ if matches!(sess.user.role.as_str(), "admin" | "owner") {
+ dash.managed = m;
+ }
+ }
+}
+
fn require_active(sess: &AuthSession) -> ConsoleResult<()> {
if sess.user.status != UserStatus::Active {
return Err(ConsoleApiError::Forbidden("user disabled".into()));
diff --git a/engine/crates/xerj-console-api/src/error.rs b/engine/crates/xerj-console-api/src/error.rs
index 69280c453..69f109b55 100644
--- a/engine/crates/xerj-console-api/src/error.rs
+++ b/engine/crates/xerj-console-api/src/error.rs
@@ -87,10 +87,17 @@ impl IntoResponse for ConsoleApiError {
tracing::error!(error = %self, "xerj-console internal error");
}
+ // Emit the API-contract keys (`code`/`message`) alongside the legacy
+ // (`type`/`reason`) pair. `code` uses the contract vocabulary
+ // (`conflict|forbidden|not_found|bad_request`, …) via `kind`, so the
+ // SPA can read the documented shape while older readers still find
+ // `type`/`reason`. Purely additive — no existing consumer breaks.
let body = json!({
"error": {
- "type": self.kind(),
- "reason": display,
+ "code": self.kind(),
+ "message": display,
+ "type": self.kind(),
+ "reason": display,
}
});
diff --git a/engine/crates/xerj-console-api/src/indices.rs b/engine/crates/xerj-console-api/src/indices.rs
index 5c6e31b16..0f6d8dbc6 100644
--- a/engine/crates/xerj-console-api/src/indices.rs
+++ b/engine/crates/xerj-console-api/src/indices.rs
@@ -151,6 +151,10 @@ fn schema_for(index: &str) -> Schema {
add(&mut s, "owner", FieldType::Keyword);
add(&mut s, "org_id", FieldType::Keyword);
add(&mut s, "visibility", FieldType::Keyword);
+ // Provenance marker for seeded built-ins; typed so admin tooling
+ // can filter managed vs user dashboards. Panel contents stay
+ // untyped in `_source` (see the panel-schema doc in dashboards.rs).
+ add(&mut s, "managed", FieldType::Boolean);
add(&mut s, "name", FieldType::Keyword);
add(&mut s, "section", FieldType::Keyword);
add(&mut s, "group", FieldType::Keyword);
diff --git a/engine/crates/xerj-console-api/src/lib.rs b/engine/crates/xerj-console-api/src/lib.rs
index a03d88795..4cb9cd234 100644
--- a/engine/crates/xerj-console-api/src/lib.rs
+++ b/engine/crates/xerj-console-api/src/lib.rs
@@ -22,6 +22,8 @@
//! User-state (drop the localStorage hacks):
//! - [`prefs`] — `GET/PUT /prefs`.
//! - [`dashboards`] — full CRUD with If-Match etag concurrency.
+//! - [`seed`] — first-launch materialisation of the 13 built-in dashboards
+//! as editable backend data (idempotent, revisioned).
//! - [`views`] — saved views CRUD.
//! - [`data_sources`] — `/data-sources/connections` + descendants
//! (read-only MVP backed by an auto-provisioned `built-in` adapter).
@@ -49,6 +51,7 @@ pub mod indices;
pub mod prefs;
pub mod response;
pub mod router;
+pub mod seed;
pub mod spa;
pub mod state;
pub mod time;
diff --git a/engine/crates/xerj-console-api/src/router.rs b/engine/crates/xerj-console-api/src/router.rs
index 9842945cb..c54b6d7b7 100644
--- a/engine/crates/xerj-console-api/src/router.rs
+++ b/engine/crates/xerj-console-api/src/router.rs
@@ -103,6 +103,13 @@ pub fn xerj_console_router(state: ConsoleState) -> Router {
"/_xerj-console/api/v1/dashboards",
get(dashboards::list).post(dashboards::create),
)
+ // Static `_bulk` sits beside the `:id` param route below; matchit
+ // gives the static segment priority, so a POST to `_bulk` never
+ // lands on the `:id` handler.
+ .route(
+ "/_xerj-console/api/v1/dashboards/_bulk",
+ post(dashboards::bulk),
+ )
.route(
"/_xerj-console/api/v1/dashboards/:id",
get(dashboards::get_one)
@@ -159,6 +166,7 @@ pub fn known_routes() -> &'static [&'static str] {
"/_xerj-console/api/v1/auth/api-tokens/:id",
"/_xerj-console/api/v1/prefs",
"/_xerj-console/api/v1/dashboards",
+ "/_xerj-console/api/v1/dashboards/_bulk",
"/_xerj-console/api/v1/dashboards/:id",
"/_xerj-console/api/v1/views",
"/_xerj-console/api/v1/views/:id",
diff --git a/engine/crates/xerj-console-api/src/seed.rs b/engine/crates/xerj-console-api/src/seed.rs
new file mode 100644
index 000000000..0db681187
--- /dev/null
+++ b/engine/crates/xerj-console-api/src/seed.rs
@@ -0,0 +1,908 @@
+//! First-launch seeding of the built-in dashboards as **editable backend data**.
+//!
+//! The SPA historically defined its 13 flagship dashboards in code
+//! (`xerj-ux/src/dashboards/*.js` + `registry.js`). That made them a fixed,
+//! un-editable set: a layout tweak or a rename never survived a reload, and
+//! there was no server object to attach a per-panel query to. This module
+//! materialises those same 13 dashboards as rows in `.xerj_dashboards` on
+//! first launch, so from that point on they are *data* the operator can edit
+//! (title, layout, panel geometry, per-panel query/viz) and that persists
+//! through the CRUD surface in [`crate::dashboards`].
+//!
+//! ## What is seeded
+//!
+//! One [`Dashboard`](crate::dashboards::Dashboard) per registry entry, with a
+//! **stable deterministic id** `default-<registry-id>` (e.g.
+//! `default-ai-overview`) — *not* a uuid — so re-seeding is idempotent by id.
+//! Each is `owner = "system"`, `visibility = "default"`, `managed = true`,
+//! `version = 1`, carrying the `section`/`group` taxonomy from `registry.js`
+//! and a panel skeleton generated from the dashboard's `.js` source
+//! (`id` / `type` / `title` (from `eyebrow`) / `layout` (from `cols`) /
+//! `builtin` provenance key).
+//!
+//! ## Honest scope of the skeletons
+//!
+//! Every flagship panel today binds to *computed mock data* in the browser,
+//! so every seeded panel carries a `builtin: "<registry-id>/<panel-id>"`
+//! provenance key and a `query: null` — the shipped renderer resolves its
+//! data through that key. Structural metadata + free-form layout become
+//! true editable data immediately; full query-backed data-fication of each
+//! panel is incremental and lands panel-by-panel in the frontend renderer
+//! (which fills in `query` + `viz` and drops `builtin`). This is the whole
+//! point of the split: geometry/title/type are editable *now*, without
+//! waiting on the data layer.
+//!
+//! ## Idempotency + the editable-default tension
+//!
+//! Seeding runs on **every** boot (mirroring [`crate::indices::ensure_all`]'s
+//! create-if-missing), not just the first:
+//!
+//! * absent id → create the skeleton (covers fresh installs *and* defaults
+//! added in a later release);
+//! * present id → **skip** — never clobber. A user edit (which bumps
+//! `version` past 1) or an operator soft-delete is therefore permanent.
+//!
+//! The single exception is an **opt-in migration**: a `default-__seed_meta`
+//! row records the shipped [`SEED_REVISION`]. Only when a new binary ships a
+//! higher revision are *untouched* defaults (`version <= 1`, not deleted)
+//! re-upserted onto the new skeleton — edited ones are still skipped. This
+//! gives "editable defaults, data not code" without a re-seed ever silently
+//! reverting an operator's work.
+//!
+//! The matching write-side change lives in [`crate::dashboards`]: a `managed`
+//! (or `default`-visibility) doc is editable by admin/owner (so layout/title
+//! edits persist) but not deletable, and re-seed skips anything past
+//! `version == 1`.
+
+use std::collections::HashMap;
+
+use serde_json::{json, Value};
+use xerj_engine::Engine;
+
+use crate::error::ConsoleResult;
+use crate::indices;
+use crate::time::now_iso;
+
+/// Shipped revision of the default-dashboard skeletons. Bump this **only**
+/// when a change to the seeded skeletons should migrate onto installs that
+/// have not forked them. See the module docs for the migration contract.
+pub const SEED_REVISION: u64 = 1;
+
+/// Id of the bookkeeping row that stores [`SEED_REVISION`]. It lives in the
+/// same index but is not a dashboard: it fails to deserialize into
+/// [`crate::dashboards::Dashboard`], so `list`/`get` skip it naturally.
+const SEED_META_ID: &str = "default-__seed_meta";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Skeleton specs (transcribed once from xerj-ux/src/dashboards/*.js)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// A single panel in a seed skeleton. `cols` is the historical 12-col width
+/// which becomes `layout.w`; `x`/`y`/`h` are computed by the flow layout.
+struct PanelSpec {
+ id: &'static str,
+ kind: &'static str,
+ title: &'static str,
+ cols: u32,
+ drilldown_to: Option<&'static str>,
+}
+
+/// One default dashboard.
+struct DashboardSpec {
+ /// registry.js id — the stable seed id is `default-<registry_id>`.
+ registry_id: &'static str,
+ name: &'static str,
+ section: Option<&'static str>,
+ group: Option<&'static str>,
+ panels: Vec<PanelSpec>,
+}
+
+/// Panel without a drilldown.
+fn p(id: &'static str, kind: &'static str, title: &'static str, cols: u32) -> PanelSpec {
+ PanelSpec {
+ id,
+ kind,
+ title,
+ cols,
+ drilldown_to: None,
+ }
+}
+
+/// Panel that drills down into another dashboard on click.
+fn pd(
+ id: &'static str,
+ kind: &'static str,
+ title: &'static str,
+ cols: u32,
+ to: &'static str,
+) -> PanelSpec {
+ PanelSpec {
+ id,
+ kind,
+ title,
+ cols,
+ drilldown_to: Some(to),
+ }
+}
+
+/// The 13 built-in dashboards, in registry order. Titles are the panel
+/// `eyebrow` strings from the `.js` sources; dynamic eyebrows are captured as
+/// a stable static string.
+fn seed_specs() -> Vec<DashboardSpec> {
+ vec![
+ // ── AI group ────────────────────────────────────────────────────────
+ DashboardSpec {
+ registry_id: "ai-overview",
+ name: "AI · Overview",
+ section: Some("dashboards"),
+ group: Some("ai"),
+ panels: vec![
+ p("queries", "metric", "LLM QUERIES", 4),
+ p("tokens", "metric", "TOKENS · IN + OUT", 2),
+ p("cost", "metric", "SPEND · USD", 2),
+ p("savings", "metric", "vs. ES + PINECONE + SPLUNK", 2),
+ p("cacheHit", "metric", "CACHE HIT", 2),
+ p("queriesSeries", "line", "QUERIES OVER TIME", 12),
+ p(
+ "latencyRibbons",
+ "ribbon3d",
+ "LATENCY · PER MODEL · AXONOMETRIC",
+ 12,
+ ),
+ p("tokenFlow", "flowband", "TOKEN BUDGET", 12),
+ p("models", "dist", "BY MODEL", 12),
+ pd(
+ "topIntents",
+ "topn",
+ "TOP INTENTS · CLICK TO DRILL",
+ 6,
+ "search-discover",
+ ),
+ p("topDocs", "topn", "TOP DOCUMENTS · CLICK TO FILTER", 6),
+ p("costHeatmap", "heatmap", "SPEND · WEEKDAY × 2H", 12),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "rag-quality",
+ name: "RAG · Quality",
+ section: Some("dashboards"),
+ group: Some("ai"),
+ panels: vec![
+ p("grounding", "metric", "GROUNDING SCORE", 4),
+ p("halluc", "metric", "HALLUCINATION RATE", 3),
+ p("hitRate", "metric", "RETRIEVAL HIT RATE", 3),
+ p("citations", "metric", "AVG CITATIONS", 2),
+ p("groundingSeries", "line", "GROUNDING OVER TIME", 12),
+ p("flow", "chord", "RETRIEVAL FLOW · QUERY → CHUNK", 12),
+ p(
+ "attention",
+ "attention",
+ "SAMPLE ANSWER · TOKEN ATTENTION",
+ 12,
+ ),
+ p("retrievalSource", "dist", "BY RETRIEVAL SOURCE", 12),
+ p("lowGrounding", "topn", "LOWEST GROUNDING PROMPTS", 6),
+ p(
+ "chunkDensity",
+ "heatmap",
+ "CHUNK HIT DENSITY · QUERY TYPE × CHUNK",
+ 6,
+ ),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "vector-index",
+ name: "Vector · Index",
+ section: Some("dashboards"),
+ group: Some("ai"),
+ panels: vec![
+ p("vectors", "metric", "VECTORS", 3),
+ p("dim", "metric", "DIMENSIONS", 2),
+ p("disk", "metric", "ON DISK", 2),
+ p("qps", "metric", "QUERIES/s", 2),
+ p("recall", "gauge", "RECALL @ 10", 3),
+ p(
+ "embedSpace",
+ "embedspace",
+ "EMBEDDING SPACE · UMAP PROJECTION",
+ 12,
+ ),
+ p(
+ "annLatency",
+ "ribbon3d",
+ "ANN LATENCY · P50 / P95 / P99",
+ 12,
+ ),
+ p(
+ "pcoords",
+ "pcoords",
+ "QUERY PROFILE · PARALLEL COORDINATES",
+ 12,
+ ),
+ p("models", "topn", "EMBEDDING MODELS", 6),
+ p("p95Spark", "metric", "p95 LATENCY", 3),
+ p("recallTimeline", "metric", "RECALL OVER TIME", 3),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "agent-memory",
+ name: "Agent · Memory",
+ section: Some("dashboards"),
+ group: Some("ai"),
+ panels: vec![
+ p("entries", "metric", "MEMORY ENTRIES", 4),
+ p("dedup", "metric", "DEDUP RATE", 2),
+ p("recall", "metric", "RECALL P95", 2),
+ p("growth", "metric", "GROWTH", 2),
+ p("agents", "metric", "AGENTS", 2),
+ p("sizeSeries", "line", "MEMORY SIZE OVER TIME", 12),
+ p(
+ "embedSpace",
+ "embedspace",
+ "SEMANTIC MEMORY · ONCALL-TRIAGE · UMAP",
+ 12,
+ ),
+ p("byAgent", "topn", "BY AGENT", 6),
+ p("topMemories", "topn", "MOST-REFERENCED MEMORIES", 6),
+ p("dedupSeries", "line", "DEDUP RATE OVER TIME", 6),
+ p("recallSeries", "line", "RECALL P95 OVER TIME", 6),
+ p("recentOps", "table", "RECENT OPERATIONS", 12),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ // ── Logs group ──────────────────────────────────────────────────────
+ DashboardSpec {
+ registry_id: "logs-overview",
+ name: "Logs",
+ section: Some("dashboards"),
+ group: Some("logs"),
+ panels: vec![
+ p("total", "metric", "TOTAL EVENTS", 4),
+ p("peak", "metric", "PEAK RATE", 3),
+ p("errRate", "metric", "ERROR RATE", 2),
+ p("sources", "metric", "SOURCES", 3),
+ p("series", "line", "EVENTS OVER TIME", 12),
+ p("levels", "dist", "BY LEVEL", 12),
+ p("topServices", "topn", "TOP SERVICES · CLICK TO FILTER", 6),
+ pd(
+ "topHosts",
+ "topn",
+ "TOP HOSTS · CLICK TO DRILL",
+ 6,
+ "system",
+ ),
+ p("heatmap", "heatmap", "INTENSITY · WEEKDAY × 2H", 12),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "anomaly-detect",
+ name: "Anomaly",
+ section: Some("dashboards"),
+ group: Some("logs"),
+ panels: vec![
+ p("detected", "metric", "ANOMALIES · LAST PERIOD", 4),
+ p("covered", "metric", "SIGNALS SCORED", 2),
+ p("falsePos", "metric", "FALSE-POSITIVE RATE", 3),
+ p("recall", "metric", "RECALL vs HAND LABELS", 3),
+ p(
+ "band",
+ "anomalyband",
+ "QUERY LATENCY · NORMAL BAND · μ ± 2.5σ",
+ 12,
+ ),
+ p(
+ "topSignals",
+ "topn",
+ "MOST-ANOMALOUS SIGNALS · BY z-SCORE",
+ 6,
+ ),
+ p("features", "topn", "FEATURE ATTRIBUTION · TOP ANOMALY", 6),
+ p(
+ "pcoords",
+ "pcoords",
+ "SIGNAL PROFILE · PARALLEL COORDINATES",
+ 12,
+ ),
+ p("cause", "treemap", "ROOT-CAUSE CANDIDATES · RANKED", 6),
+ p(
+ "trace",
+ "attention",
+ "CORRELATED LOG · ATTENTION EXPLAIN",
+ 6,
+ ),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "ingest-pipeline",
+ name: "Ingest · Pipeline",
+ section: Some("dashboards"),
+ group: Some("logs"),
+ panels: vec![
+ p("docsRate", "metric", "DOCS INDEXED/s", 3),
+ p("bytesRate", "metric", "BYTES WRITTEN/s", 2),
+ p("walLag", "metric", "WAL WRITE LATENCY", 2),
+ p("segments", "metric", "SEGMENTS", 2),
+ p("mem", "metric", "MEMORY USAGE", 2),
+ p("pipeline", "flowband", "PIPELINE · END-TO-END FLOW", 12),
+ p("docsSeries", "line", "INGEST THROUGHPUT", 12),
+ p(
+ "latency",
+ "multiples",
+ "INDEX LATENCY · p50 / p95 / p99",
+ 12,
+ ),
+ p("flushDur", "line", "FLUSH DURATION", 6),
+ p("mergeDur", "line", "MERGE DURATION", 6),
+ p("topIndices", "topn", "DOCS INDEXED · BY INDEX", 6),
+ p(
+ "encodings",
+ "table",
+ "FIELD ENCODINGS · /v1/indices/:name/encodings",
+ 6,
+ ),
+ p("compressionRatio", "gauge", "COMPRESSION RATIO", 6),
+ p("memSeries", "line", "MEMORY OVER TIME", 6),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ // ── Infra group ─────────────────────────────────────────────────────
+ DashboardSpec {
+ registry_id: "system",
+ name: "System",
+ section: Some("dashboards"),
+ group: Some("infra"),
+ panels: vec![
+ p("hosts", "metric", "HOSTS", 3),
+ p("alerts", "metric", "ACTIVE ALERTS", 3),
+ p("cpuMean", "metric", "MEAN CPU", 3),
+ p("memMean", "metric", "MEAN MEM", 3),
+ p("cpu", "line", "CPU", 6),
+ p("mem", "line", "MEMORY", 6),
+ p("disk", "line", "DISK I/O", 6),
+ p("net", "line", "NETWORK I/O", 6),
+ p("hostCpu", "multiples", "PER-HOST CPU · SMALL MULTIPLES", 12),
+ p("topProcs", "topn", "TOP PROCESSES", 6),
+ p("topHosts", "topn", "HOSTS BY LOAD", 6),
+ p("authSeries", "line", "AUTH · FAILED LOGINS", 12),
+ p("topFailUsers", "topn", "TOP FAILED USERS", 6),
+ p("topFailIPs", "topn", "TOP ATTACKING IPS", 6),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ // ── Section views (one per top-level section) ───────────────────────
+ DashboardSpec {
+ registry_id: "search-discover",
+ name: "Search · Discover",
+ section: Some("discover"),
+ group: None,
+ panels: vec![
+ p(
+ "searchbox",
+ "searchbox",
+ "QUERY · TYPE · INDEX · FILTERS",
+ 12,
+ ),
+ p(
+ "hits",
+ "hits",
+ "RESULTS · CLICK A COLUMN TO SORT · CLICK INDEX TO FILTER",
+ 8,
+ ),
+ p("facets", "facet", "FACETS · CLICK TO FILTER", 4),
+ p("histogram", "bar", "DATE_HISTOGRAM · INTERVAL=1H", 8),
+ p("searchMetrics", "metric", "INDEX · LIVE", 4),
+ p("dsl", "markdown", "REQUEST · POST /v1/indices/*/search", 6),
+ p("plan", "plan", "QUERY PLAN · FROM EXPLAIN-PLAN ENDPOINT", 6),
+ p("qps", "line", "QUERIES/s OVER TIME", 6),
+ p("latency", "line", "p95 LATENCY OVER TIME", 6),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS PANEL EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "alerts",
+ name: "Alerts",
+ section: Some("alerts"),
+ group: None,
+ panels: vec![
+ p("active", "metric", "ACTIVE FIRES", 3),
+ p("silenced", "metric", "SILENCED", 2),
+ p("rules", "metric", "RULES DEFINED", 2),
+ p("fires", "metric", "FIRES · 24H", 2),
+ p("connectors", "metric", "CONNECTORS", 3),
+ p("firesOverTime", "line", "FIRES OVER TIME", 12),
+ p("bySev", "dist", "BY SEVERITY", 12),
+ p("topNoisy", "topn", "TOP NOISY RULES · FIRES / 24H", 6),
+ p("recent", "events", "RECENT · LAST 30 EVENTS", 6),
+ p("ruleAsCode", "markdown", "RULES AS CODE · EXAMPLE", 12),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS SECTION EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "data",
+ name: "Data",
+ section: Some("data"),
+ group: None,
+ panels: vec![
+ p(
+ "clusters",
+ "clusters",
+ "CLUSTERS · CLICK TO SET DEFAULT",
+ 12,
+ ),
+ p(
+ "indices",
+ "indices",
+ "INDICES · CLICK AN INDEX TO INSPECT FIELDS",
+ 6,
+ ),
+ p(
+ "fields",
+ "fields",
+ "FIELDS · FROM /v1/indices/:name/_mapping",
+ 6,
+ ),
+ p("howTo", "markdown", "CONNECTING A NEW CLUSTER", 12),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS SECTION EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "users",
+ name: "Users",
+ section: Some("users"),
+ group: None,
+ panels: vec![
+ p("users", "metric", "USERS", 3),
+ p("roles", "metric", "ROLES", 2),
+ p("apiKeys", "metric", "API KEYS", 2),
+ p("sessions", "metric", "SESSIONS", 2),
+ p("lastLogin", "metric", "LAST LOGIN", 3),
+ p("userList", "topn", "USERS · MOST ACTIVE", 6),
+ p("roles", "table", "ROLES · INDEX PREFIX × OPS", 6),
+ p("recent", "events", "RECENT AUTH EVENTS", 12),
+ p(
+ "model",
+ "markdown",
+ "THE PERMISSION MODEL · WHY IT IS LIKE THIS",
+ 12,
+ ),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS SECTION EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ DashboardSpec {
+ registry_id: "settings",
+ name: "Settings",
+ section: Some("settings"),
+ group: None,
+ panels: vec![
+ p("defaults", "settings", "DEFAULTS", 12),
+ p("mg-dashboards-head", "markdown", "", 12),
+ p("mg-dashboards", "manage-dashboards", "", 12),
+ p("mg-new", "manage-new", "", 12),
+ p("mg-views-head", "markdown", "", 12),
+ p("mg-views", "manage-views", "", 12),
+ p("storage", "markdown", "PERSISTENT STATE INVENTORY", 12),
+ p("danger", "danger", "DANGER · WIPE ALL STATE", 12),
+ p(
+ "citations",
+ "citations",
+ "WHY THIS SECTION EXISTS · USER FEEDBACK",
+ 12,
+ ),
+ ],
+ },
+ ]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Skeleton → JSON
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Default row-unit height for a panel type. Small stat tiles are short;
+/// full-bleed charts (embedding spaces, ribbons, heatmaps) are tall. Chosen
+/// once so the seeded layout reads sensibly; the operator resizes freely
+/// from there.
+fn height_for(kind: &str) -> u32 {
+ match kind {
+ "metric" | "gauge" | "spark" => 2,
+ "citations" => 3,
+ "heatmap" | "ribbon3d" | "embedspace" | "chord" | "pcoords" | "attention" | "flowband"
+ | "multiples" | "treemap" | "scatter" | "stacked" | "anomalyband" => 6,
+ // line, topn, table, events, dist, bar, histogram, markdown, and the
+ // section-specific view types (hits, facet, plan, clusters, …).
+ _ => 4,
+ }
+}
+
+/// Flow the panel specs into a free-form 12-col grid, left-to-right, wrapping
+/// to a new row when the next panel would overflow. Advancing `y` by the
+/// tallest panel in the finished row guarantees no two panels overlap. Also
+/// de-duplicates panel ids *within* a dashboard (`registry.js` sources reuse
+/// e.g. `citations` twice) by suffixing `-2`, `-3`, … so every panel id — and
+/// therefore every `builtin` provenance key — is unique.
+fn build_panels(registry_id: &str, panels: &[PanelSpec]) -> Vec<Value> {
+ let mut seen: HashMap<&str, u32> = HashMap::new();
+ let mut out = Vec::with_capacity(panels.len());
+ let (mut x, mut y, mut row_h) = (0u32, 0u32, 0u32);
+
+ for spec in panels {
+ let w = spec.cols.clamp(1, 12);
+ let h = height_for(spec.kind);
+ if x + w > 12 {
+ x = 0;
+ y += row_h.max(1);
+ row_h = 0;
+ }
+
+ let count = seen.entry(spec.id).or_insert(0);
+ *count += 1;
+ let unique_id = if *count == 1 {
+ spec.id.to_string()
+ } else {
+ format!("{}-{}", spec.id, *count)
+ };
+
+ let drilldown = match spec.drilldown_to {
+ Some(to) => json!({ "to": to }),
+ None => Value::Null,
+ };
+
+ out.push(json!({
+ "id": unique_id,
+ "type": spec.kind,
+ "title": spec.title,
+ "layout": { "x": x, "y": y, "w": w, "h": h },
+ "query": Value::Null,
+ "viz": {},
+ "drilldown": drilldown,
+ "builtin": format!("{registry_id}/{unique_id}"),
+ }));
+
+ x += w;
+ row_h = row_h.max(h);
+ }
+ out
+}
+
+/// Build the full [`crate::dashboards::Dashboard`]-shaped JSON for one spec.
+fn build_seed_doc(spec: &DashboardSpec, now: &str) -> Value {
+ let id = format!("default-{}", spec.registry_id);
+ json!({
+ "id": id,
+ "owner": "system",
+ "org_id": "default",
+ "visibility": "default",
+ "managed": true,
+ "name": spec.name,
+ "section": spec.section,
+ "group": spec.group,
+ "cloned_from": Value::Null,
+ "panels": build_panels(spec.registry_id, &spec.panels),
+ "filters_default": {},
+ "time_default": Value::Null,
+ "version": 1,
+ "created_at": now,
+ "updated_at": now,
+ "deleted_at": Value::Null,
+ })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Seeding entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Read whether a seeded default row is still pristine (never edited, never
+/// deleted). Editing bumps `version` past 1; a soft-delete sets `deleted_at`
+/// (and also bumps `version`). Either makes it off-limits to re-seed.
+fn is_untouched_default(doc: &Value) -> bool {
+ let version = doc.get("version").and_then(Value::as_u64).unwrap_or(1);
+ let deleted = doc.get("deleted_at").is_some_and(|v| !v.is_null());
+ version <= 1 && !deleted
+}
+
+/// Idempotently materialise the built-in dashboards as editable backend data.
+///
+/// Call once from [`crate::bootstrap::run`], right after
+/// [`crate::indices::ensure_all`]. Safe on every boot — see the module docs
+/// for the create/skip/migrate contract.
+pub async fn seed_default_dashboards(engine: &Engine) -> ConsoleResult<()> {
+ let idx = engine.get_index(indices::DASHBOARDS)?;
+ let now = now_iso();
+
+ // A higher shipped revision than the recorded one authorises re-upserting
+ // *untouched* defaults onto fresh skeletons. On a brand-new data dir the
+ // recorded revision is absent (→ migrate), but every doc is absent too,
+ // so this only ever matters for pre-existing installs after a bump.
+ let stored_rev = match idx.get_document(SEED_META_ID).await? {
+ Some(meta) => meta.get("seed_revision").and_then(Value::as_u64),
+ None => None,
+ };
+ let migrate = stored_rev.is_none_or(|r| SEED_REVISION > r);
+
+ let mut created = 0u32;
+ let mut migrated = 0u32;
+ for spec in seed_specs() {
+ let id = format!("default-{}", spec.registry_id);
+ match idx.get_document(&id).await? {
+ None => {
+ idx.index_document(Some(id), build_seed_doc(&spec, &now))
+ .await?;
+ created += 1;
+ }
+ Some(existing) => {
+ if migrate && is_untouched_default(&existing) {
+ idx.index_document(Some(id), build_seed_doc(&spec, &now))
+ .await?;
+ migrated += 1;
+ }
+ // Otherwise: present + (edited | deleted | same revision) →
+ // never clobber.
+ }
+ }
+ }
+
+ // Record the shipped revision so the next boot is a no-op and a future
+ // bump migrates exactly once.
+ idx.index_document(
+ Some(SEED_META_ID.to_string()),
+ json!({
+ "kind": "seed_meta",
+ "seed_revision": SEED_REVISION,
+ "updated_at": now,
+ }),
+ )
+ .await?;
+
+ // Make the seeded set durable + immediately searchable so the first
+ // LIST after boot returns the defaults.
+ idx.flush().await?;
+
+ if created > 0 || migrated > 0 {
+ tracing::info!(
+ created,
+ migrated,
+ revision = SEED_REVISION,
+ "seeded default dashboards"
+ );
+ }
+ Ok(())
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests (pure — no engine needed)
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn seeds_the_thirteen_dashboards() {
+ let specs = seed_specs();
+ assert_eq!(
+ specs.len(),
+ 13,
+ "must seed exactly the 13 registry dashboards"
+ );
+ // Deterministic ids, all `default-` prefixed and unique.
+ let mut ids: Vec<String> = specs
+ .iter()
+ .map(|s| format!("default-{}", s.registry_id))
+ .collect();
+ let n = ids.len();
+ ids.sort();
+ ids.dedup();
+ assert_eq!(ids.len(), n, "seed ids must be unique");
+ assert!(ids.iter().all(|id| id.starts_with("default-")));
+ assert!(ids.contains(&"default-ai-overview".to_string()));
+ assert!(ids.contains(&"default-settings".to_string()));
+ }
+
+ #[test]
+ fn taxonomy_matches_registry() {
+ let by = |rid: &str| -> (Option<String>, Option<String>) {
+ let s = seed_specs();
+ let d = s.iter().find(|d| d.registry_id == rid).unwrap();
+ (d.section.map(String::from), d.group.map(String::from))
+ };
+ assert_eq!(
+ by("ai-overview"),
+ (Some("dashboards".into()), Some("ai".into()))
+ );
+ assert_eq!(
+ by("logs-overview"),
+ (Some("dashboards".into()), Some("logs".into()))
+ );
+ assert_eq!(
+ by("system"),
+ (Some("dashboards".into()), Some("infra".into()))
+ );
+ assert_eq!(by("search-discover"), (Some("discover".into()), None));
+ assert_eq!(by("alerts"), (Some("alerts".into()), None));
+ assert_eq!(by("settings"), (Some("settings".into()), None));
+ }
+
+ #[test]
+ fn panel_ids_unique_within_each_dashboard() {
+ // registry.js reuses ids like `citations` / `roles`; the builder must
+ // disambiguate so every panel id (and builtin key) is unique.
+ for spec in seed_specs() {
+ let panels = build_panels(spec.registry_id, &spec.panels);
+ let mut ids: Vec<&str> = panels.iter().map(|p| p["id"].as_str().unwrap()).collect();
+ let raw = ids.len();
+ ids.sort_unstable();
+ ids.dedup();
+ assert_eq!(
+ ids.len(),
+ raw,
+ "duplicate panel id in dashboard `{}`",
+ spec.registry_id
+ );
+ }
+ // Spot-check the known collisions were suffixed.
+ let rag = build_panels("rag-quality", &spec_panels("rag-quality"));
+ let rag_ids: Vec<&str> = rag.iter().map(|p| p["id"].as_str().unwrap()).collect();
+ assert!(rag_ids.contains(&"citations"));
+ assert!(rag_ids.contains(&"citations-2"));
+ }
+
+ #[test]
+ fn builtin_key_tracks_panel_id() {
+ for spec in seed_specs() {
+ let panels = build_panels(spec.registry_id, &spec.panels);
+ for panel in &panels {
+ let id = panel["id"].as_str().unwrap();
+ let builtin = panel["builtin"].as_str().unwrap();
+ assert_eq!(builtin, format!("{}/{}", spec.registry_id, id));
+ // Seed panels are mock-backed: query null, builtin present.
+ assert!(panel["query"].is_null(), "seed panels carry no query");
+ }
+ }
+ }
+
+ #[test]
+ fn layout_is_nonoverlapping_and_within_grid() {
+ for spec in seed_specs() {
+ let panels = build_panels(spec.registry_id, &spec.panels);
+ let rects: Vec<(u32, u32, u32, u32)> = panels
+ .iter()
+ .map(|p| {
+ let l = &p["layout"];
+ (
+ l["x"].as_u64().unwrap() as u32,
+ l["y"].as_u64().unwrap() as u32,
+ l["w"].as_u64().unwrap() as u32,
+ l["h"].as_u64().unwrap() as u32,
+ )
+ })
+ .collect();
+ for &(x, _, w, _) in &rects {
+ assert!(
+ w >= 1 && x + w <= 12,
+ "panel out of 12-col grid in {}",
+ spec.registry_id
+ );
+ }
+ for i in 0..rects.len() {
+ for j in (i + 1)..rects.len() {
+ let (ax, ay, aw, ah) = rects[i];
+ let (bx, by, bw, bh) = rects[j];
+ let x_overlap = ax < bx + bw && bx < ax + aw;
+ let y_overlap = ay < by + bh && by < ay + ah;
+ assert!(
+ !(x_overlap && y_overlap),
+ "overlapping panels {i}/{j} in {}",
+ spec.registry_id
+ );
+ }
+ }
+ }
+ }
+
+ #[test]
+ fn seed_doc_deserializes_as_a_dashboard() {
+ // The seeded JSON must round-trip through the CRUD struct, or list/get
+ // would silently drop the defaults.
+ for spec in seed_specs() {
+ let doc = build_seed_doc(&spec, "2026-07-13T00:00:00.000Z");
+ let dash: crate::dashboards::Dashboard =
+ serde_json::from_value(doc).expect("seed doc must parse as Dashboard");
+ assert_eq!(dash.owner, "system");
+ assert_eq!(dash.visibility, "default");
+ assert!(dash.managed);
+ assert_eq!(dash.version, 1);
+ assert!(!dash.panels.is_empty());
+ }
+ }
+
+ #[test]
+ fn seed_meta_is_not_a_dashboard() {
+ // The bookkeeping row must fail Dashboard parse so list/get skip it.
+ let meta = json!({ "kind": "seed_meta", "seed_revision": SEED_REVISION });
+ assert!(serde_json::from_value::<crate::dashboards::Dashboard>(meta).is_err());
+ }
+
+ #[test]
+ fn untouched_predicate() {
+ assert!(is_untouched_default(
+ &json!({ "version": 1, "deleted_at": Value::Null })
+ ));
+ assert!(!is_untouched_default(&json!({ "version": 2 })));
+ assert!(!is_untouched_default(
+ &json!({ "version": 1, "deleted_at": "2026-07-13T00:00:00.000Z" })
+ ));
+ }
+
+ /// helper: fetch one dashboard's panel specs by registry id (test-only).
+ fn spec_panels(rid: &str) -> Vec<PanelSpec> {
+ seed_specs()
+ .into_iter()
+ .find(|s| s.registry_id == rid)
+ .unwrap()
+ .panels
+ }
+}
diff --git a/engine/crates/xerj-console-api/tests/dashboards_seed_and_schema.rs b/engine/crates/xerj-console-api/tests/dashboards_seed_and_schema.rs
new file mode 100644
index 000000000..ce305316f
--- /dev/null
+++ b/engine/crates/xerj-console-api/tests/dashboards_seed_and_schema.rs
@@ -0,0 +1,538 @@
+//! Dashboards: rich panel schema round-trip, first-launch seeding of the 13
+//! built-ins as editable backend data, managed-default edit/delete rules, and
+//! the bulk endpoint.
+//!
+//! These exercise the backend half of the "Kibana-quality dashboards"
+//! rework: net-new dashboards persist at the backend, seeded defaults are
+//! editable data (not code), and free-form per-panel geometry/query/viz
+//! round-trips unchanged.
+
+use axum::{body::Body, http::Request, Router};
+use http_body_util::BodyExt;
+use serde_json::{json, Value};
+use tempfile::TempDir;
+use tower::ServiceExt;
+use xerj_common::config::Config;
+use xerj_console_api::{
+ auth::{sessions, store},
+ state::ClusterMode,
+ xerj_console_router, ConsoleState,
+};
+use xerj_engine::Engine;
+
+struct TestApp {
+ router: Router,
+ state: ConsoleState,
+ engine: Engine,
+ owner_cookie: String,
+ dir: TempDir,
+}
+
+async fn boot() -> TestApp {
+ let dir = TempDir::new().unwrap();
+ let mut cfg = Config::default();
+ cfg.server.data_dir = dir.path().to_str().unwrap().to_string();
+ let engine = Engine::new(cfg).expect("engine");
+ let outcome = xerj_console_api::bootstrap::run(&engine, dir.path(), "http://localhost:9200")
+ .await
+ .unwrap();
+ let state = ConsoleState::new(
+ engine.clone(),
+ "local".into(),
+ outcome.master_key,
+ ClusterMode::Standalone,
+ );
+
+ let owner_cookie = cookie_for(&state, &engine, "owner-test", "owner").await;
+ let router = xerj_console_router(state.clone());
+ TestApp {
+ router,
+ state,
+ engine,
+ owner_cookie,
+ dir,
+ }
+}
+
+/// Create an active user with a role and mint a session cookie for them.
+async fn cookie_for(state: &ConsoleState, engine: &Engine, id: &str, role: &str) -> String {
+ let user = store::User {
+ id: id.to_string(),
+ email: format!("{id}@example.com"),
+ display_name: id.to_string(),
+ role: role.to_string(),
+ status: store::UserStatus::Active,
+ created_at: xerj_console_api::time::now_iso(),
+ last_seen_at: Some(xerj_console_api::time::now_iso()),
+ };
+ store::upsert_user(engine, &user).await.unwrap();
+ let (_s, signed) = sessions::mint_session(state, &user.id, "passkey", None, None)
+ .await
+ .unwrap();
+ format!("xerj_session={signed}")
+}
+
+async fn body_json(resp: axum::response::Response) -> (axum::http::StatusCode, Value) {
+ let status = resp.status();
+ let bytes = resp.into_body().collect().await.unwrap().to_bytes();
+ let v = if bytes.is_empty() {
+ Value::Null
+ } else {
+ serde_json::from_slice(&bytes).unwrap_or(Value::Null)
+ };
+ (status, v)
+}
+
+fn req(method: &str, path: &str, cookie: &str, body: Option<Value>) -> Request<Body> {
+ let body = match body {
+ Some(b) => Body::from(b.to_string()),
+ None => Body::empty(),
+ };
+ Request::builder()
+ .method(method)
+ .uri(path)
+ .header("cookie", cookie)
+ .header("content-type", "application/json")
+ .body(body)
+ .unwrap()
+}
+
+fn req_etag(method: &str, path: &str, cookie: &str, etag: &str, body: Value) -> Request<Body> {
+ Request::builder()
+ .method(method)
+ .uri(path)
+ .header("cookie", cookie)
+ .header("content-type", "application/json")
+ .header("if-match", etag)
+ .body(Body::from(body.to_string()))
+ .unwrap()
+}
+
+async fn get_dash(app: &TestApp, id: &str) -> (axum::http::StatusCode, Value) {
+ let r = app
+ .router
+ .clone()
+ .oneshot(req(
+ "GET",
+ &format!("/_xerj-console/api/v1/dashboards/{id}"),
+ &app.owner_cookie,
+ None,
+ ))
+ .await
+ .unwrap();
+ body_json(r).await
+}
+
+async fn list_dash(app: &TestApp) -> Value {
+ let r = app
+ .router
+ .clone()
+ .oneshot(req(
+ "GET",
+ "/_xerj-console/api/v1/dashboards",
+ &app.owner_cookie,
+ None,
+ ))
+ .await
+ .unwrap();
+ body_json(r).await.1
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Seeding
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn seeds_thirteen_editable_defaults_on_first_boot() {
+ let app = boot().await;
+ let body = list_dash(&app).await;
+ let arr = body["data"]["dashboards"].as_array().unwrap();
+
+ let defaults: Vec<&Value> = arr
+ .iter()
+ .filter(|d| d["id"].as_str().unwrap_or("").starts_with("default-"))
+ .collect();
+ assert_eq!(defaults.len(), 13, "must seed exactly 13 defaults: {body}");
+
+ // Every registry dashboard is present by its stable id.
+ for id in [
+ "default-ai-overview",
+ "default-rag-quality",
+ "default-vector-index",
+ "default-agent-memory",
+ "default-logs-overview",
+ "default-anomaly-detect",
+ "default-ingest-pipeline",
+ "default-system",
+ "default-search-discover",
+ "default-alerts",
+ "default-data",
+ "default-users",
+ "default-settings",
+ ] {
+ assert!(
+ defaults.iter().any(|d| d["id"] == id),
+ "missing seeded default {id}"
+ );
+ }
+}
+
+#[tokio::test]
+async fn seeded_default_is_managed_data_with_geometry() {
+ let app = boot().await;
+ let (status, body) = get_dash(&app, "default-ai-overview").await;
+ assert_eq!(status, 200, "{body}");
+ let d = &body["data"];
+ assert_eq!(d["owner"], "system");
+ assert_eq!(d["visibility"], "default");
+ assert_eq!(d["managed"], true);
+ assert_eq!(d["section"], "dashboards");
+ assert_eq!(d["group"], "ai");
+ assert_eq!(d["version"], 1);
+ // ETag header + meta present.
+ assert_eq!(body["meta"]["etag"], "W/\"1\"");
+
+ let panels = d["panels"].as_array().unwrap();
+ assert!(!panels.is_empty(), "seeded panels must be present");
+ let first = &panels[0];
+ assert_eq!(first["id"], "queries");
+ assert_eq!(first["type"], "metric");
+ assert_eq!(first["title"], "LLM QUERIES");
+ // Free-form geometry (x/y/w/h), not a bare `cols`.
+ for k in ["x", "y", "w", "h"] {
+ assert!(first["layout"][k].is_u64(), "layout.{k} missing: {first}");
+ }
+ assert_eq!(first["layout"]["w"], 4);
+ // Mock-backed seed panel: builtin provenance, null query.
+ assert_eq!(first["builtin"], "ai-overview/queries");
+ assert!(first["query"].is_null());
+
+ // Duplicate `citations` id in rag-quality was disambiguated at seed time.
+ let (_, rag) = get_dash(&app, "default-rag-quality").await;
+ let ids: Vec<&str> = rag["data"]["panels"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|p| p["id"].as_str().unwrap())
+ .collect();
+ assert!(ids.contains(&"citations"));
+ assert!(ids.contains(&"citations-2"));
+}
+
+#[tokio::test]
+async fn seeding_is_idempotent_and_preserves_edits() {
+ let app = boot().await;
+
+ // Edit a seeded default (as owner) — layout/title persist, version bumps.
+ let patch = req_etag(
+ "PATCH",
+ "/_xerj-console/api/v1/dashboards/default-system",
+ &app.owner_cookie,
+ "W/\"1\"",
+ json!({ "name": "System (edited)" }),
+ );
+ let (status, body) = body_json(app.router.clone().oneshot(patch).await.unwrap()).await;
+ assert_eq!(
+ status, 200,
+ "owner must be able to edit a managed default: {body}"
+ );
+ assert_eq!(body["data"]["version"], 2);
+
+ // Re-run bootstrap (simulates a restart) — seeding must NOT duplicate or
+ // clobber.
+ xerj_console_api::bootstrap::run(&app.engine, app.dir.path(), "http://localhost:9200")
+ .await
+ .unwrap();
+
+ let body = list_dash(&app).await;
+ let defaults: Vec<&Value> = body["data"]["dashboards"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .filter(|d| d["id"].as_str().unwrap_or("").starts_with("default-"))
+ .collect();
+ assert_eq!(defaults.len(), 13, "re-seed must not duplicate defaults");
+
+ // The edit survived the re-seed.
+ let (_, sys) = get_dash(&app, "default-system").await;
+ assert_eq!(sys["data"]["name"], "System (edited)");
+ assert_eq!(sys["data"]["version"], 2);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Managed-default write rules
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn managed_default_editable_by_owner_but_not_deletable() {
+ let app = boot().await;
+
+ // Replace (PUT) the whole managed default as owner — allowed.
+ let put = req_etag(
+ "PUT",
+ "/_xerj-console/api/v1/dashboards/default-alerts",
+ &app.owner_cookie,
+ "W/\"1\"",
+ json!({
+ "name": "Alerts",
+ "visibility": "default",
+ "section": "alerts",
+ "panels": [ { "id": "x", "type": "metric", "title": "X",
+ "layout": { "x": 0, "y": 0, "w": 4, "h": 2 } } ]
+ }),
+ );
+ let (status, body) = body_json(app.router.clone().oneshot(put).await.unwrap()).await;
+ assert_eq!(
+ status, 200,
+ "owner PUT of managed default must succeed: {body}"
+ );
+ assert_eq!(body["data"]["version"], 2);
+ assert_eq!(body["data"]["managed"], true, "managed flag preserved");
+
+ // DELETE of a managed default is forbidden even for the owner.
+ let r = app
+ .router
+ .clone()
+ .oneshot(req(
+ "DELETE",
+ "/_xerj-console/api/v1/dashboards/default-alerts",
+ &app.owner_cookie,
+ None,
+ ))
+ .await
+ .unwrap();
+ assert_eq!(r.status(), 403, "managed defaults must not be deletable");
+}
+
+#[tokio::test]
+async fn managed_default_not_editable_by_viewer() {
+ let app = boot().await;
+ let viewer = cookie_for(&app.state, &app.engine, "viewer-1", "viewer").await;
+ let patch = req_etag(
+ "PATCH",
+ "/_xerj-console/api/v1/dashboards/default-system",
+ &viewer,
+ "W/\"1\"",
+ json!({ "name": "nope" }),
+ );
+ let r = app.router.clone().oneshot(patch).await.unwrap();
+ assert_eq!(r.status(), 403, "a viewer must not edit a managed default");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rich panel schema round-trip
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn rich_panels_round_trip_byte_identical() {
+ let app = boot().await;
+
+ // A net-new dashboard with free-form geometry, a per-panel ES-DSL query,
+ // per-panel viz config, a drilldown, and a static markdown panel.
+ let panels = json!([
+ {
+ "id": "traffic",
+ "type": "line",
+ "title": "PROD API TRAFFIC",
+ "layout": { "x": 0, "y": 0, "w": 8, "h": 4 },
+ "query": {
+ "index": "logs-*",
+ "time_field": "@timestamp",
+ "dsl": { "bool": { "must": [ { "match": { "service": "api" } } ] } },
+ "aggs": { "over_time": { "date_histogram": { "field": "@timestamp", "fixed_interval": "1h" } } }
+ },
+ "viz": { "unit": "req/s", "value_field": "doc_count", "spark": true, "delta": true },
+ "drilldown": { "to": "default-system", "filter_field": "host" },
+ "builtin": Value::Null
+ },
+ {
+ "id": "notes",
+ "type": "markdown",
+ "title": "RUNBOOK",
+ "layout": { "x": 8, "y": 0, "w": 4, "h": 4 },
+ "query": Value::Null,
+ "viz": { "text": "## On call\nPage the SRE." },
+ "drilldown": Value::Null,
+ "builtin": Value::Null
+ }
+ ]);
+
+ let create = req(
+ "POST",
+ "/_xerj-console/api/v1/dashboards",
+ &app.owner_cookie,
+ Some(json!({
+ "name": "Prod API Traffic",
+ "visibility": "private",
+ "section": "dashboards",
+ "group": "infra",
+ "panels": panels,
+ "filters_default": { "env": "prod" },
+ "time_default": "24H"
+ })),
+ );
+ let (status, body) = body_json(app.router.clone().oneshot(create).await.unwrap()).await;
+ assert_eq!(status, 201, "{body}");
+ let id = body["data"]["id"].as_str().unwrap().to_string();
+ assert_eq!(
+ body["data"]["managed"], false,
+ "user create is never managed"
+ );
+ assert_eq!(
+ body["data"]["panels"], panels,
+ "panels must persist verbatim"
+ );
+
+ // GET it back — panels + geometry + query + viz identical.
+ let (status, got) = get_dash(&app, &id).await;
+ assert_eq!(status, 200);
+ assert_eq!(
+ got["data"]["panels"], panels,
+ "panels must round-trip identical"
+ );
+ assert_eq!(got["data"]["filters_default"], json!({ "env": "prod" }));
+ assert_eq!(got["data"]["time_default"], "24H");
+ assert_eq!(got["data"]["group"], "infra");
+
+ // Replace the geometry (free resize/move) and confirm it sticks.
+ let moved = json!([
+ {
+ "id": "traffic",
+ "type": "line",
+ "title": "PROD API TRAFFIC",
+ "layout": { "x": 0, "y": 0, "w": 12, "h": 6 },
+ "query": Value::Null,
+ "viz": {},
+ "drilldown": Value::Null,
+ "builtin": Value::Null
+ }
+ ]);
+ let put = req_etag(
+ "PUT",
+ &format!("/_xerj-console/api/v1/dashboards/{id}"),
+ &app.owner_cookie,
+ "W/\"1\"",
+ json!({ "name": "Prod API Traffic", "visibility": "private", "panels": moved }),
+ );
+ let (status, body) = body_json(app.router.clone().oneshot(put).await.unwrap()).await;
+ assert_eq!(status, 200, "{body}");
+ assert_eq!(body["data"]["version"], 2);
+ assert_eq!(body["data"]["panels"][0]["layout"]["w"], 12);
+ assert_eq!(body["data"]["panels"][0]["layout"]["h"], 6);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Bulk endpoint
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn bulk_upsert_and_delete_as_owner() {
+ let app = boot().await;
+
+ // Create a user dashboard to delete via bulk.
+ let (_, created) = body_json(
+ app.router
+ .clone()
+ .oneshot(req(
+ "POST",
+ "/_xerj-console/api/v1/dashboards",
+ &app.owner_cookie,
+ Some(json!({ "name": "Doomed", "visibility": "private" })),
+ ))
+ .await
+ .unwrap(),
+ )
+ .await;
+ let doomed = created["data"]["id"].as_str().unwrap().to_string();
+
+ // Bulk: upsert a full dashboard (with a fixed id) + delete the doomed one.
+ let upsert_doc = json!({
+ "id": "team-infra-board",
+ "owner": "owner-test",
+ "org_id": "default",
+ "visibility": "shared",
+ "managed": false,
+ "name": "Team Infra",
+ "section": "dashboards",
+ "group": "infra",
+ "cloned_from": Value::Null,
+ "panels": [ { "id": "a", "type": "metric", "title": "A",
+ "layout": { "x": 0, "y": 0, "w": 4, "h": 2 } } ],
+ "filters_default": {},
+ "time_default": Value::Null,
+ "version": 1,
+ "created_at": "2026-07-13T00:00:00.000Z",
+ "updated_at": "2026-07-13T00:00:00.000Z",
+ "deleted_at": Value::Null
+ });
+ let bulk = req(
+ "POST",
+ "/_xerj-console/api/v1/dashboards/_bulk",
+ &app.owner_cookie,
+ Some(json!({ "upserts": [ upsert_doc ], "deletes": [ doomed ] })),
+ );
+ let (status, body) = body_json(app.router.clone().oneshot(bulk).await.unwrap()).await;
+ assert_eq!(status, 200, "{body}");
+ assert_eq!(body["data"]["upserted"], json!(["team-infra-board"]));
+ assert_eq!(body["data"]["deleted"].as_array().unwrap().len(), 1);
+
+ // The upsert is fetchable; the delete is gone.
+ let (s1, _) = get_dash(&app, "team-infra-board").await;
+ assert_eq!(s1, 200);
+ let (s2, _) = get_dash(&app, &doomed).await;
+ assert_eq!(s2, 404);
+}
+
+#[tokio::test]
+async fn bulk_forbidden_for_non_admin() {
+ let app = boot().await;
+ let editor = cookie_for(&app.state, &app.engine, "editor-1", "editor").await;
+ let r = app
+ .router
+ .clone()
+ .oneshot(req(
+ "POST",
+ "/_xerj-console/api/v1/dashboards/_bulk",
+ &editor,
+ Some(json!({ "upserts": [], "deletes": [] })),
+ ))
+ .await
+ .unwrap();
+ assert_eq!(r.status(), 403, "bulk must require admin/owner");
+}
+
+#[tokio::test]
+async fn bulk_route_matches_before_id_param() {
+ // Guards the matchit static-vs-param sibling: `_bulk` must hit the bulk
+ // handler (403 for a viewer), not the `:id` GET/PUT handler.
+ let app = boot().await;
+ let viewer = cookie_for(&app.state, &app.engine, "viewer-2", "viewer").await;
+ let r = app
+ .router
+ .clone()
+ .oneshot(req(
+ "POST",
+ "/_xerj-console/api/v1/dashboards/_bulk",
+ &viewer,
+ Some(json!({ "upserts": [], "deletes": [] })),
+ ))
+ .await
+ .unwrap();
+ // 403 (bulk authz), definitively not 404/405 from the :id route.
+ assert_eq!(r.status(), 403);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error envelope (contract-conformant code/message)
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn error_body_carries_contract_code_and_message() {
+ let app = boot().await;
+ let (status, body) = get_dash(&app, "does-not-exist").await;
+ assert_eq!(status, 404);
+ assert_eq!(body["error"]["code"], "not_found", "{body}");
+ assert!(body["error"]["message"].is_string());
+ // Legacy keys remain for older readers.
+ assert_eq!(body["error"]["type"], "not_found");
+}