okengine 0.1.4

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

@@ -0,0 +1,97 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · prompt 18.1).
+ */
+
+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 { TracesA11yView } from "./TracesA11yView.tsx";
+
+describe("Traces 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/traces" });
+    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(<TracesA11yView openRootId="run-create-ok" />);
+    });
+
+    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/traces/chain.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Causal chain tests (console §9.3).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  buildCausalChain,
+  groupTraceRoots,
+  initialFocusSpanId,
+} from "./chain.ts";
+import { TRACES_FIXTURE } from "./fixture.ts";
+
+describe("buildCausalChain", () => {
+  test("joins emit consumer under parent across async boundary", () => {
+    const chain = buildCausalChain(TRACES_FIXTURE, "run-fulfill");
+    expect(chain).not.toBeNull();
+    expect(chain?.parents.map((p) => p.id)).toEqual(["run-create-ok"]);
+    expect(chain?.current.id).toBe("run-fulfill");
+    expect(chain?.children).toEqual([]);
+    expect(chain?.connected.map((s) => s.id)).toEqual([
+      "run-create-ok",
+      "run-fulfill",
+    ]);
+  });
+
+  test("parents above, children below from root", () => {
+    const chain = buildCausalChain(TRACES_FIXTURE, "run-create-ok");
+    expect(chain?.parents).toEqual([]);
+    expect(chain?.children.map((c) => c.id)).toEqual(["run-fulfill"]);
+  });
+});
+
+describe("groupTraceRoots", () => {
+  test("groups by root and lists newest first", () => {
+    const roots = groupTraceRoots(TRACES_FIXTURE);
+    expect(roots.map((r) => r.rootId)).toContain("run-create-ok");
+    expect(roots.map((r) => r.rootId)).toContain("run-create-fail");
+    expect(roots.map((r) => r.rootId)).toContain("run-ask");
+    const ok = roots.find((r) => r.rootId === "run-create-ok");
+    expect(ok?.spans.map((s) => s.id)).toEqual([
+      "run-create-ok",
+      "run-fulfill",
+    ]);
+  });
+});
+
+describe("initialFocusSpanId", () => {
+  test("opens on the failing span", () => {
+    const failRoot = groupTraceRoots(TRACES_FIXTURE).find(
+      (r) => r.rootId === "run-create-fail",
+    );
+    expect(initialFocusSpanId(failRoot!.spans)).toBe("run-create-fail");
+  });
+
+  test("honours preferred id when present", () => {
+    const ok = groupTraceRoots(TRACES_FIXTURE).find(
+      (r) => r.rootId === "run-create-ok",
+    );
+    expect(initialFocusSpanId(ok!.spans, "run-fulfill")).toBe("run-fulfill");
+  });
+});

package/src/console/ui/traces/chain.ts

