okengine 0.1.4

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

@@ -0,0 +1,117 @@
+/**
+ * Channels panel view types (console §9.9).
+ */
+
+/** Panel face. */
+export type ChannelsFace = "inbox" | "deliverability";
+
+/** Seven-state taxonomy. */
+export type DeliveryOutcomeState =
+  | "suppressed/opted-out"
+  | "suppressed/prior-bounce"
+  | "blocked/invalid-address"
+  | "soft-bounce"
+  | "hard-bounce"
+  | "provider-error"
+  | "delivered-then-complained";
+
+/** Verdict beside each count. */
+export type DeliveryVerdict = "correct" | "retry" | "suppress" | "review";
+
+/** Outcome row from `console.channel.list`. */
+export interface OutcomeRow {
+  readonly state: DeliveryOutcomeState;
+  readonly count: number;
+  readonly verdict: DeliveryVerdict;
+  readonly weight: number;
+}
+
+/** Template row. */
+export interface ChannelTemplate {
+  readonly name: string;
+  readonly medium: string;
+  readonly locales: readonly string[];
+  readonly from: string | null;
+  readonly schema: unknown;
+}
+
+/** Fallback financial metric. */
+export interface FallbackMetric {
+  readonly template: string | null;
+  readonly chainExample: string;
+  readonly fallbackRate: number;
+  readonly fallbackCount: number;
+  readonly totalCount: number;
+  readonly weeklyDeltaUsd: number;
+  readonly primaryMedium: string;
+  readonly fallbackMedium: string;
+  readonly summary: string;
+}
+
+/** Inbox row (dev face). */
+export interface InboxRow {
+  readonly id: string;
+  readonly medium: string;
+  readonly toMasked: string;
+  readonly subject: string | null;
+  readonly text: string | null;
+  readonly html: string | null;
+  readonly template: string | null;
+  readonly locale: string | null;
+  readonly at: number;
+}
+
+/** Receipt row. */
+export interface ReceiptRow {
+  readonly id: string;
+  readonly template: string;
+  readonly toMasked: string;
+  readonly medium: string;
+  readonly locale: string | null;
+  readonly localeChain: readonly string[];
+  readonly status: string;
+  readonly chain: string;
+  readonly messageId: string | null;
+  readonly at: number;
+  readonly error: string | null;
+}
+
+/** Suppression row. */
+export interface SuppressionRow {
+  readonly subjectMasked: string;
+  readonly medium: string;
+  readonly reason: "opted-out" | "prior-bounce";
+  readonly at: number;
+}
+
+/** Full list response. */
+export interface ChannelsListResponse {
+  readonly face: ChannelsFace;
+  readonly production: boolean;
+  readonly templates: readonly ChannelTemplate[];
+  readonly outcomes: readonly OutcomeRow[];
+  readonly fallback: FallbackMetric;
+  readonly inbox: readonly InboxRow[];
+  readonly receipts: readonly ReceiptRow[];
+  readonly suppression: readonly SuppressionRow[];
+}
+
+/** Template preview. */
+export interface ChannelPreview {
+  readonly template: string;
+  readonly locale: string;
+  readonly localeChain: readonly string[];
+  readonly dir: "ltr" | "rtl";
+  readonly subject: string | null;
+  readonly text: string | null;
+  readonly html: string | null;
+}
+
+/** Email auth strip. */
+export interface EmailAuthView {
+  readonly domain: string;
+  readonly spf: "pass" | "fail" | "missing";
+  readonly dkim: "pass" | "fail" | "missing";
+  readonly dmarc: "pass" | "fail" | "missing";
+  readonly checkedAt: number;
+}

package/src/console/ui/clock/ClockA11yView.tsx

