okengine 0.1.4

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

@@ -0,0 +1,102 @@
+/**
+ * Typed search params for the Signals panel (console §7 · §9.4).
+ */
+
+import { z } from "zod";
+
+/** Zod schema for Signals URL search params. */
+export const SignalsSearchSchema = z.object({
+  /** Free-text filter. */
+  q: z.string().optional(),
+  /** Open signal name. */
+  signal: z.string().optional(),
+  /** Open dead-letter id. */
+  dlq: z.string().optional(),
+  /** Live monitor paused. */
+  paused: z
+    .union([z.boolean(), z.literal("true"), z.literal("false")])
+    .optional()
+    .transform((v) =>
+      v === undefined ? undefined : v === true || v === "true",
+    ),
+  /** Bulk repair rate (messages/sec). */
+  rate: z.coerce.number().min(1).max(1_000).optional(),
+  /** Broadcast subscriber target for replay. */
+  sub: z.string().optional(),
+});
+
+/** Parsed Signals search state. */
+export type SignalsSearch = z.infer<typeof SignalsSearchSchema>;
+
+/**
+ * Parse URL search into Signals state.
+ *
+ * @param search - Raw router search
+ */
+export function parseSignalsSearch(
+  search: Record<string, unknown>,
+): SignalsSearch {
+  const parsed = SignalsSearchSchema.safeParse(search);
+  return parsed.success ? parsed.data : {};
+}
+
+/**
+ * Serialize Signals search for the router (omit defaults).
+ *
+ * @param search - Current state
+ */
+export function serializeSignalsSearch(
+  search: SignalsSearch,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (search.q) out.q = search.q;
+  if (search.signal) out.signal = search.signal;
+  if (search.dlq) out.dlq = search.dlq;
+  if (search.paused === true) out.paused = true;
+  if (search.rate !== undefined && search.rate !== 10) out.rate = search.rate;
+  if (search.sub) out.sub = search.sub;
+  return out;
+}
+
+/**
+ * Open a signal in the detail pane.
+ *
+ * @param search - Current
+ * @param name - Signal name
+ */
+export function openSignal(search: SignalsSearch, name: string): SignalsSearch {
+  return { ...search, signal: name, dlq: undefined };
+}
+
+/**
+ * Close the detail pane.
+ *
+ * @param search - Current
+ */
+export function closeSignal(search: SignalsSearch): SignalsSearch {
+  const { signal: _s, dlq: _d, ...rest } = search;
+  return rest;
+}
+
+/**
+ * Open a dead-letter detail.
+ *
+ * @param search - Current
+ * @param id - Message id
+ */
+export function openDeadLetter(
+  search: SignalsSearch,
+  id: string,
+): SignalsSearch {
+  return { ...search, dlq: id };
+}
+
+/**
+ * Close dead-letter detail (keep signal open).
+ *
+ * @param search - Current
+ */
+export function closeDeadLetter(search: SignalsSearch): SignalsSearch {
+  const { dlq: _d, ...rest } = search;
+  return rest;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Signals panel types (console §9.4).
+ */
+
+/** Delivery physics — grouping key, not a separate panel. */
+export type SignalDelivery = "once" | "broadcast" | "live";
+
+/** Typed failure preserved per attempt. */
+export interface SignalFailure {
+  readonly code: string;
+  readonly message: string;
+  readonly at: number;
+  readonly attempt: number;
+}
+
+/** Dead-letter row with causal link. */
+export interface SignalDeadLetter {
+  readonly id: string;
+  readonly signal: string;
+  readonly payload: unknown;
+  readonly delivery: SignalDelivery;
+  readonly attempts: number;
+  readonly failures: readonly SignalFailure[];
+  readonly createdAt: number;
+  readonly availableAt: number;
+  readonly status: "dead";
+  readonly causeRunId?: string;
+  readonly causeFlow?: string;
+}
+
+/** Producer or consumer endpoint. */
+export interface SignalEndpoint {
+  readonly flowId: string;
+  readonly durable: boolean;
+  readonly external: boolean;
+  readonly peakTier: string;
+}
+
+/** One signal in the operator list. */
+export interface SignalRecord {
+  readonly name: string;
+  readonly delivery: SignalDelivery;
+  readonly retries: number;
+  readonly deadLetterEnabled: boolean;
+  readonly orphaned: boolean;
+  readonly pending: number;
+  readonly inflight: number;
+  readonly dead: number;
+  readonly delivered: number;
+  readonly outboxLagMs: number | null;
+  readonly connections: number;
+  readonly throughputPerSec: number;
+  readonly schema?: unknown;
+  readonly subscribers: ReadonlyArray<{
+    readonly id: string;
+    readonly lag: number;
+    readonly errorCount: number;
+  }>;
+  readonly recentLive: readonly unknown[];
+  readonly deadLetters: readonly SignalDeadLetter[];
+  readonly producers: readonly SignalEndpoint[];
+  readonly consumers: readonly SignalEndpoint[];
+  readonly consumersDurable: boolean | null;
+}
+
+/** Grouped list section. */
+export interface SignalPhysicsGroup {
+  readonly delivery: SignalDelivery;
+  readonly label: string;
+  readonly signals: readonly SignalRecord[];
+}

package/src/console/ui/store/StoreA11yView.tsx

@@ -0,0 +1,199 @@
+/**
+ * Static Store markup for the axe gate — same landmarks as the live panel.
+ */
+
+import { explainCache } from "./cache-view.ts";
+import { STORE_LIST_FIXTURE } from "./fixture.ts";
+import { groupByFacet } from "./group.ts";
+import { formatWillNotFire } from "./will-not-fire.ts";
+
+/** Props for {@link StoreA11yView}. */
+export interface StoreA11yViewProps {
+  /** Optional store ref to open. */
+  readonly openRef?: string;
+  /** Optional child name. */
+  readonly openChild?: string;
+  /** Whether tenancy is declared (header selector). */
+  readonly tenancyDeclared?: boolean;
+}
+
+/**
+ * Accessible Store list + detail for CI.
+ *
+ * @param props - Open store / child
+ */
+export function StoreA11yView(props: StoreA11yViewProps) {
+  const tenancy =
+    props.tenancyDeclared ?? STORE_LIST_FIXTURE.tenancyDeclared;
+  const groups = groupByFacet(STORE_LIST_FIXTURE.stores);
+  const openRef = props.openRef ?? "sql:db";
+  const open = STORE_LIST_FIXTURE.stores.find((s) => s.ref === openRef);
+  const childName = props.openChild ?? "bookings";
+  const child = open?.children.find((c) => c.name === childName);
+  const willNot = child ? formatWillNotFire(child.willNotFire) : null;
+  const cache = child ? explainCache(child) : null;
+
+  return (
+    <div className="store-a11y">
+      <a href="#store-main">Skip to main content</a>
+      <header>
+        <h1>Store</h1>
+        <p>One list, grouped by facet</p>
+        {tenancy ? (
+          <label>
+            Tenant
+            <select aria-label="Tenant" defaultValue="tenant_a">
+              {STORE_LIST_FIXTURE.tenants.map((t) => (
+                <option key={t} value={t}>
+                  {t}
+                </option>
+              ))}
+            </select>
+          </label>
+        ) : null}
+        <label>
+          Filter stores
+          <input aria-label="Filter stores" defaultValue="" />
+        </label>
+      </header>
+      <main id="store-main">
+        <section aria-label="Store list">
+          <h2>Stores</h2>
+          {groups.map((group) => (
+            <section key={group.facet} aria-label={group.label}>
+              <h3>{group.label}</h3>
+              <ul>
+                {group.stores.map((s) => (
+                  <li key={s.ref}>
+                    <button
+                      type="button"
+                      aria-pressed={s.ref === openRef}
+                      style={{ minHeight: 32, width: "100%" }}
+                    >
+                      <span>{s.name}</span>
+                      {s.replicaLagMs != null && s.replicaLagMs > 0 ? (
+                        <span role="status"> lag {s.replicaLagMs}ms</span>
+                      ) : null}
+                      {s.migrationDrift?.drifted ? (
+                        <span role="status"> drift</span>
+                      ) : null}
+                      {s.warnings.length > 0 ? (
+                        <span role="status">
+                          {" "}
+                          {s.warnings.length} warning(s)
+                        </span>
+                      ) : null}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </section>
+
+        {open && child ? (
+          <section aria-label="Store detail" aria-live="polite">
+            <h2>
+              {open.name} / {child.name}
+            </h2>
+            <p role="status">
+              Writers: {child.writers.join(", ") || "none"} · Readers:{" "}
+              {child.readers.join(", ") || "none"}
+            </p>
+
+            {open.facet === "sql" ? (
+              <>
+                <h3>Table browser</h3>
+                <table>
+                  <thead>
+                    <tr>
+                      <th scope="col">id</th>
+                      <th scope="col">email</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    <tr>
+                      <td>b1</td>
+                      <td>[redacted]</td>
+                    </tr>
+                  </tbody>
+                </table>
+                <label>
+                  SQL (read-only)
+                  <textarea
+                    aria-label="SQL console"
+                    defaultValue='SELECT * FROM "bookings" LIMIT 50'
+                    rows={3}
+                  />
+                </label>
+              </>
+            ) : null}
+
+            {open.facet === "kv" ? (
+              <>
+                <h3>Key browser</h3>
+                <ul aria-label="Keys">
+                  <li>session:abc</li>
+                </ul>
+              </>
+            ) : null}
+
+            {open.facet === "files" ? (
+              <>
+                <h3>Bucket browser</h3>
+                <ul aria-label="Objects">
+                  {open.warnings.map((w) => (
+                    <li key={w.key}>
+                      {w.key}
+                      <span role="status"> {w.message}</span>
+                    </li>
+                  ))}
+                </ul>
+              </>
+            ) : null}
+
+            {open.facet === "index" ? (
+              <>
+                <h3>Similarity probe</h3>
+                <label>
+                  Vector
+                  <input aria-label="Probe vector" defaultValue="0.1,0.2,0.3" />
+                </label>
+              </>
+            ) : null}
+
+            {cache ? (
+              <section aria-label="Cache">
+                <h3>Cache</h3>
+                <p role="status">{cache.summary}</p>
+              </section>
+            ) : null}
+
+            {willNot && !willNot.empty ? (
+              <section aria-label="Edit confirmation">
+                <h3>Before saving a direct edit</h3>
+                <p>{willNot.headline}</p>
+                <ul>
+                  {willNot.lines.map((line) => (
+                    <li key={line}>{line}</li>
+                  ))}
+                </ul>
+                <label>
+                  Type EDIT
+                  <input aria-label="Confirmation phrase" />
+                </label>
+                <label>
+                  Reason
+                  <input aria-label="Confirmation reason" />
+                </label>
+                <button type="button" style={{ minHeight: 32 }}>
+                  Save edit
+                </button>
+              </section>
+            ) : null}
+          </section>
+        ) : null}
+      </main>
+    </div>
+  );
+}

package/src/console/ui/store/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 { StoreA11yView } from "./StoreA11yView.tsx";
+
+describe("Store 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/store" });
+    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(
+        <StoreA11yView openRef="sql:db" openChild="bookings" />,
+      );
+    });
+
+    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/store/cache-view.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "bun:test";
+import { explainCache } from "./cache-view.ts";
+import { STORE_FIXTURE } from "./fixture.ts";
+
+describe("explainCache", () => {
+  test("surfaces produced-by-read and invalidators", () => {
+    const child = STORE_FIXTURE[0]!.children[0]!;
+    const expl = explainCache(child);
+    expect(expl.producedByRead).toBe("computed:sql:bookings");
+    expect(expl.invalidatedBy).toContain("sql:bookings");
+    expect(expl.summary).toContain("computed:sql:bookings");
+  });
+});

package/src/console/ui/store/cache-view.ts

@@ -0,0 +1,36 @@
+/**
+ * Cache sub-view — surfaces effects-derived invalidation (console §9.5).
+ *
+ * Does not recompute invalidation rules; projects what Store already knows.
+ */
+
+import type { StoreCacheView, StoreChild } from "./types.ts";
+
+/** Operator-facing cache explanation. */
+export interface CacheExplanation {
+  readonly producedByRead: string;
+  readonly invalidatedBy: readonly string[];
+  readonly invalidatingFlows: readonly string[];
+  readonly summary: string;
+}
+
+/**
+ * Explain which read produced a key and which writes invalidate it.
+ *
+ * @param child - Child resource with cache projection
+ */
+export function explainCache(child: StoreChild): CacheExplanation {
+  const view: StoreCacheView = child.cache;
+  const invalidators = view.invalidatedByWrites;
+  const flows = view.invalidatingFlowIds;
+  const summary =
+    invalidators.length === 0
+      ? `Read key \`${view.producedByRead}\` — no write invalidators declared.`
+      : `Read key \`${view.producedByRead}\` — invalidated by writes to ${invalidators.map((r) => `\`${r}\``).join(", ")}.`;
+  return {
+    producedByRead: view.producedByRead,
+    invalidatedBy: invalidators,
+    invalidatingFlows: flows,
+    summary,
+  };
+}

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

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import {
+  deleteConfirmation,
+  editConfirmation,
+  purgeConfirmation,
+  validateTypedConfirm,
+} from "./confirmation.ts";
+
+describe("store confirmation", () => {
+  test("edit/delete/purge are typed in production", () => {
+    expect(editConfirmation({ production: true })).toEqual({
+      kind: "typed",
+      phrase: "EDIT",
+      requireReason: true,
+    });
+    expect(deleteConfirmation({ production: true }).kind).toBe("typed");
+    expect(purgeConfirmation({ production: true })).toMatchObject({
+      phrase: "PURGE",
+    });
+  });
+
+  test("non-production uses undo window", () => {
+    expect(editConfirmation({ production: false }).kind).toBe("undo");
+  });
+
+  test("validateTypedConfirm requires phrase + reason", () => {
+    expect(
+      validateTypedConfirm({
+        typed: "EDIT",
+        reason: "fix bad row",
+        phrase: "EDIT",
+      }),
+    ).toBeNull();
+    expect(
+      validateTypedConfirm({ typed: "x", reason: "ab", phrase: "EDIT" }),
+    ).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,55 @@
+/**
+ * Reversibility-governed confirmation for Store actions (console §10.5 · §9.5).
+ *
+ * Direct edit / delete / purge are irreversible in production — typed confirm.
+ */
+
+import {
+  UNDO_WINDOW_MS,
+  type ConfirmationPattern,
+} from "../flows/confirmation.ts";
+
+export { UNDO_WINDOW_MS, validateTypedConfirm } from "../flows/confirmation.ts";
+export type { ConfirmationPattern } from "../flows/confirmation.ts";
+
+/**
+ * Confirmation for a direct row/key edit (not a flow execution).
+ *
+ * @param options - Environment
+ */
+export function editConfirmation(
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  if (options.production) {
+    return { kind: "typed", phrase: "EDIT", requireReason: true };
+  }
+  return { kind: "undo", windowMs: UNDO_WINDOW_MS };
+}
+
+/**
+ * Confirmation for deleting rows/keys.
+ *
+ * @param options - Environment
+ */
+export function deleteConfirmation(
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  if (options.production) {
+    return { kind: "typed", phrase: "DELETE", requireReason: true };
+  }
+  return { kind: "undo", windowMs: UNDO_WINDOW_MS };
+}
+
+/**
+ * Confirmation for purging a cache namespace.
+ *
+ * @param options - Environment
+ */
+export function purgeConfirmation(
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  if (options.production) {
+    return { kind: "typed", phrase: "PURGE", requireReason: true };
+  }
+  return { kind: "undo", windowMs: UNDO_WINDOW_MS };
+}

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

@@ -0,0 +1,15 @@
+import { describe, expect, test } from "bun:test";
+import { previewOffer } from "./dry-run.ts";
+import { STORE_FIXTURE } from "./fixture.ts";
+
+describe("previewOffer", () => {
+  test("allows sql / kv / files", () => {
+    expect(previewOffer(STORE_FIXTURE[0]!).ok).toBe(true);
+    expect(previewOffer(STORE_FIXTURE[1]!).ok).toBe(true);
+  });
+
+  test("refuses index probe mutations", () => {
+    const offer = previewOffer(STORE_FIXTURE[3]!);
+    expect(offer.ok).toBe(false);
+  });
+});

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

@@ -0,0 +1,29 @@
+/**
+ * Preview / dry-run safety for Store mutations (console §9.5).
+ *
+ * Uses the same dual contract as Signals: irreversible effects stubbed,
+ * writes rolled back — refuse when isolation cannot be guaranteed.
+ */
+
+import type { StoreRecord } from "./types.ts";
+
+/** Whether the panel may offer a mutation preview. */
+export type PreviewOffer =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * Decide whether preview is offered for this store.
+ *
+ * @param store - Projected store row
+ */
+export function previewOffer(store: StoreRecord): PreviewOffer {
+  if (store.facet === "index") {
+    return {
+      ok: false,
+      reason:
+        "Index facet has no bulk-update preview — similarity probe is read-only.",
+    };
+  }
+  return { ok: true };
+}