@@ -0,0 +1,144 @@
+/**
+ * Causal chain across asynchronous boundaries (console §9.3).
+ *
+ * When `create` emits `order-placed` and another flow consumes it, declared
+ * parentId joins them: parent above, current, children below.
+ */
+
+import type { TraceSpan } from "./types.ts";
+
+/** Causal chain focused on one span. */
+export interface CausalChain {
+  /** Ancestors from root to immediate parent. */
+  readonly parents: readonly TraceSpan[];
+  /** Focused span. */
+  readonly current: TraceSpan;
+  /** Direct children. */
+  readonly children: readonly TraceSpan[];
+  /** Every span in the connected component (for waterfall / replay). */
+  readonly connected: readonly TraceSpan[];
+}
+
+/** Root-grouped forest entry for the list. */
+export interface TraceRoot {
+  /** Root span id. */
+  readonly rootId: string;
+  /** Root span. */
+  readonly root: TraceSpan;
+  /** All spans in this trace (root + descendants), start-time order. */
+  readonly spans: readonly TraceSpan[];
+}
+
+/**
+ * Index spans by id and parent.
+ *
+ * @param spans - All known spans
+ */
+export function indexSpans(spans: readonly TraceSpan[]): {
+  readonly byId: ReadonlyMap<string, TraceSpan>;
+  readonly childrenOf: ReadonlyMap<string, readonly TraceSpan[]>;
+} {
+  const byId = new Map<string, TraceSpan>();
+  const childrenOf = new Map<string, TraceSpan[]>();
+  for (const s of spans) {
+    byId.set(s.id, s);
+  }
+  for (const s of spans) {
+    if (!s.parentId) continue;
+    const list = childrenOf.get(s.parentId) ?? [];
+    list.push(s);
+    childrenOf.set(s.parentId, list);
+  }
+  for (const [, list] of childrenOf) {
+    list.sort((a, b) => a.startedAt - b.startedAt);
+  }
+  return { byId, childrenOf };
+}
+
+/**
+ * Build the causal chain for a focused span.
+ *
+ * @param spans - All known spans
+ * @param currentId - Focused span id
+ */
+export function buildCausalChain(
+  spans: readonly TraceSpan[],
+  currentId: string,
+): CausalChain | null {
+  const { byId, childrenOf } = indexSpans(spans);
+  const current = byId.get(currentId);
+  if (!current) return null;
+
+  const parents: TraceSpan[] = [];
+  let cursor: TraceSpan | undefined = current;
+  const seen = new Set<string>();
+  while (cursor?.parentId) {
+    if (seen.has(cursor.parentId)) break;
+    seen.add(cursor.parentId);
+    const parent = byId.get(cursor.parentId);
+    if (!parent) break;
+    parents.unshift(parent);
+    cursor = parent;
+  }
+
+  const children = childrenOf.get(current.id) ?? [];
+  const root = parents[0] ?? current;
+  const connected = collectDescendants(root.id, byId, childrenOf);
+  return { parents, current, children, connected };
+}
+
+/**
+ * Group spans into root traces for the list.
+ *
+ * @param spans - All known spans
+ */
+export function groupTraceRoots(spans: readonly TraceSpan[]): TraceRoot[] {
+  const { byId, childrenOf } = indexSpans(spans);
+  const roots = spans.filter(
+    (s) => !s.parentId || !byId.has(s.parentId),
+  );
+  roots.sort((a, b) => b.startedAt - a.startedAt);
+  return roots.map((root) => ({
+    rootId: root.id,
+    root,
+    spans: collectDescendants(root.id, byId, childrenOf),
+  }));
+}
+
+/**
+ * Initial focus when opening a trace: the failing span if any, else the root.
+ *
+ * @param spans - Spans in the connected component
+ * @param preferredId - Optional URL-selected span
+ */
+export function initialFocusSpanId(
+  spans: readonly TraceSpan[],
+  preferredId?: string,
+): string | undefined {
+  if (preferredId && spans.some((s) => s.id === preferredId)) {
+    return preferredId;
+  }
+  const failed = spans.find((s) => s.errorCode != null && s.errorCode !== "");
+  if (failed) return failed.id;
+  const root = spans.find((s) => !s.parentId || !spans.some((p) => p.id === s.parentId));
+  return root?.id ?? spans[0]?.id;
+}
+
+function collectDescendants(
+  rootId: string,
+  byId: ReadonlyMap<string, TraceSpan>,
+  childrenOf: ReadonlyMap<string, readonly TraceSpan[]>,
+): TraceSpan[] {
+  const out: TraceSpan[] = [];
+  const walk = (id: string): void => {
+    const span = byId.get(id);
+    if (!span) return;
+    out.push(span);
+    for (const child of childrenOf.get(id) ?? []) {
+      walk(child.id);
+    }
+  };
+  walk(rootId);
+  out.sort((a, b) => a.startedAt - b.startedAt);
+  return out;
+}

package/src/console/ui/traces/critical-path.test.ts

