okengine 0.1.4

package/src/drivers/signal-redis.ts

@@ -0,0 +1,275 @@
+/**
+ * `redis` signal driver — throughput path with internal outbox relay.
+ *
+ * Emit still enrols in a transactional outbox (semantics never regress).
+ * After commit, a relay pushes to Redis Streams (`once`) or pub/sub
+ * (`broadcast` / `live`). Consumer delivery is driven from the outbox so
+ * exactly-once / fan-out physics stay correct under `drain()`.
+ *
+ * Production bind: {@link createBunSignalRedisClient} (typed `publish` /
+ * `subscribe`; Streams via `send` — Bun 1.3.14 has no typed `xadd` yet).
+ */
+
+import { createSignalEngine } from "./signal-engine.ts";
+import type {
+  SignalBus,
+  SignalDriver,
+  SignalOpenOptions,
+  SignalRedisClientLike,
+} from "./signal-types.ts";
+
+/**
+ * Bind {@link Bun.RedisClient} to {@link SignalRedisClientLike}.
+ *
+ * Streams (`XADD` / `XGROUP` / `XREADGROUP` / `XACK`) use `send` because
+ * Bun 1.3.14 still lacks typed stream helpers — that is a Bun limitation.
+ * Pub/sub uses typed `publish` / `subscribe` (gap closed vs earlier fake-only).
+ *
+ * @param url - Optional Redis URL
+ */
+export function createBunSignalRedisClient(
+  url?: string,
+): SignalRedisClientLike {
+  const redis =
+    url !== undefined ? new Bun.RedisClient(url) : Bun.redis;
+  /** Subscribe blocks a connection — keep a dedicated client. */
+  let sub:
+    | InstanceType<typeof Bun.RedisClient>
+    | undefined;
+
+  function subClient(): InstanceType<typeof Bun.RedisClient> {
+    if (!sub) {
+      sub = url !== undefined ? new Bun.RedisClient(url) : new Bun.RedisClient();
+    }
+    return sub;
+  }
+
+  return {
+    async xadd(key, id, fields) {
+      const args: string[] = [key, id];
+      for (const [k, v] of Object.entries(fields)) {
+        args.push(k, v);
+      }
+      return String(await redis.send("XADD", args));
+    },
+    async xgroupCreate(key, group, id, opts) {
+      const args = ["CREATE", key, group, id];
+      if (opts?.mkstream) args.push("MKSTREAM");
+      try {
+        await redis.send("XGROUP", args);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!/BUSYGROUP/i.test(msg)) throw err;
+      }
+    },
+    async xreadgroup(group, consumer, key, count) {
+      const reply = await redis.send("XREADGROUP", [
+        "GROUP",
+        group,
+        consumer,
+        "COUNT",
+        String(count),
+        "STREAMS",
+        key,
+        ">",
+      ]);
+      return parseXreadgroupReply(reply);
+    },
+    async xack(key, group, id) {
+      return Number(await redis.send("XACK", [key, group, id]));
+    },
+    async publish(channel, message) {
+      return redis.publish(channel, message);
+    },
+    async subscribe(channel, listener) {
+      const client = subClient();
+      await client.subscribe(channel, (message) => {
+        listener(message);
+      });
+      return () => {
+        void client.unsubscribe(channel);
+      };
+    },
+  };
+}
+
+/**
+ * Parse Redis `XREADGROUP` nested-array reply into field maps.
+ *
+ * @param reply - Raw `send` result
+ */
+export function parseXreadgroupReply(
+  reply: unknown,
+): Array<{ id: string; fields: Record<string, string> }> {
+  if (reply == null || !Array.isArray(reply)) return [];
+  const out: Array<{ id: string; fields: Record<string, string> }> = [];
+  for (const stream of reply) {
+    if (!Array.isArray(stream) || stream.length < 2) continue;
+    const entries = stream[1];
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (!Array.isArray(entry) || entry.length < 2) continue;
+      const id = String(entry[0]);
+      const flat = entry[1];
+      const fields: Record<string, string> = {};
+      if (Array.isArray(flat)) {
+        for (let i = 0; i + 1 < flat.length; i += 2) {
+          fields[String(flat[i])] = String(flat[i + 1]);
+        }
+      }
+      out.push({ id, fields });
+    }
+  }
+  return out;
+}
+
+/**
+ * In-memory redis-protocol fake for signal streams + pub/sub.
+ */
+export function createSignalRedisFake(): SignalRedisClientLike & {
+  readonly streams: Map<
+    string,
+    Array<{ id: string; fields: Record<string, string> }>
+  >;
+  readonly published: Array<{ channel: string; message: string }>;
+} {
+  const streams = new Map<
+    string,
+    Array<{ id: string; fields: Record<string, string> }>
+  >();
+  const groups = new Map<string, Set<string>>();
+  const claimed = new Map<string, Set<string>>();
+  const subs = new Map<string, Set<(message: string) => void>>();
+  const published: Array<{ channel: string; message: string }> = [];
+  let seq = 0;
+
+  return {
+    streams,
+    published,
+    async xadd(key, id, fields) {
+      let list = streams.get(key);
+      if (!list) {
+        list = [];
+        streams.set(key, list);
+      }
+      const realId = id === "*" ? `${Date.now()}-${seq++}` : id;
+      list.push({ id: realId, fields: { ...fields } });
+      return realId;
+    },
+    async xgroupCreate(key, group, _id, opts) {
+      if (opts?.mkstream && !streams.has(key)) streams.set(key, []);
+      const gkey = `${key}::${group}`;
+      if (!groups.has(gkey)) groups.set(gkey, new Set());
+      if (!claimed.has(gkey)) claimed.set(gkey, new Set());
+    },
+    async xreadgroup(group, consumer, key, count) {
+      const gkey = `${key}::${group}`;
+      if (!groups.has(gkey)) {
+        await this.xgroupCreate(key, group, "0", { mkstream: true });
+      }
+      const seen = claimed.get(gkey)!;
+      const list = streams.get(key) ?? [];
+      const out: Array<{ id: string; fields: Record<string, string> }> = [];
+      for (const entry of list) {
+        if (seen.has(entry.id)) continue;
+        seen.add(entry.id);
+        out.push({
+          id: entry.id,
+          fields: { ...entry.fields, _consumer: consumer },
+        });
+        if (out.length >= count) break;
+      }
+      return out;
+    },
+    async xack() {
+      return 1;
+    },
+    async publish(channel, message) {
+      published.push({ channel, message });
+      const set = subs.get(channel);
+      if (!set) return 0;
+      for (const fn of set) fn(message);
+      return set.size;
+    },
+    async subscribe(channel, listener) {
+      let set = subs.get(channel);
+      if (!set) {
+        set = new Set();
+        subs.set(channel, set);
+      }
+      set.add(listener);
+      return () => {
+        set!.delete(listener);
+      };
+    },
+  };
+}
+
+/**
+ * Open a redis signal bus (outbox + relay).
+ *
+ * @param options - Declarations / redis client / durable outbox path
+ */
+export async function openRedisSignal(
+  options: SignalOpenOptions,
+): Promise<SignalBus> {
+  // Same DI shape as postgres/redis/s3: inject a client in tests; production
+  // binds Bun.redis (Streams via send until Bun ships typed xadd).
+  const redis = options.redis ?? createBunSignalRedisClient();
+  const outbox = await createSignalEngine("redis", options);
+
+  async function relayToRedis(signal: string, payload: unknown): Promise<void> {
+    const decl = options.signals.get(signal);
+    if (!decl) return;
+    const body = JSON.stringify(payload ?? null);
+    if (decl.delivery === "once") {
+      const key = `oke:signal:${signal}`;
+      await redis.xgroupCreate(key, "oke", "0", { mkstream: true });
+      await redis.xadd(key, "*", { payload: body, signal });
+    } else if (decl.delivery === "broadcast") {
+      await redis.publish(`oke:signal:bcast:${signal}`, body);
+    } else {
+      await redis.publish(`oke:signal:live:${signal}`, body);
+    }
+  }
+
+  return {
+    driverId: "redis",
+    async emit(signal, payload) {
+      await outbox.emit(signal, payload);
+      await relayToRedis(signal, payload);
+    },
+    async begin() {
+      const staged: Array<{ signal: string; payload: unknown }> = [];
+      const tx = await outbox.begin();
+      return {
+        write: (k, v) => tx.write(k, v),
+        async emit(signal, payload) {
+          staged.push({ signal, payload });
+          await tx.emit(signal, payload);
+        },
+        async commit() {
+          await tx.commit();
+          for (const e of staged) await relayToRedis(e.signal, e.payload);
+        },
+        rollback: () => tx.rollback(),
+      };
+    },
+    subscribe: (signal, subscriberId, handler) =>
+      outbox.subscribe(signal, subscriberId, handler),
+    live: (signal, handler) => outbox.live(signal, handler),
+    drain: () => outbox.drain(),
+    deadLetters: (s) => outbox.deadLetters(s),
+    inspect: (s) => outbox.inspect(s),
+    replay: (opts) => outbox.replay(opts),
+    discard: (opts) => outbox.discard(opts),
+    getWrite: (k) => outbox.getWrite(k),
+    close: () => outbox.close(),
+  };
+}
+
+/** Protocol-named redis signal driver. */
+export const redisSignalDriver: SignalDriver = {
+  id: "redis",
+  open: openRedisSignal,
+};

