okengine 0.1.4

package/src/console/ui/runs/RunsA11yView.tsx

@@ -0,0 +1,267 @@
+/**
+ * Static Runs markup for the axe gate — same landmarks / roles as the
+ * live panel, fed by fixtures (no router / network).
+ */
+
+import { explainDurationOutliers } from "./explain.ts";
+import { RUNS_CHAIN_FIXTURE, runsOutlierFixture } from "./fixture.ts";
+import { groupByDimension } from "./group.ts";
+import {
+  durationHistogram,
+  formatDurationMs,
+} from "./histogram.ts";
+import { filterRuns, parseDimensionQuery } from "./query.ts";
+import {
+  shouldOfferTracesLink,
+  tracesHrefForRun,
+} from "./trace-link.ts";
+
+/** Props for {@link RunsA11yView}. */
+export interface RunsA11yViewProps {
+  /** Optional run id to open in detail. */
+  readonly openRunId?: string;
+  /** Include the outlier population fixture (heavier). */
+  readonly withOutliers?: boolean;
+}
+
+/**
+ * Accessible Runs analysis view for CI.
+ *
+ * @param props - Optional open run + outlier fixture flag
+ */
+export function RunsA11yView(props: RunsA11yViewProps) {
+  const population = props.withOutliers
+    ? [...RUNS_CHAIN_FIXTURE, ...runsOutlierFixture().slice(0, 80)]
+    : RUNS_CHAIN_FIXTURE;
+  const query = parseDimensionQuery("");
+  const filtered = filterRuns(population, query);
+  const buckets = durationHistogram(filtered, 10);
+  const maxBucket = Math.max(1, ...buckets.map((b) => b.count));
+  const range = { minMs: 1000, maxMs: 10_000 };
+  const findings = explainDurationOutliers(filtered, range);
+  const groups = groupByDimension(filtered, "cache");
+  const openId = props.openRunId ?? "run-create-ok";
+  const open = population.find((r) => r.id === openId);
+
+  return (
+    <div className="runs-a11y">
+      <a href="#runs-main">Skip to main content</a>
+      <header>
+        <h1>Runs</h1>
+        <p>Population analysis</p>
+        <label>
+          Query dimension
+          <select aria-label="Query dimension" defaultValue="cache">
+            <option value="cache">cache</option>
+            <option value="flow">flow</option>
+            <option value="tenant">tenant</option>
+          </select>
+        </label>
+        <label>
+          Query operator
+          <select aria-label="Query operator" defaultValue="=">
+            <option value="=">=</option>
+            <option value="!=">!=</option>
+          </select>
+        </label>
+        <label>
+          Query value
+          <input aria-label="Query value" defaultValue="miss" />
+        </label>
+        <button type="button" style={{ minHeight: 32, minWidth: 24 }}>
+          Add
+        </button>
+        <label>
+          Dimension query expression
+          <input
+            aria-label="Dimension query expression"
+            defaultValue="cache = miss"
+            placeholder="flow = X AND cache = miss AND duration > 1s"
+          />
+        </label>
+        <label>
+          Group by
+          <select aria-label="Group by dimension" defaultValue="cache">
+            <option value="">None</option>
+            <option value="cache">cache</option>
+            <option value="tenant">tenant</option>
+          </select>
+        </label>
+      </header>
+
+      <main id="runs-main">
+        <section aria-label="Duration distribution">
+          <h2>Duration distribution</h2>
+          <div
+            role="group"
+            aria-label="Duration histogram"
+            style={{
+              display: "flex",
+              alignItems: "flex-end",
+              gap: 1,
+              height: 120,
+            }}
+          >
+            {buckets.map((b, i) => {
+              const selected =
+                b.minMs <= range.maxMs && b.maxMs >= range.minMs;
+              return (
+                <button
+                  key={i}
+                  type="button"
+                  aria-pressed={selected}
+                  aria-label={`Duration ${formatDurationMs(b.minMs)} to ${formatDurationMs(b.maxMs)}, ${b.count} runs`}
+                  style={{
+                    minHeight: 32,
+                    minWidth: 24,
+                    flex: 1,
+                    height: `${Math.max(8, (b.count / maxBucket) * 100)}%`,
+                    background: selected ? "#3d9a6a" : "#666",
+                  }}
+                />
+              );
+            })}
+          </div>
+          <button type="button" style={{ minHeight: 32, minWidth: 24 }}>
+            Clear selection
+          </button>
+        </section>
+
+        <section aria-label="Outlier explanation">
+          <h2>Outlier explanation</h2>
+          <ol>
+            {findings.slice(0, 5).map((f) => (
+              <li key={`${f.dimension}:${f.value}`}>{f.explanation}</li>
+            ))}
+          </ol>
+        </section>
+
+        <section aria-label="Group aggregates">
+          <h2>Group by cache</h2>
+          <table>
+            <thead>
+              <tr>
+                <th scope="col">cache</th>
+                <th scope="col">Count</th>
+                <th scope="col">Avg</th>
+                <th scope="col">p50</th>
+                <th scope="col">p99</th>
+                <th scope="col">Cost</th>
+              </tr>
+            </thead>
+            <tbody>
+              {groups.map((g) => (
+                <tr key={g.key}>
+                  <td>{g.key}</td>
+                  <td>{g.count}</td>
+                  <td>{formatDurationMs(g.avgDurationMs)}</td>
+                  <td>{formatDurationMs(g.p50DurationMs)}</td>
+                  <td>{formatDurationMs(g.p99DurationMs)}</td>
+                  <td>{g.sumCost}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </section>
+
+        <section aria-label="Run list">
+          <h2>Runs</h2>
+          <ul>
+            {RUNS_CHAIN_FIXTURE.map((run) => (
+              <li key={run.id}>
+                <button
+                  type="button"
+                  aria-pressed={run.id === openId}
+                  style={{ minHeight: 32, width: "100%" }}
+                >
+                  {run.flow}{" "}
+                  {run.error ? (
+                    <span role="status">{run.error}</span>
+                  ) : (
+                    formatDurationMs(run.durationMs)
+                  )}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </section>
+
+        {open ? (
+          <section aria-label="Run detail" aria-live="polite">
+            <h2>{open.flow}</h2>
+            <dl>
+              <div>
+                <dt>flow</dt>
+                <dd>{open.flow}</dd>
+              </div>
+              <div>
+                <dt>unit</dt>
+                <dd>{open.unit ?? "—"}</dd>
+              </div>
+              <div>
+                <dt>trigger</dt>
+                <dd>{open.trigger}</dd>
+              </div>
+              <div>
+                <dt>plane</dt>
+                <dd>{open.plane}</dd>
+              </div>
+              <div>
+                <dt>tenant</dt>
+                <dd>{open.tenant ?? "—"}</dd>
+              </div>
+              <div>
+                <dt>principal</dt>
+                <dd>{open.principal ?? "—"}</dd>
+              </div>
+              <div>
+                <dt>gates</dt>
+                <dd>{open.gates.join(", ") || "—"}</dd>
+              </div>
+              <div>
+                <dt>cache</dt>
+                <dd>{open.cache}</dd>
+              </div>
+              <div>
+                <dt>error</dt>
+                <dd>
+                  {open.error ? (
+                    <span role="status">{open.error}</span>
+                  ) : (
+                    "—"
+                  )}
+                </dd>
+              </div>
+            </dl>
+            <h3>Effects</h3>
+            <ul>
+              {open.effects.map((e, i) => (
+                <li key={i}>
+                  {e.kind} {e.resource}
+                </li>
+              ))}
+            </ul>
+            <details open>
+              <summary>fx.log ({open.logs.length})</summary>
+              <ul>
+                {open.logs.map((line, i) => (
+                  <li key={i}>
+                    [{line.level}] {line.message}
+                  </li>
+                ))}
+              </ul>
+            </details>
+            {shouldOfferTracesLink(population, open.id) ? (
+              <a href={tracesHrefForRun(population, open.id)}>
+                Open in Traces
+              </a>
+            ) : null}
+            <button type="button" style={{ minHeight: 32, minWidth: 24 }}>
+              Close
+            </button>
+          </section>
+        ) : null}
+      </main>
+    </div>
+  );
+}

package/src/console/ui/runs/a11y.test.tsx

@@ -0,0 +1,99 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · prompt 19).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import axe from "axe-core";
+import { Window } from "happy-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react";
+import { RunsA11yView } from "./RunsA11yView.tsx";
+
+describe("Runs panel accessibility", () => {
+  let window: Window;
+  let root: Root;
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+      true;
+    window = new Window({ url: "http://console.test/runs" });
+    Object.defineProperty(globalThis, "window", {
+      value: window,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "document", {
+      value: window.document,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "HTMLElement", {
+      value: window.HTMLElement,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "Node", {
+      value: window.Node,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "navigator", {
+      value: window.navigator,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "getComputedStyle", {
+      value: window.getComputedStyle.bind(window),
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "requestAnimationFrame", {
+      value: (cb: FrameRequestCallback) => window.setTimeout(cb, 0),
+      configurable: true,
+      writable: true,
+    });
+
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+    window.close();
+  });
+
+  test("axe reports zero violations at WCAG 2.2 AA", async () => {
+    await act(async () => {
+      root.render(
+        <RunsA11yView openRunId="run-create-ok" withOutliers />,
+      );
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    const results = await axe.run(container, {
+      runOnly: {
+        type: "tag",
+        values: ["wcag2a", "wcag2aa", "wcag22aa"],
+      },
+    });
+
+    if (results.violations.length > 0) {
+      const summary = results.violations
+        .map(
+          (v) =>
+            `${v.id}: ${v.help} (${v.nodes.length} nodes) — ${v.nodes.map((n) => n.html).join("; ")}`,
+        )
+        .join("\n");
+      console.error(summary);
+    }
+
+    expect(results.violations).toEqual([]);
+  });
+});

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

@@ -0,0 +1,23 @@
+/**
+ * Outlier explanation via Prompt 14's explainOutliers (console §9.11).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { explainDurationOutliers } from "./explain.ts";
+import { runsOutlierFixture } from "./fixture.ts";
+
+describe("explainDurationOutliers", () => {
+  test("surfaces cache=miss as the top separator for the slow region", () => {
+    const runs = runsOutlierFixture();
+    const findings = explainDurationOutliers(runs, {
+      minMs: 1000,
+      maxMs: 10_000,
+    });
+    expect(findings.length).toBeGreaterThan(0);
+    const top = findings[0]!;
+    expect(top.dimension).toBe("cache");
+    expect(top.value).toBe("miss");
+    expect(top.explanation).toMatch(/cache=miss/);
+    expect(top.lift).toBeGreaterThan(0.5);
+  });
+});

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

@@ -0,0 +1,32 @@
+/**
+ * Outlier explanation bridge — calls Prompt 14's {@link explainOutliers}
+ * (console §9.11 · §14), never a reimplementation.
+ */
+
+import {
+  explainOutliers,
+  type OutlierFinding,
+} from "../../../runs/outlier.ts";
+import { runToWideEvent } from "./project.ts";
+import type { DurationRange, RunRecord } from "./types.ts";
+
+export type { OutlierFinding };
+
+/**
+ * Explain what separates the duration-selected population from the rest.
+ *
+ * @param runs - Filtered population (current dimension query)
+ * @param range - Selected region of the distribution
+ */
+export function explainDurationOutliers(
+  runs: readonly RunRecord[],
+  range: DurationRange,
+): OutlierFinding[] {
+  const events = runs.map(runToWideEvent);
+  return explainOutliers(events, {
+    select: (e) =>
+      e.durationMs >= range.minMs && e.durationMs <= range.maxMs,
+    minLift: 0.15,
+    ignore: ["duration_ms", "duration", "flow"],
+  });
+}

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

@@ -0,0 +1,189 @@
+/**
+ * Runs fixtures for unit tests and the axe gate (console §9.11).
+ *
+ * Population volume for outlier explanation reuses Prompt 14's
+ * {@link seedOutlierDataset}; a small multi-span chain covers Traces cross-links.
+ */
+
+import { seedOutlierDataset } from "../../../runs/outlier.ts";
+import { rowToRun } from "./project.ts";
+import type { RunRecord } from "./types.ts";
+
+const T0 = 1_700_000_000_000;
+
+/**
+ * Compact multi-span chain + a few named runs for UI / a11y tests.
+ */
+export const RUNS_CHAIN_FIXTURE: readonly RunRecord[] = [
+  rowToRun({
+    id: "run-create-ok",
+    flow: "bookings.create",
+    unit: "bookings",
+    trigger: "http",
+    plane: "user",
+    tenant: "org_a41",
+    principal: "user_1",
+    gates: ["member"],
+    cache: "hit",
+    startedAt: T0,
+    endedAt: T0 + 45,
+    durationMs: 45,
+    effects: [
+      {
+        kind: "read",
+        resource: "sql:bookings",
+        timestamp: T0 + 2,
+        duration: 8,
+        reversibility: "none",
+      },
+      {
+        kind: "write",
+        resource: "sql:bookings",
+        timestamp: T0 + 12,
+        duration: 15,
+        reversibility: "reversible",
+      },
+    ],
+    logs: [
+      {
+        level: "info",
+        message: "booking started",
+        at: T0 + 1,
+      },
+    ],
+    dimensions: {
+      flow: "bookings.create",
+      unit: "bookings",
+      cache: "hit",
+      tenant: "org_a41",
+      duration_ms: 45,
+    },
+  }),
+  rowToRun({
+    id: "run-fulfill",
+    parentId: "run-create-ok",
+    flow: "fulfillment.onOrder",
+    unit: "fulfillment",
+    trigger: "signal",
+    plane: "user",
+    tenant: "org_a41",
+    principal: "user_1",
+    gates: [],
+    cache: "none",
+    startedAt: T0 + 7 * 24 * 60 * 60 * 1000,
+    endedAt: T0 + 7 * 24 * 60 * 60 * 1000 + 120,
+    durationMs: 120,
+    effects: [
+      {
+        kind: "send",
+        resource: "booking-confirmed",
+        timestamp: T0 + 7 * 24 * 60 * 60 * 1000 + 40,
+        duration: 60,
+        reversibility: "irreversible",
+      },
+    ],
+    logs: [],
+    dimensions: {
+      flow: "fulfillment.onOrder",
+      unit: "fulfillment",
+      cache: "none",
+      tenant: "org_a41",
+      duration_ms: 120,
+    },
+  }),
+  rowToRun({
+    id: "run-create-fail",
+    flow: "bookings.create",
+    unit: "bookings",
+    trigger: "http",
+    plane: "user",
+    tenant: "org_b12",
+    principal: "user_2",
+    gates: ["member"],
+    cache: "miss",
+    replica: "replica",
+    replicaLagMs: 240,
+    startedAt: T0 + 1_000,
+    endedAt: T0 + 1_028,
+    durationMs: 28,
+    error: "FlightFull",
+    effects: [
+      {
+        kind: "read",
+        resource: "sql:bookings",
+        timestamp: T0 + 1_002,
+        duration: 18,
+        reversibility: "none",
+      },
+    ],
+    logs: [
+      {
+        level: "warn",
+        message: "flight full",
+        data: { code: "FlightFull" },
+        at: T0 + 1_020,
+      },
+    ],
+    dimensions: {
+      flow: "bookings.create",
+      unit: "bookings",
+      cache: "miss",
+      tenant: "org_b12",
+      error_code: "FlightFull",
+      replica: "replica",
+      replica_lag_ms: 240,
+      duration_ms: 28,
+    },
+  }),
+];
+
+/**
+ * Large seeded population where cache=miss cleanly separates slow runs.
+ * Used for outlier-explanation unit tests.
+ */
+export function runsOutlierFixture(): RunRecord[] {
+  return seedOutlierDataset({
+    n: 400,
+    slowShare: 0.12,
+    separatingDimension: "cache",
+    separatingValue: "miss",
+    slowDurationMs: 2000,
+    fastDurationMs: 40,
+  }).map((e) =>
+    rowToRun({
+      id: e.id,
+      parentId: e.parentId ?? null,
+      flow: e.flow,
+      unit: e.unit ?? null,
+      trigger: e.trigger,
+      plane: e.plane,
+      tenant: e.tenant ?? null,
+      principal: e.principal ?? null,
+      gates: e.gates,
+      cache: e.cache,
+      replica: e.replica ?? null,
+      replicaLagMs: e.replicaLagMs ?? null,
+      cost: e.cost ?? null,
+      promptVersion: e.promptVersion ?? null,
+      buildVersion: e.buildVersion ?? null,
+      startedAt: e.startedAt,
+      endedAt: e.endedAt,
+      durationMs: e.durationMs,
+      error: e.error?.code ?? null,
+      effects: e.effects.map((x) => ({
+        kind: x.kind,
+        resource: x.resource,
+        timestamp: x.timestamp,
+        duration: x.duration,
+        reversibility: x.reversibility,
+      })),
+      logs: e.logs,
+      dimensions: Object.fromEntries(
+        Object.entries(e.dimensions).filter(([, v]) => v !== undefined),
+      ) as Record<string, string | number | boolean | null>,
+    }),
+  );
+}
+
+/** Epoch origin used by {@link RUNS_CHAIN_FIXTURE}. */
+export const RUNS_FIXTURE_T0 = T0;

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

@@ -0,0 +1,24 @@
+/**
+ * Group-by aggregate tests (console §9.11).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { RUNS_CHAIN_FIXTURE } from "./fixture.ts";
+import { groupByDimension } from "./group.ts";
+
+describe("groupByDimension", () => {
+  test("groups by cache with count and duration aggregates", () => {
+    const rows = groupByDimension(RUNS_CHAIN_FIXTURE, "cache");
+    const byKey = Object.fromEntries(rows.map((r) => [r.key, r]));
+    expect(byKey.hit?.count).toBe(1);
+    expect(byKey.miss?.count).toBe(1);
+    expect(byKey.none?.count).toBe(1);
+    expect(byKey.hit?.avgDurationMs).toBe(45);
+  });
+
+  test("groups by flow", () => {
+    const rows = groupByDimension(RUNS_CHAIN_FIXTURE, "flow");
+    const create = rows.find((r) => r.key === "bookings.create");
+    expect(create?.count).toBe(2);
+  });
+});