okengine 0.13.0 → 0.15.2

package/src/drivers/pg-rls.ts

@@ -1,5 +1,6 @@
 /**
- * Postgres row-level security — identifiers and `CREATE POLICY` SQL.
+ * Postgres row-level security — identifiers, `CREATE POLICY` SQL,
+ * Drizzle emit, and Gate identity helpers (`oke.gate` / `oke.user` / `oke.has_scope`).
  */
 
 /** Policy command (`FOR`). */
@@ -31,6 +32,110 @@ export type SqlPolicyAlterSpec = {
 const POLICY_COMMANDS = new Set<string>(["ALL", "SELECT", "INSERT", "UPDATE", "DELETE"]);
 const POLICY_BEHAVIORS = new Set<string>(["PERMISSIVE", "RESTRICTIVE"]);
 
+/** Drizzle / Postgres `TO` targets that must not be quoted. */
+const SPECIAL_POLICY_ROLES = new Set(["public", "current_role", "current_user", "session_user"]);
+
+/** Drivers that honor `SET LOCAL row_security` + `oke.*` GUCs. */
+export const RLS_CONTEXT_DRIVERS = new Set<string>(["postgres", "pglite"]);
+
+/**
+ * Non-superuser role the stamp `SET LOCAL ROLE`s into so RLS applies.
+ * Table owners and PGlite's `postgres` superuser otherwise bypass policies.
+ */
+export const OKE_RLS_ROLE = "oke_app";
+
+/** Live Gate principal stamped onto a SQL statement. */
+export type RlsIdentity = {
+  readonly gate: string;
+  readonly userId: string;
+  readonly scopes: readonly string[];
+};
+
+/**
+ * One statement at a time — Bun.SQL `unsafe` / PGlite `query` reject
+ * multi-command batches. Safe to run repeatedly.
+ */
+export const OKE_RLS_HELPER_STATEMENTS: readonly string[] = [
+  "CREATE SCHEMA IF NOT EXISTS oke",
+  // DB user is often `oke` — default search_path `"$user", public` then
+  // creates unqualified tables in schema `oke`. Domain tables belong in public.
+  "SET search_path TO public, oke",
+  `DO $oke_search_path$
+BEGIN
+  EXECUTE 'ALTER ROLE CURRENT_USER SET search_path TO public, oke';
+EXCEPTION
+  WHEN others THEN NULL;
+END
+$oke_search_path$`,
+  `DO $oke_rehome$
+DECLARE r record;
+BEGIN
+  FOR r IN
+    SELECT c.relname AS name
+    FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = 'oke' AND c.relkind = 'r'
+  LOOP
+    IF NOT EXISTS (
+      SELECT 1
+      FROM pg_class c2
+      JOIN pg_namespace n2 ON n2.oid = c2.relnamespace
+      WHERE n2.nspname = 'public' AND c2.relname = r.name AND c2.relkind = 'r'
+    ) THEN
+      EXECUTE format('ALTER TABLE oke.%I SET SCHEMA public', r.name);
+    END IF;
+  END LOOP;
+END
+$oke_rehome$`,
+  `CREATE OR REPLACE FUNCTION oke.gate() RETURNS text
+LANGUAGE sql STABLE AS $$ SELECT current_setting('oke.gate', true) $$`,
+  `CREATE OR REPLACE FUNCTION oke.user() RETURNS text
+LANGUAGE sql STABLE AS $$ SELECT current_setting('oke.user', true) $$`,
+  `CREATE OR REPLACE FUNCTION oke.has_scope(p_scope text) RETURNS boolean
+LANGUAGE sql STABLE AS $$
+  SELECT CASE
+    WHEN current_setting('oke.scopes', true) IN ('') THEN false
+    ELSE jsonb_exists(current_setting('oke.scopes', true)::jsonb, p_scope)
+  END
+$$`,
+  `DO $oke_rls_role$
+BEGIN
+  CREATE ROLE ${OKE_RLS_ROLE} NOSUPERUSER NOBYPASSRLS NOLOGIN;
+EXCEPTION
+  WHEN duplicate_object THEN NULL;
+END
+$oke_rls_role$`,
+  `GRANT USAGE ON SCHEMA public TO ${OKE_RLS_ROLE}`,
+  `GRANT USAGE ON SCHEMA oke TO ${OKE_RLS_ROLE}`,
+  `GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA oke TO ${OKE_RLS_ROLE}`,
+  `GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO ${OKE_RLS_ROLE}`,
+  `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${OKE_RLS_ROLE}`,
+  `GRANT ${OKE_RLS_ROLE} TO CURRENT_USER`,
+  `DO $oke_app_search_path$
+BEGIN
+  EXECUTE 'ALTER ROLE ${OKE_RLS_ROLE} SET search_path TO public, oke';
+EXCEPTION
+  WHEN others THEN NULL;
+END
+$oke_app_search_path$`,
+];
+
+/**
+ * All {@link OKE_RLS_HELPER_STATEMENTS} as one script (PGlite `exec` / `oke db push`).
+ */
+export const OKE_RLS_HELPER_SQL = `${OKE_RLS_HELPER_STATEMENTS.join(";\n")};`;
+
+/**
+ * Install `oke.*` helpers one statement at a time.
+ *
+ * @param exec - Statement runner
+ */
+export async function installOkeRlsHelpers(exec: (sql: string) => Promise<unknown>): Promise<void> {
+  for (const stmt of OKE_RLS_HELPER_STATEMENTS) {
+    await exec(stmt);
+  }
+}
+
 /**
  * Quote a Postgres identifier (`"`), stripping embedded quotes.
  *
@@ -102,11 +207,38 @@ export function parseSqlPolicyRoles(raw: string): readonly string[] | null {
     .filter((part) => part.length > 0);
   if (parts.length === 0) return ["public"];
   for (const part of parts) {
-    if (part !== "public" && !isPgIdent(part)) return null;
+    if (!isPolicyRoleName(part)) return null;
   }
   return parts;
 }
 
+/**
+ * True when `name` is `public`, a Drizzle special role, or a simple identifier.
+ *
+ * @param name - Role token
+ */
+export function isPolicyRoleName(name: string): boolean {
+  return SPECIAL_POLICY_ROLES.has(name.toLowerCase()) || isPgIdent(name);
+}
+
+/**
+ * Format a `TO` role — special names stay unquoted.
+ *
+ * @param role - Role token
+ */
+export function formatPolicyRole(role: string): string {
+  return SPECIAL_POLICY_ROLES.has(role.toLowerCase()) ? role.toLowerCase() : quotePgIdent(role);
+}
+
+/**
+ * JSON text stored in `oke.scopes` (sorted unique).
+ *
+ * @param scopes - Scope strings
+ */
+export function rlsScopesJson(scopes: readonly string[]): string {
+  return JSON.stringify([...new Set(scopes)].sort());
+}
+
 /**
  * `CREATE POLICY` from a validated spec.
  *
@@ -116,7 +248,7 @@ export function buildCreatePolicySql(spec: SqlPolicySpec): string {
   const roles =
     spec.roles.length === 0
       ? "public"
-      : spec.roles.map((role) => (role === "public" ? "public" : quotePgIdent(role))).join(", ");
+      : spec.roles.map((role) => formatPolicyRole(role)).join(", ");
   let text = `CREATE POLICY ${quotePgIdent(spec.name)} ON ${quotePgIdent(spec.table)} AS ${spec.behavior} FOR ${spec.command} TO ${roles}`;
   if (spec.using !== undefined && spec.using.trim() !== "") {
     text += ` USING (${spec.using.trim()})`;
@@ -153,7 +285,7 @@ export function buildAlterPolicySql(spec: SqlPolicyAlterSpec): string {
     const roles =
       spec.roles.length === 0
         ? "public"
-        : spec.roles.map((role) => (role === "public" ? "public" : quotePgIdent(role))).join(", ");
+        : spec.roles.map((role) => formatPolicyRole(role)).join(", ");
     parts.push(`TO ${roles}`);
   }
   if (spec.using !== undefined && spec.using.trim() !== "") {
@@ -189,9 +321,9 @@ export function parseSqlPolicySpec(raw: Readonly<Record<string, unknown>>): SqlP
   const table = typeof raw.table === "string" ? raw.table.trim() : "";
   if (!isPgPolicyName(name)) throw new Error(`invalid policy name "${name}"`);
   if (!isPgIdent(table)) throw new Error(`invalid table name "${table}"`);
-  const command = parseSqlPolicyCommand(raw.command) ?? "SELECT";
-  const behavior = parseSqlPolicyBehavior(raw.behavior ?? raw.permissive) ?? "PERMISSIVE";
-  const rolesRaw = typeof raw.roles === "string" ? raw.roles : "public";
+  const command = parseSqlPolicyCommand(raw.command) ?? parseSqlPolicyCommand(raw.for) ?? "SELECT";
+  const behavior = parseSqlPolicyBehavior(raw.behavior ?? raw.permissive ?? raw.as) ?? "PERMISSIVE";
+  const rolesRaw = rolesField(raw.roles ?? raw.to);
   const roles = parseSqlPolicyRoles(rolesRaw);
   if (!roles) throw new Error("invalid policy roles");
   const using = typeof raw.using === "string" ? raw.using.trim() : "";
@@ -232,3 +364,97 @@ export function parseSqlPolicyRowId(id: string): { readonly table: string; reado
   }
   return { table: id.slice(0, cut), name: id.slice(cut + 1) };
 }
+
+function rolesField(raw: unknown): string {
+  if (typeof raw === "string") return raw;
+  if (Array.isArray(raw)) {
+    return raw.filter((part): part is string => typeof part === "string").join(", ");
+  }
+  return "public";
+}
+
+/**
+ * Drizzle `pgPolicy(...)` source for emit / Console copy-as-code.
+ *
+ * @param spec - Validated policy
+ */
+export function emitPgPolicySource(spec: SqlPolicySpec): string {
+  const to =
+    spec.roles.length === 1
+      ? JSON.stringify(formatEmitRole(spec.roles[0]!))
+      : `[${spec.roles.map((role) => JSON.stringify(formatEmitRole(role))).join(", ")}]`;
+  const lines = [
+    `pgPolicy(${JSON.stringify(spec.name)}, {`,
+    `  as: ${JSON.stringify(spec.behavior.toLowerCase())},`,
+    `  to: ${to},`,
+    `  for: ${JSON.stringify(spec.command.toLowerCase())},`,
+  ];
+  if (spec.using !== undefined && spec.using.trim() !== "") {
+    lines.push(`  using: sql\`${escapeSqlTemplate(spec.using.trim())}\`,`);
+  }
+  if (spec.withCheck !== undefined && spec.withCheck.trim() !== "") {
+    lines.push(`  withCheck: sql\`${escapeSqlTemplate(spec.withCheck.trim())}\`,`);
+  }
+  lines.push(`})`);
+  return lines.join("\n");
+}
+
+/**
+ * `store.schema.policy(...)` source for Console copy-as-code.
+ *
+ * @param spec - Validated policy
+ */
+export function emitStoreSchemaPolicySource(spec: SqlPolicySpec): string {
+  const to =
+    spec.roles.length === 1
+      ? JSON.stringify(formatEmitRole(spec.roles[0]!))
+      : `[${spec.roles.map((role) => JSON.stringify(formatEmitRole(role))).join(", ")}]`;
+  const lines = [
+    `store.schema.policy(${JSON.stringify(spec.name)}, {`,
+    `  as: ${JSON.stringify(spec.behavior.toLowerCase())},`,
+    `  to: ${to},`,
+    `  for: ${JSON.stringify(spec.command.toLowerCase())},`,
+  ];
+  if (spec.using !== undefined && spec.using.trim() !== "") {
+    lines.push(`  using: ${JSON.stringify(spec.using.trim())},`);
+  }
+  if (spec.withCheck !== undefined && spec.withCheck.trim() !== "") {
+    lines.push(`  withCheck: ${JSON.stringify(spec.withCheck.trim())},`);
+  }
+  lines.push(`})`);
+  return lines.join("\n");
+}
+
+function formatEmitRole(role: string): string {
+  return SPECIAL_POLICY_ROLES.has(role.toLowerCase()) ? role.toLowerCase() : role;
+}
+
+function escapeSqlTemplate(expr: string): string {
+  return expr.replaceAll("\\", "\\\\").replaceAll("`", "\\`");
+}
+
+/** One statement in the RLS identity prelude (never a multi-command batch). */
+export type RlsPreludeStatement = {
+  readonly sql: string;
+  readonly params?: readonly string[];
+};
+
+/**
+ * Per-statement identity frame (no user SQL, no `BEGIN`).
+ *
+ * The caller pins these to one backend connection via `SqlConnection.transaction`.
+ * PGlite's `query` path is prepared statements and rejects `BEGIN; SET; SELECT`
+ * as one script.
+ *
+ * @param identity - Gate principal
+ */
+export function buildRlsIdentityPreludeSql(identity: RlsIdentity): readonly RlsPreludeStatement[] {
+  return [
+    { sql: `SET LOCAL ROLE ${OKE_RLS_ROLE}` },
+    { sql: "SET LOCAL row_security = on" },
+    {
+      sql: `SELECT set_config('oke.gate', ?, true), set_config('oke.user', ?, true), set_config('oke.scopes', ?, true)`,
+      params: [identity.gate, identity.userId, rlsScopesJson(identity.scopes)],
+    },
+  ];
+}

package/src/drivers/pglite.ts

@@ -77,21 +77,44 @@ export async function connectPglite(options: SqlConnectOptions = {}): Promise<Sq
     resolved === "memory"
       ? await PGlite.create({ extensions: { vector } })
       : await PGlite.create(resolved, { extensions: { vector } });
-  return {
+  const connection: SqlConnection = {
     driverId: "pglite",
     role,
     async query(sql, params = []) {
-      const rs = await db.query<SqlRow>(toPostgresParams(sql), [...params]);
+      const rs = await db.query<SqlRow>(toPostgresParams(sql, params), [...params]);
       return rs.rows;
     },
     async exec(sql, params = []) {
-      const rs = await db.query<SqlRow>(toPostgresParams(sql), [...params]);
+      // Prepared `query` rejects multi-command scripts (`BEGIN; SET; …`).
+      // Param-less SQL uses simple-protocol `exec` (helpers, BEGIN, SET).
+      if (params.length === 0) {
+        const results = await db.exec(sql);
+        const last = results[results.length - 1];
+        return { changes: last?.affectedRows ?? 0 };
+      }
+      const rs = await db.query<SqlRow>(toPostgresParams(sql, params), [...params]);
       return { changes: rs.affectedRows ?? 0 };
     },
+    async transaction(fn) {
+      await db.exec("BEGIN");
+      try {
+        const result = await fn(connection);
+        await db.exec("COMMIT");
+        return result;
+      } catch (err) {
+        try {
+          await db.exec("ROLLBACK");
+        } catch {
+          // Already aborted.
+        }
+        throw err;
+      }
+    },
     async close() {
       await db.close();
     },
   };
+  return connection;
 }
 
 /** Protocol-named pglite driver. */

package/src/drivers/postgres.test.ts

@@ -0,0 +1,23 @@
+/**
+ * Postgres placeholder conversion.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { toPostgresParams } from "./postgres.ts";
+
+describe("toPostgresParams", () => {
+  test("rewrites ? only when values are bound", () => {
+    expect(toPostgresParams("SELECT * FROM t WHERE id = ?", ["a"])).toBe(
+      "SELECT * FROM t WHERE id = $1",
+    );
+    expect(toPostgresParams("INSERT INTO t (a, b) VALUES (?, ?)", [1, 2])).toBe(
+      "INSERT INTO t (a, b) VALUES ($1, $2)",
+    );
+  });
+
+  test("leaves jsonb ? operators unchanged when there are no values", () => {
+    const sql = "SELECT current_setting('oke.scopes', true)::jsonb ? p_scope";
+    expect(toPostgresParams(sql)).toBe(sql);
+    expect(toPostgresParams(sql, [])).toBe(sql);
+  });
+});

package/src/drivers/postgres.ts

@@ -4,7 +4,13 @@
  * Protocol-named: Neon, Supabase, RDS, Timescale all speak postgres.
  */
 
-import type { SqlConnectOptions, SqlConnection, SqlDriver, SqlRow } from "./types.ts";
+import type { SqlConnectOptions, SqlConnection, SqlDriver, SqlRole, SqlRow } from "./types.ts";
+
+/** Bun.SQL client checked out via {@link PostgresClientLike.reserve}. */
+export interface PostgresReservedClient extends PostgresClientLike {
+  /** Return the connection to the pool. */
+  release(): void;
+}
 
 /** Minimal surface we use from Bun.SQL (and test fakes). */
 export interface PostgresClientLike {
@@ -12,15 +18,98 @@ export interface PostgresClientLike {
     sql: string,
     values?: unknown[],
   ): PromiseLike<SqlRow[] | { length: number; changes?: number } | SqlRow[]>;
+  /**
+   * Pin one pooled TCP connection. Required in front of PgDog — `begin()`
+   * then `unsafe()` on the parent client can checkout a second slot and
+   * deadlock the pool (`checkout timeout`).
+   */
+  reserve?(): Promise<PostgresReservedClient>;
+  /**
+   * Reserve one pooled connection for a transaction (Bun.SQL).
+   *
+   * @param fn - Work on the reserved client
+   */
+  begin?<T>(fn: (tx: PostgresClientLike) => Promise<T> | T): Promise<T>;
   close?(options?: { timeout?: number }): Promise<void>;
 }
 
+/** Cap shared Bun.SQL pools so one process cannot outrun PgDog (default 10). */
+export const POSTGRES_POOL_MAX = 8;
+
+const sharedClients = new Map<string, PostgresClientLike>();
+
+/**
+ * Resolve the Postgres URL (injected, `DATABASE_URL`, then localhost).
+ *
+ * @param url - Explicit URL
+ */
+export function resolvePostgresUrl(url?: string): string {
+  return url ?? process.env.DATABASE_URL ?? "postgres://localhost:5432/oke";
+}
+
+/**
+ * One Bun.SQL pool per URL for store / journal / clock / vault / console.
+ *
+ * @param url - Connection URL
+ */
+export function sharedPostgresClient(url?: string): PostgresClientLike {
+  const key = resolvePostgresUrl(url);
+  const existing = sharedClients.get(key);
+  if (existing) return existing;
+  const created = new Bun.SQL(key, { max: POSTGRES_POOL_MAX }) as unknown as PostgresClientLike;
+  sharedClients.set(key, created);
+  return created;
+}
+
+/**
+ * Pin one pooled connection, `BEGIN`, run `fn`, `COMMIT`/`ROLLBACK`, release.
+ *
+ * Prefer `reserve()` — Bun.SQL `begin()` then `unsafe()` on the parent
+ * client can checkout a second slot and deadlock PgDog.
+ *
+ * @param client - Pool or test fake
+ * @param fn - Work on the pinned client
+ */
+export async function withPinnedPostgres<T>(
+  client: PostgresClientLike,
+  fn: (tx: PostgresClientLike) => Promise<T>,
+): Promise<T> {
+  if (typeof client.reserve === "function") {
+    const reserved = await client.reserve();
+    try {
+      await reserved.unsafe("BEGIN");
+      try {
+        const result = await fn(reserved);
+        await reserved.unsafe("COMMIT");
+        return result;
+      } catch (err) {
+        try {
+          await reserved.unsafe("ROLLBACK");
+        } catch {
+          // Already aborted.
+        }
+        throw err;
+      }
+    } finally {
+      reserved.release();
+    }
+  }
+  if (typeof client.begin === "function") {
+    return client.begin(fn);
+  }
+  throw new Error("postgres client needs reserve() or begin() to pin a transaction");
+}
+
 /**
  * Convert `?` placeholders to Postgres `$1…$n`.
+ * Leaves SQL unchanged when there are no bound values so operators
+ * like `jsonb ? key` are not rewritten.
  *
  * @param sql - SQL with `?` placeholders
+ * @param values - Bound values (empty skips conversion)
  */
-export function toPostgresParams(sql: string): string {
+export function toPostgresParams(sql: string, values: readonly unknown[] = []): string {
+  if (values.length === 0) return sql;
   let i = 0;
   return sql.replace(/\?/g, () => `$${++i}`);
 }
@@ -32,21 +121,34 @@ export function toPostgresParams(sql: string): string {
  */
 export async function connectPostgres(options: SqlConnectOptions = {}): Promise<SqlConnection> {
   const role = options.role ?? "primary";
-  const client =
-    (options.client as PostgresClientLike | undefined) ??
-    new Bun.SQL(options.url ?? process.env.DATABASE_URL ?? "postgres://localhost:5432/oke");
+  const injected = options.client as PostgresClientLike | undefined;
+  const client = injected ?? sharedPostgresClient(options.url);
+  return wrapPostgresClient(client, role, { shared: injected === undefined });
+}
 
-  return {
+/**
+ * Bind a Bun.SQL-compatible client as {@link SqlConnection}.
+ *
+ * @param client - Pool or reserved transaction client
+ * @param role - Primary vs replica
+ * @param opts - Shared-pool / already-pinned flags
+ */
+function wrapPostgresClient(
+  client: PostgresClientLike,
+  role: SqlRole,
+  opts: { readonly shared?: boolean; readonly pinned?: boolean } = {},
+): SqlConnection {
+  const connection: SqlConnection = {
     driverId: "postgres",
     role,
     async query(sql, params = []) {
-      const pg = toPostgresParams(sql);
+      const pg = toPostgresParams(sql, params);
       const result = await client.unsafe(pg, [...params]);
       if (Array.isArray(result)) return result as SqlRow[];
       return Array.from(result as ArrayLike<SqlRow>);
     },
     async exec(sql, params = []) {
-      const pg = toPostgresParams(sql);
+      const pg = toPostgresParams(sql, params);
       const result = await client.unsafe(pg, [...params]);
       if (
         result &&
@@ -61,10 +163,15 @@ export async function connectPostgres(options: SqlConnectOptions = {}): Promise<
       }
       return { changes: 0 };
     },
+    async transaction(fn) {
+      if (opts.pinned) return fn(connection);
+      return withPinnedPostgres(client, (tx) => fn(wrapPostgresClient(tx, role, { pinned: true })));
+    },
     async close() {
-      await client.close?.();
+      if (!opts.shared) await client.close?.();
     },
   };
+  return connection;
 }
 
 /**
@@ -82,10 +189,27 @@ export function createPostgresFakeClient(): PostgresClientLike & {
 
   return {
     tables,
+    async begin(fn) {
+      return fn(this);
+    },
+    async reserve() {
+      return Object.assign(this, {
+        release() {
+          /* fake has no pool */
+        },
+      });
+    },
     async unsafe(sql, values = []) {
       const text = sql.trim();
       // Accept both ? (pre-conversion) and $n forms.
       const normalised = text.replace(/\$\d+/g, "?");
+      if (
+        /^(begin|commit|rollback|set\b|select set_config|create\b|grant\b|do\b|alter\b)\b/i.test(
+          normalised,
+        )
+      ) {
+        return [];
+      }
 
       const create =
         /^CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS\s+("?[a-zA-Z_][a-zA-Z0-9_]*"?)\s*\((.+)\)\s*$/i.exec(

package/src/drivers/redis.ts

@@ -140,11 +140,19 @@ function ttlToSeconds(ttl: string): number {
   }
 }
 
+/** Bun 1.4 typed methods — `@types/bun` may lag the runtime. */
+interface BunRedisEval {
+  eval(script: string, numkeys: number, ...keysAndArgs: string[]): Promise<unknown>;
+}
+
+function typedRedis(redis: Bun.RedisClient): Bun.RedisClient & BunRedisEval {
+  return redis as Bun.RedisClient & BunRedisEval;
+}
+
 /**
  * Bind {@link Bun.RedisClient} / {@link Bun.redis} to {@link KvClientLike}.
  *
- * Uses typed `scan` (Bun ≥1.3). `EVAL` still goes through `send` — Bun 1.3.14
- * has no typed `eval` yet (platform limitation, not an OKE stub).
+ * Uses typed `scan` / `eval` (Bun ≥1.4). `send` remains the escape hatch.
  *
  * @param url - Optional Redis URL
  */
@@ -174,8 +182,7 @@ export function createBunRedisClient(url?: string): KvClientLike {
       return redis.scan(cursor);
     },
     async eval(script, numkeys, ...keysAndArgs) {
-      // Bun 1.3.14: no typed eval — raw send remains the native path.
-      return redis.send("EVAL", [script, String(numkeys), ...keysAndArgs]);
+      return typedRedis(redis).eval(script, numkeys, ...keysAndArgs);
     },
     send: (command, args) => redis.send(command, args),
   };

