okengine 0.1.4

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

@@ -0,0 +1,67 @@
+/**
+ * Folded-time waterfall tests (console §9.3).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { TRACES_FIXTURE } from "./fixture.ts";
+import {
+  COLLAPSED_FOLD_DISPLAY_MS,
+  foldTimeline,
+  formatFoldLabel,
+  intervalsFromSpans,
+} from "./fold.ts";
+
+describe("foldTimeline", () => {
+  test("collapses multi-day idle into one labelled fold", () => {
+    const chain = TRACES_FIXTURE.filter(
+      (s) => s.id === "run-create-ok" || s.id === "run-fulfill",
+    );
+    const folded = foldTimeline(intervalsFromSpans(chain));
+    const folds = folded.segments.filter((s) => s.kind === "fold");
+    expect(folds.length).toBe(1);
+    const fold = folds[0];
+    expect(fold?.kind).toBe("fold");
+    if (fold?.kind !== "fold") return;
+    expect(fold.durationMs).toBeGreaterThan(6 * 24 * 60 * 60 * 1000);
+    expect(fold.label).toContain("d idle");
+    expect(fold.displayMs).toBe(COLLAPSED_FOLD_DISPLAY_MS);
+    expect(fold.expanded).toBe(false);
+  });
+
+  test("expanded fold restores proportional display weight", () => {
+    const chain = TRACES_FIXTURE.filter(
+      (s) => s.id === "run-create-ok" || s.id === "run-fulfill",
+    );
+    const intervals = intervalsFromSpans(chain);
+    const draft = foldTimeline(intervals);
+    const foldId = draft.segments.find((s) => s.kind === "fold")?.id;
+    expect(foldId).toBeDefined();
+    const folded = foldTimeline(intervals, {
+      expandedFolds: new Set([foldId!]),
+    });
+    const fold = folded.segments.find((s) => s.kind === "fold");
+    expect(fold?.kind).toBe("fold");
+    if (fold?.kind !== "fold") return;
+    expect(fold.expanded).toBe(true);
+    expect(fold.displayMs).toBe(fold.durationMs);
+  });
+
+  test("work stays proportional — display sum excludes collapsed dead time", () => {
+    const chain = TRACES_FIXTURE.filter(
+      (s) => s.id === "run-create-ok" || s.id === "run-fulfill",
+    );
+    const folded = foldTimeline(intervalsFromSpans(chain));
+    const workDisplay = folded.segments
+      .filter((s) => s.kind === "work")
+      .reduce((s, seg) => s + seg.displayMs, 0);
+    expect(folded.displayDurationMs).toBe(
+      workDisplay + COLLAPSED_FOLD_DISPLAY_MS,
+    );
+    expect(folded.wallDurationMs).toBeGreaterThan(folded.displayDurationMs);
+  });
+
+  test("formatFoldLabel uses human units", () => {
+    expect(formatFoldLabel(20)).toBe("20ms idle");
+    expect(formatFoldLabel(7 * 24 * 60 * 60 * 1000)).toBe("7d idle");
+  });
+});

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

@@ -0,0 +1,170 @@
+/**
+ * Folded-time waterfall (console §9.3).
+ *
+ * Dead time collapses into a labelled, expandable bar the way a diff folds
+ * unchanged lines; real work stays exactly proportional. One linear scale
+ * serves a 20 ms trace and a week-long one — no modes, no log axis.
+ */
+
+import { tierOfKind } from "./tier.ts";
+import type { TimelineSegment, TraceSpan, WorkInterval } from "./types.ts";
+
+/** Collapsed fold occupies this much of the display scale (ms-equivalent). */
+export const COLLAPSED_FOLD_DISPLAY_MS = 40;
+
+/** Gaps at or above this threshold become folds. */
+export const DEFAULT_FOLD_THRESHOLD_MS = 50;
+
+/** Options for {@link foldTimeline}. */
+export interface FoldOptions {
+  /** Gap threshold before collapsing (default {@link DEFAULT_FOLD_THRESHOLD_MS}). */
+  readonly foldThresholdMs?: number;
+  /** Ids of folds the operator has expanded. */
+  readonly expandedFolds?: ReadonlySet<string>;
+}
+
+/** Result of folding a work timeline. */
+export interface FoldedTimeline {
+  /** Ordered segments (work + folds). */
+  readonly segments: readonly TimelineSegment[];
+  /** Sum of display weights — denominator for proportional widths. */
+  readonly displayDurationMs: number;
+  /** Wall-clock span of the whole timeline. */
+  readonly wallDurationMs: number;
+}
+
+/**
+ * Format a duration for fold labels (`7d`, `2h`, `340ms`).
+ *
+ * @param ms - Duration in milliseconds
+ */
+export function formatFoldLabel(ms: number): string {
+  const abs = Math.max(0, Math.round(ms));
+  if (abs < 1000) return `${abs}ms idle`;
+  const sec = abs / 1000;
+  if (sec < 60) return `${trim(sec)}s idle`;
+  const min = sec / 60;
+  if (min < 60) return `${trim(min)}m idle`;
+  const hr = min / 60;
+  if (hr < 48) return `${trim(hr)}h idle`;
+  const day = hr / 24;
+  return `${trim(day)}d idle`;
+}
+
+/**
+ * Fold dead time out of a sorted work timeline.
+ *
+ * @param intervals - Work intervals (any order; sorted internally)
+ * @param options - Fold threshold and expansion state
+ * @param criticalSpanIds - Spans on the critical path
+ */
+export function foldTimeline(
+  intervals: readonly WorkInterval[],
+  options: FoldOptions = {},
+  criticalSpanIds: ReadonlySet<string> = new Set(),
+): FoldedTimeline {
+  const threshold = options.foldThresholdMs ?? DEFAULT_FOLD_THRESHOLD_MS;
+  const expanded = options.expandedFolds ?? new Set<string>();
+  const sorted = [...intervals].sort((a, b) => a.startMs - b.startMs);
+
+  if (sorted.length === 0) {
+    return { segments: [], displayDurationMs: 0, wallDurationMs: 0 };
+  }
+
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  if (!first || !last) {
+    return { segments: [], displayDurationMs: 0, wallDurationMs: 0 };
+  }
+
+  const wallStart = first.startMs;
+  const wallEnd = Math.max(...sorted.map((i) => i.endMs));
+  const segments: TimelineSegment[] = [];
+  let cursor = wallStart;
+
+  for (const interval of sorted) {
+    const gap = interval.startMs - cursor;
+    if (gap >= threshold) {
+      const foldId = `fold:${cursor}:${interval.startMs}`;
+      const isExpanded = expanded.has(foldId);
+      const durationMs = gap;
+      segments.push({
+        kind: "fold",
+        id: foldId,
+        startMs: cursor,
+        endMs: interval.startMs,
+        durationMs,
+        label: formatFoldLabel(durationMs),
+        expanded: isExpanded,
+        displayMs: isExpanded ? durationMs : COLLAPSED_FOLD_DISPLAY_MS,
+      });
+    }
+
+    const durationMs = Math.max(0, interval.endMs - interval.startMs);
+    segments.push({
+      kind: "work",
+      id: interval.id,
+      label: interval.label,
+      startMs: interval.startMs,
+      endMs: interval.endMs,
+      durationMs,
+      tier: interval.tier,
+      spanId: interval.spanId,
+      critical: criticalSpanIds.has(interval.spanId),
+      failed: interval.failed === true,
+      displayMs: Math.max(1, durationMs),
+    });
+    cursor = Math.max(cursor, interval.endMs);
+  }
+
+  const displayDurationMs = segments.reduce((s, seg) => s + seg.displayMs, 0);
+  return {
+    segments,
+    displayDurationMs: Math.max(1, displayDurationMs),
+    wallDurationMs: wallEnd - wallStart,
+  };
+}
+
+/**
+ * Build work intervals from spans — one interval per span covering its
+ * active wall time. Prefer effect sub-intervals when present so intra-span
+ * idle (sleep) can fold too.
+ *
+ * @param spans - Spans in the open trace
+ */
+export function intervalsFromSpans(spans: readonly TraceSpan[]): WorkInterval[] {
+  const out: WorkInterval[] = [];
+  for (const span of spans) {
+    if (span.effects.length > 0) {
+      for (const e of span.effects) {
+        out.push({
+          id: `${span.id}:${e.kind}:${e.resource}:${e.timestamp}`,
+          label: `${e.kind} ${e.resource}`,
+          startMs: e.timestamp,
+          endMs: e.timestamp + Math.max(1, e.duration),
+          tier: tierOfKind(e.kind),
+          spanId: span.id,
+          failed:
+            span.errorCode != null &&
+            e === span.effects[span.effects.length - 1],
+        });
+      }
+    } else {
+      out.push({
+        id: span.id,
+        label: span.flow,
+        startMs: span.startedAt,
+        endMs: span.endedAt,
+        tier: "none",
+        spanId: span.id,
+        failed: span.errorCode != null,
+      });
+    }
+  }
+  return out;
+}
+
+function trim(n: number): string {
+  const r = Math.round(n * 10) / 10;
+  return Number.isInteger(r) ? String(r) : r.toFixed(1);
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Traces panel — folded-time causal chain (console §9.3).
+ *
+ * Pure modules live here so `bun test src/console/ui/traces` gates behaviour
+ * without mounting the full SPA.
+ */
+
+export {
+  buildCausalChain,
+  groupTraceRoots,
+  indexSpans,
+  initialFocusSpanId,
+  type CausalChain,
+  type TraceRoot,
+} from "./chain.ts";
+export { criticalPathSpanIds, workMs } from "./critical-path.ts";
+export {
+  matchesEffectFilter,
+  parseEffectFilter,
+  serializeEffectFilter,
+  traceMatchesEffectFilter,
+} from "./filter.ts";
+export {
+  COLLAPSED_FOLD_DISPLAY_MS,
+  DEFAULT_FOLD_THRESHOLD_MS,
+  foldTimeline,
+  formatFoldLabel,
+  intervalsFromSpans,
+  type FoldedTimeline,
+  type FoldOptions,
+} from "./fold.ts";
+export { miniWaterfall, rootErrorCode } from "./mini.ts";
+export { replayDecision, type ReplayDecision } from "./replay.ts";
+export {
+  boostFlowFully,
+  DEFAULT_SAMPLING_LABEL,
+  FULL_TRACE_BOOST_MS,
+  pruneBoosts,
+  samplingLabel,
+  type FullTraceBoost,
+} from "./sampling.ts";
+export {
+  closeTrace,
+  effectFilterOf,
+  expandedFoldsOf,
+  openTrace,
+  parseTracesSearch,
+  serializeTracesSearch,
+  setEffectFilter,
+  toggleFold,
+  TracesSearchSchema,
+  type TracesSearch,
+} from "./search.ts";
+export { peakSpanTier, tierOfKind, traceHasExternal } from "./tier.ts";
+export type {
+  EffectFilter,
+  MiniBar,
+  SampleReason,
+  SpanTier,
+  TimelineSegment,
+  TraceEffect,
+  TraceSpan,
+  WorkInterval,
+} from "./types.ts";

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

@@ -0,0 +1,65 @@
+/**
+ * Inline mini-waterfall for list rows (console §9.3).
+ */
+
+import { peakSpanTier, tierOfKind } from "./tier.ts";
+import type { MiniBar, TraceSpan } from "./types.ts";
+
+/**
+ * Build proportional mini-bars for a root row (connected spans).
+ *
+ * @param spans - Spans in the root's connected component
+ */
+export function miniWaterfall(spans: readonly TraceSpan[]): MiniBar[] {
+  if (spans.length === 0) return [];
+  const start = Math.min(...spans.map((s) => s.startedAt));
+  const end = Math.max(...spans.map((s) => s.endedAt));
+  const wall = Math.max(1, end - start);
+
+  if (spans.every((s) => s.effects.length === 0)) {
+    return spans.map((s) => ({
+      start: (s.startedAt - start) / wall,
+      width: Math.max(0.02, s.durationMs / wall),
+      tier: peakSpanTier(s.effects),
+      failed: s.errorCode != null,
+    }));
+  }
+
+  const bars: MiniBar[] = [];
+  for (const s of spans) {
+    if (s.effects.length === 0) {
+      bars.push({
+        start: (s.startedAt - start) / wall,
+        width: Math.max(0.02, s.durationMs / wall),
+        tier: "none",
+        failed: s.errorCode != null,
+      });
+      continue;
+    }
+    for (let i = 0; i < s.effects.length; i++) {
+      const e = s.effects[i];
+      if (!e) continue;
+      bars.push({
+        start: (e.timestamp - start) / wall,
+        width: Math.max(0.02, e.duration / wall),
+        tier: tierOfKind(e.kind),
+        failed: s.errorCode != null && i === s.effects.length - 1,
+      });
+    }
+  }
+  return bars;
+}
+
+/**
+ * Typed error code for a root row — first failure in the chain, else null.
+ *
+ * @param spans - Connected spans
+ */
+export function rootErrorCode(
+  spans: readonly TraceSpan[],
+): string | null {
+  for (const s of spans) {
+    if (s.errorCode) return s.errorCode;
+  }
+  return null;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Replay reversibility tests (console §9.3).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { TRACES_FIXTURE } from "./fixture.ts";
+import { replayDecision } from "./replay.ts";
+
+describe("replayDecision", () => {
+  test("offers dry-run when the trace has an external effect", () => {
+    const chain = TRACES_FIXTURE.filter(
+      (s) => s.id === "run-create-ok" || s.id === "run-fulfill",
+    );
+    const decision = replayDecision(chain);
+    expect(decision.mode).toBe("dry-run");
+    if (decision.mode !== "dry-run") return;
+    expect(decision.reason).toContain("external");
+  });
+
+  test("allows full replay when every effect is reversible", () => {
+    const fail = TRACES_FIXTURE.filter((s) => s.id === "run-create-fail");
+    expect(replayDecision(fail)).toEqual({ mode: "replay" });
+  });
+});

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

@@ -0,0 +1,35 @@
+/**
+ * Replay governed by reversibility (console §9.3 · §9.1 · §10.5).
+ *
+ * A trace containing an external effect offers a dry run with external
+ * effects stubbed — never a silent re-send of email / charge.
+ */
+
+import { traceHasExternal } from "./tier.ts";
+import type { TraceSpan } from "./types.ts";
+
+/** Replay decision for a connected trace. */
+export type ReplayDecision =
+  | { readonly mode: "replay" }
+  | {
+      readonly mode: "dry-run";
+      readonly reason: string;
+    };
+
+/**
+ * Decide how Replay may proceed for the open trace.
+ *
+ * @param spans - Connected spans
+ */
+export function replayDecision(
+  spans: readonly TraceSpan[],
+): ReplayDecision {
+  if (traceHasExternal(spans)) {
+    return {
+      mode: "dry-run",
+      reason:
+        "This trace contains an external effect. Replay runs as a dry run with external effects stubbed.",
+    };
+  }
+  return { mode: "replay" };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Sampling honesty tests (console §9.3).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  boostFlowFully,
+  DEFAULT_SAMPLING_LABEL,
+  FULL_TRACE_BOOST_MS,
+  pruneBoosts,
+  samplingLabel,
+} from "./sampling.ts";
+
+describe("sampling", () => {
+  test("default label states 10% + all errors", () => {
+    expect(samplingLabel([])).toBe(DEFAULT_SAMPLING_LABEL);
+  });
+
+  test("boost adds a 10-minute full-trace escape hatch", () => {
+    const now = 1_000_000;
+    const boosts = boostFlowFully([], "bookings.create", now);
+    expect(boosts[0]?.until).toBe(now + FULL_TRACE_BOOST_MS);
+    expect(samplingLabel(boosts, now)).toContain("bookings.create");
+    expect(pruneBoosts(boosts, now + FULL_TRACE_BOOST_MS + 1)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,66 @@
+/**
+ * Honest sampling labels + full-trace escape hatch (console §9.3).
+ *
+ * Sampling is stated in the list (10% + all errors) with a
+ * "trace this flow fully for 10 minutes" override.
+ */
+
+/** Default sampling policy shown in the list header. */
+export const DEFAULT_SAMPLING_LABEL = "10% + all errors";
+
+/** Full-trace boost window (10 minutes). */
+export const FULL_TRACE_BOOST_MS = 10 * 60 * 1000;
+
+/** Active boost for one flow. */
+export interface FullTraceBoost {
+  /** Flow name. */
+  readonly flow: string;
+  /** Epoch-ms when the boost expires. */
+  readonly until: number;
+}
+
+/**
+ * Sampling line for the list header, including active boosts.
+ *
+ * @param boosts - Active boosts
+ * @param now - Clock
+ */
+export function samplingLabel(
+  boosts: readonly FullTraceBoost[],
+  now: number = Date.now(),
+): string {
+  const live = boosts.filter((b) => b.until > now);
+  if (live.length === 0) return DEFAULT_SAMPLING_LABEL;
+  const flows = live.map((b) => b.flow).join(", ");
+  return `${DEFAULT_SAMPLING_LABEL} · full: ${flows}`;
+}
+
+/**
+ * Create / refresh a 10-minute full-trace boost for a flow.
+ *
+ * @param boosts - Existing boosts
+ * @param flow - Flow to boost
+ * @param now - Clock
+ */
+export function boostFlowFully(
+  boosts: readonly FullTraceBoost[],
+  flow: string,
+  now: number = Date.now(),
+): FullTraceBoost[] {
+  const until = now + FULL_TRACE_BOOST_MS;
+  const rest = boosts.filter((b) => b.flow !== flow && b.until > now);
+  return [...rest, { flow, until }];
+}
+
+/**
+ * Prune expired boosts.
+ *
+ * @param boosts - Boosts
+ * @param now - Clock
+ */
+export function pruneBoosts(
+  boosts: readonly FullTraceBoost[],
+  now: number = Date.now(),
+): FullTraceBoost[] {
+  return boosts.filter((b) => b.until > now);
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Typed search params for the Traces panel (console §7 · §9.3).
+ *
+ * Pasted links reproduce the exact view — open trace, focus span, effect
+ * filter, expanded folds.
+ */
+
+import { z } from "zod";
+import {
+  parseEffectFilter,
+  serializeEffectFilter,
+  type EffectFilter,
+} from "./filter.ts";
+
+/** Zod schema for Traces URL search params. */
+export const TracesSearchSchema = z.object({
+  /** Open root / connected-component id (usually the root span id). */
+  trace: z.string().optional(),
+  /** Focused span within the open trace. */
+  span: z.string().optional(),
+  /** Effect filter compact form (`wrote:sql:bookings`, `cost:0.05`, …). */
+  effect: z.string().optional(),
+  /** Free-text filter (dims, never hides). */
+  q: z.string().optional(),
+  /** Comma-separated expanded fold ids. */
+  folds: z.string().optional(),
+  /** Flow selected for the full-trace boost control (UI only). */
+  boost: z.string().optional(),
+});
+
+/** Parsed, typed Traces search state. */
+export type TracesSearch = z.infer<typeof TracesSearchSchema>;
+
+/**
+ * Parse unknown search params into a typed {@link TracesSearch}.
+ *
+ * @param raw - Router search object
+ */
+export function parseTracesSearch(raw: unknown): TracesSearch {
+  const result = TracesSearchSchema.safeParse(raw ?? {});
+  if (result.success) return result.data;
+  return TracesSearchSchema.parse({});
+}
+
+/**
+ * Serialise typed search into a plain object suitable for TanStack Router.
+ *
+ * @param search - Typed search
+ */
+export function serializeTracesSearch(
+  search: TracesSearch,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (search.trace) out.trace = search.trace;
+  if (search.span) out.span = search.span;
+  if (search.effect) out.effect = search.effect;
+  if (search.q) out.q = search.q;
+  if (search.folds) out.folds = search.folds;
+  if (search.boost) out.boost = search.boost;
+  return out;
+}
+
+/**
+ * Effect filter derived from search.
+ *
+ * @param search - Typed search
+ */
+export function effectFilterOf(search: TracesSearch): EffectFilter | null {
+  return parseEffectFilter(search.effect);
+}
+
+/**
+ * Expanded fold ids from search.
+ *
+ * @param search - Typed search
+ */
+export function expandedFoldsOf(search: TracesSearch): Set<string> {
+  if (!search.folds) return new Set();
+  return new Set(
+    search.folds
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Open a trace (root id) and optional focus span.
+ *
+ * @param prev - Current search
+ * @param rootId - Root span id
+ * @param spanId - Optional focus span
+ */
+export function openTrace(
+  prev: TracesSearch,
+  rootId: string,
+  spanId?: string,
+): TracesSearch {
+  return {
+    ...prev,
+    trace: rootId,
+    span: spanId,
+  };
+}
+
+/**
+ * Close the detail view; stay on the Traces panel.
+ *
+ * @param prev - Current search
+ */
+export function closeTrace(prev: TracesSearch): TracesSearch {
+  return {
+    ...prev,
+    trace: undefined,
+    span: undefined,
+    folds: undefined,
+  };
+}
+
+/**
+ * Toggle a fold's expanded state in the URL.
+ *
+ * @param prev - Current search
+ * @param foldId - Fold segment id
+ */
+export function toggleFold(prev: TracesSearch, foldId: string): TracesSearch {
+  const set = expandedFoldsOf(prev);
+  if (set.has(foldId)) set.delete(foldId);
+  else set.add(foldId);
+  const folds = [...set].join(",");
+  return { ...prev, folds: folds || undefined };
+}
+
+/**
+ * Set the effect filter (or clear with null).
+ *
+ * @param prev - Current search
+ * @param filter - Effect filter
+ */
+export function setEffectFilter(
+  prev: TracesSearch,
+  filter: EffectFilter | null,
+): TracesSearch {
+  return {
+    ...prev,
+    effect: serializeEffectFilter(filter),
+  };
+}