okengine 0.11.2 → 0.12.0

package/src/console/ui-next/src/features/flows/traces/effect-summary.ts

@@ -0,0 +1,193 @@
+/**
+ * Summary chips for the trace detail Sheet — counts from real effects[] + logs.
+ *
+ * SQL store work is elevated as "DB queries" (resource prefix `sql:`), matching
+ * the compact scan language of professional trace sheets — without inventing an
+ * EffectKind. Tier-1 cache lookups (`computed:…`) are "cache reads". Other
+ * reads/writes still surface as EffectKind chips.
+ */
+
+import type { RunEffect, RunRow } from "@/client.ts";
+import { formatDuration } from "./format-duration.ts";
+import { effectKindSummaryLabel, type RunEffectKind } from "./effect-kind.ts";
+
+/** Visual variant for a summary chip (drives icon + accent). */
+export type EffectSummaryVariant =
+  | "duration"
+  | "api"
+  | "gate"
+  | "cache"
+  | "db"
+  | "logs"
+  | RunEffectKind;
+
+/** One chip in the Sheet summary row. */
+export type EffectSummaryChip = {
+  /** Stable key for React lists. */
+  readonly key: string;
+  /** Human label, e.g. `"2 DB queries"` or `"1 API call"`. */
+  readonly label: string;
+  /** Compact label for dense strips, e.g. `"2 DB"` or `"1 API"`. */
+  readonly shortLabel: string;
+  /** Icon / color variant for the summary strip. */
+  readonly variant: EffectSummaryVariant;
+  /** How the value was derived from the run (tooltip / a11y). */
+  readonly detail: string;
+};
+
+/** Ordered EffectKind keys for stable chip order (after DB aggregation). */
+const KIND_ORDER: readonly RunEffectKind[] = [
+  "read",
+  "write",
+  "emit",
+  "call",
+  "ask",
+  "send",
+  "secret",
+];
+
+/**
+ * True when an effect targets a SQL store resource (`sql:…`).
+ *
+ * @param resource - Effect resource ref
+ */
+export function isSqlResource(resource: string): boolean {
+  return resource.startsWith("sql:");
+}
+
+/**
+ * True when an effect is a tier-1 auto-cache lookup (`computed:…`).
+ *
+ * @param resource - Effect resource ref
+ */
+export function isComputedCacheKey(resource: string): boolean {
+  return resource.startsWith("computed:");
+}
+
+/**
+ * Build summary chips from a projected run.
+ *
+ * - Duration always first (via {@link formatDuration}).
+ * - HTTP triggers add `"1 API call"` for the invocation itself (not an effect).
+ * - Evaluated gates (`run.gates`) add `"N gate(s)"` with names in the detail.
+ * - SQL store effects (`sql:…`) collapse into `"N DB queries"`.
+ * - Remaining EffectKinds (non-SQL reads/writes, emits, …) get their own chips.
+ * - Log line count from `logs.length`.
+ *
+ * @param run - Projected run row
+ */
+export function effectSummaryChips(
+  run: Pick<RunRow, "trigger" | "durationMs" | "effects" | "logs" | "gates">,
+): readonly EffectSummaryChip[] {
+  const chips: EffectSummaryChip[] = [
+    {
+      key: "duration",
+      label: formatDuration(run.durationMs),
+      shortLabel: formatDuration(run.durationMs),
+      variant: "duration",
+      detail: `Handler duration from the run ledger (${formatDuration(run.durationMs)}).`,
+    },
+  ];
+
+  if (run.trigger === "http") {
+    chips.push({
+      key: "api",
+      label: "1 API call",
+      shortLabel: "1 API",
+      variant: "api",
+      detail: "HTTP trigger invocation for this run (not counted as an effect).",
+    });
+  }
+
+  const gateCount = run.gates.length;
+  if (gateCount > 0) {
+    chips.push({
+      key: "gates",
+      label: `${gateCount} ${gateCount === 1 ? "gate" : "gates"}`,
+      shortLabel: `${gateCount} gate${gateCount === 1 ? "" : "s"}`,
+      variant: "gate",
+      detail: `Evaluated on this run: ${run.gates.join(", ")}.`,
+    });
+  }
+
+  const cacheCount = run.effects.filter((e) => isComputedCacheKey(e.resource)).length;
+  if (cacheCount > 0) {
+    chips.push({
+      key: "cache",
+      label: `${cacheCount} cache ${cacheCount === 1 ? "read" : "reads"}`,
+      shortLabel: `${cacheCount} cache`,
+      variant: "cache",
+      detail: `${cacheCount} effect${cacheCount === 1 ? "" : "s"} targeting computed:… cache keys.`,
+    });
+  }
+
+  const dbCount = run.effects.filter((e) => isSqlResource(e.resource)).length;
+  if (dbCount > 0) {
+    chips.push({
+      key: "db",
+      label: `${dbCount} DB ${dbCount === 1 ? "query" : "queries"}`,
+      shortLabel: `${dbCount} DB`,
+      variant: "db",
+      detail: `${dbCount} effect${dbCount === 1 ? "" : "s"} targeting sql:… store resources.`,
+    });
+  }
+
+  const counts = countByKindExcludingSpecial(run.effects);
+  for (const kind of KIND_ORDER) {
+    const n = counts.get(kind) ?? 0;
+    if (n === 0) continue;
+    chips.push({
+      key: kind,
+      label: effectKindSummaryLabel(kind, n),
+      shortLabel: effectKindSummaryLabel(kind, n),
+      variant: kind,
+      detail: `${n} non-SQL ${kind} effect${n === 1 ? "" : "s"} on the run ledger.`,
+    });
+  }
+
+  const logCount = run.logs.length;
+  if (logCount > 0) {
+    chips.push({
+      key: "logs",
+      label: `${logCount} log ${logCount === 1 ? "line" : "lines"}`,
+      shortLabel: `${logCount} log${logCount === 1 ? "" : "s"}`,
+      variant: "logs",
+      detail: `${logCount} ${logCount === 1 ? "entry" : "entries"} in run.logs.`,
+    });
+  }
+
+  return chips;
+}
+
+/**
+ * Event-detail label — SQL resources read as "DB query" / "DB write".
+ *
+ * @param effect - Ledger entry
+ */
+export function effectEventLabel(effect: Pick<RunEffect, "kind" | "resource">): string {
+  if (isComputedCacheKey(effect.resource)) {
+    return "Cache read";
+  }
+  if (isSqlResource(effect.resource)) {
+    return effect.kind === "write" ? "DB write" : "DB query";
+  }
+  const labels: Record<RunEffectKind, string> = {
+    read: "Read",
+    write: "Write",
+    emit: "Emit",
+    send: "Send",
+    ask: "Ask",
+    secret: "Secret",
+    call: "Call",
+  };
+  return labels[effect.kind];
+}
+
+function countByKindExcludingSpecial(effects: readonly RunEffect[]): Map<RunEffectKind, number> {
+  const counts = new Map<RunEffectKind, number>();
+  for (const e of effects) {
+    if (isSqlResource(e.resource) || isComputedCacheKey(e.resource)) continue;
+    counts.set(e.kind, (counts.get(e.kind) ?? 0) + 1);
+  }
+  return counts;
+}