@@ -0,0 +1,24 @@
+/**
+ * Critical-path tests (console §9.3).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { criticalPathSpanIds } from "./critical-path.ts";
+import { TRACES_FIXTURE } from "./fixture.ts";
+
+describe("criticalPathSpanIds", () => {
+  test("selects the longer root-to-leaf work path", () => {
+    const chain = TRACES_FIXTURE.filter(
+      (s) => s.id === "run-create-ok" || s.id === "run-fulfill",
+    );
+    const path = criticalPathSpanIds(chain);
+    expect(path.has("run-create-ok")).toBe(true);
+    expect(path.has("run-fulfill")).toBe(true);
+  });
+
+  test("single-span trace is its own critical path", () => {
+    const ask = TRACES_FIXTURE.filter((s) => s.id === "run-ask");
+    const path = criticalPathSpanIds(ask);
+    expect([...path]).toEqual(["run-ask"]);
+  });
+});

package/src/console/ui/traces/critical-path.ts

@@ -0,0 +1,59 @@
+/**
+ * Critical-path highlighting for the folded waterfall (console §9.3).
+ *
+ * On open: *why was it slow* — the critical path is highlighted and the rest
+ * dims. Path = root-to-leaf chain with maximum summed work duration.
+ */
+
+import { indexSpans } from "./chain.ts";
+import type { TraceSpan } from "./types.ts";
+
+/**
+ * Span ids on the critical path of a connected component.
+ *
+ * @param spans - Connected spans (one trace)
+ */
+export function criticalPathSpanIds(
+  spans: readonly TraceSpan[],
+): ReadonlySet<string> {
+  if (spans.length === 0) return new Set();
+  const { byId, childrenOf } = indexSpans(spans);
+  const roots = spans.filter(
+    (s) => !s.parentId || !byId.has(s.parentId),
+  );
+  let best: string[] = [];
+  let bestCost = -1;
+
+  const dfs = (id: string, path: string[], cost: number): void => {
+    const kids = childrenOf.get(id) ?? [];
+    const span = byId.get(id);
+    if (!span) return;
+    const nextCost = cost + workMs(span);
+    const nextPath = [...path, id];
+    if (kids.length === 0) {
+      if (nextCost > bestCost) {
+        bestCost = nextCost;
+        best = nextPath;
+      }
+      return;
+    }
+    for (const child of kids) {
+      dfs(child.id, nextPath, nextCost);
+    }
+  };
+
+  for (const root of roots) {
+    dfs(root.id, [], 0);
+  }
+  return new Set(best);
+}
+
+/**
+ * Active work milliseconds for a span (sum of effect durations, else wall).
+ *
+ * @param span - Span
+ */
+export function workMs(span: TraceSpan): number {
+  if (span.effects.length === 0) return Math.max(0, span.durationMs);
+  return span.effects.reduce((s, e) => s + Math.max(0, e.duration), 0);
+}

package/src/console/ui/traces/filter.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Effect-filter tests (console §9.3).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  matchesEffectFilter,
+  parseEffectFilter,
+  serializeEffectFilter,
+  traceMatchesEffectFilter,
+} from "./filter.ts";
+import { TRACES_FIXTURE } from "./fixture.ts";
+
+describe("effect filter", () => {
+  test("wrote:sql:bookings matches create spans", () => {
+    const filter = parseEffectFilter("wrote:sql:bookings");
+    expect(filter).toEqual({ kind: "wrote", resource: "sql:bookings" });
+    const create = TRACES_FIXTURE.find((s) => s.id === "run-create-ok")!;
+    expect(matchesEffectFilter(create, filter)).toBe(true);
+    const ask = TRACES_FIXTURE.find((s) => s.id === "run-ask")!;
+    expect(matchesEffectFilter(ask, filter)).toBe(false);
+  });
+
+  test("asked / sent / secret / cost queries", () => {
+    expect(
+      matchesEffectFilter(
+        TRACES_FIXTURE.find((s) => s.id === "run-ask")!,
+        { kind: "asked" },
+      ),
+    ).toBe(true);
+    expect(
+      matchesEffectFilter(
+        TRACES_FIXTURE.find((s) => s.id === "run-fulfill")!,
+        { kind: "sent", resource: "booking-confirmed" },
+      ),
+    ).toBe(true);
+    expect(
+      matchesEffectFilter(
+        TRACES_FIXTURE.find((s) => s.id === "run-ask")!,
+        { kind: "secret", resource: "OPENAI_KEY" },
+      ),
+    ).toBe(true);
+    expect(
+      matchesEffectFilter(
+        TRACES_FIXTURE.find((s) => s.id === "run-ask")!,
+        { kind: "cost", min: 0.05 },
+      ),
+    ).toBe(true);
+    expect(
+      matchesEffectFilter(
+        TRACES_FIXTURE.find((s) => s.id === "run-create-ok")!,
+        { kind: "cost", min: 0.05 },
+      ),
+    ).toBe(false);
+  });
+
+  test("round-trips through URL serialisation", () => {
+    const filters = [
+      parseEffectFilter("wrote:sql:bookings"),
+      parseEffectFilter("asked"),
+      parseEffectFilter("sent:booking-confirmed"),
+      parseEffectFilter("secret"),
+      parseEffectFilter("cost:0.05"),
+    ];
+    for (const f of filters) {
+      expect(parseEffectFilter(serializeEffectFilter(f))).toEqual(f);
+    }
+  });
+
+  test("trace-level match when any connected span matches", () => {
+    const chain = TRACES_FIXTURE.filter(
+      (s) => s.id === "run-create-ok" || s.id === "run-fulfill",
+    );
+    expect(
+      traceMatchesEffectFilter(chain, { kind: "sent" }),
+    ).toBe(true);
+  });
+});