@@ -0,0 +1,182 @@
+/**
+ * Static Clock markup for the axe gate — same landmarks as the live panel.
+ */
+
+import { formatHealth } from "./health.ts";
+import { CLOCK_LIST_FIXTURE } from "./fixture.ts";
+import { formatTimelineWhen, forwardTimeline } from "./timeline.ts";
+import { formatWakeIn, waitingOnBanner } from "./waiting-on.ts";
+
+/** Props for {@link ClockA11yView}. */
+export interface ClockA11yViewProps {
+  /** Optional cron name to open. */
+  readonly openCron?: string;
+  /** Optional wake run id to open. */
+  readonly openWake?: string;
+}
+
+/**
+ * Accessible Clock timeline + waiting-on + cron detail for CI.
+ *
+ * @param props - Open cron / wake
+ */
+export function ClockA11yView(props: ClockA11yViewProps) {
+  const data = CLOCK_LIST_FIXTURE;
+  const timeline = forwardTimeline(data.timeline, data.now);
+  const openCronName = props.openCron ?? "nightly";
+  const openCron = data.crons.find((c) => c.name === openCronName);
+  const openWakeId = props.openWake ?? "run_sleep_1";
+  const openWake = data.waitingOn.find((w) => w.runId === openWakeId);
+  const health = openCron ? formatHealth(openCron.health) : null;
+  const banner = waitingOnBanner(
+    data.waitingOn.length,
+    data.waitingOnCounts,
+  );
+
+  return (
+    <div className="clock-a11y">
+      <a href="#clock-main">Skip to main content</a>
+      <header>
+        <h1>Clock</h1>
+        <p>Forward timeline, waiting-on, cron health</p>
+        <label>
+          Filter clock
+          <input aria-label="Filter clock" defaultValue="" />
+        </label>
+      </header>
+      <main id="clock-main">
+        <section aria-label="Forward timeline">
+          <h2>Next 24 hours</h2>
+          <ol>
+            {timeline.map((e) => (
+              <li key={`${e.kind}-${e.name}-${e.at}`}>
+                <span>{formatTimelineWhen(e.at, data.now)}</span>
+                <span>
+                  {" "}
+                  {e.kind === "cron" ? "cron" : "wake"} {e.name}
+                </span>
+                {e.meta ? <span> ({e.meta})</span> : null}
+              </li>
+            ))}
+          </ol>
+        </section>
+
+        <section aria-label="Waiting on">
+          <h2>Waiting on</h2>
+          <p role="status">{banner}</p>
+          <ul>
+            {data.waitingOn.map((w) => (
+              <li key={w.runId}>
+                <button
+                  type="button"
+                  aria-pressed={w.runId === openWakeId}
+                  style={{ minHeight: 32, width: "100%" }}
+                >
+                  <span>{w.label || w.flow}</span>
+                  <span> wake-in {formatWakeIn(w.wakeInMs)}</span>
+                  {w.step ? <span> step {w.step}</span> : null}
+                  <span>
+                    {" "}
+                    runs{" "}
+                    {
+                      data.waitingOnCounts.find(
+                        (c) => c.label === (w.label || "(unlabelled)"),
+                      )?.count ?? 1
+                    }
+                  </span>
+                </button>
+              </li>
+            ))}
+          </ul>
+        </section>
+
+        <section aria-label="Cron schedules">
+          <h2>Schedules</h2>
+          <ul>
+            {data.crons.map((c) => {
+              const h = formatHealth(c.health);
+              return (
+                <li key={c.name}>
+                  <button
+                    type="button"
+                    aria-pressed={c.name === openCronName}
+                    style={{ minHeight: 32, width: "100%" }}
+                  >
+                    <span>{c.name}</span>
+                    {c.health.overdue ? (
+                      <span role="status"> overdue</span>
+                    ) : null}
+                    {c.dstAmbiguity ? (
+                      <span role="status"> DST {c.dstAmbiguity.kind}</span>
+                    ) : null}
+                    {c.external ? (
+                      <span aria-label="external effect"> ↗</span>
+                    ) : null}
+                  </button>
+                  <p role="status">
+                    {h.drift} · {h.overdue} · {h.missedWithPolicy} · {h.lease}
+                  </p>
+                </li>
+              );
+            })}
+          </ul>
+        </section>
+
+        {openCron && health ? (
+          <section aria-label="Cron detail" aria-live="polite">
+            <h2>{openCron.name}</h2>
+            <p role="status">
+              {openCron.effectiveCron ?? openCron.effectiveEvery} ·{" "}
+              {openCron.timezone}
+            </p>
+            <dl>
+              <div>
+                <dt>Drift</dt>
+                <dd>{health.drift}</dd>
+              </div>
+              <div>
+                <dt>Overdue</dt>
+                <dd>{health.overdue}</dd>
+              </div>
+              <div>
+                <dt>Missed + catch-up</dt>
+                <dd>{health.missedWithPolicy}</dd>
+              </div>
+              <div>
+                <dt>Lease</dt>
+                <dd>{health.lease}</dd>
+              </div>
+            </dl>
+            {openCron.dstAmbiguity ? (
+              <p role="alert">{openCron.dstAmbiguity.reason}</p>
+            ) : null}
+            <div>
+              <button type="button">Run now</button>
+              <button type="button">Pause</button>
+              {openCron.overridable ? (
+                <button type="button">Edit schedule</button>
+              ) : null}
+            </div>
+            {openCron.external ? (
+              <label>
+                Type RUN to confirm
+                <input aria-label="Type RUN to confirm" defaultValue="" />
+              </label>
+            ) : null}
+          </section>
+        ) : null}
+
+        {openWake ? (
+          <section aria-label="Wake detail" aria-live="polite">
+            <h2>{openWake.label || openWake.flow}</h2>
+            <p role="status">
+              Wake in {formatWakeIn(openWake.wakeInMs)}
+              {openWake.step ? ` · step ${openWake.step}` : ""}
+            </p>
+            <button type="button">Wake early</button>
+          </section>
+        ) : null}
+      </main>
+    </div>
+  );
+}

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