package/src/console/ui-next/src/features/flows/traces/filter-runs.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Unit tests for Traces client-side filters.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { RunRow } from "@/client.ts";
+import { EMPTY_DIMENSION_QUERY, parseDimensionQuery } from "./dimension-query.ts";
+import { filterScopedRuns, type TracesFilters } from "./filter-runs.ts";
+
+function run(partial: Partial<RunRow> & Pick<RunRow, "id" | "flow" | "durationMs">): RunRow {
+  return {
+    parentId: null,
+    unit: null,
+    trigger: "http",
+    plane: "user",
+    tenant: null,
+    principal: null,
+    gates: [],
+    cache: "none",
+    replica: null,
+    replicaLagMs: null,
+    cost: null,
+    inputTokens: null,
+    outputTokens: null,
+    promptVersion: null,
+    buildVersion: null,
+    startedAt: 1,
+    endedAt: 2,
+    error: null,
+    errorMessage: null,
+    sampled: "sample",
+    effects: [],
+    logs: [],
+    dimensions: {},
+    input: null,
+    output: null,
+    ...partial,
+  };
+}
+
+const base: Pick<TracesFilters, "advanced" | "query"> = {
+  advanced: EMPTY_DIMENSION_QUERY,
+  query: "",
+};
+
+describe("filterScopedRuns", () => {
+  const rows = [
+    run({ id: "ok-fast", flow: "a", durationMs: 5, error: null }),
+    run({ id: "ok-mid", flow: "a", durationMs: 56, error: null, trigger: "signal" }),
+    run({ id: "err-slow", flow: "b", durationMs: 1_200, error: "Timeout", cache: "miss" }),
+  ];
+
+  test("all returns every row", () => {
+    const filters: TracesFilters = { status: "all", ...base };
+    expect(filterScopedRuns(rows, filters).map((r) => r.id)).toEqual([
+      "ok-fast",
+      "ok-mid",
+      "err-slow",
+    ]);
+  });
+
+  test("errors-only keeps failed runs", () => {
+    const filters: TracesFilters = { status: "errors", ...base };
+    expect(filterScopedRuns(rows, filters).map((r) => r.id)).toEqual(["err-slow"]);
+  });
+
+  test("advanced dimension query composes with basic filters", () => {
+    const filters: TracesFilters = {
+      ...base,
+      status: "all",
+      advanced: parseDimensionQuery("trigger = signal"),
+    };
+    expect(filterScopedRuns(rows, filters).map((r) => r.id)).toEqual(["ok-mid"]);
+  });
+
+  test("free-text query matches flow, trigger, cache, and error", () => {
+    expect(filterScopedRuns(rows, { status: "all", ...base, query: "b" }).map((r) => r.id)).toEqual(
+      ["err-slow"],
+    );
+    expect(
+      filterScopedRuns(rows, {
+        status: "all",
+        ...base,
+        query: "signal",
+      }).map((r) => r.id),
+    ).toEqual(["ok-mid"]);
+    expect(
+      filterScopedRuns(rows, { status: "all", ...base, query: "miss" }).map((r) => r.id),
+    ).toEqual(["err-slow"]);
+    expect(
+      filterScopedRuns(rows, {
+        status: "all",
+        ...base,
+        query: "timeout",
+      }).map((r) => r.id),
+    ).toEqual(["err-slow"]);
+  });
+});

