okengine 0.1.4

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

@@ -0,0 +1,105 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · prompt 17).
+ */
+
+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 { FLOWS_TEST_MANIFEST } from "./fixture.ts";
+import { FlowsA11yView } from "./FlowsA11yView.tsx";
+
+describe("Flows panel accessibility", () => {
+  let window: Window;
+  let root: Root;
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    // React 19 act() environment flag for bun:test + happy-dom.
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+      true;
+    window = new Window({ url: "http://console.test/flows" });
+    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(
+        <FlowsA11yView
+          manifest={FLOWS_TEST_MANIFEST}
+          effect="sql:bookings"
+        />,
+      );
+    });
+
+    // Allow layout / aria tree to settle.
+    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/flows/buffer.test.ts

@@ -0,0 +1,91 @@
+/**
+ * New-rows buffer — never move the ground (console §7.2).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createRowBuffer, matchesQuery } from "./buffer.ts";
+import {
+  confirmationFor,
+  createUndoStack,
+  validateTypedConfirm,
+} from "./confirmation.ts";
+
+describe("row buffer", () => {
+  test("new rows buffer behind a pill and never push existing ones", () => {
+    const buf = createRowBuffer([
+      { id: "a", value: 1, arrivedAt: 1 },
+      { id: "b", value: 2, arrivedAt: 2 },
+    ]);
+    buf.offer({ id: "c", value: 3, arrivedAt: 3 });
+    expect(buf.visible.map((r) => r.id)).toEqual(["a", "b"]);
+    expect(buf.pendingCount).toBe(1);
+
+    buf.flush();
+    expect(buf.visible.map((r) => r.id)).toEqual(["c", "a", "b"]);
+    expect(buf.pendingCount).toBe(0);
+  });
+
+  test("updates existing rows in place", () => {
+    const buf = createRowBuffer([{ id: "a", value: 1, arrivedAt: 1 }]);
+    buf.offer({ id: "a", value: 9, arrivedAt: 2 });
+    expect(buf.visible[0]?.value).toBe(9);
+    expect(buf.pendingCount).toBe(0);
+  });
+});
+
+describe("dim never hide", () => {
+  test("matchesQuery is case-insensitive", () => {
+    expect(matchesQuery(["Bookings.Create"], "book")).toBe(true);
+    expect(matchesQuery(["payments"], "book")).toBe(false);
+  });
+});
+
+describe("confirmation pattern", () => {
+  test("reversible actions get undo; irreversible get typed confirm", () => {
+    expect(confirmationFor("writes").kind).toBe("undo");
+    expect(confirmationFor("external", { production: true }).kind).toBe(
+      "typed",
+    );
+    expect(confirmationFor("external", { production: false }).kind).toBe(
+      "undo",
+    );
+  });
+
+  test("typed confirm requires phrase and reason", () => {
+    expect(
+      validateTypedConfirm({
+        typed: "INVOKE",
+        reason: "incident replay",
+        phrase: "INVOKE",
+      }),
+    ).toBeNull();
+    expect(
+      validateTypedConfirm({
+        typed: "yes",
+        reason: "x",
+        phrase: "INVOKE",
+      }),
+    ).toEqual({
+      typed: "Type INVOKE to confirm",
+      reason: "Reason is required (min 3 characters)",
+    });
+  });
+
+  test("undo stack expires", async () => {
+    let t = 0;
+    const stack = createUndoStack(() => t);
+    let undone = false;
+    stack.push({
+      id: "1",
+      label: "ping",
+      payload: null,
+      windowMs: 15_000,
+      undo: () => {
+        undone = true;
+      },
+    });
+    t = 16_000;
+    expect(await stack.undo("1")).toBe(false);
+    expect(undone).toBe(false);
+  });
+});

package/src/console/ui/flows/buffer.ts

@@ -0,0 +1,118 @@
+/**
+ * New-rows buffer — never move the ground (console §7.2 law 1).
+ *
+ * Incoming rows accumulate behind a "N new" pill and never push existing ones.
+ * Flushing prepends them in a single transition the operator controls.
+ */
+
+/** Buffered row with stable identity. */
+export interface BufferedRow<T> {
+  /** Stable id. */
+  readonly id: string;
+  /** Payload. */
+  readonly value: T;
+  /** Arrival timestamp (ms). */
+  readonly arrivedAt: number;
+}
+
+/** Mutable new-rows buffer. */
+export interface RowBuffer<T> {
+  /** Rows currently visible (stable order). */
+  readonly visible: readonly BufferedRow<T>[];
+  /** Rows waiting behind the pill. */
+  readonly pending: readonly BufferedRow<T>[];
+  /** Count shown on the pill. */
+  readonly pendingCount: number;
+  /**
+   * Offer a new row. If it already exists in visible/pending, update in place.
+   * Otherwise buffer it (does not push visible rows).
+   *
+   * @param row - Incoming row
+   */
+  offer(row: BufferedRow<T>): void;
+  /**
+   * Update an existing visible row in place (no reflow of siblings).
+   *
+   * @param id - Row id
+   * @param value - New value
+   */
+  updateInPlace(id: string, value: T): boolean;
+  /** Flush pending rows to the front of the visible list. */
+  flush(): void;
+  /** Discard pending without applying. */
+  discardPending(): void;
+}
+
+/**
+ * Create a new-rows buffer.
+ *
+ * @param initial - Initial visible rows
+ */
+export function createRowBuffer<T>(
+  initial: readonly BufferedRow<T>[] = [],
+): RowBuffer<T> {
+  const visible: BufferedRow<T>[] = [...initial];
+  const pending: BufferedRow<T>[] = [];
+
+  const findVisible = (id: string): number =>
+    visible.findIndex((r) => r.id === id);
+  const findPending = (id: string): number =>
+    pending.findIndex((r) => r.id === id);
+
+  return {
+    get visible() {
+      return visible;
+    },
+    get pending() {
+      return pending;
+    },
+    get pendingCount() {
+      return pending.length;
+    },
+    offer(row: BufferedRow<T>): void {
+      const vi = findVisible(row.id);
+      if (vi >= 0) {
+        visible[vi] = row;
+        return;
+      }
+      const pi = findPending(row.id);
+      if (pi >= 0) {
+        pending[pi] = row;
+        return;
+      }
+      pending.push(row);
+    },
+    updateInPlace(id: string, value: T): boolean {
+      const vi = findVisible(id);
+      if (vi < 0) return false;
+      const prev = visible[vi];
+      if (!prev) return false;
+      visible[vi] = { ...prev, value };
+      return true;
+    },
+    flush(): void {
+      if (pending.length === 0) return;
+      const batch = pending.splice(0, pending.length);
+      visible.unshift(...batch);
+    },
+    discardPending(): void {
+      pending.length = 0;
+    },
+  };
+}
+
+/**
+ * Dim-never-hide match: returns whether a row matches the query.
+ * Callers keep non-matches in the DOM at reduced opacity.
+ *
+ * @param haystack - Fields to search
+ * @param query - Free-text query
+ */
+export function matchesQuery(
+  haystack: readonly string[],
+  query: string | undefined,
+): boolean {
+  const q = query?.trim().toLowerCase();
+  if (!q) return true;
+  return haystack.some((h) => h.toLowerCase().includes(q));
+}

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

