okengine 0.1.4

package/src/console/ui/shell/styles.css

@@ -0,0 +1,75 @@
+@import "tailwindcss";
+
+:root {
+  --oke-bg: #0e1116;
+  --oke-fg: #e8eaed;
+  --oke-muted: #9aa3b2;
+  --oke-line: color-mix(in oklab, var(--oke-fg) 12%, transparent);
+  --oke-accent: #3d9a6a;
+  /* Effect-tier accent — irreversible / external only (console §9.1). */
+  --oke-external: #d97706;
+  --oke-danger: #c44b4b;
+  --oke-font: "IBM Plex Sans", "Segoe UI", sans-serif;
+  --oke-mono: "IBM Plex Mono", ui-monospace, monospace;
+  --oke-dim: 0.38;
+}
+
+@font-face {
+  font-family: "IBM Plex Sans";
+  font-style: normal;
+  font-weight: 400 600;
+  font-display: swap;
+  src: local("IBM Plex Sans");
+}
+
+html,
+body,
+#root {
+  height: 100%;
+}
+
+body {
+  margin: 0;
+  font-family: var(--oke-font);
+  background:
+    radial-gradient(1200px 600px at 10% -10%, #1a2433 0%, transparent 55%),
+    radial-gradient(900px 500px at 100% 0%, #13201a 0%, transparent 50%),
+    var(--oke-bg);
+  color: var(--oke-fg);
+  font-variant-numeric: tabular-nums;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+:focus-visible {
+  outline: 2px solid var(--oke-accent);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation: none !important;
+    transition: none !important;
+  }
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}

package/src/console/ui/signals/SignalsA11yView.tsx

@@ -0,0 +1,276 @@
+/**
+ * Static Signals markup for the axe gate — same landmarks / roles as the
+ * live panel, fed by a fixture (no router / network).
+ */
+
+import { durableLine } from "./durable.ts";
+import { SIGNALS_FIXTURE } from "./fixture.ts";
+import { groupByPhysics } from "./group.ts";
+import {
+  fieldsFromSchema,
+  payloadToFormValues,
+} from "./schema-form.ts";
+
+/** Props for {@link SignalsA11yView}. */
+export interface SignalsA11yViewProps {
+  /** Optional signal name to open in detail. */
+  readonly openSignal?: string;
+  /** Optional dead-letter id to open. */
+  readonly openDlq?: string;
+}
+
+/**
+ * Accessible Signals list + detail for CI.
+ *
+ * @param props - Optional open signal / DLQ
+ */
+export function SignalsA11yView(props: SignalsA11yViewProps) {
+  const groups = groupByPhysics(SIGNALS_FIXTURE);
+  const openName = props.openSignal ?? "order-placed";
+  const open = SIGNALS_FIXTURE.find((s) => s.name === openName);
+  const line = open ? durableLine(open.consumersDurable) : null;
+  const dlqId = props.openDlq ?? "dlq-1";
+  const dlq = open?.deadLetters.find((d) => d.id === dlqId);
+  const fields = open ? fieldsFromSchema(open.schema) : [];
+  const formValues = dlq ? payloadToFormValues(dlq.payload, fields) : {};
+
+  return (
+    <div className="signals-a11y">
+      <a href="#signals-main">Skip to main content</a>
+      <header>
+        <h1>Signals</h1>
+        <p>One list, grouped by delivery physics</p>
+        <label>
+          Filter signals
+          <input aria-label="Filter signals" defaultValue="" />
+        </label>
+      </header>
+      <main id="signals-main">
+        <section aria-label="Signal list">
+          <h2>Signals</h2>
+          {groups.map((group) => (
+            <section
+              key={group.delivery}
+              aria-label={group.label}
+            >
+              <h3>{group.label}</h3>
+              <ul>
+                {group.signals.map((s) => (
+                  <li key={s.name}>
+                    <button
+                      type="button"
+                      aria-pressed={s.name === openName}
+                      style={{ minHeight: 32, width: "100%" }}
+                    >
+                      <span>{s.name}</span>
+                      {s.orphaned ? (
+                        <span role="status"> orphaned</span>
+                      ) : null}
+                      {s.dead > 0 ? (
+                        <span role="status"> DLQ {s.dead}</span>
+                      ) : null}
+                      {s.outboxLagMs !== null && s.outboxLagMs > 0 ? (
+                        <span> outbox {s.outboxLagMs}ms</span>
+                      ) : null}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </section>
+
+        {open && line ? (
+          <section aria-label="Signal detail" aria-live="polite">
+            <h2>{open.name}</h2>
+            <p role="status" data-durable={String(line.durable)}>
+              {line.statement}
+            </p>
+
+            {open.delivery === "once" ? (
+              <dl>
+                <dt>Pending</dt>
+                <dd>{open.pending}</dd>
+                <dt>In-flight</dt>
+                <dd>{open.inflight}</dd>
+                <dt>DLQ</dt>
+                <dd>{open.dead}</dd>
+                <dt>Retry policy</dt>
+                <dd>{open.retries} retries</dd>
+              </dl>
+            ) : null}
+
+            {open.delivery === "broadcast" ? (
+              <table>
+                <caption>Subscribers</caption>
+                <thead>
+                  <tr>
+                    <th scope="col">Subscriber</th>
+                    <th scope="col">Lag</th>
+                    <th scope="col">Errors</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {open.subscribers.map((sub) => (
+                    <tr key={sub.id}>
+                      <td>{sub.id}</td>
+                      <td>{sub.lag}</td>
+                      <td>{sub.errorCount}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            ) : null}
+
+            {open.delivery === "live" ? (
+              <section aria-label="Payload monitor">
+                <h3>Payload monitor</h3>
+                <p>
+                  {open.connections} connections · {open.throughputPerSec}/s
+                </p>
+                <button type="button" style={{ minHeight: 32 }}>
+                  Pause
+                </button>
+                <button type="button" style={{ minHeight: 32 }}>
+                  Export
+                </button>
+                <ul>
+                  {open.recentLive.map((p, i) => (
+                    <li key={i}>
+                      <code>{JSON.stringify(p)}</code>
+                    </li>
+                  ))}
+                </ul>
+              </section>
+            ) : null}
+
+            <section aria-label="Producers and consumers">
+              <h3>Causality</h3>
+              <ul>
+                {open.producers.map((p) => (
+                  <li key={`p-${p.flowId}`}>
+                    <a href={`/flows?sel=flow&flow=${encodeURIComponent(p.flowId)}`}>
+                      Producer {p.flowId}
+                    </a>
+                  </li>
+                ))}
+                {open.consumers.map((c) => (
+                  <li key={`c-${c.flowId}`}>
+                    <a href={`/flows?sel=flow&flow=${encodeURIComponent(c.flowId)}`}>
+                      Consumer {c.flowId}
+                      {c.durable ? " (durable)" : ""}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </section>
+
+            {open.dead > 0 ? (
+              <section aria-label="Dead letters">
+                <h3>Dead letters</h3>
+                <p>
+                  Bulk repair: dry run first, then replay at a controlled rate.
+                </p>
+                <label>
+                  Replay rate (per second)
+                  <input
+                    aria-label="Replay rate (per second)"
+                    type="number"
+                    defaultValue={10}
+                    min={1}
+                    max={1000}
+                  />
+                </label>
+                <button type="button" style={{ minHeight: 32 }}>
+                  Dry run
+                </button>
+                <button type="button" style={{ minHeight: 32 }}>
+                  Replay
+                </button>
+                <ul>
+                  {open.deadLetters.map((d) => (
+                    <li key={d.id}>
+                      <button
+                        type="button"
+                        aria-pressed={d.id === dlqId}
+                        style={{ minHeight: 32 }}
+                      >
+                        {d.id} · {d.failures[d.failures.length - 1]?.code}
+                      </button>
+                    </li>
+                  ))}
+                </ul>
+              </section>
+            ) : null}
+
+            {dlq ? (
+              <section aria-label="Dead-letter detail">
+                <h3>Dead letter {dlq.id}</h3>
+                <p role="status">{line.statement}</p>
+                <form aria-label="Editable payload">
+                  {fields.length > 0 ? (
+                    fields.map((f) => (
+                      <label key={f.key}>
+                        {f.key}
+                        {f.enumValues ? (
+                          <select
+                            aria-label={f.key}
+                            defaultValue={formValues[f.key] ?? ""}
+                          >
+                            {f.enumValues.map((v) => (
+                              <option key={v} value={v}>
+                                {v}
+                              </option>
+                            ))}
+                          </select>
+                        ) : (
+                          <input
+                            aria-label={f.key}
+                            defaultValue={formValues[f.key] ?? ""}
+                          />
+                        )}
+                      </label>
+                    ))
+                  ) : (
+                    <label>
+                      Payload JSON
+                      <textarea
+                        aria-label="Payload JSON"
+                        defaultValue={formValues._raw ?? ""}
+                        rows={4}
+                      />
+                    </label>
+                  )}
+                </form>
+                <h4>Attempt history</h4>
+                <ol>
+                  {dlq.failures.map((f) => (
+                    <li key={`${f.attempt}-${f.code}`}>
+                      Attempt {f.attempt}: {f.code} — {f.message}
+                    </li>
+                  ))}
+                </ol>
+                {dlq.causeRunId ? (
+                  <p>
+                    Causal chain:{" "}
+                    <a
+                      href={`/traces?trace=${encodeURIComponent(dlq.causeRunId)}`}
+                    >
+                      {dlq.causeFlow ?? dlq.causeRunId}
+                    </a>
+                  </p>
+                ) : null}
+                <button type="button" style={{ minHeight: 32 }}>
+                  Replay this message
+                </button>
+                <button type="button" style={{ minHeight: 32 }}>
+                  Discard
+                </button>
+              </section>
+            ) : null}
+          </section>
+        ) : null}
+      </main>
+    </div>
+  );
+}

package/src/console/ui/signals/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 { SignalsA11yView } from "./SignalsA11yView.tsx";
+
+describe("Signals 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/signals" });
+    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(
+        <SignalsA11yView openSignal="order-placed" openDlq="dlq-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/signals/confirmation.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import {
+  discardConfirmation,
+  replayConfirmation,
+  validateTypedConfirm,
+} from "./confirmation.ts";
+import { SIGNALS_FIXTURE } from "./fixture.ts";
+
+describe("signal confirmation", () => {
+  test("external non-durable consumer requires typed REPLAY in production", () => {
+    const order = SIGNALS_FIXTURE.find((s) => s.name === "order-placed")!;
+    const c = replayConfirmation(order, { production: true });
+    expect(c.kind).toBe("typed");
+    if (c.kind === "typed") expect(c.phrase).toBe("REPLAY");
+  });
+
+  test("durable broadcast consumers get undo window", () => {
+    const inv = SIGNALS_FIXTURE.find((s) => s.name === "inventory-changed")!;
+    const c = replayConfirmation(inv, { production: true });
+    expect(c.kind).toBe("undo");
+  });
+
+  test("discard requires typed confirmation in production", () => {
+    const order = SIGNALS_FIXTURE.find((s) => s.name === "order-placed")!;
+    const c = discardConfirmation(order, { production: true });
+    expect(c.kind).toBe("typed");
+    if (c.kind === "typed") expect(c.phrase).toBe("DISCARD");
+  });
+
+  test("validateTypedConfirm rejects short reason", () => {
+    expect(
+      validateTypedConfirm({
+        typed: "REPLAY",
+        reason: "no",
+        phrase: "REPLAY",
+      }),
+    ).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,63 @@
+/**
+ * Reversibility-governed confirmation for signal replay / discard (console §10.5).
+ *
+ * - Reversible (durable consumer, no external) → undo window.
+ * - Replay that re-triggers an external effect → typed confirmation + reason.
+ */
+
+import {
+  UNDO_WINDOW_MS,
+  type ConfirmationPattern,
+} from "../flows/confirmation.ts";
+import type { SignalRecord } from "./types.ts";
+
+export { UNDO_WINDOW_MS, validateTypedConfirm } from "../flows/confirmation.ts";
+export type { ConfirmationPattern } from "../flows/confirmation.ts";
+
+/**
+ * Confirmation for replaying dead letters of a signal.
+ *
+ * @param signal - Signal row
+ * @param options - Environment
+ */
+export function replayConfirmation(
+  signal: SignalRecord,
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  const retriggersExternal =
+    options.production &&
+    signal.consumers.some((c) => c.external) &&
+    signal.consumersDurable !== true;
+  if (retriggersExternal) {
+    return {
+      kind: "typed",
+      phrase: "REPLAY",
+      requireReason: true,
+    };
+  }
+  return { kind: "undo", windowMs: UNDO_WINDOW_MS };
+}
+
+/**
+ * Confirmation for discarding dead letters.
+ *
+ * @param signal - Signal row
+ * @param options - Environment
+ */
+export function discardConfirmation(
+  signal: SignalRecord,
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  const irreversible =
+    options.production &&
+    (signal.consumers.some((c) => c.external || !c.durable) ||
+      signal.dead > 0);
+  if (irreversible) {
+    return {
+      kind: "typed",
+      phrase: "DISCARD",
+      requireReason: true,
+    };
+  }
+  return { kind: "undo", windowMs: UNDO_WINDOW_MS };
+}

package/src/console/ui/signals/dry-run.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { dryRunOffer } from "./dry-run.ts";
+import { SIGNALS_FIXTURE } from "./fixture.ts";
+
+describe("dryRunOffer", () => {
+  test("offers dry-run when Manifest consumers are known", () => {
+    const order = SIGNALS_FIXTURE.find((s) => s.name === "order-placed")!;
+    expect(dryRunOffer(order)).toEqual({ ok: true });
+  });
+
+  test("refuses dry-run for orphaned signals", () => {
+    const orphan = SIGNALS_FIXTURE.find((s) => s.name === "legacy-shipped")!;
+    const offer = dryRunOffer(orphan);
+    expect(offer.ok).toBe(false);
+    if (offer.ok) return;
+    expect(offer.reason).toContain("Orphaned");
+  });
+});

package/src/console/ui/signals/dry-run.ts

@@ -0,0 +1,36 @@
+/**
+ * Dry-run safety for Signals — mirrors Traces' reversibility model (console §9.4 · §9.3).
+ *
+ * Dry run is safe by definition: send/ask are stubbed through `fx` ALS;
+ * unknown consumer shapes are refused rather than silently risked.
+ */
+
+import type { SignalRecord } from "./types.ts";
+
+/** Whether the panel may offer dry-run for this signal. */
+export type DryRunOffer =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * Decide whether dry-run is offered — same refusal spirit as Traces.
+ *
+ * @param signal - Projected signal row
+ */
+export function dryRunOffer(signal: SignalRecord): DryRunOffer {
+  if (signal.orphaned) {
+    return {
+      ok: false,
+      reason:
+        "Orphaned signal — consumer shape unknown; dry-run refused rather than risk a side effect.",
+    };
+  }
+  if (signal.consumers.length === 0) {
+    return {
+      ok: false,
+      reason:
+        "No Manifest consumer — dry-run refused rather than invoke an unknown handler unsafely.",
+    };
+  }
+  return { ok: true };
+}

package/src/console/ui/signals/durable.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { durableLine } from "./durable.ts";
+
+describe("durableLine", () => {
+  test("durable consumer — resume at failed journal step", () => {
+    const line = durableLine(true);
+    expect(line.durable).toBe(true);
+    expect(line.statement).toContain("resumes at the failed journal step");
+    expect(line.statement).toContain("will not repeat");
+  });
+
+  test("non-durable — everything re-runs from the start", () => {
+    const line = durableLine(false);
+    expect(line.durable).toBe(false);
+    expect(line.statement).toContain("re-runs from the start");
+    expect(line.statement).toContain("durable: true");
+  });
+
+  test("no consumers", () => {
+    expect(durableLine(null).statement).toContain("No consumer");
+  });
+});

package/src/console/ui/signals/durable.ts

@@ -0,0 +1,41 @@
+/**
+ * The single most important line in the Signals panel (console §9.4).
+ *
+ * Read from Manifest `flow.durable` on consumers — never guess.
+ */
+
+/** Durability statement shown at the point of replay decision. */
+export interface DurableLine {
+  /** Whether consumers are durable (`null` = no consumers). */
+  readonly durable: boolean | null;
+  /** Plain-language statement for the operator. */
+  readonly statement: string;
+}
+
+/**
+ * Build the durability statement for a signal's consumers.
+ *
+ * @param consumersDurable - From Manifest (`flow.durable` on every consumer)
+ */
+export function durableLine(
+  consumersDurable: boolean | null,
+): DurableLine {
+  if (consumersDurable === true) {
+    return {
+      durable: true,
+      statement:
+        "Consumer is durable — replay resumes at the failed journal step and side effects will not repeat.",
+    };
+  }
+  if (consumersDurable === false) {
+    return {
+      durable: false,
+      statement:
+        "Consumer is not durable — everything re-runs from the start, including side effects. Declare durable: true on the consumer so replay resumes at the failed journal step.",
+    };
+  }
+  return {
+    durable: null,
+    statement: "No consumer declared — replay has no target flow.",
+  };
+}