@reddb-io/ui 0.2.0 → 0.3.1

package/src/lib/query-tabs.svelte.ts

@@ -4,57 +4,99 @@
 // running flag. Stored separately from the tabs store so the Tab type
 // stays a thin identity record and switching tabs preserves state.
 
-import type { QueryResult } from '#reddb'
+import { activity } from "./activity.svelte";
+import type { QueryResult } from "#reddb";
 
 export interface QueryTabState {
-  sql: string
-  result: QueryResult | null
-  error: string | null
-  running: boolean
+  sql: string;
+  result: QueryResult | null;
+  error: string | null;
+  running: boolean;
+  runningStartedAt: number | null;
 }
 
-export type QueryExecutor = (sql: string) => Promise<QueryResult>
+export interface QueryRunOptions {
+  signal?: AbortSignal;
+}
+
+export type QueryExecutor = (
+  sql: string,
+  options?: QueryRunOptions
+) => Promise<QueryResult>;
 
 function emptyState(): QueryTabState {
-  return { sql: '', result: null, error: null, running: false }
+  return {
+    sql: "",
+    result: null,
+    error: null,
+    running: false,
+    runningStartedAt: null,
+  };
+}
+
+function queryActivityLabel(sql: string): string {
+  const oneLine = sql.replace(/\s+/g, " ").trim();
+  if (oneLine.length <= 80) return `query · ${oneLine}`;
+  return `query · ${oneLine.slice(0, 79).trimEnd()}…`;
+}
+
+function isAbortError(e: unknown): boolean {
+  return (
+    (e instanceof DOMException && e.name === "AbortError") ||
+    (e instanceof Error && e.name === "AbortError")
+  );
+}
+
+export function formatElapsed(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(ms / 60_000);
+  const seconds = Math.floor((ms % 60_000) / 1000);
+  return `${minutes}m ${seconds.toString().padStart(2, "0")}s`;
 }
 
 class QueryTabsStore {
   /** Per-tab state keyed by tab id. */
-  states = $state<Record<string, QueryTabState>>({})
+  states = $state<Record<string, QueryTabState>>({});
   /** Monotonic counter for "Query N" labels — survives close so numbers don't reuse. */
-  private counter = 0
-  private executor: QueryExecutor | null = null
+  private counter = 0;
+  private executor: QueryExecutor | null = null;
+  private runSeq = 0;
+  private inFlight = new Map<
+    string,
+    { token: number; controller: AbortController }
+  >();
 
   setExecutor(executor: QueryExecutor | null): void {
-    this.executor = executor
+    this.executor = executor;
   }
 
   nextLabel(): string {
-    this.counter += 1
-    return `Query ${this.counter}`
+    this.counter += 1;
+    return `Query ${this.counter}`;
   }
 
   ensure(id: string): QueryTabState {
-    if (!this.states[id]) this.states[id] = emptyState()
-    return this.states[id]
+    if (!this.states[id]) this.states[id] = emptyState();
+    return this.states[id];
   }
 
   setSql(id: string, sql: string): void {
-    const s = this.ensure(id)
-    s.sql = sql
+    const s = this.ensure(id);
+    s.sql = sql;
   }
 
   get(id: string): QueryTabState | undefined {
-    return this.states[id]
+    return this.states[id];
   }
 
   has(id: string): boolean {
-    return this.states[id] !== undefined
+    return this.states[id] !== undefined;
   }
 
   remove(id: string): void {
-    delete this.states[id]
+    this.cancel(id);
+    delete this.states[id];
   }
 
   /**
@@ -63,9 +105,9 @@ class QueryTabsStore {
    * confirmation.
    */
   isDirty(id: string): boolean {
-    const s = this.states[id]
-    if (!s) return false
-    return s.sql.trim().length > 0
+    const s = this.states[id];
+    if (!s) return false;
+    return s.sql.trim().length > 0;
   }
 
   /**
@@ -74,42 +116,75 @@ class QueryTabsStore {
    * running flag guards against re-entry.
    */
   async run(id: string): Promise<void> {
-    const s = this.ensure(id)
-    if (s.running) return
+    const s = this.ensure(id);
+    if (s.running) return;
     if (!this.executor) {
-      s.error = 'No connection — connect to a reddb instance first.'
-      s.result = null
-      return
+      s.error = "No connection — connect to a reddb instance first.";
+      s.result = null;
+      return;
     }
-    const sql = s.sql.trim()
+    const sql = s.sql.trim();
     if (!sql) {
-      s.error = 'Empty query.'
-      s.result = null
-      return
+      s.error = "Empty query.";
+      s.result = null;
+      return;
     }
-    s.running = true
-    s.error = null
+    const controller = new AbortController();
+    const token = ++this.runSeq;
+    this.inFlight.set(id, { token, controller });
+    s.running = true;
+    s.runningStartedAt = Date.now();
+    s.error = null;
     try {
-      const r = await this.executor(sql)
-      s.result = r
-      s.error = r.ok ? null : (r.error ?? 'Query failed.')
+      const r = await activity.track(queryActivityLabel(sql), () =>
+        this.executor!(sql, { signal: controller.signal })
+      );
+      if (this.inFlight.get(id)?.token !== token) return;
+      s.result = r;
+      s.error = r.ok ? null : (r.error ?? "Query failed.");
     } catch (e) {
-      s.error = (e as Error).message
-      s.result = null
+      if (this.inFlight.get(id)?.token !== token) return;
+      if (controller.signal.aborted || isAbortError(e)) {
+        s.error = null;
+        return;
+      }
+      s.error = (e as Error).message;
+      s.result = null;
     } finally {
-      s.running = false
+      if (this.inFlight.get(id)?.token === token) {
+        this.inFlight.delete(id);
+        s.running = false;
+        s.runningStartedAt = null;
+      }
+    }
+  }
+
+  cancel(id: string): boolean {
+    const run = this.inFlight.get(id);
+    if (!run) return false;
+    this.inFlight.delete(id);
+    run.controller.abort();
+    const s = this.states[id];
+    if (s) {
+      s.running = false;
+      s.runningStartedAt = null;
+      s.error = null;
     }
+    return true;
   }
 
   /** Test-only reset. */
   clear(): void {
-    this.states = {}
-    this.counter = 0
-    this.executor = null
+    for (const run of this.inFlight.values()) run.controller.abort();
+    this.inFlight.clear();
+    this.states = {};
+    this.counter = 0;
+    this.executor = null;
+    this.runSeq = 0;
   }
 }
 