@@ -0,0 +1,131 @@
+/**
+ * Reversibility-governed confirmation (console §10.5).
+ *
+ * - Reversible → execute immediately, 15-second undo, no dialogue.
+ * - Irreversible → typed confirmation + recorded reason. No undo.
+ */
+
+import type { UiEffectTier } from "./tiers.ts";
+
+/** Undo window for reversible actions. */
+export const UNDO_WINDOW_MS = 15_000;
+
+/** Confirmation strategy derived from effect tier. */
+export type ConfirmationPattern =
+  | { readonly kind: "undo"; readonly windowMs: number }
+  | {
+      readonly kind: "typed";
+      readonly phrase: string;
+      readonly requireReason: true;
+    };
+
+/**
+ * Derive the confirmation pattern from a flow's peak effect tier and
+ * environment. External effects in production require typed confirmation.
+ *
+ * @param peakTier - Peak effect tier
+ * @param options - Environment
+ */
+export function confirmationFor(
+  peakTier: UiEffectTier | "none",
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  if (peakTier === "external" && options.production) {
+    return {
+      kind: "typed",
+      phrase: "INVOKE",
+      requireReason: true,
+    };
+  }
+  return { kind: "undo", windowMs: UNDO_WINDOW_MS };
+}
+
+/** Result of validating a typed confirmation. */
+export interface TypedConfirmInput {
+  readonly typed: string;
+  readonly reason: string;
+  readonly phrase: string;
+}
+
+/** Validation errors for typed confirm. */
+export interface TypedConfirmErrors {
+  readonly typed?: string;
+  readonly reason?: string;
+}
+
+/**
+ * Validate typed confirmation + reason for an irreversible action.
+ *
+ * @param input - Operator input
+ */
+export function validateTypedConfirm(
+  input: TypedConfirmInput,
+): TypedConfirmErrors | null {
+  const errors: {
+    typed?: string;
+    reason?: string;
+  } = {};
+  if (input.typed.trim() !== input.phrase) {
+    errors.typed = `Type ${input.phrase} to confirm`;
+  }
+  if (input.reason.trim().length < 3) {
+    errors.reason = "Reason is required (min 3 characters)";
+  }
+  return Object.keys(errors).length > 0 ? errors : null;
+}
+
+/** Pending undo entry. */
+export interface UndoEntry<T = unknown> {
+  readonly id: string;
+  readonly label: string;
+  readonly payload: T;
+  readonly expiresAt: number;
+  readonly undo: () => void | Promise<void>;
+}
+
+/**
+ * Create an undo stack that expires entries after {@link UNDO_WINDOW_MS}.
+ */
+export function createUndoStack(now: () => number = () => Date.now()): {
+  readonly entries: readonly UndoEntry[];
+  push(entry: Omit<UndoEntry, "expiresAt"> & { readonly windowMs?: number }): void;
+  undo(id: string): Promise<boolean>;
+  prune(): void;
+} {
+  const entries: UndoEntry[] = [];
+  return {
+    get entries() {
+      return entries;
+    },
+    push(entry): void {
+      const windowMs = entry.windowMs ?? UNDO_WINDOW_MS;
+      entries.push({
+        id: entry.id,
+        label: entry.label,
+        payload: entry.payload,
+        undo: entry.undo,
+        expiresAt: now() + windowMs,
+      });
+    },
+    async undo(id: string): Promise<boolean> {
+      const i = entries.findIndex((e) => e.id === id);
+      if (i < 0) return false;
+      const entry = entries[i];
+      if (!entry) return false;
+      if (now() > entry.expiresAt) {
+        entries.splice(i, 1);
+        return false;
+      }
+      entries.splice(i, 1);
+      await entry.undo();
+      return true;
+    },
+    prune(): void {
+      const t = now();
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (e && e.expiresAt <= t) entries.splice(i, 1);
+      }
+    },
+  };
+}

