okengine 0.1.4

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

@@ -0,0 +1,33 @@
+/**
+ * Dead-letter findings for Overview aggregation (console §9.4 · §9.16).
+ *
+ * Detection is the panel's `dead` / `deadLetters` projection — this only
+ * surfaces rows that already failed into the DLQ.
+ */
+
+import type { SignalRecord } from "./types.ts";
+
+/** One dead-letter finding from the Signals panel. */
+export interface DeadLetterFinding {
+  readonly signal: string;
+  readonly dead: number;
+  readonly delivery: SignalRecord["delivery"];
+}
+
+/**
+ * Signals with dead letters waiting in the DLQ.
+ *
+ * @param signals - Signals panel rows
+ */
+export function deadLetterFindings(
+  signals: readonly SignalRecord[],
+): readonly DeadLetterFinding[] {
+  return signals
+    .filter((s) => s.dead > 0)
+    .map((s) => ({
+      signal: s.name,
+      dead: s.dead,
+      delivery: s.delivery,
+    }))
+    .sort((a, b) => b.dead - a.dead || a.signal.localeCompare(b.signal));
+}

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

@@ -0,0 +1,242 @@
+/**
+ * Fixture signals for unit tests and the axe gate.
+ */
+
+import type { SignalRecord } from "./types.ts";
+
+/** Skyport-shaped Signals fixture covering once / broadcast / live + DLQ. */
+export const SIGNALS_FIXTURE: readonly SignalRecord[] = [
+  {
+    name: "order-placed",
+    delivery: "once",
+    retries: 5,
+    deadLetterEnabled: true,
+    orphaned: false,
+    pending: 12,
+    inflight: 2,
+    dead: 2,
+    delivered: 480,
+    outboxLagMs: 340,
+    connections: 0,
+    throughputPerSec: 4,
+    schema: {
+      type: "object",
+      required: ["orderId", "amount"],
+      properties: {
+        orderId: { type: "string" },
+        amount: { type: "number" },
+        currency: { type: "string", enum: ["USD", "EUR"] },
+      },
+    },
+    subscribers: [],
+    recentLive: [],
+    deadLetters: [
+      {
+        id: "dlq-1",
+        signal: "order-placed",
+        payload: { orderId: "ord_1", amount: 49.5, currency: "USD" },
+        delivery: "once",
+        attempts: 5,
+        failures: [
+          {
+            code: "PaymentDeclined",
+            message: "card declined",
+            at: 1_700_000_001_000,
+            attempt: 1,
+          },
+          {
+            code: "PaymentDeclined",
+            message: "card declined",
+            at: 1_700_000_002_000,
+            attempt: 2,
+          },
+          {
+            code: "PaymentDeclined",
+            message: "card declined",
+            at: 1_700_000_003_000,
+            attempt: 3,
+          },
+          {
+            code: "PaymentDeclined",
+            message: "card declined",
+            at: 1_700_000_004_000,
+            attempt: 4,
+          },
+          {
+            code: "GatewayTimeout",
+            message: "upstream timed out",
+            at: 1_700_000_005_000,
+            attempt: 5,
+          },
+        ],
+        createdAt: 1_700_000_000_000,
+        availableAt: 1_700_000_005_000,
+        status: "dead",
+        causeRunId: "run-create-ok",
+        causeFlow: "bookings.create",
+      },
+      {
+        id: "dlq-2",
+        signal: "order-placed",
+        payload: { orderId: "ord_2", amount: 12, currency: "EUR" },
+        delivery: "once",
+        attempts: 5,
+        failures: [
+          {
+            code: "GatewayTimeout",
+            message: "upstream timed out",
+            at: 1_700_000_010_000,
+            attempt: 5,
+          },
+        ],
+        createdAt: 1_700_000_009_000,
+        availableAt: 1_700_000_010_000,
+        status: "dead",
+        causeRunId: "run-create-fail",
+        causeFlow: "bookings.create",
+      },
+    ],
+    producers: [
+      {
+        flowId: "bookings.create",
+        durable: false,
+        external: false,
+        peakTier: "emits",
+      },
+    ],
+    consumers: [
+      {
+        flowId: "fulfillment.onOrder",
+        durable: false,
+        external: true,
+        peakTier: "external",
+      },
+      {
+        flowId: "payments.chargeBooking",
+        durable: true,
+        external: false,
+        peakTier: "capabilities",
+      },
+    ],
+    consumersDurable: false,
+  },
+  {
+    name: "inventory-changed",
+    delivery: "broadcast",
+    retries: 3,
+    deadLetterEnabled: true,
+    orphaned: false,
+    pending: 3,
+    inflight: 0,
+    dead: 0,
+    delivered: 90,
+    outboxLagMs: 12,
+    connections: 0,
+    throughputPerSec: 1,
+    schema: {
+      type: "object",
+      properties: { sku: { type: "string" }, delta: { type: "integer" } },
+    },
+    subscribers: [
+      { id: "cache-warmer", lag: 2, errorCount: 0 },
+      { id: "search-indexer", lag: 1, errorCount: 3 },
+    ],
+    recentLive: [],
+    deadLetters: [],
+    producers: [
+      {
+        flowId: "inventory.adjust",
+        durable: false,
+        external: false,
+        peakTier: "emits",
+      },
+    ],
+    consumers: [
+      {
+        flowId: "cache.onInventory",
+        durable: true,
+        external: false,
+        peakTier: "writes",
+      },
+      {
+        flowId: "search.onInventory",
+        durable: true,
+        external: false,
+        peakTier: "writes",
+      },
+    ],
+    consumersDurable: true,
+  },
+  {
+    name: "ops-feed",
+    delivery: "live",
+    retries: 0,
+    deadLetterEnabled: false,
+    orphaned: false,
+    pending: 0,
+    inflight: 0,
+    dead: 0,
+    delivered: 1_204,
+    outboxLagMs: null,
+    connections: 7,
+    throughputPerSec: 18,
+    schema: undefined,
+    subscribers: [],
+    recentLive: [
+      { kind: "heartbeat", at: 1 },
+      { kind: "alert", code: "lag", at: 2 },
+      { kind: "heartbeat", at: 3 },
+    ],
+    deadLetters: [],
+    producers: [
+      {
+        flowId: "ops.emit",
+        durable: false,
+        external: false,
+        peakTier: "emits",
+      },
+    ],
+    consumers: [],
+    consumersDurable: null,
+  },
+  {
+    name: "legacy-shipped",
+    delivery: "once",
+    retries: 3,
+    deadLetterEnabled: true,
+    orphaned: true,
+    pending: 4,
+    inflight: 0,
+    dead: 1,
+    delivered: 0,
+    outboxLagMs: 86_400_000,
+    connections: 0,
+    throughputPerSec: 0,
+    schema: undefined,
+    subscribers: [],
+    recentLive: [],
+    deadLetters: [
+      {
+        id: "dlq-orphan",
+        signal: "legacy-shipped",
+        payload: { shipmentId: "shp_9" },
+        delivery: "once",
+        attempts: 3,
+        failures: [
+          {
+            code: "NoConsumer",
+            message: "signal removed from code",
+            at: 1_700_000_100_000,
+            attempt: 3,
+          },
+        ],
+        createdAt: 1_700_000_090_000,
+        availableAt: 1_700_000_100_000,
+        status: "dead",
+      },
+    ],
+    producers: [],
+    consumers: [],
+    consumersDurable: null,
+  },
+];

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

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { SIGNALS_FIXTURE } from "./fixture.ts";
+import { groupByPhysics } from "./group.ts";
+
+describe("groupByPhysics", () => {
+  test("one list grouped by delivery — not three tabs", () => {
+    const groups = groupByPhysics(SIGNALS_FIXTURE);
+    expect(groups.map((g) => g.delivery)).toEqual([
+      "once",
+      "broadcast",
+      "live",
+    ]);
+    expect(groups.find((g) => g.delivery === "once")?.signals.length).toBe(2);
+    expect(groups.find((g) => g.delivery === "broadcast")?.signals[0]?.name).toBe(
+      "inventory-changed",
+    );
+  });
+
+  test("retains orphaned signals in the list", () => {
+    const groups = groupByPhysics(SIGNALS_FIXTURE);
+    const once = groups.find((g) => g.delivery === "once");
+    expect(once?.signals.some((s) => s.name === "legacy-shipped" && s.orphaned)).toBe(
+      true,
+    );
+  });
+
+  test("free-text filter dims across name and endpoints", () => {
+    const groups = groupByPhysics(SIGNALS_FIXTURE, "fulfillment");
+    expect(groups).toHaveLength(1);
+    expect(groups[0]?.signals[0]?.name).toBe("order-placed");
+  });
+});

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

