okengine 0.1.4

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

@@ -0,0 +1,283 @@
+/**
+ * Dimension query language for the Runs panel (console §9.11).
+ *
+ * Expression form: `flow = X AND cache = miss AND duration > 1s`
+ * — analysis by dimension, not free-text search.
+ */
+
+import type {
+  DimensionQuery,
+  QueryClause,
+  QueryOp,
+  RunRecord,
+} from "./types.ts";
+
+const OPS: readonly QueryOp[] = ["!=", ">=", "<=", "=", ">", "<"];
+
+/**
+ * Parse a dimension query expression into clauses.
+ * Invalid tokens yield an empty query (never throw from the URL).
+ *
+ * @param expr - Expression string
+ */
+export function parseDimensionQuery(expr: string | undefined | null): DimensionQuery {
+  if (!expr || !expr.trim()) return { clauses: [] };
+  const parts = expr.split(/\s+AND\s+/i).map((p) => p.trim()).filter(Boolean);
+  const clauses: QueryClause[] = [];
+  for (const part of parts) {
+    const clause = parseClause(part);
+    if (clause) clauses.push(clause);
+  }
+  return { clauses };
+}
+
+/**
+ * Serialise clauses back to expression syntax.
+ *
+ * @param query - Parsed query
+ */
+export function serializeDimensionQuery(query: DimensionQuery): string {
+  return query.clauses.map(formatClause).join(" AND ");
+}
+
+/**
+ * Append one clause (or replace same dimension).
+ *
+ * @param query - Current query
+ * @param clause - Clause to add
+ */
+export function upsertClause(
+  query: DimensionQuery,
+  clause: QueryClause,
+): DimensionQuery {
+  const rest = query.clauses.filter((c) => c.dimension !== clause.dimension);
+  return { clauses: [...rest, clause] };
+}
+
+/**
+ * Remove a dimension from the query.
+ *
+ * @param query - Current query
+ * @param dimension - Dimension name
+ */
+export function removeClause(
+  query: DimensionQuery,
+  dimension: string,
+): DimensionQuery {
+  return {
+    clauses: query.clauses.filter((c) => c.dimension !== dimension),
+  };
+}
+
+/**
+ * Whether a run matches every clause.
+ *
+ * @param run - Wide-event projection
+ * @param query - Dimension query
+ */
+export function matchesDimensionQuery(
+  run: RunRecord,
+  query: DimensionQuery,
+): boolean {
+  for (const clause of query.clauses) {
+    if (!matchClause(run, clause)) return false;
+  }
+  return true;
+}
+
+/**
+ * Filter a population by the dimension query.
+ *
+ * @param runs - All runs
+ * @param query - Dimension query
+ */
+export function filterRuns(
+  runs: readonly RunRecord[],
+  query: DimensionQuery,
+): RunRecord[] {
+  if (query.clauses.length === 0) return [...runs];
+  return runs.filter((r) => matchesDimensionQuery(r, query));
+}
+
+/**
+ * Format a single clause for display / URL.
+ *
+ * @param clause - Clause
+ */
+export function formatClause(clause: QueryClause): string {
+  const v = formatValue(clause.dimension, clause.value);
+  return `${clause.dimension} ${clause.op} ${v}`;
+}
+
+/**
+ * Common dimensions offered by the builder (others remain typed).
+ */
+export const BUILDER_DIMENSIONS = [
+  "flow",
+  "unit",
+  "trigger",
+  "plane",
+  "tenant",
+  "principal",
+  "cache",
+  "replica",
+  "error",
+  "buildVersion",
+  "promptVersion",
+  "duration",
+] as const;
+
+function parseClause(raw: string): QueryClause | null {
+  let op: QueryOp | null = null;
+  let opAt = -1;
+  for (const candidate of OPS) {
+    const idx = raw.indexOf(` ${candidate} `);
+    if (idx === -1) continue;
+    // Prefer longer ops already ordered first.
+    op = candidate;
+    opAt = idx;
+    break;
+  }
+  if (op === null || opAt < 0) return null;
+  const dimension = raw.slice(0, opAt).trim();
+  const valueRaw = raw.slice(opAt + op.length + 2).trim();
+  if (!dimension || !valueRaw) return null;
+  const value = parseValue(dimension, valueRaw);
+  if (value === undefined) return null;
+  return { dimension, op, value };
+}
+
+function parseValue(
+  dimension: string,
+  raw: string,
+): string | number | boolean | undefined {
+  if (dimension === "duration" || dimension === "duration_ms") {
+    return parseDurationMs(raw);
+  }
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (
+    (raw.startsWith('"') && raw.endsWith('"')) ||
+    (raw.startsWith("'") && raw.endsWith("'"))
+  ) {
+    return raw.slice(1, -1);
+  }
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+  return raw;
+}
+
+/**
+ * Parse a duration literal (`1s`, `200ms`, `2m`, bare number = ms).
+ *
+ * @param raw - Literal
+ */
+export function parseDurationMs(raw: string): number | undefined {
+  const m = /^(-?\d+(?:\.\d+)?)\s*(ms|s|m)?$/i.exec(raw.trim());
+  if (!m) return undefined;
+  const n = Number(m[1]);
+  const unit = (m[2] ?? "ms").toLowerCase();
+  if (unit === "ms") return n;
+  if (unit === "s") return n * 1000;
+  if (unit === "m") return n * 60_000;
+  return undefined;
+}
+
+function formatValue(dimension: string, value: string | number | boolean): string {
+  if (dimension === "duration" || dimension === "duration_ms") {
+    const ms = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(ms)) return String(value);
+    if (ms >= 60_000 && ms % 60_000 === 0) return `${ms / 60_000}m`;
+    if (ms >= 1000 && ms % 1000 === 0) return `${ms / 1000}s`;
+    return `${ms}ms`;
+  }
+  if (typeof value === "string" && /\s/.test(value)) return `"${value}"`;
+  return String(value);
+}
+
+function matchClause(run: RunRecord, clause: QueryClause): boolean {
+  const left = dimensionValue(run, clause.dimension);
+  if (left === undefined || left === null) {
+    return clause.op === "!=";
+  }
+  const right = clause.value;
+  if (clause.op === "=") return compareEq(left, right);
+  if (clause.op === "!=") return !compareEq(left, right);
+  const ln = toNumber(left);
+  const rn = toNumber(right);
+  if (ln === undefined || rn === undefined) return false;
+  if (clause.op === ">") return ln > rn;
+  if (clause.op === "<") return ln < rn;
+  if (clause.op === ">=") return ln >= rn;
+  if (clause.op === "<=") return ln <= rn;
+  return false;
+}
+
+/**
+ * Resolve a dimension from top-level fields or `dimensions`.
+ *
+ * @param run - Run record
+ * @param name - Dimension name
+ */
+export function dimensionValue(
+  run: RunRecord,
+  name: string,
+): string | number | boolean | null | undefined {
+  switch (name) {
+    case "flow":
+      return run.flow;
+    case "unit":
+      return run.unit ?? null;
+    case "trigger":
+      return run.trigger;
+    case "plane":
+      return run.plane;
+    case "tenant":
+      return run.tenant ?? null;
+    case "principal":
+      return run.principal ?? null;
+    case "cache":
+      return run.cache;
+    case "replica":
+      return run.replica ?? null;
+    case "replicaLagMs":
+    case "replica_lag_ms":
+      return run.replicaLagMs ?? null;
+    case "error":
+    case "error_code":
+      return run.error ?? null;
+    case "buildVersion":
+    case "build_version":
+      return run.buildVersion ?? null;
+    case "promptVersion":
+    case "prompt_version":
+      return run.promptVersion ?? null;
+    case "cost":
+      return run.cost ?? null;
+    case "duration":
+    case "duration_ms":
+      return run.durationMs;
+    case "gates":
+      return run.gates.join(",");
+    default:
+      return run.dimensions[name];
+  }
+}
+
+function compareEq(
+  left: string | number | boolean,
+  right: string | number | boolean,
+): boolean {
+  if (typeof left === "number" || typeof right === "number") {
+    const ln = toNumber(left);
+    const rn = toNumber(right);
+    if (ln !== undefined && rn !== undefined) return ln === rn;
+  }
+  return String(left) === String(right);
+}
+
+function toNumber(v: string | number | boolean): number | undefined {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "boolean") return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Runs URL search state tests (console §9.11).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  dimensionQueryOf,
+  durationRangeOf,
+  parseRunsSearch,
+  serializeRunsSearch,
+  setDurationRange,
+  setWhere,
+} from "./search.ts";
+import { parseDimensionQuery } from "./query.ts";
+
+describe("runs search", () => {
+  test("round-trips where + group + brush + run", () => {
+    const search = parseRunsSearch({
+      where: "cache = miss AND duration > 1s",
+      group: "tenant",
+      run: "run_1",
+      durMin: "1000",
+      durMax: "5000",
+    });
+    expect(dimensionQueryOf(search).clauses).toHaveLength(2);
+    expect(durationRangeOf(search)).toEqual({ minMs: 1000, maxMs: 5000 });
+    expect(serializeRunsSearch(search)).toEqual({
+      where: "cache = miss AND duration > 1s",
+      group: "tenant",
+      run: "run_1",
+      durMin: 1000,
+      durMax: 5000,
+    });
+  });
+
+  test("setWhere / setDurationRange helpers", () => {
+    let s = parseRunsSearch({});
+    s = setWhere(s, parseDimensionQuery("flow = book"));
+    s = setDurationRange(s, { minMs: 10, maxMs: 20 });
+    expect(s.where).toBe("flow = book");
+    expect(s.durMin).toBe(10);
+    s = setDurationRange(s, null);
+    expect(s.durMin).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,141 @@
+/**
+ * Typed search params for the Runs panel (console §7 · §9.11).
+ *
+ * Population query, group-by, duration brush, and open run all live in the URL.
+ */
+
+import { z } from "zod";
+import {
+  parseDimensionQuery,
+  serializeDimensionQuery,
+} from "./query.ts";
+import type { DimensionQuery, DurationRange } from "./types.ts";
+
+/** Zod schema for Runs URL search params. */
+export const RunsSearchSchema = z.object({
+  /** Dimension query expression (`flow = X AND cache = miss`). */
+  where: z.string().optional(),
+  /** Group-by dimension. */
+  group: z.string().optional(),
+  /** Open run id for the flat detail record. */
+  run: z.string().optional(),
+  /** Duration brush lower bound (ms). */
+  durMin: z.coerce.number().optional(),
+  /** Duration brush upper bound (ms). */
+  durMax: z.coerce.number().optional(),
+});
+
+/** Parsed, typed Runs search state. */
+export type RunsSearch = z.infer<typeof RunsSearchSchema>;
+
+/**
+ * Parse unknown search params into a typed {@link RunsSearch}.
+ *
+ * @param raw - Router search object
+ */
+export function parseRunsSearch(raw: unknown): RunsSearch {
+  const result = RunsSearchSchema.safeParse(raw ?? {});
+  if (result.success) return result.data;
+  return RunsSearchSchema.parse({});
+}
+
+/**
+ * Serialise typed search into a plain object for TanStack Router.
+ *
+ * @param search - Typed search
+ */
+export function serializeRunsSearch(
+  search: RunsSearch,
+): Record<string, string | number> {
+  const out: Record<string, string | number> = {};
+  if (search.where) out.where = search.where;
+  if (search.group) out.group = search.group;
+  if (search.run) out.run = search.run;
+  if (search.durMin !== undefined) out.durMin = search.durMin;
+  if (search.durMax !== undefined) out.durMax = search.durMax;
+  return out;
+}
+
+/**
+ * Dimension query derived from search.
+ *
+ * @param search - Typed search
+ */
+export function dimensionQueryOf(search: RunsSearch): DimensionQuery {
+  return parseDimensionQuery(search.where);
+}
+
+/**
+ * Duration range when both bounds are present.
+ *
+ * @param search - Typed search
+ */
+export function durationRangeOf(search: RunsSearch): DurationRange | null {
+  if (search.durMin === undefined || search.durMax === undefined) return null;
+  return {
+    minMs: Math.min(search.durMin, search.durMax),
+    maxMs: Math.max(search.durMin, search.durMax),
+  };
+}
+
+/**
+ * Set the dimension query expression from a parsed query.
+ *
+ * @param prev - Current search
+ * @param query - Dimension query
+ */
+export function setWhere(
+  prev: RunsSearch,
+  query: DimensionQuery,
+): RunsSearch {
+  const where = serializeDimensionQuery(query);
+  return { ...prev, where: where || undefined };
+}
+
+/**
+ * Set or clear the group-by dimension.
+ *
+ * @param prev - Current search
+ * @param dimension - Dimension or null to clear
+ */
+export function setGroup(
+  prev: RunsSearch,
+  dimension: string | null,
+): RunsSearch {
+  return { ...prev, group: dimension ?? undefined };
+}
+
+/**
+ * Open a run's flat detail record.
+ *
+ * @param prev - Current search
+ * @param runId - Run id
+ */
+export function openRun(prev: RunsSearch, runId: string): RunsSearch {
+  return { ...prev, run: runId };
+}
+
+/**
+ * Close the detail view; stay on the Runs panel.
+ *
+ * @param prev - Current search
+ */
+export function closeRun(prev: RunsSearch): RunsSearch {
+  return { ...prev, run: undefined };
+}
+
+/**
+ * Set the duration brush (outlier population), or clear with null.
+ *
+ * @param prev - Current search
+ * @param range - Selected range
+ */
+export function setDurationRange(
+  prev: RunsSearch,
+  range: DurationRange | null,
+): RunsSearch {
+  if (!range) {
+    return { ...prev, durMin: undefined, durMax: undefined };
+  }
+  return { ...prev, durMin: range.minMs, durMax: range.maxMs };
+}

package/src/console/ui/runs/trace-link.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Runs ↔ Traces cross-link tests (console §9.11).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { RUNS_CHAIN_FIXTURE } from "./fixture.ts";
+import {
+  rootIdOf,
+  runsHrefForSpan,
+  shouldOfferTracesLink,
+  spanCountInTrace,
+  tracesHrefForRun,
+} from "./trace-link.ts";
+
+describe("trace cross-link", () => {
+  test("multi-span chain offers Traces link", () => {
+    expect(rootIdOf(RUNS_CHAIN_FIXTURE, "run-fulfill")).toBe("run-create-ok");
+    expect(spanCountInTrace(RUNS_CHAIN_FIXTURE, "run-create-ok")).toBe(2);
+    expect(shouldOfferTracesLink(RUNS_CHAIN_FIXTURE, "run-fulfill")).toBe(
+      true,
+    );
+    expect(shouldOfferTracesLink(RUNS_CHAIN_FIXTURE, "run-create-fail")).toBe(
+      false,
+    );
+    expect(tracesHrefForRun(RUNS_CHAIN_FIXTURE, "run-fulfill")).toBe(
+      "/traces?trace=run-create-ok&span=run-fulfill",
+    );
+    expect(runsHrefForSpan("run-create-ok")).toBe("/runs?run=run-create-ok");
+  });
+});

package/src/console/ui/runs/trace-link.ts

@@ -0,0 +1,99 @@
+/**
+ * Cross-links between Runs (population) and Traces (causal chain).
+ */
+
+import type { RunRecord } from "./types.ts";
+
+/**
+ * Walk parentId links to the root of a run's causal chain.
+ *
+ * @param runs - Population (must include ancestors)
+ * @param runId - Starting run id
+ */
+export function rootIdOf(
+  runs: readonly RunRecord[],
+  runId: string,
+): string {
+  const byId = new Map(runs.map((r) => [r.id, r]));
+  let cursor = byId.get(runId);
+  if (!cursor) return runId;
+  const seen = new Set<string>();
+  while (cursor.parentId && byId.has(cursor.parentId)) {
+    if (seen.has(cursor.id)) break;
+    seen.add(cursor.id);
+    cursor = byId.get(cursor.parentId)!;
+  }
+  return cursor.id;
+}
+
+/**
+ * Count spans in the connected component rooted at {@link rootId}.
+ *
+ * @param runs - Population
+ * @param rootId - Trace root id
+ */
+export function spanCountInTrace(
+  runs: readonly RunRecord[],
+  rootId: string,
+): number {
+  const byId = new Map(runs.map((r) => [r.id, r]));
+  if (!byId.has(rootId)) return 0;
+  const childrenOf = new Map<string, string[]>();
+  for (const r of runs) {
+    if (!r.parentId || !byId.has(r.parentId)) continue;
+    const list = childrenOf.get(r.parentId) ?? [];
+    list.push(r.id);
+    childrenOf.set(r.parentId, list);
+  }
+  let count = 0;
+  const stack = [rootId];
+  const seen = new Set<string>();
+  while (stack.length > 0) {
+    const id = stack.pop()!;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    count += 1;
+    for (const child of childrenOf.get(id) ?? []) stack.push(child);
+  }
+  return count;
+}
+
+/**
+ * Whether opening this run should offer "Open in Traces"
+ * (trace has more than one span).
+ *
+ * @param runs - Population
+ * @param runId - Selected run
+ */
+export function shouldOfferTracesLink(
+  runs: readonly RunRecord[],
+  runId: string,
+): boolean {
+  const root = rootIdOf(runs, runId);
+  return spanCountInTrace(runs, root) > 1;
+}
+
+/**
+ * Build the Traces panel href for a run.
+ *
+ * @param runs - Population
+ * @param runId - Selected run (becomes focus span)
+ */
+export function tracesHrefForRun(
+  runs: readonly RunRecord[],
+  runId: string,
+): string {
+  const root = rootIdOf(runs, runId);
+  const params = new URLSearchParams({ trace: root, span: runId });
+  return `/traces?${params.toString()}`;
+}
+
+/**
+ * Build the Runs panel href for a span.
+ *
+ * @param runId - Span / run id
+ */
+export function runsHrefForSpan(runId: string): string {
+  const params = new URLSearchParams({ run: runId });
+  return `/runs?${params.toString()}`;
+}