package/src/console/ui/traces/filter.ts

@@ -0,0 +1,112 @@
+/**
+ * Filter traces by declared effect (console §9.3).
+ *
+ * Because effects are declared, this is a query rather than a text search.
+ */
+
+import type { EffectFilter, TraceSpan } from "./types.ts";
+
+/**
+ * Whether a span matches an effect filter.
+ *
+ * @param span - Span to test
+ * @param filter - Effect filter, or null for match-all
+ */
+export function matchesEffectFilter(
+  span: TraceSpan,
+  filter: EffectFilter | null | undefined,
+): boolean {
+  if (!filter) return true;
+  switch (filter.kind) {
+    case "wrote":
+      return span.effects.some(
+        (e) => e.kind === "write" && e.resource === filter.resource,
+      );
+    case "asked":
+      return span.effects.some((e) => e.kind === "ask");
+    case "sent":
+      return span.effects.some(
+        (e) =>
+          e.kind === "send" &&
+          (filter.resource === undefined || e.resource === filter.resource),
+      );
+    case "secret":
+      return span.effects.some(
+        (e) =>
+          e.kind === "secret" &&
+          (filter.resource === undefined || e.resource === filter.resource),
+      );
+    case "cost":
+      return (span.cost ?? 0) > filter.min;
+  }
+}
+
+/**
+ * Whether any span in a root's connected component matches.
+ *
+ * @param spans - Spans in the trace
+ * @param filter - Effect filter
+ */
+export function traceMatchesEffectFilter(
+  spans: readonly TraceSpan[],
+  filter: EffectFilter | null | undefined,
+): boolean {
+  if (!filter) return true;
+  return spans.some((s) => matchesEffectFilter(s, filter));
+}
+
+/**
+ * Parse a compact effect-filter string from the URL.
+ *
+ * Forms: `wrote:sql:bookings`, `asked`, `sent`, `sent:booking-confirmed`,
+ * `secret:STRIPE_KEY`, `cost:0.05`.
+ *
+ * @param raw - URL value
+ */
+export function parseEffectFilter(
+  raw: string | undefined,
+): EffectFilter | null {
+  if (!raw?.trim()) return null;
+  const value = raw.trim();
+  if (value === "asked") return { kind: "asked" };
+  if (value === "sent") return { kind: "sent" };
+  if (value.startsWith("wrote:")) {
+    return { kind: "wrote", resource: value.slice("wrote:".length) };
+  }
+  if (value.startsWith("sent:")) {
+    return { kind: "sent", resource: value.slice("sent:".length) };
+  }
+  if (value.startsWith("secret:")) {
+    return { kind: "secret", resource: value.slice("secret:".length) };
+  }
+  if (value === "secret") return { kind: "secret" };
+  if (value.startsWith("cost:")) {
+    const min = Number(value.slice("cost:".length));
+    if (!Number.isFinite(min)) return null;
+    return { kind: "cost", min };
+  }
+  return null;
+}
+
+/**
+ * Serialise an effect filter for the URL.
+ *
+ * @param filter - Filter
+ */
+export function serializeEffectFilter(
+  filter: EffectFilter | null | undefined,
+): string | undefined {
+  if (!filter) return undefined;
+  switch (filter.kind) {
+    case "wrote":
+      return `wrote:${filter.resource}`;
+    case "asked":
+      return "asked";
+    case "sent":
+      return filter.resource ? `sent:${filter.resource}` : "sent";
+    case "secret":
+      return filter.resource ? `secret:${filter.resource}` : "secret";
+    case "cost":
+      return `cost:${filter.min}`;
+  }
+}

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