package/src/drivers/signal-types.ts

@@ -0,0 +1,328 @@
+/**
+ * Signal driver contracts — protocol-named (`memory` · `postgres` · `redis` · `nats`).
+ */
+
+import type { SignalDelivery } from "../manifest/types.ts";
+import type { SignalDecl } from "../elements/signal/declare.ts";
+
+/** Protocol ids for signal drivers. */
+export type SignalDriverId = "memory" | "postgres" | "redis" | "nats";
+
+/**
+ * Typed failure reason preserved on every delivery attempt.
+ *
+ * Survives into the DLQ so operators can see the full attempt history.
+ */
+export interface SignalFailureReason {
+  /** Machine-readable failure code. */
+  readonly code: string;
+  /** Human-readable detail. */
+  readonly message: string;
+  /** Epoch-ms when the attempt failed. */
+  readonly at: number;
+  /** 1-based attempt number that failed. */
+  readonly attempt: number;
+}
+
+/** A durable signal message. */
+export interface SignalMessage {
+  readonly id: string;
+  readonly signal: string;
+  readonly payload: unknown;
+  readonly delivery: SignalDelivery;
+  readonly attempts: number;
+  readonly failures: readonly SignalFailureReason[];
+  readonly createdAt: number;
+  /** Available for claim (once); null while locked / delivered. */
+  readonly availableAt: number;
+  readonly status: "pending" | "inflight" | "delivered" | "dead";
+}
+
+/** Dead-letter entry with full attempt history. */
+export interface DeadLetter extends SignalMessage {
+  readonly status: "dead";
+}
+
+/** Per-subscriber lag / errors (broadcast physics). */
+export interface SignalSubscriberStats {
+  /** Stable subscriber id. */
+  readonly id: string;
+  /** Undelivered message count for this subscriber. */
+  readonly lag: number;
+  /** Handler failures attributed to this subscriber. */
+  readonly errorCount: number;
+}
+
+/**
+ * Operator-plane snapshot of one signal's live queue state.
+ *
+ * Reads the real bus — the Console must not reimplement delivery physics.
+ */
+export interface SignalStats {
+  /** Signal name. */
+  readonly signal: string;
+  /** Delivery physics. */
+  readonly delivery: SignalDelivery;
+  /** Competing / fan-out pending count. */
+  readonly pending: number;
+  /** Claimed but not yet acked (`once`). */
+  readonly inflight: number;
+  /** Dead-letter count. */
+  readonly dead: number;
+  /** Successfully delivered count. */
+  readonly delivered: number;
+  /** Declared retry budget. */
+  readonly retries: number;
+  /** Whether exhausted messages enter the DLQ. */
+  readonly deadLetterEnabled: boolean;
+  /**
+   * Age (ms) of the oldest committed-but-not-yet-relayed/consumed message.
+   * Surfaces transactional outbox lag (postgres-default case).
+   */
+  readonly outboxLagMs: number | null;
+  /** Broadcast subscriber rows. */
+  readonly subscribers: readonly SignalSubscriberStats[];
+  /** Live connection count (`delivery: "live"`). */
+  readonly connections: number;
+  /** Deliveries completed in the last trailing second. */
+  readonly throughputPerSec: number;
+  /** Declared payload schema when present. */
+  readonly schema: unknown;
+  /** Recent live payloads (newest last) for the payload monitor. */
+  readonly recentLive: readonly unknown[];
+  /** Dead-letter entries with typed per-attempt failures. */
+  readonly deadLetters: readonly DeadLetter[];
+}
+
+/** Options for {@link SignalBus.replay}. */
+export interface SignalReplayOptions {
+  /** Signal name. */
+  readonly signal: string;
+  /** Dead-letter message ids to replay (empty = all dead for the signal). */
+  readonly messageIds?: readonly string[];
+  /** Broadcast: target a single subscriber. */
+  readonly subscriberId?: string;
+  /** Max replays per second — never an unthrottled flood. */
+  readonly ratePerSec: number;
+  /** When true, invoke handlers but leave DLQ rows untouched. */
+  readonly dryRun: boolean;
+  /** Optional payload overrides keyed by message id (schema form edits). */
+  readonly payloads?: Readonly<Record<string, unknown>>;
+}
+
+/** Per-message result from a replay / dry-run pass. */
+export interface SignalReplayMessageResult {
+  readonly id: string;
+  readonly ok: boolean;
+  readonly error?: { readonly code: string; readonly message: string };
+}
+
+/** Irreversible effect intercepted during a dry-run replay. */
+export interface SignalDryRunStub {
+  readonly kind: "send" | "ask";
+  readonly resource: string;
+  readonly messageId?: string;
+}
+
+/** Aggregate result of {@link SignalBus.replay}. */
+export interface SignalReplayResult {
+  readonly attempted: number;
+  readonly succeeded: number;
+  readonly failed: number;
+  readonly dryRun: boolean;
+  readonly results: readonly SignalReplayMessageResult[];
+  /**
+   * Irreversible effects recorded as "would have fired" during dry-run.
+   * Empty for live replay.
+   */
+  readonly wouldHaveFired: readonly SignalDryRunStub[];
+  /**
+   * When set, dry-run was refused because a safe stubbed run is impossible
+   * for this consumer shape (same refusal spirit as Traces).
+   */
+  readonly refused?: {
+    readonly code: "dry_run_unsafe";
+    readonly reason: string;
+  };
+}
+
+/** Options for {@link SignalBus.discard}. */
+export interface SignalDiscardOptions {
+  readonly signal: string;
+  readonly messageIds: readonly string[];
+}
+
+/** Unsubscribe handle. */
+export type SignalUnsubscribe = () => void | Promise<void>;
+
+/** Consumer handler for once / broadcast. */
+export type SignalHandler = (message: SignalMessage) => void | Promise<void>;
+
+/** Live client handler (payload only). */
+export type LiveHandler = (payload: unknown) => void | Promise<void>;
+
+/**
+ * Transaction that enrols store writes and signal emits atomically.
+ *
+ * Postgres: emit inserts into the outbox on the caller's connection.
+ * Redis / NATS: emit still writes the outbox first; relay runs after commit.
+ */
+export interface SignalTransaction {
+  /**
+   * Stage a durable paired write (dual-write proof / chaos tests).
+   *
+   * @param key - Logical key
+   * @param value - Value
+   */
+  write(key: string, value: unknown): Promise<void>;
+  /**
+   * Stage an emit into the same transaction.
+   *
+   * @param signal - Signal name
+   * @param payload - Payload
+   */
+  emit(signal: string, payload?: unknown): Promise<void>;
+  /** Commit writes + emits together. */
+  commit(): Promise<void>;
+  /** Discard the transaction — nothing is visible. */
+  rollback(): Promise<void>;
+}
+
+/** Options when opening a signal bus. */
+export interface SignalOpenOptions {
+  /** Registered signal declarations (name → decl). */
+  readonly signals: ReadonlyMap<string, SignalDecl>;
+  /** Clock. */
+  readonly now?: () => number;
+  /**
+   * Durable path for chaos / crash recovery tests.
+   * When set, committed state survives process death.
+   */
+  readonly durablePath?: string;
+  /** Injected SQL client / connection for postgres outbox. */
+  readonly sql?: unknown;
+  /** Injected redis-protocol client (streams + pub/sub). */
+  readonly redis?: SignalRedisClientLike;
+  /** Injected NATS / JetStream-like client. */
+  readonly nats?: SignalNatsClientLike;
+  /** Outbox SQL for redis/nats relay (defaults to in-process). */
+  readonly outboxSql?: unknown;
+}
+
+/**
+ * Minimal Redis surface used by the signal redis driver.
+ * Streams for `once`, pub/sub for `broadcast` / `live`.
+ */
+export interface SignalRedisClientLike {
+  xadd(key: string, id: string, fields: Record<string, string>): Promise<string>;
+  xgroupCreate(
+    key: string,
+    group: string,
+    id: string,
+    opts?: { mkstream?: boolean },
+  ): Promise<void>;
+  xreadgroup(
+    group: string,
+    consumer: string,
+    key: string,
+    count: number,
+  ): Promise<Array<{ id: string; fields: Record<string, string> }>>;
+  xack(key: string, group: string, id: string): Promise<number>;
+  publish(channel: string, message: string): Promise<number>;
+  subscribe(
+    channel: string,
+    listener: (message: string) => void,
+  ): Promise<() => void>;
+}
+
+/** Minimal NATS / JetStream surface. */
+export interface SignalNatsClientLike {
+  publish(subject: string, data: Uint8Array | string): Promise<void>;
+  subscribe(
+    subject: string,
+    opts: {
+      queue?: string;
+      callback: (data: Uint8Array) => void | Promise<void>;
+    },
+  ): Promise<() => void>;
+}
+
+/** Open signal bus from a driver. */
+export interface SignalBus {
+  readonly driverId: SignalDriverId;
+  /**
+   * Emit outside a transaction (auto-commits a one-shot txn).
+   *
+   * @param signal - Signal name
+   * @param payload - Payload
+   */
+  emit(signal: string, payload?: unknown): Promise<void>;
+  /** Begin a transaction that enrols writes + emits. */
+  begin(): Promise<SignalTransaction>;
+  /**
+   * Subscribe a competing / fan-out consumer.
+   *
+   * @param signal - Signal name
+   * @param subscriberId - Stable subscriber id (exactly-once per id for once)
+   * @param handler - Message handler
+   */
+  subscribe(
+    signal: string,
+    subscriberId: string,
+    handler: SignalHandler,
+  ): Promise<SignalUnsubscribe>;
+  /**
+   * Client-subscribable live feed.
+   *
+   * @param signal - Signal name (`delivery: "live"`)
+   * @param handler - Payload handler
+   */
+  live(signal: string, handler: LiveHandler): Promise<SignalUnsubscribe>;
+  /**
+   * Process pending work until idle (deterministic tests).
+   */
+  drain(): Promise<void>;
+  /**
+   * Inspect dead-letter queue for a signal.
+   *
+   * @param signal - Signal name
+   */
+  deadLetters(signal: string): Promise<readonly DeadLetter[]>;
+  /**
+   * Operator inspect — queue depths, subscribers, outbox lag, DLQ.
+   *
+   * @param signal - Optional name; omit for every registered signal
+   */
+  inspect(signal?: string): Promise<readonly SignalStats[]>;
+  /**
+   * Replay dead letters at a controlled rate (or dry-run without mutating).
+   *
+   * @param options - Target messages, rate, dry-run, payload overrides
+   */
+  replay(options: SignalReplayOptions): Promise<SignalReplayResult>;
+  /**
+   * Permanently discard dead-letter messages.
+   *
+   * @param options - Signal + message ids
+   */
+  discard(options: SignalDiscardOptions): Promise<{ readonly discarded: number }>;
+  /**
+   * Read a durable paired write (post-commit / post-recovery).
+   *
+   * @param key - Key written via {@link SignalTransaction.write}
+   */
+  getWrite(key: string): Promise<unknown>;
+  /** Close the bus. */
+  close(): Promise<void>;
+}
+
+/** Signal driver factory. */
+export interface SignalDriver {
+  readonly id: SignalDriverId;
+  /**
+   * Open a bus.
+   *
+   * @param options - Declarations and injected clients
+   */
+  open(options: SignalOpenOptions): Promise<SignalBus>;
+}

