okengine 0.1.4

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

@@ -0,0 +1,72 @@
+/**
+ * Map span effects onto the Flows effect-tier vocabulary (console §9.3).
+ */
+
+import type { EffectKind } from "../../../kernel/effects.ts";
+import type { UiEffectTier } from "../flows/tiers.ts";
+import type { SpanTier, TraceEffect, TraceSpan } from "./types.ts";
+
+/**
+ * UI tier for a single effect kind.
+ *
+ * @param kind - Kernel effect kind
+ */
+export function tierOfKind(kind: EffectKind): UiEffectTier {
+  switch (kind) {
+    case "read":
+      return "reads";
+    case "write":
+      return "writes";
+    case "emit":
+      return "emits";
+    case "send":
+    case "ask":
+      return "external";
+    case "secret":
+      return "capabilities";
+    case "call":
+      return "reads";
+  }
+}
+
+/**
+ * Highest (most severe) effect tier on a span.
+ *
+ * @param effects - Span effects
+ */
+export function peakSpanTier(
+  effects: readonly TraceEffect[],
+): SpanTier {
+  let peak: SpanTier = "none";
+  for (const e of effects) {
+    const t = tierOfKind(e.kind);
+    if (rank(t) > rank(peak)) peak = t;
+  }
+  return peak;
+}
+
+/**
+ * Whether any span in the set has an irreversible (external) effect.
+ *
+ * @param spans - Spans in the trace
+ */
+export function traceHasExternal(spans: readonly TraceSpan[]): boolean {
+  return spans.some((s) => peakSpanTier(s.effects) === "external");
+}
+
+function rank(tier: SpanTier): number {
+  switch (tier) {
+    case "external":
+      return 5;
+    case "capabilities":
+      return 4;
+    case "emits":
+      return 3;
+    case "writes":
+      return 2;
+    case "reads":
+      return 1;
+    case "none":
+      return 0;
+  }
+}

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