@@ -0,0 +1,49 @@
+/**
+ * Group signals by delivery physics — one list, not three tabs (console §9.4).
+ */
+
+import type {
+  SignalDelivery,
+  SignalPhysicsGroup,
+  SignalRecord,
+} from "./types.ts";
+
+const PHYSICS_ORDER: readonly SignalDelivery[] = [
+  "once",
+  "broadcast",
+  "live",
+];
+
+const LABELS: Record<SignalDelivery, string> = {
+  once: "Once — competing consumers",
+  broadcast: "Broadcast — every subscriber",
+  live: "Live — client stream",
+};
+
+/**
+ * Group signals by delivery physics, preserving declaration order within.
+ *
+ * @param signals - Flat list
+ * @param query - Optional free-text filter
+ */
+export function groupByPhysics(
+  signals: readonly SignalRecord[],
+  query = "",
+): readonly SignalPhysicsGroup[] {
+  const q = query.trim().toLowerCase();
+  const filtered = q
+    ? signals.filter(
+        (s) =>
+          s.name.toLowerCase().includes(q) ||
+          s.delivery.includes(q) ||
+          s.producers.some((p) => p.flowId.toLowerCase().includes(q)) ||
+          s.consumers.some((c) => c.flowId.toLowerCase().includes(q)),
+      )
+    : signals;
+
+  return PHYSICS_ORDER.map((delivery) => ({
+    delivery,
+    label: LABELS[delivery],
+    signals: filtered.filter((s) => s.delivery === delivery),
+  })).filter((g) => g.signals.length > 0);
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Signals panel pure modules (console §9.4).
+ */
+
+export type {
+  SignalDelivery,
+  SignalDeadLetter,
+  SignalEndpoint,
+  SignalFailure,
+  SignalPhysicsGroup,
+  SignalRecord,
+} from "./types.ts";
+
+export {
+  parseSignalsSearch,
+  serializeSignalsSearch,
+  openSignal,
+  closeSignal,
+  openDeadLetter,
+  closeDeadLetter,
+  type SignalsSearch,
+} from "./search.ts";
+
+export { groupByPhysics } from "./group.ts";
+export { durableLine, type DurableLine } from "./durable.ts";
+export {
+  replayConfirmation,
+  discardConfirmation,
+  validateTypedConfirm,
+  UNDO_WINDOW_MS,
+  type ConfirmationPattern,
+} from "./confirmation.ts";
+export {
+  fieldsFromSchema,
+  payloadToFormValues,
+  formValuesToPayload,
+  type SchemaField,
+} from "./schema-form.ts";
+export {
+  createLiveMonitor,
+  appendLivePayload,
+  setPaused,
+  onMonitorScroll,
+  exportLivePayloads,
+  type LiveMonitorState,
+} from "./monitor.ts";
+export { SIGNALS_FIXTURE } from "./fixture.ts";
+export { dryRunOffer, type DryRunOffer } from "./dry-run.ts";
+export {
+  deadLetterFindings,
+  type DeadLetterFinding,
+} from "./findings.ts";

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

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import {
+  appendLivePayload,
+  createLiveMonitor,
+  exportLivePayloads,
+  onMonitorScroll,
+  setPaused,
+} from "./monitor.ts";
+
+describe("live monitor", () => {
+  test("appends while running and freezes when paused", () => {
+    let state = createLiveMonitor([{ a: 1 }]);
+    state = appendLivePayload(state, { a: 2 });
+    expect(state.payloads).toHaveLength(2);
+    state = setPaused(state, true);
+    state = appendLivePayload(state, { a: 3 });
+    expect(state.payloads).toHaveLength(2);
+  });
+
+  test("scroll auto-pauses", () => {
+    const state = onMonitorScroll(createLiveMonitor());
+    expect(state.paused).toBe(true);
+    expect(state.autoPausedByScroll).toBe(true);
+  });
+
+  test("export is JSON", () => {
+    const json = exportLivePayloads([{ x: 1 }]);
+    expect(JSON.parse(json)).toEqual([{ x: 1 }]);
+  });
+});

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

@@ -0,0 +1,79 @@
+/**
+ * Live payload monitor — pause / export; auto-pauses on scroll (console §9.4).
+ */
+
+/** Monitor state. */
+export interface LiveMonitorState {
+  readonly paused: boolean;
+  readonly autoPausedByScroll: boolean;
+  readonly payloads: readonly unknown[];
+}
+
+/**
+ * Apply a new live payload when the monitor is not paused.
+ *
+ * @param state - Current
+ * @param payload - Incoming
+ * @param cap - Max retained
+ */
+export function appendLivePayload(
+  state: LiveMonitorState,
+  payload: unknown,
+  cap = 50,
+): LiveMonitorState {
+  if (state.paused) return state;
+  const payloads = [...state.payloads, payload];
+  while (payloads.length > cap) payloads.shift();
+  return { ...state, payloads };
+}
+
+/**
+ * Operator toggles pause.
+ *
+ * @param state - Current
+ * @param paused - Desired
+ */
+export function setPaused(
+  state: LiveMonitorState,
+  paused: boolean,
+): LiveMonitorState {
+  return {
+    ...state,
+    paused,
+    autoPausedByScroll: paused ? state.autoPausedByScroll : false,
+  };
+}
+
+/**
+ * Scroll interaction auto-pauses the stream so the operator can read.
+ *
+ * @param state - Current
+ */
+export function onMonitorScroll(state: LiveMonitorState): LiveMonitorState {
+  if (state.paused) return state;
+  return { ...state, paused: true, autoPausedByScroll: true };
+}
+
+/**
+ * Export retained payloads as JSON.
+ *
+ * @param payloads - Retained rows
+ */
+export function exportLivePayloads(payloads: readonly unknown[]): string {
+  return JSON.stringify(payloads, null, 2);
+}
+
+/**
+ * Create an empty monitor.
+ *
+ * @param seed - Optional initial payloads
+ */
+export function createLiveMonitor(
+  seed: readonly unknown[] = [],
+): LiveMonitorState {
+  return {
+    paused: false,
+    autoPausedByScroll: false,
+    payloads: [...seed],
+  };
+}

package/src/console/ui/signals/schema-form.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import {
+  fieldsFromSchema,
+  formValuesToPayload,
+  payloadToFormValues,
+} from "./schema-form.ts";
+import { SIGNALS_FIXTURE } from "./fixture.ts";
+
+describe("schema-form", () => {
+  test("builds editable fields from declared schema", () => {
+    const order = SIGNALS_FIXTURE.find((s) => s.name === "order-placed")!;
+    const fields = fieldsFromSchema(order.schema);
+    expect(fields.map((f) => f.key)).toEqual([
+      "orderId",
+      "amount",
+      "currency",
+    ]);
+    expect(fields.find((f) => f.key === "currency")?.enumValues).toEqual([
+      "USD",
+      "EUR",
+    ]);
+  });
+
+  test("round-trips payload through form values", () => {
+    const order = SIGNALS_FIXTURE.find((s) => s.name === "order-placed")!;
+    const fields = fieldsFromSchema(order.schema);
+    const dlq = order.deadLetters[0]!;
+    const values = payloadToFormValues(dlq.payload, fields);
+    values.amount = "99";
+    const next = formValuesToPayload(values, fields) as Record<string, unknown>;
+    expect(next.orderId).toBe("ord_1");
+    expect(next.amount).toBe(99);
+  });
+});

package/src/console/ui/signals/schema-form.ts

@@ -0,0 +1,112 @@
+/**
+ * Render a signal payload as an editable form from the declared schema.
+ */
+
+/** One field derived from a JSON-schema-like object. */
+export interface SchemaField {
+  readonly key: string;
+  readonly type: "string" | "number" | "boolean" | "integer" | "unknown";
+  readonly required: boolean;
+  readonly enumValues?: readonly string[];
+}
+
+/**
+ * Extract editable fields from a signal's declared schema.
+ *
+ * @param schema - Manifest / Standard Schema object form
+ */
+export function fieldsFromSchema(schema: unknown): readonly SchemaField[] {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return [];
+  }
+  const obj = schema as {
+    type?: string;
+    properties?: Record<string, unknown>;
+    required?: unknown;
+  };
+  if (obj.type !== "object" || !obj.properties) return [];
+  const required = new Set(
+    Array.isArray(obj.required)
+      ? obj.required.filter((k): k is string => typeof k === "string")
+      : [],
+  );
+  return Object.entries(obj.properties).map(([key, def]) => {
+    const d = (def ?? {}) as {
+      type?: string;
+      enum?: unknown[];
+    };
+    const enumValues = Array.isArray(d.enum)
+      ? d.enum.filter((v): v is string => typeof v === "string")
+      : undefined;
+    const type =
+      d.type === "string" ||
+      d.type === "number" ||
+      d.type === "boolean" ||
+      d.type === "integer"
+        ? d.type
+        : "unknown";
+    return {
+      key,
+      type,
+      required: required.has(key),
+      ...(enumValues && enumValues.length > 0 ? { enumValues } : {}),
+    };
+  });
+}
+
+/**
+ * Coerce a payload object into string form values for controlled inputs.
+ *
+ * @param payload - Dead-letter payload
+ * @param fields - Schema fields
+ */
+export function payloadToFormValues(
+  payload: unknown,
+  fields: readonly SchemaField[],
+): Record<string, string> {
+  const src =
+    payload && typeof payload === "object" && !Array.isArray(payload)
+      ? (payload as Record<string, unknown>)
+      : {};
+  const out: Record<string, string> = {};
+  for (const f of fields) {
+    const v = src[f.key];
+    if (v === undefined || v === null) out[f.key] = "";
+    else if (typeof v === "boolean") out[f.key] = v ? "true" : "false";
+    else out[f.key] = String(v);
+  }
+  if (fields.length === 0) {
+    out._raw = JSON.stringify(payload ?? null, null, 2);
+  }
+  return out;
+}
+
+/**
+ * Parse form values back into a payload object.
+ *
+ * @param values - Form strings
+ * @param fields - Schema fields
+ */
+export function formValuesToPayload(
+  values: Record<string, string>,
+  fields: readonly SchemaField[],
+): unknown {
+  if (fields.length === 0) {
+    try {
+      return JSON.parse(values._raw ?? "null") as unknown;
+    } catch {
+      return values._raw ?? null;
+    }
+  }
+  const out: Record<string, unknown> = {};
+  for (const f of fields) {
+    const raw = values[f.key] ?? "";
+    if (raw === "" && !f.required) continue;
+    if (f.type === "boolean") out[f.key] = raw === "true";
+    else if (f.type === "number" || f.type === "integer") {
+      const n = Number(raw);
+      out[f.key] = Number.isFinite(n) ? n : raw;
+    } else out[f.key] = raw;
+  }
+  return out;
+}