package/src/drivers/signal-redis.ts

@@ -7,7 +7,7 @@
  * 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).
+ * `subscribe` / `xadd` / `xreadgroup` / `xack` / `xgroup` on Bun ≥1.4).
  */
 
 import { createSignalEngine } from "./signal-engine.ts";
@@ -18,12 +18,23 @@ import type {
   SignalRedisClientLike,
 } from "./signal-types.ts";
 
+/** Bun 1.4 typed stream methods — `@types/bun` may lag the runtime. */
+interface BunRedisStreams {
+  xadd(key: string, ...args: (string | number)[]): Promise<unknown>;
+  xreadgroup(...args: (string | number)[]): Promise<unknown>;
+  xack(key: string, group: string, id: string): Promise<unknown>;
+  xgroup(subcommand: string, ...args: (string | number)[]): Promise<unknown>;
+}
+
+function typedStreams(redis: Bun.RedisClient): Bun.RedisClient & BunRedisStreams {
+  return redis as Bun.RedisClient & BunRedisStreams;
+}
+
 /**
  * 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).
+ * Streams use typed `xadd` / `xgroup` / `xreadgroup` / `xack` (Bun ≥1.4).
+ * Pub/sub uses typed `publish` / `subscribe`.
  *
  * @param url - Optional Redis URL
  */