@@ -0,0 +1,125 @@
+/**
+ * Trace panel domain types (console §9.3 · §9.11).
+ *
+ * One flow execution = one wide event = one span. A trace is a causal chain
+ * of runs joined across async boundaries via {@link TraceSpan.parentId}.
+ */
+
+import type { EffectKind, ReversibilityTier } from "../../../kernel/effects.ts";
+import type { UiEffectTier } from "../flows/tiers.ts";
+
+/** One recorded effect on a span (subset of the ledger entry). */
+export interface TraceEffect {
+  /** 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;
+}
+
+/** Why a run appears in the sampled list (console §9.3). */
+export type SampleReason = "full" | "error" | "sample" | "boost";
+
+/**
+ * One span in a trace — the UI projection of a wide event.
+ */
+export interface TraceSpan {
+  /** Run id (= span id). */
+  readonly id: string;
+  /** Parent run id when caused by another execution. */
+  readonly parentId?: string;
+  /** Flow name. */
+  readonly flow: string;
+  /** Optional unit scope. */
+  readonly unit?: string;
+  /** Trigger kind. */
+  readonly trigger: string;
+  /** Epoch-ms start. */
+  readonly startedAt: number;
+  /** Epoch-ms end. */
+  readonly endedAt: number;
+  /** Wall duration in milliseconds. */
+  readonly durationMs: number;
+  /** Typed error code when the flow failed. */
+  readonly errorCode?: string | null;
+  /** Effect ledger snapshot. */
+  readonly effects: readonly TraceEffect[];
+  /** AI cost accrued during the run. */
+  readonly cost?: number;
+  /** Sampling classification for honest list labelling. */
+  readonly sampled: SampleReason;
+}
+
+/** Peak UI effect tier for a span (drives waterfall colour). */
+export type SpanTier = UiEffectTier | "none";
+
+/** One bar in a list-row mini-waterfall. */
+export interface MiniBar {
+  /** Relative start 0..1. */
+  readonly start: number;
+  /** Relative width 0..1. */
+  readonly width: number;
+  /** Effect tier colour key. */
+  readonly tier: SpanTier;
+  /** True when this bar is the failing effect. */
+  readonly failed?: boolean;
+}
+
+/** Filter by declared effect (console §9.3 — the filter no one else can offer). */
+export type EffectFilter =
+  | { readonly kind: "wrote"; readonly resource: string }
+  | { readonly kind: "asked" }
+  | { readonly kind: "sent"; readonly resource?: string }
+  | { readonly kind: "secret"; readonly resource?: string }
+  | { readonly kind: "cost"; readonly min: number };
+
+/** Work interval on a absolute timeline (before folding). */
+export interface WorkInterval {
+  /** Stable id for the segment. */
+  readonly id: string;
+  /** Display label. */
+  readonly label: string;
+  /** Absolute start (ms, same epoch as spans). */
+  readonly startMs: number;
+  /** Absolute end. */
+  readonly endMs: number;
+  /** Peak effect tier. */
+  readonly tier: SpanTier;
+  /** Span this interval belongs to. */
+  readonly spanId: string;
+  /** True when this interval carries the typed failure. */
+  readonly failed?: boolean;
+}
+
+/** Folded-time timeline segment after collapse. */
+export type TimelineSegment =
+  | {
+      readonly kind: "work";
+      readonly id: string;
+      readonly label: string;
+      readonly startMs: number;
+      readonly endMs: number;
+      readonly durationMs: number;
+      readonly tier: SpanTier;
+      readonly spanId: string;
+      readonly critical: boolean;
+      readonly failed: boolean;
+      /** Display width weight (proportional to real work). */
+      readonly displayMs: number;
+    }
+  | {
+      readonly kind: "fold";
+      readonly id: string;
+      readonly startMs: number;
+      readonly endMs: number;
+      readonly durationMs: number;
+      readonly label: string;
+      readonly expanded: boolean;
+      /** Collapsed folds use a fixed weight; expanded use full duration. */
+      readonly displayMs: number;
+    };

package/src/console/ui/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "types": ["vite/client", "bun"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "include": ["./**/*.ts", "./**/*.tsx"]
+}

package/src/console/ui/vault/VaultA11yView.tsx

@@ -0,0 +1,177 @@
+/**
+ * Static Vault markup for the axe gate — same landmarks as the live panel.
+ */
+
+import { formatBlastRadius } from "./blast-radius.ts";
+import { VAULT_LIST_FIXTURE } from "./fixture.ts";
+import { groupByKind } from "./group.ts";
+
+/** Props for {@link VaultA11yView}. */
+export interface VaultA11yViewProps {
+  /** Optional contract name to open. */
+  readonly openName?: string;
+}
+
+/**
+ * Accessible Vault list + detail for CI.
+ *
+ * @param props - Open contract
+ */
+export function VaultA11yView(props: VaultA11yViewProps) {
+  const groups = groupByKind(VAULT_LIST_FIXTURE.secrets);
+  const openName = props.openName ?? "STRIPE_KEY";
+  const open = VAULT_LIST_FIXTURE.secrets.find((s) => s.name === openName);
+  const blast = open ? formatBlastRadius(open.blastRadius) : null;
+  const env = VAULT_LIST_FIXTURE.env;
+
+  return (
+    <div className="vault-a11y">
+      <a href="#vault-main">Skip to main content</a>
+      <header>
+        <h1>Vault</h1>
+        <p>Contracts, fingerprints, resolution — never secret values</p>
+        <p role="status">Environment {env}</p>
+        <label>
+          Filter vault
+          <input aria-label="Filter vault" defaultValue="" />
+        </label>
+      </header>
+      <main id="vault-main">
+        <section aria-label="Vault list">
+          <h2>Contracts</h2>
+          {groups.map((group) => (
+            <section key={group.kind} aria-label={group.label}>
+              <h3>{group.label}</h3>
+              <ul>
+                {group.secrets.map((s) => (
+                  <li key={s.name}>
+                    <button
+                      type="button"
+                      aria-pressed={s.name === openName}
+                      style={{ minHeight: 32, width: "100%" }}
+                    >
+                      <span>{s.name}</span>
+                      {s.sensitive && s.fingerprint ? (
+                        <span> {s.fingerprint}</span>
+                      ) : null}
+                      {!s.sensitive && s.cleartext ? (
+                        <span> {s.cleartext}</span>
+                      ) : null}
+                      {s.blastRadius.count > 0 ? (
+                        <span role="status">
+                          {" "}
+                          blast {s.blastRadius.count}
+                        </span>
+                      ) : null}
+                      {s.sharedFingerprintEnvs.length > 0 ? (
+                        <span role="status"> shared fingerprint</span>
+                      ) : null}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </section>
+
+        {open ? (
+          <section aria-label="Vault detail" aria-live="polite">
+            <h2>{open.name}</h2>
+            {open.description ? <p>{open.description}</p> : null}
+            <p role="status">
+              {open.sensitive
+                ? `Fingerprint (${env}): ${open.fingerprint ?? "unset"}`
+                : `Value: ${open.cleartext ?? "unset"}`}
+            </p>
+
+            <section aria-label="Fingerprints by environment">
+              <h3>Fingerprints</h3>
+              {open.sensitive ? (
+                <ul>
+                  {Object.entries(open.fingerprints).map(([e, fp]) => (
+                    <li key={e}>
+                      {e}: {fp}
+                      {open.sharedFingerprintEnvs.includes(e) ? (
+                        <span role="status"> (matches {env})</span>
+                      ) : null}
+                    </li>
+                  ))}
+                </ul>
+              ) : (
+                <p>Config is shown in the clear — not fingerprinted.</p>
+              )}
+            </section>
+
+            <section aria-label="Resolution chain">
+              <h3>Resolution chain</h3>
+              <ol>
+                {open.resolution.map((step) => (
+                  <li key={step.source}>
+                    {step.source}
+                    {step.won
+                      ? " — won"
+                      : step.present
+                        ? " — present (lost)"
+                        : " — absent"}
+                  </li>
+                ))}
+              </ol>
+              <p role="status">Winner: {open.winner ?? "none"}</p>
+            </section>
+
+            <section aria-label="Readers">
+              <h3>Readers</h3>
+              <p>
+                Flows that declare fx.vault({open.name}):{" "}
+                {open.readers.join(", ") || "none"}
+              </p>
+            </section>
+
+            <section aria-label="Rotation blast radius">
+              <h3>Rotation blast radius</h3>
+              {blast ? (
+                <>
+                  <p role={blast.warn ? "alert" : "status"}>{blast.summary}</p>
+                  {blast.detail ? <p>{blast.detail}</p> : null}
+                </>
+              ) : null}
+            </section>
+
+            <section aria-label="Last read">
+              <h3>Last read</h3>
+              <p role="status">
+                {open.lastReadAt != null
+                  ? new Date(open.lastReadAt).toISOString()
+                  : "Never read — possible dead secret"}
+              </p>
+            </section>
+
+            <section aria-label="Set or rotate">
+              <h3>Set / rotate</h3>
+              <p>Write-only — values are never revealed after submit.</p>
+              <label>
+                New value
+                <input
+                  aria-label="New vault value"
+                  type="password"
+                  autoComplete="off"
+                  defaultValue=""
+                />
+              </label>
+              <label>
+                Confirmation
+                <input aria-label="Confirmation phrase" defaultValue="" />
+              </label>
+              <label>
+                Reason
+                <input aria-label="Reason for vault write" defaultValue="" />
+              </label>
+              <button type="button">Set</button>
+              <button type="button">Rotate</button>
+            </section>
+          </section>
+        ) : null}
+      </main>
+    </div>
+  );
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · §9.8).
+ */
+
+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 { VaultA11yView } from "./VaultA11yView.tsx";
+
+describe("Vault 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/vault" });
+    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(<VaultA11yView openName="STRIPE_KEY" />);
+    });
+
+    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/vault/blast-radius.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { formatBlastRadius, formatDuration } from "./blast-radius.ts";
+
+describe("formatBlastRadius", () => {
+  test("empty", () => {
+    const line = formatBlastRadius({
+      count: 0,
+      longestWakeAt: null,
+      longestOutstandingMs: null,
+      runIds: [],
+    });
+    expect(line.warn).toBe(false);
+    expect(line.summary).toContain("No in-flight");
+  });
+
+  test("warns with count and duration", () => {
+    const line = formatBlastRadius({
+      count: 3,
+      longestWakeAt: 1,
+      longestOutstandingMs: 3_600_000,
+      runIds: ["a", "b", "c"],
+    });
+    expect(line.warn).toBe(true);
+    expect(line.summary).toContain("3");
+    expect(line.detail).toContain("1h");
+  });
+});
+
+describe("formatDuration", () => {
+  test("units", () => {
+    expect(formatDuration(500)).toBe("500ms");
+    expect(formatDuration(5_000)).toBe("5s");
+    expect(formatDuration(120_000)).toBe("2m");
+  });
+});

package/src/console/ui/vault/blast-radius.ts

@@ -0,0 +1,55 @@
+/**
+ * Format journal-queried rotation blast radius for the Vault panel.
+ */
+
+import type { VaultBlastRadius } from "./types.ts";
+
+/** Human-readable blast-radius line. */
+export interface BlastRadiusLine {
+  readonly summary: string;
+  readonly detail: string | null;
+  readonly warn: boolean;
+}
+
+/**
+ * Format blast radius for display.
+ *
+ * @param blast - Queried radius
+ */
+export function formatBlastRadius(blast: VaultBlastRadius): BlastRadiusLine {
+  if (blast.count === 0) {
+    return {
+      summary: "No in-flight durable runs hold this secret",
+      detail: null,
+      warn: false,
+    };
+  }
+  const remaining =
+    blast.longestOutstandingMs != null
+      ? formatDuration(blast.longestOutstandingMs)
+      : null;
+  return {
+    summary: `${blast.count} in-flight durable run(s) will wake holding a new key`,
+    detail: remaining
+      ? `Longest outstanding wake in ${remaining}`
+      : blast.longestWakeAt != null
+        ? `Longest wake at ${new Date(blast.longestWakeAt).toISOString()}`
+        : null,
+    warn: true,
+  };
+}
+
+/**
+ * @param ms - Duration
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1_000) return `${ms}ms`;
+  const sec = Math.floor(ms / 1_000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.floor(min / 60);
+  if (hr < 48) return `${hr}h`;
+  const days = Math.floor(hr / 24);
+  return `${days}d`;
+}

package/src/console/ui/vault/confirmation.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import {
+  rotateConfirmation,
+  setConfirmation,
+  validateTypedConfirm,
+} from "./confirmation.ts";
+
+describe("vault confirmation", () => {
+  test("set requires typed confirm in production", () => {
+    expect(setConfirmation({ production: true })).toEqual({
+      kind: "typed",
+      phrase: "SET",
+      requireReason: true,
+    });
+  });
+
+  test("rotate always requires typed confirm", () => {
+    expect(rotateConfirmation({ production: false })).toEqual({
+      kind: "typed",
+      phrase: "ROTATE",
+      requireReason: true,
+    });
+  });
+
+  test("validateTypedConfirm", () => {
+    expect(
+      validateTypedConfirm({
+        typed: "ROTATE",
+        reason: "key compromise",
+        phrase: "ROTATE",
+      }),
+    ).toBeNull();
+    expect(
+      validateTypedConfirm({
+        typed: "nope",
+        reason: "x",
+        phrase: "ROTATE",
+      }),
+    ).not.toBeNull();
+  });
+});

package/src/console/ui/vault/confirmation.ts

@@ -0,0 +1,39 @@
+/**
+ * Typed confirmation for vault set / rotate (console §6 · §9.8).
+ *
+ * There is no preview affordance for Vault — set and rotate are real writes.
+ */
+
+import {
+  type ConfirmationPattern,
+  validateTypedConfirm,
+} from "../flows/confirmation.ts";
+
+export { validateTypedConfirm };
+export type { ConfirmationPattern };
+
+/**
+ * Confirmation for setting a vault value.
+ *
+ * @param options - Environment
+ */
+export function setConfirmation(
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  if (options.production) {
+    return { kind: "typed", phrase: "SET", requireReason: true };
+  }
+  // Dev still records a reason-less write; no typed phrase required.
+  return { kind: "undo", windowMs: 15_000 };
+}
+
+/**
+ * Confirmation for rotating a vault value — always typed (blast radius).
+ *
+ * @param _options - Reserved for environment flags
+ */
+export function rotateConfirmation(
+  _options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  return { kind: "typed", phrase: "ROTATE", requireReason: true };
+}