okengine 0.1.4

package/src/console/ui/gates/search.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Gates URL search state tests (console §7 · §9.7).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  decodePrincipal,
+  encodePrincipal,
+  openFlow,
+  openPrincipal,
+  parseGatesSearch,
+  serializeGatesSearch,
+} from "./search.ts";
+
+describe("gates search", () => {
+  test("round-trips principal inquiry", () => {
+    const next = openPrincipal({}, "role", "role_member");
+    expect(next.from).toBe("principal");
+    expect(next.principal).toBe("role:role_member");
+    expect(decodePrincipal(next.principal)).toEqual({
+      kind: "role",
+      id: "role_member",
+    });
+    expect(serializeGatesSearch(next)).toEqual({
+      from: "principal",
+      principal: "role:role_member",
+    });
+  });
+
+  test("round-trips flow inquiry", () => {
+    const next = openFlow({ q: "book" }, "bookings.create");
+    expect(next.from).toBe("flow");
+    expect(next.flow).toBe("bookings.create");
+    expect(parseGatesSearch(serializeGatesSearch(next))).toMatchObject({
+      from: "flow",
+      flow: "bookings.create",
+      q: "book",
+    });
+  });
+
+  test("encode/decode principal", () => {
+    expect(encodePrincipal("key", "key_demo")).toBe("key:key_demo");
+    expect(decodePrincipal("user:user_demo")).toEqual({
+      kind: "user",
+      id: "user_demo",
+    });
+    expect(decodePrincipal("nope")).toBeNull();
+  });
+});

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

@@ -0,0 +1,115 @@
+/**
+ * URL search state for the Gates panel (console §7 · §9.7).
+ */
+
+import { z } from "zod";
+
+const GatesSearchSchema = z.object({
+  q: z.string().optional(),
+  /** Inquiry direction — principal or flow. */
+  from: z.enum(["principal", "flow"]).optional(),
+  /** Selected principal id (`role:…` / `key:…` / `user:…`). */
+  principal: z.string().optional(),
+  /** Selected flow id. */
+  flow: z.string().optional(),
+  /** Companion selection for the simulator (other direction). */
+  as: z.string().optional(),
+});
+
+/** Parsed Gates URL search. */
+export type GatesSearch = z.infer<typeof GatesSearchSchema>;
+
+/**
+ * Parse Gates panel search params.
+ *
+ * @param search - Raw router search
+ */
+export function parseGatesSearch(
+  search: Record<string, unknown>,
+): GatesSearch {
+  const parsed = GatesSearchSchema.safeParse(search);
+  return parsed.success ? parsed.data : {};
+}
+
+/**
+ * Serialize Gates search for navigation (omit empties).
+ *
+ * @param search - Search state
+ */
+export function serializeGatesSearch(
+  search: GatesSearch,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (search.q) out.q = search.q;
+  if (search.from) out.from = search.from;
+  if (search.principal) out.principal = search.principal;
+  if (search.flow) out.flow = search.flow;
+  if (search.as) out.as = search.as;
+  return out;
+}
+
+/**
+ * Encode a principal selection for the URL.
+ *
+ * @param kind - Principal kind
+ * @param id - Principal id
+ */
+export function encodePrincipal(
+  kind: "role" | "key" | "user",
+  id: string,
+): string {
+  return `${kind}:${id}`;
+}
+
+/**
+ * Decode a principal selection from the URL.
+ *
+ * @param value - Encoded value
+ */
+export function decodePrincipal(
+  value: string | undefined,
+): { kind: "role" | "key" | "user"; id: string } | null {
+  if (!value) return null;
+  const i = value.indexOf(":");
+  if (i === -1) return null;
+  const kind = value.slice(0, i);
+  const id = value.slice(i + 1);
+  if (kind !== "role" && kind !== "key" && kind !== "user") return null;
+  if (!id) return null;
+  return { kind, id };
+}
+
+/**
+ * Open a principal in the from-principal direction.
+ *
+ * @param search - Current search
+ * @param kind - Principal kind
+ * @param id - Principal id
+ */
+export function openPrincipal(
+  search: GatesSearch,
+  kind: "role" | "key" | "user",
+  id: string,
+): GatesSearch {
+  return {
+    ...search,
+    from: "principal",
+    principal: encodePrincipal(kind, id),
+    flow: undefined,
+  };
+}
+
+/**
+ * Open a flow in the from-flow direction.
+ *
+ * @param search - Current search
+ * @param flowId - Flow id
+ */
+export function openFlow(search: GatesSearch, flowId: string): GatesSearch {
+  return {
+    ...search,
+    from: "flow",
+    flow: flowId,
+    principal: undefined,
+  };
+}

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