@@ -0,0 +1,99 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · prompt 20).
+ */
+
+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 { ClockA11yView } from "./ClockA11yView.tsx";
+
+describe("Clock 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/clock" });
+    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(
+        <ClockA11yView openCron="nightly" openWake="run_sleep_1" />,
+      );
+    });
+
+    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/clock/confirmation.test.ts

@@ -0,0 +1,32 @@
+/**
+ * Run-now confirmation — external follows D.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { runNowConfirmation } from "./confirmation.ts";
+import { CLOCK_LIST_FIXTURE } from "./fixture.ts";
+
+describe("runNowConfirmation", () => {
+  test("typed RUN when external in production", () => {
+    const nightly = CLOCK_LIST_FIXTURE.crons.find((c) => c.name === "nightly")!;
+    expect(runNowConfirmation(nightly, { production: true })).toEqual({
+      kind: "typed",
+      phrase: "RUN",
+      requireReason: true,
+    });
+  });
+
+  test("undo when not external", () => {
+    const expire = CLOCK_LIST_FIXTURE.crons.find(
+      (c) => c.name === "expire-holds",
+    )!;
+    const conf = runNowConfirmation(expire, { production: true });
+    expect(conf.kind).toBe("undo");
+  });
+
+  test("undo when external but not production", () => {
+    const nightly = CLOCK_LIST_FIXTURE.crons.find((c) => c.name === "nightly")!;
+    const conf = runNowConfirmation(nightly, { production: false });
+    expect(conf.kind).toBe("undo");
+  });
+});

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

@@ -0,0 +1,34 @@
+/**
+ * Run-now confirmation — external effects follow §10.5 (D).
+ */
+
+import {
+  UNDO_WINDOW_MS,
+  type ConfirmationPattern,
+} from "../flows/confirmation.ts";
+import type { ClockCronRecord } from "./types.ts";
+
+export { UNDO_WINDOW_MS, validateTypedConfirm } from "../flows/confirmation.ts";
+export type { ConfirmationPattern } from "../flows/confirmation.ts";
+
+/**
+ * Confirmation for running a cron now.
+ *
+ * External effects in production → typed `"RUN"` + reason.
+ *
+ * @param cron - Cron row
+ * @param options - Environment
+ */
+export function runNowConfirmation(
+  cron: ClockCronRecord,
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  if (options.production && cron.external) {
+    return {
+      kind: "typed",
+      phrase: "RUN",
+      requireReason: true,
+    };
+  }
+  return { kind: "undo", windowMs: UNDO_WINDOW_MS };
+}

package/src/console/ui/clock/findings.ts