package/src/drivers/sqlite.ts

@@ -0,0 +1,53 @@
+/**
+ * `sqlite` driver — binds `bun:sqlite` (never better-sqlite3).
+ */
+
+import { Database, type SQLQueryBindings } from "bun:sqlite";
+import type {
+  SqlConnectOptions,
+  SqlConnection,
+  SqlDriver,
+  SqlRow,
+} from "./types.ts";
+
+/**
+ * Open a bun:sqlite connection implementing {@link SqlConnection}.
+ *
+ * @param options - URL (`:memory:` / path) or injected Database
+ */
+export async function connectSqlite(
+  options: SqlConnectOptions = {},
+): Promise<SqlConnection> {
+  const role = options.role ?? "primary";
+  const db =
+    options.client instanceof Database
+      ? options.client
+      : new Database(options.url ?? ":memory:");
+
+  function asBindings(params: readonly unknown[]): SQLQueryBindings[] {
+    return params as SQLQueryBindings[];
+  }
+
+  return {
+    driverId: "sqlite",
+    role,
+    async query(sql, params = []) {
+      const stmt = db.query(sql);
+      return stmt.all(...(asBindings(params) as never[])) as SqlRow[];
+    },
+    async exec(sql, params = []) {
+      const result = db.run(sql, ...(asBindings(params) as never[]));
+      return { changes: result.changes };
+    },
+    async close() {
+      db.close();
+    },
+  };
+}
+
+/** Protocol-named sqlite driver. */
+export const sqliteDriver: SqlDriver = {
+  id: "sqlite",
+  facet: "sql",
+  connect: connectSqlite,
+};