@@ -0,0 +1,121 @@
+/**
+ * Gates panel view types (console §9.7).
+ */
+
+/** Principal kinds for the from-principal inquiry. */
+export type GatePrincipalKind = "role" | "key" | "user";
+
+/** Flow gate chain row. */
+export interface FlowGatesRecord {
+  readonly flowId: string;
+  readonly plane: "user" | "operator";
+  readonly gates: readonly string[];
+  readonly unguarded: boolean;
+}
+
+/** Declared gate definition. */
+export interface GateDefRecord {
+  readonly name: string;
+  readonly kind: "policy" | "rate";
+  readonly scopes: readonly string[];
+  readonly roles: readonly string[];
+  readonly strategy?: string;
+  readonly max?: number;
+  readonly per?: string;
+  readonly keyBy?: string;
+  readonly overridable: boolean;
+  readonly attachedTo: readonly string[];
+}
+
+/** Principal row (never an operator holding application scopes). */
+export interface PrincipalRecord {
+  readonly kind: GatePrincipalKind;
+  readonly id: string;
+  readonly name: string;
+  readonly plane: "user" | "operator";
+  readonly scopes: readonly string[];
+  readonly memberCount?: number;
+  readonly email?: string;
+}
+
+/** Two-plane violation — operator holding application scope. */
+export interface PlaneViolationRecord {
+  readonly kind: "operator-application-scope";
+  readonly operatorId: string;
+  readonly name: string;
+  readonly email: string;
+  readonly applicationScopes: readonly string[];
+}
+
+/** Continuous audit findings. */
+export interface GateAuditRecord {
+  readonly unguardedFlows: readonly string[];
+  readonly orphanPermissions: readonly string[];
+  readonly emptyRoles: readonly string[];
+  readonly unattachedGates: readonly string[];
+}
+
+/** Permission-widening deploy diff line. */
+export interface WideningRecord {
+  readonly path: string;
+  readonly category: string;
+  readonly kind: string;
+  readonly summary: string;
+}
+
+/** `console.gates.list` response. */
+export interface GatesListResponse {
+  readonly moduleActions: readonly string[];
+  readonly flows: readonly FlowGatesRecord[];
+  readonly gates: readonly GateDefRecord[];
+  readonly principals: readonly PrincipalRecord[];
+  readonly violations: readonly PlaneViolationRecord[];
+  readonly audit: GateAuditRecord;
+  readonly widenings: readonly WideningRecord[];
+}
+
+/** One evaluation step in the simulator. */
+export interface GateEvaluationRecord {
+  readonly name: string;
+  readonly allowed: boolean;
+  readonly kind: "policy" | "rate";
+  readonly remaining?: number;
+  readonly retryAfterMs?: number;
+  readonly reason?: string;
+}
+
+/** Typed denial the client would receive. */
+export interface GateDenialRecord {
+  readonly code: "Unauthorized" | "Forbidden" | "RateLimited";
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly status: 401 | 403 | 429;
+}
+
+/** `console.gates.simulate` response. */
+export interface SimulateResponse {
+  readonly flowId: string;
+  readonly gates: readonly string[];
+  readonly evaluations: readonly GateEvaluationRecord[];
+  readonly deniedAt: string | null;
+  readonly denial: GateDenialRecord | null;
+  readonly allowed: boolean;
+}
+
+/** `console.gates.powers` response. */
+export interface PowersResponse {
+  readonly scopes: readonly string[];
+  readonly allowedFlowIds: readonly string[];
+  readonly deniedFlowIds: readonly string[];
+}
+
+/** Grouped list section for the bidirectional inquiry. */
+export interface GatesListGroup {
+  readonly id: string;
+  readonly label: string;
+  readonly items: ReadonlyArray<{
+    readonly id: string;
+    readonly label: string;
+    readonly meta?: string;
+    readonly flag?: string;
+  }>;
+}

package/src/console/ui/overview/OverviewA11yView.tsx