package/src/console/ui-next/src/features/flows/traces/filter-runs.ts

@@ -0,0 +1,68 @@
+/**
+ * Client-side Traces filters over the already-scoped runs buffer.
+ *
+ * Always-on: free-text search + status.
+ * Advanced: dimension query language shared with Runs (§9.11).
+ */
+
+import type { RunRow } from "@/client.ts";
+import {
+  EMPTY_DIMENSION_QUERY,
+  filterByDimensionQuery,
+  type DimensionQuery,
+} from "./dimension-query.ts";
+
+/** Status filter for the Traces pane (All / Errors only). */
+export type TracesStatusFilter = "all" | "errors";
+
+/** Active Traces list filters. */
+export type TracesFilters = {
+  /** Free-text needle — flow, unit, trigger, cache, error, run id. */
+  readonly query: string;
+  readonly status: TracesStatusFilter;
+  /** Advanced dimension query (`flow = X AND …`). */
+  readonly advanced: DimensionQuery;
+};
+
+/** Default filters — show every scoped run. */
+export const DEFAULT_TRACES_FILTERS: TracesFilters = {
+  query: "",
+  status: "all",
+  advanced: EMPTY_DIMENSION_QUERY,
+};
+
+/**
+ * Whether a run matches the Traces search box.
+ *
+ * @param run - Projected run
+ * @param query - Free-text needle
+ */
+export function runMatchesQuery(run: RunRow, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  const haystacks = [
+    run.flow,
+    run.unit ?? "",
+    run.trigger,
+    run.cache,
+    run.id,
+    run.error ?? "",
+    run.errorMessage ?? "",
+  ];
+  return haystacks.some((h) => h.toLowerCase().includes(q));
+}
+
+/**
+ * Apply search + status + advanced dimension filters.
+ *
+ * @param runs - Already graph-scoped runs
+ * @param filters - Active filters
+ */
+export function filterScopedRuns(runs: readonly RunRow[], filters: TracesFilters): RunRow[] {
+  const basic = runs.filter((run) => {
+    if (!runMatchesQuery(run, filters.query)) return false;
+    if (filters.status === "errors" && run.error === null) return false;
+    return true;
+  });
+  return filterByDimensionQuery(basic, filters.advanced);
+}