@@ -0,0 +1,40 @@
+/**
+ * Overdue cron findings for Overview aggregation (console §9.6 · §9.16).
+ *
+ * Detection is {@link CronHealth.overdue} from ClockRuntime physics —
+ * this only lists rows the health check already flagged.
+ */
+
+import type { ClockCronRecord } from "./types.ts";
+
+/** One overdue cron finding from the Clock panel. */
+export interface OverdueCronFinding {
+  readonly name: string;
+  readonly driftMs: number | null;
+  readonly missedRuns: number;
+  readonly nextRunAt?: number;
+  readonly flowIds: readonly string[];
+}
+
+/**
+ * Crons whose health already reports overdue.
+ *
+ * @param crons - Clock panel cron rows
+ */
+export function overdueCronFindings(
+  crons: readonly ClockCronRecord[],
+): readonly OverdueCronFinding[] {
+  return crons
+    .filter((c) => c.health.overdue)
+    .map((c) => ({
+      name: c.name,
+      driftMs: c.health.driftMs,
+      missedRuns: c.health.missedRuns,
+      ...(c.nextRunAt !== undefined ? { nextRunAt: c.nextRunAt } : {}),
+      flowIds: c.flowIds,
+    }))
+    .sort(
+      (a, b) =>
+        b.missedRuns - a.missedRuns || a.name.localeCompare(b.name),
+    );
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Clock panel fixture for unit + axe tests.
+ */
+
+import type { ClockListResponse } from "./types.ts";
+
+const NOW = 1_700_000_000_000;
+
+/** List response covering timeline, waiting-on, health, DST. */
+export const CLOCK_LIST_FIXTURE: ClockListResponse = {
+  now: NOW,
+  crons: [
+    {
+      name: "expire-holds",
+      status: "active",
+      timezone: "UTC",
+      overridable: true,
+      declaredEvery: "10m",
+      effectiveEvery: "10m",
+      lastRunAt: NOW - 30 * 60_000,
+      nextRunAt: NOW - 20 * 60_000,
+      health: {
+        driftMs: 1_200,
+        overdue: true,
+        missedRuns: 3,
+        catchUp: "one",
+        leaderInstanceId: "inst-a",
+        leaderLeaseUntil: NOW + 30_000,
+      },
+      dstAmbiguity: null,
+      external: false,
+      flowIds: ["holds.expire"],
+    },
+    {
+      name: "nightly",
+      status: "active",
+      timezone: "America/New_York",
+      overridable: false,
+      declaredCron: "0 2 * * *",
+      effectiveCron: "0 2 * * *",
+      lastRunAt: NOW - 86_400_000,
+      nextRunAt: NOW + 3_600_000,
+      health: {
+        driftMs: 0,
+        overdue: false,
+        missedRuns: 0,
+        catchUp: "one",
+        leaderInstanceId: "inst-b",
+        leaderLeaseUntil: NOW + 15_000,
+      },
+      dstAmbiguity: {
+        kind: "gap",
+        reason: "02:00 in America/New_York is skipped on 2024-03-10 (DST spring forward)",
+        on: "2024-03-10",
+        localTime: "02:00",
+      },
+      external: true,
+      flowIds: ["reports.nightly"],
+    },
+  ],
+  waitingOn: [
+    {
+      runId: "run_sleep_1",
+      flow: "payments.verify",
+      label: "verify-window",
+      wakeAt: NOW + 120_000,
+      wakeInMs: 120_000,
+      step: "create-intent",
+    },
+    {
+      runId: "run_sleep_2",
+      flow: "trials.start",
+      label: "trial-period",
+      wakeAt: NOW + 86_400_000,
+      wakeInMs: 86_400_000,
+      step: null,
+    },
+    {
+      runId: "run_sleep_3",
+      flow: "trials.start",
+      label: "trial-period",
+      wakeAt: NOW + 90_000_000,
+      wakeInMs: 90_000_000,
+      step: "enroll",
+    },
+  ],
+  waitingOnCounts: [
+    { label: "trial-period", count: 2 },
+    { label: "verify-window", count: 1 },
+  ],
+  timeline: [
+    {
+      at: NOW + 120_000,
+      kind: "wake",
+      name: "verify-window",
+      meta: "run_sleep_1",
+    },
+    {
+      at: NOW + 3_600_000,
+      kind: "cron",
+      name: "nightly",
+      meta: "0 2 * * *",
+    },
+    {
+      at: NOW + 86_400_000 - 1,
+      kind: "wake",
+      name: "trial-period",
+      meta: "run_sleep_2",
+    },
+  ],
+};

package/src/console/ui/clock/health.test.ts

@@ -0,0 +1,25 @@
+/**
+ * Health formatting.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { CLOCK_LIST_FIXTURE } from "./fixture.ts";
+import { filterCrons, formatHealth } from "./health.ts";
+
+describe("formatHealth", () => {
+  test("four numbers for overdue cron", () => {
+    const expire = CLOCK_LIST_FIXTURE.crons[0]!;
+    const h = formatHealth(expire.health);
+    expect(h.overdue).toBe("overdue");
+    expect(h.missedWithPolicy).toContain("catch-up one");
+    expect(h.lease).toContain("inst-a");
+    expect(h.drift).toContain("drift");
+  });
+});
+
+describe("filterCrons", () => {
+  test("matches name and schedule", () => {
+    expect(filterCrons(CLOCK_LIST_FIXTURE.crons, "nightly")).toHaveLength(1);
+    expect(filterCrons(CLOCK_LIST_FIXTURE.crons, "10m")).toHaveLength(1);
+  });
+});