okengine 0.1.4

package/src/console/ui/runs/group.ts

@@ -0,0 +1,85 @@
+/**
+ * Group-by with aggregates over a filtered run population (console §9.11).
+ */
+
+import { dimensionValue } from "./query.ts";
+import type { GroupAggregate, RunRecord } from "./types.ts";
+
+/**
+ * Group runs by any dimension and compute duration/cost/count aggregates.
+ *
+ * @param runs - Filtered population
+ * @param dimension - Dimension to group by
+ */
+export function groupByDimension(
+  runs: readonly RunRecord[],
+  dimension: string,
+): GroupAggregate[] {
+  const buckets = new Map<string, RunRecord[]>();
+  for (const run of runs) {
+    const raw = dimensionValue(run, dimension);
+    const key =
+      raw === undefined || raw === null || raw === ""
+        ? "(empty)"
+        : String(raw);
+    const list = buckets.get(key) ?? [];
+    list.push(run);
+    buckets.set(key, list);
+  }
+
+  const rows: GroupAggregate[] = [];
+  for (const [key, list] of buckets) {
+    const durations = list.map((r) => r.durationMs).sort((a, b) => a - b);
+    const sumDuration = durations.reduce((a, b) => a + b, 0);
+    const sumCost = list.reduce((a, r) => a + (r.cost ?? 0), 0);
+    rows.push({
+      key,
+      count: list.length,
+      avgDurationMs: list.length === 0 ? 0 : sumDuration / list.length,
+      p50DurationMs: percentile(durations, 0.5),
+      p99DurationMs: percentile(durations, 0.99),
+      sumCost,
+    });
+  }
+
+  rows.sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
+  return rows;
+}
+
+/**
+ * Discover dimension names present in a population (for group-by picker).
+ *
+ * @param runs - Population
+ */
+export function discoverDimensions(runs: readonly RunRecord[]): string[] {
+  const known = new Set<string>([
+    "flow",
+    "unit",
+    "trigger",
+    "plane",
+    "tenant",
+    "principal",
+    "cache",
+    "replica",
+    "error",
+    "buildVersion",
+    "promptVersion",
+  ]);
+  for (const run of runs) {
+    for (const k of Object.keys(run.dimensions)) {
+      if (k === "duration_ms") continue;
+      known.add(k);
+    }
+  }
+  return [...known].sort((a, b) => a.localeCompare(b));
+}
+
+function percentile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0]!;
+  const idx = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil(p * sorted.length) - 1),
+  );
+  return sorted[idx]!;
+}

package/src/console/ui/runs/histogram.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Duration distribution tests (console §9.11).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { runsOutlierFixture } from "./fixture.ts";
+import {
+  durationHistogram,
+  inDurationRange,
+  normalizeRange,
+} from "./histogram.ts";
+
+describe("duration histogram", () => {
+  test("buckets cover the population", () => {
+    const runs = runsOutlierFixture();
+    const buckets = durationHistogram(runs, 10);
+    expect(buckets.length).toBe(10);
+    const total = buckets.reduce((a, b) => a + b.count, 0);
+    expect(total).toBe(runs.length);
+  });
+
+  test("range helpers", () => {
+    expect(normalizeRange(2000, 40)).toEqual({ minMs: 40, maxMs: 2000 });
+    expect(
+      inDurationRange(
+        { durationMs: 2000 } as never,
+        { minMs: 1000, maxMs: 3000 },
+      ),
+    ).toBe(true);
+  });
+});

package/src/console/ui/runs/histogram.ts