package/src/console/ui-next/src/features/flows/traces/format-duration.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Unit tests for {@link formatDuration} — three unit ranges + boundaries.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { formatDuration } from "./format-duration.ts";
+
+describe("formatDuration", () => {
+  test("microseconds for sub-millisecond runs", () => {
+    expect(formatDuration(0)).toBe("0μs");
+    expect(formatDuration(0.001)).toBe("1μs");
+    expect(formatDuration(0.974)).toBe("974μs");
+    expect(formatDuration(0.999)).toBe("999μs");
+  });
+
+  test("milliseconds for the normal range", () => {
+    expect(formatDuration(1)).toBe("1ms");
+    expect(formatDuration(12)).toBe("12ms");
+    expect(formatDuration(56.2)).toBe("56.2ms");
+    expect(formatDuration(56.24)).toBe("56.2ms");
+    expect(formatDuration(999)).toBe("999ms");
+    expect(formatDuration(999.94)).toBe("999.9ms");
+  });
+
+  test("seconds for slow runs", () => {
+    expect(formatDuration(1_000)).toBe("1s");
+    expect(formatDuration(1_700)).toBe("1.7s");
+    expect(formatDuration(12_340)).toBe("12.3s");
+    expect(formatDuration(60_000)).toBe("60s");
+  });
+
+  test("boundary values at unit transitions", () => {
+    expect(formatDuration(0.5)).toBe("500μs");
+    expect(formatDuration(1 - Number.EPSILON)).toBe("1000μs");
+    expect(formatDuration(1)).toBe("1ms");
+    expect(formatDuration(999.95)).toBe("1000ms");
+    expect(formatDuration(1_000)).toBe("1s");
+    expect(formatDuration(1_049)).toBe("1s");
+    expect(formatDuration(1_050)).toBe("1.1s");
+  });
+
+  test("non-finite and negative collapse to 0μs", () => {
+    expect(formatDuration(Number.NaN)).toBe("0μs");
+    expect(formatDuration(Number.POSITIVE_INFINITY)).toBe("0μs");
+    expect(formatDuration(-12)).toBe("0μs");
+  });
+});

package/src/console/ui-next/src/features/flows/traces/format-duration.ts

@@ -0,0 +1,25 @@
+/**
+ * Contextual duration formatting for Traces rows.
+ *
+ * Sub-millisecond → microseconds, mid-range → milliseconds,
+ * slow runs → seconds — matching the reference Traces density pattern.
+ */
+
+/**
+ * Format a duration in milliseconds into a compact display string.
+ *
+ * @param ms - Duration in milliseconds (may be fractional for sub-ms runs)
+ */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "0μs";
+  if (ms < 1) {
+    return `${Math.round(ms * 1_000)}μs`;
+  }
+  if (ms < 1_000) {
+    const rounded = Math.round(ms * 10) / 10;
+    return Number.isInteger(rounded) ? `${rounded}ms` : `${rounded.toFixed(1)}ms`;
+  }
+  const seconds = ms / 1_000;
+  const rounded = Math.round(seconds * 10) / 10;
+  return Number.isInteger(rounded) ? `${rounded}s` : `${rounded.toFixed(1)}s`;
+}