-export const queryTabs = new QueryTabsStore()
+export const queryTabs = new QueryTabsStore();
 
 /**
  * Derive a tab title from the SQL text. Defaults to `fallback` (e.g.
@@ -118,13 +193,17 @@ export const queryTabs = new QueryTabsStore()
  *
  * Kept pure & exported for unit tests.
  */
-export function deriveQueryLabel(sql: string, fallback: string, max = 24): string {
-  const trimmed = sql.trim()
-  if (!trimmed) return fallback
-  const match = trimmed.match(/^\s*select\s+([\s\S]+?)\s+from\b/i)
-  if (!match) return fallback
-  const clause = match[1].replace(/\s+/g, ' ').trim()
-  if (!clause || clause === '*') return fallback
-  if (clause.length <= max) return clause
-  return clause.slice(0, max - 1).trimEnd() + '…'
+export function deriveQueryLabel(
+  sql: string,
+  fallback: string,
+  max = 24
+): string {
+  const trimmed = sql.trim();
+  if (!trimmed) return fallback;
+  const match = trimmed.match(/^\s*select\s+([\s\S]+?)\s+from\b/i);
+  if (!match) return fallback;
+  const clause = match[1].replace(/\s+/g, " ").trim();
+  if (!clause || clause === "*") return fallback;
+  if (clause.length <= max) return clause;
+  return clause.slice(0, max - 1).trimEnd() + "…";
 }

package/src/lib/reddb/analytics.ts

@@ -0,0 +1,208 @@
+// Analytics v0 surface: metric descriptors (`red.metrics`) + the Prometheus
+// HTTP query adapter (`/api/v1/query[_range]`), plus the bridge the UI needs:
+// given a metric's *kind*, what chart shows it honestly.
+//
+// Pinned against reddb source (2026-06):
+//   - descriptor catalog columns: crates/reddb-server/src/runtime/red_schema.rs (red.metrics, #747)
+//   - PromQL envelope + subset: docs/operations/metrics-compatibility.md (ADR 0017)
+//
+// Premise (the user's): if we know the *nature* of a metric, we know the
+// chart. A counter is a rate line, a gauge is a point-in-time gauge, a
+// histogram is a P50/P95/P99 percentile curve. `chartKindForMetric` encodes
+// exactly that, and `promQLForMetric` builds the matching query.
+
+/** Metric kinds reddb's descriptor catalog validates (immutable per metric). */
+export type MetricKind =
+  | "counter"
+  | "gauge"
+  | "histogram"
+  | "ratio"
+  | "derived";
+
+/** `role` tags the metric's intent — drives grouping, not chart choice. */
+export type MetricRole = "metric" | "operational" | "kpi" | "sli" | string;
+
+/** One row of `red.metrics` (the typed descriptor projection, #747). */
+export interface MetricDescriptor {
+  path: string;
+  kind: MetricKind;
+  role: MetricRole;
+  /** Reserved in v0 (NULL until the catalog tracks it). */
+  unit?: string | null;
+  labels?: Record<string, unknown> | null;
+  retention_ms?: number | null;
+  supports_prometheus_query?: boolean;
+  created_at_ms?: number;
+}
+
+/** The chart family the UI renders for a metric. */
+export type ChartKind =
+  | "line" // counter rate / derived series over time
+  | "area" // gauge over time
+  | "gauge" // gauge / ratio point-in-time dial
+  | "percentiles" // histogram → P50/P95/P99 curves
+  | "bars"; // fallback categorical
+
+/**
+ * Map a metric's nature to its chart. This is the heart of eixo 3: the UI
+ * never asks the user "what chart?" — the descriptor's `kind` decides.
+ */
+export function chartKindForMetric(kind: MetricKind): ChartKind {
+  switch (kind) {
+    case "counter":
+      return "line"; // rate() over time
+    case "gauge":
+      return "area"; // point-in-time level, filled
+    case "histogram":
+      return "percentiles"; // P50/P95/P99 via histogram_quantile
+    case "ratio":
+      return "gauge"; // 0..1 dial
+    case "derived":
+      return "line";
+    default:
+      return "line";
+  }
+}
+
+// ── Prometheus HTTP API envelopes (standard shapes) ──────────────────────────
+
+/** A single `[unixSeconds, "value"]` sample (Prometheus encodes value as a string). */
+export type PromSample = [number, string];
+
+export interface PromVectorEntry {
+  metric: Record<string, string>;
+  value: PromSample;
+}
+
+export interface PromMatrixEntry {
+  metric: Record<string, string>;
+  values: PromSample[];
+}
+
+export interface PromResponse {
+  status: "success" | "error";
+  data?: {
+    resultType: "vector" | "matrix" | "scalar" | "string";
+    result: PromVectorEntry[] | PromMatrixEntry[];
+  };
+  errorType?: string;
+  error?: string;
+}
+
+/** A normalised time-series point the chart layer consumes. */
+export interface SeriesPoint {
+  /** epoch milliseconds */
+  t: number;
+  v: number;
+}
+
+export interface NormalizedSeries {
+  /** A short stable label built from the series' distinguishing labels. */
+  label: string;
+  labels: Record<string, string>;
+  points: SeriesPoint[];
+}
+
+function seriesLabel(metric: Record<string, string>): string {
+  const name = metric.__name__;
+  const rest = Object.entries(metric)
+    .filter(([k]) => k !== "__name__")
+    .map(([k, v]) => `${k}=${v}`)
+    .join(",");
+  if (name && rest) return `${name}{${rest}}`;
+  if (rest) return `{${rest}}`;
+  return name ?? "series";
+}
+
+function toPoint(sample: PromSample): SeriesPoint | null {
+  const v = Number(sample[1]);
+  if (!Number.isFinite(v)) return null; // Prometheus emits "NaN" for gaps
+  return { t: sample[0] * 1000, v };
+}
+
+/** Normalise a `query_range` (matrix) response into chartable series. */
+export function parsePromMatrix(resp: PromResponse): NormalizedSeries[] {
+  if (resp.status !== "success" || resp.data?.resultType !== "matrix")
+    return [];
+  return (resp.data.result as PromMatrixEntry[]).map((entry) => ({
+    label: seriesLabel(entry.metric),
+    labels: entry.metric,
+    points: entry.values
+      .map(toPoint)
+      .filter((p): p is SeriesPoint => p !== null),
+  }));
+}
+
+/** Normalise an instant (vector) response into one point per series. */
+export function parsePromVector(resp: PromResponse): NormalizedSeries[] {
+  if (resp.status !== "success" || resp.data?.resultType !== "vector")
+    return [];
+  return (resp.data.result as PromVectorEntry[])
+    .map((entry) => {
+      const point = toPoint(entry.value);
+      return point
+        ? {
+            label: seriesLabel(entry.metric),
+            labels: entry.metric,
+            points: [point],
+          }
+        : null;
+    })
+    .filter((s): s is NormalizedSeries => s !== null);
+}
+
+/** A PromQL expression plus the label it should be charted under. */
+export interface MetricQuery {
+  label: string;
+  expr: string;
+}
+
+export interface MetricQueryPlan {
+  chart: ChartKind;
+  /** Range vector window for rate()/histogram_quantile(), e.g. "5m". */
+  window: string;
+  /** One expr for simple metrics; three (p50/p95/p99) for histograms. */
+  queries: MetricQuery[];
+}
+
+const PERCENTILES: Array<{ label: string; phi: number }> = [
+  { label: "p50", phi: 0.5 },
+  { label: "p95", phi: 0.95 },
+  { label: "p99", phi: 0.99 },
+];
+
+/**
+ * Build the PromQL query plan for a descriptor. Honours the v0 subset
+ * documented in metrics-compatibility.md:
+ *   - counter → `rate(<path>[w])`
+ *   - histogram → `histogram_quantile(phi, sum by (le) (rate(<path>_bucket[w])))` ×3
+ *   - gauge / ratio / derived → bare `<path>`
+ */
+export function promQLForMetric(
+  descriptor: Pick<MetricDescriptor, "path" | "kind">,
+  opts: { window?: string } = {}
+): MetricQueryPlan {
+  const window = opts.window ?? "5m";
+  const path = descriptor.path;
+  const chart = chartKindForMetric(descriptor.kind);
+
+  if (descriptor.kind === "histogram") {
+    return {
+      chart,
+      window,
+      queries: PERCENTILES.map(({ label, phi }) => ({
+        label,
+        expr: `histogram_quantile(${phi}, sum by (le) (rate(${path}_bucket[${window}])))`,
+      })),
+    };
+  }
+  if (descriptor.kind === "counter") {
+    return {
+      chart,
+      window,
+      queries: [{ label: path, expr: `rate(${path}[${window}])` }],
+    };
+  }
+  // gauge | ratio | derived — read the level directly.
+  return { chart, window, queries: [{ label: path, expr: path }] };
+}

package/src/lib/reddb/ask.ts

@@ -0,0 +1,123 @@
+// RedDB's `ASK` — a grounded natural-language query that retrieves context
+// (tables, documents, vectors, graphs, KV) and synthesises an answer with
+// inline `[^N]` citations tied to specific sources (ADR 0013, v1 stable).
+//
+// Pinned against reddb: docs/api/http.md `POST /ai/ask` response shape +
+// .red/adr/0013-ask-grounding-citations.md (citation contract).
+//
+// This is the substrate for the /ask chat (eixo 4): the answer goes in the
+// conversation column, sources_flat becomes the visualization column, and the
+// citations link one to the other.
+
+export type AskSourceKind =
+  | "table"
+  | "document"
+  | "vector"
+  | "graph_node"
+  | "graph_edge"
+  | "kv";
+
+export interface AskSource {
+  kind: AskSourceKind;
+  /** `reddb:<collection>/<id>` (+ `#<score>`/`#<edge_id>`/`#<fragment>`). */
+  urn: string;
+  /** Raw text/JSON view of the retrieved source. */
+  content: string;
+  /** Retrieval rank score. */
+  score?: number;
+  // kind-specific extras
+  node_label?: string;
+  edge_relation?: string;
+  version?: string;
+}
+
+export interface AskCitation {
+  /** 1-based positional index into `sources_flat`. */
+  marker: number;
+  /** [start, end) character span of the cited claim in `answer`. */
+  span: [number, number];
+  urn: string;
+}
+
+export interface AskValidation {
+  ok: boolean;
+  warnings: string[];
+  errors: string[];
+}
+
+export interface AskResponse {
+  answer: string;
+  sources_flat: AskSource[];
+  citations: AskCitation[];
+  validation: AskValidation;
+  cache_hit?: boolean;
+  provider?: string;
+  model?: string;
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  cost_usd?: number;
+  mode?: string;
+  retry_count?: number;
+}
+
+export interface AskOptions {
+  provider?: string;
+  model?: string;
+  credential?: string;
+}
+
+/** A rendered piece of an answer: plain text, or a citation marker chip. */
+export type AnswerSegment =
+  | { type: "text"; value: string }
+  | { type: "cite"; marker: number };
+
+const MARKER_RE = /\[\^(\d+)\]/g;
+
+/**
+ * Split an answer into text + citation-marker segments for rendering. `[^N]`
+ * becomes a `cite` segment; an escaped `\[^N\]` is emitted as literal text
+ * (the backslash dropped), matching the ADR's escape rule. Markers inside
+ * fenced code blocks are left as text so we don't turn code into chips.
+ */
+export function parseAnswerSegments(answer: string): AnswerSegment[] {
+  const segments: AnswerSegment[] = [];
+  // Mask fenced code blocks so markers inside them are never parsed.
+  const codeSpans: Array<[number, number]> = [];
+  const fence = /```[\s\S]*?```|`[^`\n]*`/g;
+  let fm: RegExpExecArray | null;
+  while ((fm = fence.exec(answer)) !== null) {
+    codeSpans.push([fm.index, fm.index + fm[0].length]);
+  }
+  const inCode = (i: number) => codeSpans.some(([s, e]) => i >= s && i < e);
+
+  let last = 0;
+  let m: RegExpExecArray | null;
+  MARKER_RE.lastIndex = 0;
+  while ((m = MARKER_RE.exec(answer)) !== null) {
+    const start = m.index;
+    const escaped = start > 0 && answer[start - 1] === "\\";
+    if (escaped || inCode(start)) continue;
+    if (start > last)
+      segments.push({ type: "text", value: answer.slice(last, start) });
+    segments.push({ type: "cite", marker: Number(m[1]) });
+    last = start + m[0].length;
+  }
+  if (last < answer.length)
+    segments.push({ type: "text", value: answer.slice(last) });
+  // Render an escaped `\[^N\]` as the literal citation syntax by dropping the
+  // backslashes before its brackets.
+  return segments.map((seg) =>
+    seg.type === "text"
+      ? { type: "text", value: seg.value.replace(/\\([[\]])/g, "$1") }
+      : seg
+  );
+}
+
+/** Parse the collection + id out of a `reddb:<collection>/<id>` URN. */
+export function parseUrn(
+  urn: string
+): { collection: string; id: string } | null {
+  const m = /^reddb:([^/]+)\/(.+?)(?:#.*)?$/.exec(urn);
+  if (!m) return null;
+  return { collection: m[1], id: m[2] };
+}