@@ -0,0 +1,85 @@
+/**
+ * Duration distribution over the current filter (console §9.11).
+ */
+
+import type { DurationBucket, DurationRange, RunRecord } from "./types.ts";
+
+/** Default bucket count for the histogram. */
+export const DEFAULT_BUCKET_COUNT = 20;
+
+/**
+ * Build a duration histogram for the filtered population.
+ *
+ * @param runs - Filtered runs
+ * @param bucketCount - Number of buckets (default 20)
+ */
+export function durationHistogram(
+  runs: readonly RunRecord[],
+  bucketCount: number = DEFAULT_BUCKET_COUNT,
+): DurationBucket[] {
+  if (runs.length === 0 || bucketCount < 1) return [];
+
+  let min = Infinity;
+  let max = -Infinity;
+  for (const r of runs) {
+    min = Math.min(min, r.durationMs);
+    max = Math.max(max, r.durationMs);
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return [];
+  if (min === max) {
+    return [{ minMs: min, maxMs: max + 1, count: runs.length }];
+  }
+
+  const width = (max - min) / bucketCount;
+  const buckets: DurationBucket[] = [];
+  for (let i = 0; i < bucketCount; i++) {
+    const lo = min + i * width;
+    const hi = i === bucketCount - 1 ? max + Number.EPSILON : min + (i + 1) * width;
+    buckets.push({ minMs: lo, maxMs: hi, count: 0 });
+  }
+
+  for (const r of runs) {
+    let idx = Math.floor((r.durationMs - min) / width);
+    if (idx < 0) idx = 0;
+    if (idx >= bucketCount) idx = bucketCount - 1;
+    const b = buckets[idx]!;
+    buckets[idx] = { ...b, count: b.count + 1 };
+  }
+
+  return buckets;
+}
+
+/**
+ * Whether a run falls inside an inclusive duration range.
+ *
+ * @param run - Run
+ * @param range - Selected region
+ */
+export function inDurationRange(
+  run: RunRecord,
+  range: DurationRange,
+): boolean {
+  return run.durationMs >= range.minMs && run.durationMs <= range.maxMs;
+}
+
+/**
+ * Normalise a brush selection against histogram bounds.
+ *
+ * @param a - First bound (ms)
+ * @param b - Second bound (ms)
+ */
+export function normalizeRange(a: number, b: number): DurationRange {
+  return a <= b ? { minMs: a, maxMs: b } : { minMs: b, maxMs: a };
+}
+
+/**
+ * Format a duration for axis / chip labels.
+ *
+ * @param ms - Milliseconds
+ */
+export function formatDurationMs(ms: number): string {
+  if (!Number.isFinite(ms)) return "—";
+  if (ms >= 60_000) return `${(ms / 60_000).toFixed(ms % 60_000 === 0 ? 0 : 1)}m`;
+  if (ms >= 1000) return `${(ms / 1000).toFixed(ms % 1000 === 0 ? 0 : 2)}s`;
+  return `${Math.round(ms)}ms`;
+}

package/src/console/ui/runs/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Runs panel — population analysis of the wide-event store (console §9.11).
+ *
+ * Pure modules live here so `bun test src/console/ui/runs` gates behaviour
+ * without mounting the full SPA.
+ */
+
+export {
+  explainDurationOutliers,
+  type OutlierFinding,
+} from "./explain.ts";
+export {
+  RUNS_CHAIN_FIXTURE,
+  RUNS_FIXTURE_T0,
+  runsOutlierFixture,
+} from "./fixture.ts";
+export {
+  discoverDimensions,
+  groupByDimension,
+} from "./group.ts";
+export {
+  DEFAULT_BUCKET_COUNT,
+  durationHistogram,
+  formatDurationMs,
+  inDurationRange,
+  normalizeRange,
+} from "./histogram.ts";
+export {
+  rowToRun,
+  runToWideEvent,
+  type RunsListRow,
+} from "./project.ts";
+export {
+  BUILDER_DIMENSIONS,
+  dimensionValue,
+  filterRuns,
+  formatClause,
+  matchesDimensionQuery,
+  parseDimensionQuery,
+  parseDurationMs,
+  removeClause,
+  serializeDimensionQuery,
+  upsertClause,
+} from "./query.ts";
+export {
+  closeRun,
+  dimensionQueryOf,
+  durationRangeOf,
+  openRun,
+  parseRunsSearch,
+  RunsSearchSchema,
+  serializeRunsSearch,
+  setDurationRange,
+  setGroup,
+  setWhere,
+  type RunsSearch,
+} from "./search.ts";
+export {
+  rootIdOf,
+  runsHrefForSpan,
+  shouldOfferTracesLink,
+  spanCountInTrace,
+  tracesHrefForRun,
+} from "./trace-link.ts";
+export type {
+  DimensionQuery,
+  DurationBucket,
+  DurationRange,
+  GroupAggregate,
+  QueryClause,
+  QueryOp,
+  RunEffect,
+  RunLogLine,
+  RunRecord,
+} from "./types.ts";

package/src/console/ui/runs/project.ts

@@ -0,0 +1,122 @@
+/**
+ * Project API rows ↔ Runs panel records ↔ WideEvent for outlier explanation.
+ */
+
+import type { WideEvent } from "../../../runs/types.ts";
+import type { RunRecord } from "./types.ts";
+
+/** Loose API row from `console.runs.list`. */
+export interface RunsListRow {
+  readonly id: string;
+  readonly parentId?: string | null;
+  readonly flow: string;
+  readonly unit?: string | null;
+  readonly trigger: string;
+  readonly plane: string;
+  readonly tenant?: string | null;
+  readonly principal?: string | null;
+  readonly gates?: readonly string[];
+  readonly cache?: "hit" | "miss" | "none";
+  readonly replica?: "primary" | "replica" | null;
+  readonly replicaLagMs?: number | null;
+  readonly cost?: number | null;
+  readonly promptVersion?: number | null;
+  readonly buildVersion?: string | null;
+  readonly startedAt: number;
+  readonly endedAt: number;
+  readonly durationMs: number;
+  readonly error?: string | null;
+  readonly effects?: RunRecord["effects"];
+  readonly logs?: RunRecord["logs"];
+  readonly dimensions?: Readonly<
+    Record<string, string | number | boolean | null>
+  >;
+}
+
+/**
+ * Map an API row to a {@link RunRecord}.
+ *
+ * @param row - GET /console/runs row
+ */
+export function rowToRun(row: RunsListRow): RunRecord {
+  const dimensions: Record<string, string | number | boolean | null> = {
+    ...(row.dimensions ?? {}),
+  };
+  // Ensure top-level fields are queryable even when dimensions omit them.
+  if (dimensions.flow === undefined) dimensions.flow = row.flow;
+  if (dimensions.unit === undefined) dimensions.unit = row.unit ?? null;
+  if (dimensions.trigger === undefined) dimensions.trigger = row.trigger;
+  if (dimensions.plane === undefined) dimensions.plane = row.plane;
+  if (dimensions.tenant === undefined) dimensions.tenant = row.tenant ?? null;
+  if (dimensions.principal === undefined) {
+    dimensions.principal = row.principal ?? null;
+  }
+  if (dimensions.cache === undefined) {
+    dimensions.cache = row.cache ?? "none";
+  }
+  if (dimensions.duration_ms === undefined) {
+    dimensions.duration_ms = row.durationMs;
+  }
+  if (dimensions.error_code === undefined && row.error) {
+    dimensions.error_code = row.error;
+  }
+
+  return {
+    id: row.id,
+    parentId: row.parentId ?? null,
+    flow: row.flow,
+    unit: row.unit ?? null,
+    trigger: row.trigger,
+    plane: row.plane,
+    tenant: row.tenant ?? null,
+    principal: row.principal ?? null,
+    gates: row.gates ?? [],
+    cache: row.cache ?? "none",
+    replica: row.replica ?? null,
+    replicaLagMs: row.replicaLagMs ?? null,
+    cost: row.cost ?? null,
+    promptVersion: row.promptVersion ?? null,
+    buildVersion: row.buildVersion ?? null,
+    startedAt: row.startedAt,
+    endedAt: row.endedAt,
+    durationMs: row.durationMs,
+    error: row.error ?? null,
+    effects: row.effects ?? [],
+    logs: row.logs ?? [],
+    dimensions,
+  };
+}
+
+/**
+ * Convert a run record into a WideEvent shape for {@link explainOutliers}.
+ *
+ * @param run - Panel record
+ */
+export function runToWideEvent(run: RunRecord): WideEvent {
+  return {
+    id: run.id,
+    ...(run.parentId ? { parentId: run.parentId } : {}),
+    flow: run.flow,
+    ...(run.unit ? { unit: run.unit } : {}),
+    trigger: run.trigger,
+    plane: run.plane as WideEvent["plane"],
+    tenant: run.tenant,
+    principal: run.principal,
+    gates: run.gates,
+    cache: run.cache,
+    ...(run.replica ? { replica: run.replica } : {}),
+    ...(run.replicaLagMs != null ? { replicaLagMs: run.replicaLagMs } : {}),
+    ...(run.cost != null ? { cost: run.cost } : {}),
+    ...(run.promptVersion != null
+      ? { promptVersion: run.promptVersion }
+      : {}),
+    ...(run.buildVersion ? { buildVersion: run.buildVersion } : {}),
+    error: run.error ? { code: run.error } : null,
+    effects: run.effects as WideEvent["effects"],
+    logs: run.logs,
+    durationMs: run.durationMs,
+    startedAt: run.startedAt,
+    endedAt: run.endedAt,
+    dimensions: { ...run.dimensions },
+  };
+}

package/src/console/ui/runs/query.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Dimension query language tests (console §9.11).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { RUNS_CHAIN_FIXTURE } from "./fixture.ts";
+import {
+  filterRuns,
+  formatClause,
+  parseDimensionQuery,
+  parseDurationMs,
+  serializeDimensionQuery,
+  upsertClause,
+} from "./query.ts";
+
+describe("dimension query", () => {
+  test("parses flow = X AND cache = miss AND duration > 1s", () => {
+    const q = parseDimensionQuery(
+      "flow = bookings.create AND cache = miss AND duration > 1s",
+    );
+    expect(q.clauses).toEqual([
+      { dimension: "flow", op: "=", value: "bookings.create" },
+      { dimension: "cache", op: "=", value: "miss" },
+      { dimension: "duration", op: ">", value: 1000 },
+    ]);
+    expect(serializeDimensionQuery(q)).toBe(
+      "flow = bookings.create AND cache = miss AND duration > 1s",
+    );
+  });
+
+  test("duration units ms / s / m", () => {
+    expect(parseDurationMs("200ms")).toBe(200);
+    expect(parseDurationMs("1s")).toBe(1000);
+    expect(parseDurationMs("2m")).toBe(120_000);
+    expect(parseDurationMs("50")).toBe(50);
+  });
+
+  test("filters the chain fixture by cache = miss", () => {
+    const q = parseDimensionQuery("cache = miss");
+    const hits = filterRuns(RUNS_CHAIN_FIXTURE, q);
+    expect(hits.map((r) => r.id)).toEqual(["run-create-fail"]);
+  });
+
+  test("upsert replaces same dimension", () => {
+    let q = parseDimensionQuery("cache = hit");
+    q = upsertClause(q, { dimension: "cache", op: "=", value: "miss" });
+    expect(serializeDimensionQuery(q)).toBe("cache = miss");
+    expect(formatClause(q.clauses[0]!)).toBe("cache = miss");
+  });
+});