@@ -41,37 +52,36 @@ export function createBunSignalRedisClient(url?: string): SignalRedisClientLike
 
   return {
     async xadd(key, id, fields) {
-      const args: string[] = [key, id];
+      const pairs: string[] = [];
       for (const [k, v] of Object.entries(fields)) {
-        args.push(k, v);
+        pairs.push(k, v);
       }
-      return String(await redis.send("XADD", args));
+      return String(await typedStreams(redis).xadd(key, id, ...pairs));
     },
     async xgroupCreate(key, group, id, opts) {
-      const args = ["CREATE", key, group, id];
-      if (opts?.mkstream) args.push("MKSTREAM");
+      const extra = opts?.mkstream ? (["MKSTREAM"] as const) : [];
       try {
-        await redis.send("XGROUP", args);
+        await typedStreams(redis).xgroup("CREATE", key, group, id, ...extra);
       } 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", [
+      const reply = await typedStreams(redis).xreadgroup(
         "GROUP",
         group,
         consumer,
         "COUNT",
-        String(count),
+        count,
         "STREAMS",
         key,
         ">",
-      ]);
+      );
       return parseXreadgroupReply(reply);
     },
     async xack(key, group, id) {
-      return Number(await redis.send("XACK", [key, group, id]));
+      return Number(await typedStreams(redis).xack(key, group, id));
     },
     async publish(channel, message) {
       return redis.publish(channel, message);

package/src/drivers/signal-types.ts

@@ -69,8 +69,9 @@ export interface SignalMessage {
 }
 
 /** Dead-letter entry with full attempt history. */
-export interface DeadLetter extends SignalMessage {
+export interface DeadLetter<T = unknown> extends Omit<SignalMessage, "payload" | "status"> {
   readonly status: "dead";
+  readonly payload: T;
 }
 
 /** Per-subscriber lag / errors (broadcast physics). */