package/src/console/ui-next/src/features/flows/traces/graph-filter.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Unit tests for graph-driven Traces filtering.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Manifest } from "../../../../../../manifest/types.ts";
+import type { RunRow } from "@/client.ts";
+import { EMPTY_DIMENSION_QUERY } from "./dimension-query.ts";
+import {
+  applyGraphFilterToQuery,
+  filterRunsByGraph,
+  graphFilterForNodeId,
+  graphFilterLabel,
+  matchesGraphFilter,
+} from "./graph-filter.ts";
+
+function sampleRun(partial: Partial<RunRow> = {}): RunRow {
+  return {
+    id: "run-1",
+    parentId: null,
+    flow: "bookings.create",
+    unit: "bookings",
+    trigger: "http",
+    plane: "user",
+    tenant: null,
+    principal: null,
+    gates: [],
+    cache: "none",
+    replica: null,
+    replicaLagMs: null,
+    cost: null,
+    inputTokens: null,
+    outputTokens: null,
+    promptVersion: null,
+    buildVersion: null,
+    startedAt: 1,
+    endedAt: 13,
+    durationMs: 12,
+    error: null,
+    errorMessage: null,
+    sampled: "sample",
+    effects: [],
+    logs: [],
+    dimensions: {},
+    input: null,
+    output: null,
+    ...partial,
+  };
+}
+
+const MANIFEST: Manifest = {
+  app: "skyport",
+  flows: {
+    "bookings.create": {
+      trigger: { http: { method: "POST", path: "/bookings" } },
+      effects: { emits: ["order-placed"] },
+    },
+    "fulfillment.onOrder": {
+      trigger: { signal: "order-placed" },
+      effects: { writes: ["sql:shipments"] },
+    },
+  },
+} as unknown as Manifest;
+
+describe("graphFilterForNodeId", () => {
+  test("maps flow, signal, unit, element, and resource node ids", () => {
+    expect(graphFilterForNodeId("flow:bookings.create")).toEqual({
+      kind: "flow",
+      flowId: "bookings.create",
+    });
+    expect(graphFilterForNodeId("signal:order-placed")).toEqual({
+      kind: "signal",
+      signal: "order-placed",
+    });
+    expect(graphFilterForNodeId("unit:bookings")).toEqual({ kind: "unit", unit: "bookings" });
+    expect(graphFilterForNodeId("element:store")).toEqual({ kind: "element", element: "store" });
+    expect(graphFilterForNodeId("type:store:sql")).toEqual({ kind: "element", element: "store" });
+    expect(graphFilterForNodeId("type:store:kv")).toEqual({ kind: "element", element: "store" });
+    expect(graphFilterForNodeId("kv:cache")).toEqual({
+      kind: "resource",
+      nodeId: "kv:cache",
+    });
+    expect(graphFilterForNodeId("type:flow:http")).toEqual({ kind: "element", element: "flow" });
+    expect(graphFilterForNodeId("sql:bookings")).toEqual({
+      kind: "resource",
+      nodeId: "sql:bookings",
+    });
+    expect(graphFilterForNodeId("ai:ticket-triage")).toEqual({
+      kind: "resource",
+      nodeId: "ai:ticket-triage",
+    });
+  });
+
+  test("returns null for unknown node kinds", () => {
+    expect(graphFilterForNodeId("store:sql:bookings")).toBeNull();
+    expect(graphFilterForNodeId("element:nope")).toBeNull();
+  });
+});
+
+describe("applyGraphFilterToQuery", () => {
+  test("upserts a flow clause", () => {
+    const q = applyGraphFilterToQuery(EMPTY_DIMENSION_QUERY, {
+      kind: "flow",
+      flowId: "bookings.create",
+    });
+    expect(q.clauses).toEqual([{ dimension: "flow", op: "=", value: "bookings.create" }]);
+  });
+
+  test("upserts a unit clause", () => {
+    const q = applyGraphFilterToQuery(EMPTY_DIMENSION_QUERY, {
+      kind: "unit",
+      unit: "bookings",
+    });
+    expect(q.clauses).toEqual([{ dimension: "unit", op: "=", value: "bookings" }]);
+  });
+
+  test("leaves the query untouched for signal filters", () => {
+    const q = applyGraphFilterToQuery(EMPTY_DIMENSION_QUERY, {
+      kind: "signal",
+      signal: "order-placed",
+    });
+    expect(q.clauses).toEqual([]);
+  });
+});
+
+describe("graphFilterLabel", () => {
+  test("names the chip from the filter kind", () => {
+    expect(graphFilterLabel({ kind: "flow", flowId: "bookings.create" })).toBe("bookings.create");
+    expect(graphFilterLabel({ kind: "element", element: "store" })).toBe("Store");
+    expect(graphFilterLabel({ kind: "unit", unit: "bookings" })).toBe("bookings");
+  });
+});
+
+describe("matchesGraphFilter", () => {
+  test("flow filter matches the run's own flow", () => {
+    const run = sampleRun({ flow: "bookings.create" });
+    expect(matchesGraphFilter(run, { kind: "flow", flowId: "bookings.create" }, MANIFEST)).toBe(
+      true,
+    );
+    expect(matchesGraphFilter(run, { kind: "flow", flowId: "other.flow" }, MANIFEST)).toBe(false);
+  });
+
+  test("unit filter matches the run unit", () => {
+    const run = sampleRun({ unit: "bookings" });
+    expect(matchesGraphFilter(run, { kind: "unit", unit: "bookings" }, MANIFEST)).toBe(true);
+    expect(matchesGraphFilter(run, { kind: "unit", unit: "payments" }, MANIFEST)).toBe(false);
+  });
+
+  test("element filter matches ledger-touched elements", () => {
+    const run = sampleRun({
+      effects: [
+        {
+          kind: "write",
+          resource: "sql:bookings",
+          timestamp: 1,
+          duration: 2,
+          reversibility: "reversible",
+        },
+      ],
+    });
+    expect(matchesGraphFilter(run, { kind: "element", element: "store" }, MANIFEST)).toBe(true);
+    expect(matchesGraphFilter(run, { kind: "element", element: "vault" }, MANIFEST)).toBe(false);
+    expect(matchesGraphFilter(run, { kind: "element", element: "flow" }, MANIFEST)).toBe(true);
+  });
+
+  test("signal filter matches emitter and consumer flows", () => {
+    const emitter = sampleRun({ flow: "bookings.create" });
+    const consumer = sampleRun({ flow: "fulfillment.onOrder" });
+    const unrelated = sampleRun({ flow: "ops.nightlyReconcile" });
+    const filter = { kind: "signal" as const, signal: "order-placed" };
+    expect(matchesGraphFilter(emitter, filter, MANIFEST)).toBe(true);
+    expect(matchesGraphFilter(consumer, filter, MANIFEST)).toBe(true);
+    expect(matchesGraphFilter(unrelated, filter, MANIFEST)).toBe(false);
+  });
+});
+
+describe("filterRunsByGraph", () => {
+  test("null filter returns the population", () => {
+    const runs = [sampleRun({ id: "a" }), sampleRun({ id: "b" })];
+    expect(filterRunsByGraph(runs, null, MANIFEST)).toHaveLength(2);
+  });
+
+  test("signal filter keeps only linked runs", () => {
+    const runs = [
+      sampleRun({ id: "a", flow: "bookings.create" }),
+      sampleRun({ id: "b", flow: "fulfillment.onOrder" }),
+      sampleRun({ id: "c", flow: "ops.nightlyReconcile" }),
+    ];
+    const out = filterRunsByGraph(runs, { kind: "signal", signal: "order-placed" }, MANIFEST);
+    expect(out.map((r) => r.id)).toEqual(["a", "b"]);
+  });
+});