@@ -0,0 +1,126 @@
+/**
+ * Trace fixtures for unit tests and the axe gate (console §9.3).
+ */
+
+import type { TraceSpan } from "./types.ts";
+
+const T0 = 1_700_000_000_000;
+
+/**
+ * Causal chain: bookings.create → (7d sleep) → fulfillment.onOrder (email) ·
+ * plus a failed sibling bookings.create with FlightFull.
+ */
+export const TRACES_FIXTURE: readonly TraceSpan[] = [
+  {
+    id: "run-create-ok",
+    flow: "bookings.create",
+    unit: "bookings",
+    trigger: "http",
+    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",
+      },
+      {
+        kind: "emit",
+        resource: "order-placed",
+        timestamp: T0 + 30,
+        duration: 4,
+        reversibility: "deferred",
+      },
+    ],
+    sampled: "sample",
+  },
+  {
+    id: "run-fulfill",
+    parentId: "run-create-ok",
+    flow: "fulfillment.onOrder",
+    unit: "fulfillment",
+    trigger: "signal",
+    // 7-day sleep between emit and consume (folded time).
+    startedAt: T0 + 7 * 24 * 60 * 60 * 1000,
+    endedAt: T0 + 7 * 24 * 60 * 60 * 1000 + 120,
+    durationMs: 120,
+    effects: [
+      {
+        kind: "write",
+        resource: "sql:shipments",
+        timestamp: T0 + 7 * 24 * 60 * 60 * 1000 + 10,
+        duration: 20,
+        reversibility: "reversible",
+      },
+      {
+        kind: "send",
+        resource: "booking-confirmed",
+        timestamp: T0 + 7 * 24 * 60 * 60 * 1000 + 40,
+        duration: 60,
+        reversibility: "irreversible",
+      },
+    ],
+    cost: 0,
+    sampled: "full",
+  },
+  {
+    id: "run-create-fail",
+    flow: "bookings.create",
+    unit: "bookings",
+    trigger: "http",
+    startedAt: T0 + 1_000,
+    endedAt: T0 + 1_028,
+    durationMs: 28,
+    errorCode: "FlightFull",
+    effects: [
+      {
+        kind: "read",
+        resource: "sql:bookings",
+        timestamp: T0 + 1_002,
+        duration: 18,
+        reversibility: "none",
+      },
+    ],
+    sampled: "error",
+  },
+  {
+    id: "run-ask",
+    flow: "support.triage",
+    unit: "support",
+    trigger: "http",
+    startedAt: T0 + 2_000,
+    endedAt: T0 + 2_400,
+    durationMs: 400,
+    effects: [
+      {
+        kind: "secret",
+        resource: "OPENAI_KEY",
+        timestamp: T0 + 2_010,
+        duration: 2,
+        reversibility: "capability",
+      },
+      {
+        kind: "ask",
+        resource: "triage@3",
+        timestamp: T0 + 2_020,
+        duration: 350,
+        reversibility: "irreversible",
+      },
+    ],
+    cost: 0.08,
+    sampled: "sample",
+  },
+];
+
+/** Epoch origin used by {@link TRACES_FIXTURE}. */
+export const TRACES_FIXTURE_T0 = T0;