package/src/console/ui/flows/contract.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Dual contract editor — local validation before send (console §9.2).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  diffAgainstSchema,
+  fieldsFromSchema,
+  parseJsonEditor,
+  seedFromSchema,
+  setAtPath,
+  validateContract,
+  valueToJsonText,
+} from "./contract.ts";
+import { FLOWS_TEST_MANIFEST } from "./fixture.ts";
+
+const schema = FLOWS_TEST_MANIFEST.flows!["bookings.create"]!
+  .in as Record<string, unknown>;
+
+describe("contract editor", () => {
+  test("validates locally before sending", () => {
+    const bad = validateContract(schema, { flightId: "SK1" });
+    expect(bad.ok).toBe(false);
+    expect(bad.errors.some((e) => e.path.includes("seats") || e.message.includes("required"))).toBe(
+      true,
+    );
+
+    const good = validateContract(schema, {
+      flightId: "SK1",
+      seats: 2,
+      cabin: "economy",
+    });
+    expect(good.ok).toBe(true);
+    expect(good.errors).toEqual([]);
+  });
+
+  test("rejects out-of-range seats without a network round trip", () => {
+    const result = validateContract(schema, {
+      flightId: "SK1",
+      seats: 0,
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  test("seeds a plausible example from constraints", () => {
+    const seed = seedFromSchema(schema) as Record<string, unknown>;
+    expect(typeof seed.flightId).toBe("string");
+    expect(seed.seats).toBe(1);
+    expect(seed.cabin).toBe("economy");
+    expect(validateContract(schema, seed).ok).toBe(true);
+  });
+
+  test("form fields map enum / min / nested", () => {
+    const fields = fieldsFromSchema(schema);
+    const seats = fields.find((f) => f.name === "seats");
+    const cabin = fields.find((f) => f.name === "cabin");
+    expect(seats?.type).toBe("integer");
+    expect(seats?.minimum).toBe(1);
+    expect(cabin?.type).toBe("enum");
+    expect(cabin?.enumValues).toEqual(["economy", "business"]);
+  });
+
+  test("form ⇄ JSON sync round-trips", () => {
+    const value = { flightId: "SK1", seats: 2 };
+    const text = valueToJsonText(value);
+    const parsed = parseJsonEditor(text);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.value).toEqual(value);
+
+    const next = setAtPath(value, "/seats", 3) as { seats: number };
+    expect(next.seats).toBe(3);
+  });
+
+  test("response schema diff surfaces missing / extra fields", () => {
+    const out = FLOWS_TEST_MANIFEST.flows!["bookings.create"]!
+      .out as Record<string, unknown>;
+    expect(diffAgainstSchema(out, { id: "b1" })).toEqual({
+      missing: [],
+      extra: [],
+    });
+    expect(diffAgainstSchema(out, {})).toEqual({
+      missing: ["id"],
+      extra: [],
+    });
+    expect(diffAgainstSchema(out, { id: "b1", surprise: true }).extra).toContain(
+      "surprise",
+    );
+  });
+});