okengine 0.11.2 → 0.12.0

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

@@ -1,260 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,143 +0,0 @@
-/**
- * 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(),
-  /**
-   * Lookback window: duration (`1h`, `5m`, `24h`) or epoch-ms lower bound.
-   * Filters the population by `startedAt`.
-   */
-  since: z.string().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;
-  if (search.since) out.since = search.since;
-  return out;
-}
-
-/**
- * Set or clear the lookback window (`1h`, `5m`, …).
- *
- * @param prev - Current search
- * @param since - Window string or null to clear
- */
-export function setSince(prev: RunsSearch, since: string | null): RunsSearch {
-  return { ...prev, since: since ?? undefined };
-}
-
-/**
- * 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

@@ -1,26 +0,0 @@
-/**
- * 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

@@ -1,87 +0,0 @@
-/**
- * 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()}`;
-}

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

@@ -1,135 +0,0 @@
-/**
- * Runs panel domain types — population view of the wide-event store
- * (console §9.11).
- */
-
-import type { EffectKind, ReversibilityTier } from "../../../kernel/effects.ts";
-
-/** One `fx.log` line on a run (never a separate stream). */
-export interface RunLogLine {
-  /** Log level. */
-  readonly level: "debug" | "info" | "warn" | "error";
-  /** Message. */
-  readonly message: string;
-  /** Optional structured payload. */
-  readonly data?: Record<string, unknown>;
-  /** Epoch-ms when emitted. */
-  readonly at: number;
-}
-
-/** One recorded effect on a run. */
-export interface RunEffect {
-  /** Effect kind. */
-  readonly kind: EffectKind;
-  /** Resource / signal / template / prompt / secret / flow ref. */
-  readonly resource: string;
-  /** Epoch-ms when the call started. */
-  readonly timestamp: number;
-  /** Wall duration in milliseconds. */
-  readonly duration: number;
-  /** Reversibility tier. */
-  readonly reversibility: ReversibilityTier;
-}
-
-/**
- * Flat wide-event record for the Runs panel (same store Traces folds).
- */
-export interface RunRecord {
-  /** Run id (= span id). */
-  readonly id: string;
-  /** Parent run id when caused by another execution. */
-  readonly parentId?: string | null;
-  /** Flow name. */
-  readonly flow: string;
-  /** Optional unit scope. */
-  readonly unit?: string | null;
-  /** Trigger kind. */
-  readonly trigger: string;
-  /** Auth plane. */
-  readonly plane: string;
-  /** Tenant id. */
-  readonly tenant?: string | null;
-  /** Principal id. */
-  readonly principal?: string | null;
-  /** Gate names evaluated. */
-  readonly gates: readonly string[];
-  /** Cache outcome. */
-  readonly cache: "hit" | "miss" | "none";
-  /** SQL role when observed. */
-  readonly replica?: "primary" | "replica" | null;
-  /** Replica lag ms when observed. */
-  readonly replicaLagMs?: number | null;
-  /** AI cost. */
-  readonly cost?: number | null;
-  /** Prompt version. */
-  readonly promptVersion?: number | null;
-  /** Build / release version. */
-  readonly buildVersion?: string | null;
-  /** Epoch-ms start. */
-  readonly startedAt: number;
-  /** Epoch-ms end. */
-  readonly endedAt: number;
-  /** Wall duration in milliseconds. */
-  readonly durationMs: number;
-  /** Typed error code when failed. */
-  readonly error?: string | null;
-  /** Effect ledger snapshot. */
-  readonly effects: readonly RunEffect[];
-  /** `fx.log` lines. */
-  readonly logs: readonly RunLogLine[];
-  /** All queryable dimensions. */
-  readonly dimensions: Readonly<Record<string, string | number | boolean | null>>;
-}
-
-/** Comparison operators for dimension clauses. */
-export type QueryOp = "=" | "!=" | ">" | "<" | ">=" | "<=";
-
-/** One dimension predicate in a population query. */
-export interface QueryClause {
-  /** Dimension name (`flow`, `cache`, `duration`, …). */
-  readonly dimension: string;
-  /** Comparison operator. */
-  readonly op: QueryOp;
-  /** Compared value (numbers already normalised; duration in ms). */
-  readonly value: string | number | boolean;
-}
-
-/** Parsed dimension query — AND of clauses (console §9.11). */
-export interface DimensionQuery {
-  /** Conjuncts. Empty means match all. */
-  readonly clauses: readonly QueryClause[];
-}
-
-/** Aggregate row for a group-by bucket. */
-export interface GroupAggregate {
-  /** Group key (dimension value as string, or `(empty)`). */
-  readonly key: string;
-  /** Run count. */
-  readonly count: number;
-  /** Mean duration ms. */
-  readonly avgDurationMs: number;
-  /** p50 duration ms. */
-  readonly p50DurationMs: number;
-  /** p99 duration ms. */
-  readonly p99DurationMs: number;
-  /** Sum of cost (0 when absent). */
-  readonly sumCost: number;
-}
-
-/** One histogram bucket over duration. */
-export interface DurationBucket {
-  /** Inclusive lower bound (ms). */
-  readonly minMs: number;
-  /** Exclusive upper bound (ms), except last bucket which is inclusive. */
-  readonly maxMs: number;
-  /** Runs in this bucket. */
-  readonly count: number;
-}
-
-/** Selected duration range on the distribution (outlier population). */
-export interface DurationRange {
-  /** Inclusive lower bound (ms). */
-  readonly minMs: number;
-  /** Inclusive upper bound (ms). */
-  readonly maxMs: number;
-}