@@ -0,0 +1,152 @@
+/**
+ * Static Overview markup for the axe gate — same landmarks / roles as the
+ * live panel (console §9.16).
+ */
+
+import { composeOverview } from "./compose.ts";
+import {
+  OVERVIEW_DAY_ONE_INPUTS,
+  OVERVIEW_INPUTS_FIXTURE,
+} from "./fixture.ts";
+import {
+  formatBudgetDuration,
+  formatBurnRate,
+} from "./verdict.ts";
+
+/** Props for {@link OverviewA11yView}. */
+export interface OverviewA11yViewProps {
+  /** Use the day-one (no SLOs) fixture. */
+  readonly dayOne?: boolean;
+}
+
+/**
+ * Accessible Overview for CI.
+ *
+ * @param props - Fixture selection
+ */
+export function OverviewA11yView(props: OverviewA11yViewProps = {}) {
+  const view = composeOverview(
+    props.dayOne ? OVERVIEW_DAY_ONE_INPUTS : OVERVIEW_INPUTS_FIXTURE,
+  );
+
+  return (
+    <div className="overview-a11y">
+      <a href="#overview-main">Skip to main content</a>
+      <header>
+        <h1>Overview</h1>
+        <p role="status" aria-live="polite" data-tone={view.verdict.tone}>
+          {view.verdict.line}
+        </p>
+      </header>
+      <main id="overview-main">
+        {view.hasDeclaredSlos ? (
+          <section aria-label="Error budgets">
+            <h2>Error budgets</h2>
+            <ul>
+              {view.slos.map((s) => (
+                <li key={s.id}>
+                  <span>
+                    {s.kind}:{s.name}
+                  </span>
+                  <span> {s.availability}</span>
+                  <span> burn {formatBurnRate(s.burnRate)}</span>
+                  <span>
+                    {" "}
+                    exhausts {formatBudgetDuration(s.timeToExhaustionMs)}
+                  </span>
+                  {s.ceremonial ? (
+                    <span role="status"> CEREMONIAL</span>
+                  ) : null}
+                </li>
+              ))}
+            </ul>
+          </section>
+        ) : null}
+
+        <section aria-label="Cost budgets">
+          <h2>Cost budgets</h2>
+          {view.costBudgets.length === 0 ? (
+            <p>No cost budgets declared.</p>
+          ) : (
+            <ul>
+              {view.costBudgets.map((c) => (
+                <li key={c.id}>
+                  <span>{c.name}</span>
+                  <span>
+                    {" "}
+                    ${c.spent.toFixed(2)} / ${c.declaredBudget.toFixed(2)}
+                  </span>
+                  <span> burn {formatBurnRate(c.burnRate)}</span>
+                  <span>
+                    {" "}
+                    exhausts {formatBudgetDuration(c.timeToExhaustionMs)}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          )}
+        </section>
+
+        <section aria-label="What changed">
+          <h2>What changed</h2>
+          <p>
+            <a href={view.whatChanged.href}>{view.whatChanged.line}</a>
+          </p>
+        </section>
+
+        <section aria-label="Findings" aria-live="polite">
+          <h2>Findings</h2>
+          {view.findings.length === 0 ? (
+            <p>No findings from other panels.</p>
+          ) : (
+            <ol>
+              {view.findings.map((f) => (
+                <li key={f.id}>
+                  <a href={f.href}>
+                    {f.title}: {f.detail}
+                  </a>
+                </li>
+              ))}
+            </ol>
+          )}
+        </section>
+
+        <section aria-label="Golden signals">
+          <h2>Golden signals</h2>
+          <dl>
+            <div>
+              <dt>Latency p99</dt>
+              <dd>{view.golden.latencyP99Ms} ms</dd>
+            </div>
+            <div>
+              <dt>Traffic</dt>
+              <dd>{view.golden.trafficPerMin.toFixed(1)} / min</dd>
+            </div>
+            <div>
+              <dt>Errors</dt>
+              <dd>{(view.golden.errorRate * 100).toFixed(2)}%</dd>
+            </div>
+            <div>
+              <dt>Saturation</dt>
+              <dd>{(view.golden.saturation * 100).toFixed(1)}%</dd>
+            </div>
+          </dl>
+        </section>
+
+        {view.firstSloInvite ? (
+          <section aria-label="Declare first SLO">
+            <h2>Declare a first objective</h2>
+            <p>
+              Your busiest flow is{" "}
+              <a href={view.firstSloInvite.href}>
+                {view.firstSloInvite.busiestFlow}
+              </a>{" "}
+              ({view.firstSloInvite.runCount} runs). Add{" "}
+              <code>slo: {"{ availability: \"99.9%\" }"}</code> on that flow.
+            </p>
+          </section>
+        ) : null}
+      </main>
+    </div>
+  );
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · §9.16).
+ */
+
+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 { OverviewA11yView } from "./OverviewA11yView.tsx";
+
+describe("Overview 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/overview" });
+    Object.defineProperty(globalThis, "window", {
+      value: window,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "document", {
+      value: window.document,
+      configurable: 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 (burning state)", async () => {
+    await act(async () => {
+      root.render(<OverviewA11yView />);
+    });
+
+    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([]);
+  });
+
+  test("axe reports zero violations at WCAG 2.2 AA (day-one empty SLOs)", async () => {
+    await act(async () => {
+      root.render(<OverviewA11yView dayOne />);
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    const results = await axe.run(container, {
+      runOnly: {
+        type: "tag",
+        values: ["wcag2a", "wcag2aa", "wcag22aa"],
+      },
+    });
+
+    expect(results.violations).toEqual([]);
+  });
+});

package/src/console/ui/overview/busiest.ts

@@ -0,0 +1,26 @@
+/**
+ * Busiest flow from real Runs volume (console §9.16 day-one invite).
+ */
+
+import { groupByDimension } from "../runs/group.ts";
+import type { RunRecord } from "../runs/types.ts";
+import type { FirstSloInvite } from "./types.ts";
+
+/**
+ * Invite to declare a first SLO on the busiest flow by run count.
+ *
+ * @param runs - Real Runs population
+ */
+export function firstSloInvite(
+  runs: readonly RunRecord[],
+): FirstSloInvite | null {
+  if (runs.length === 0) return null;
+  const groups = groupByDimension(runs, "flow");
+  const top = groups[0];
+  if (!top || top.key === "(empty)") return null;
+  return {
+    busiestFlow: top.key,
+    runCount: top.count,
+    href: `/flows?flow=${encodeURIComponent(top.key)}`,
+  };
+}