okengine 0.10.2 → 0.11.0

package/src/elements/vault/declare.ts

@@ -4,7 +4,7 @@
  * Physics: secrets · config · environment.
  */
 
-import { secretRegistry } from "../../kernel/element-registries.ts";
+import { requiredEnvRegistry, secretRegistry } from "../../kernel/element-registries.ts";
 
 /** Options for {@link vault} / {@link vault.secret} / {@link vault.config}. */
 export interface VaultSecretOptions {
@@ -105,6 +105,163 @@ function declareConfig(name: string, options: VaultSecretOptions = {}): VaultSec
   };
 }
 
+/**
+ * Synchronous environment-variable helpers on `vault.env`.
+ *
+ * Plain process configuration — no boot chain, no driver, no redaction.
+ * Reach for {@link vault.secret} when the value is a contract the runtime
+ * must resolve, fingerprint, and keep out of logs.
+ */
+export interface VaultEnvApi {
+  /**
+   * Raw value, or `undefined` when unset / empty.
+   *
+   * @param name - Environment variable name
+   */
+  (name: string): string | undefined;
+  /**
+   * Value that must exist. Registers `name` so boot reports every missing
+   * variable at once alongside secret gaps.
+   *
+   * @param name - Environment variable name
+   * @throws TypeError when the variable is unset or empty
+   */
+  required(name: string): string;
+  /**
+   * Integer value.
+   *
+   * @param name - Environment variable name
+   * @param defaultValue - Used when the variable is unset or empty
+   * @throws TypeError when missing without a default, or not an integer
+   */
+  int(name: string, defaultValue?: number): number;
+  /**
+   * Boolean value (`1`/`true`/`yes`/`on` · `0`/`false`/`no`/`off`).
+   *
+   * @param name - Environment variable name
+   * @param defaultValue - Used when the variable is unset or empty
+   * @throws TypeError when missing without a default, or not boolean-shaped
+   */
+  bool(name: string, defaultValue?: boolean): boolean;
+  /**
+   * JSON-parsed value, or `undefined` when unset / empty.
+   *
+   * @param name - Environment variable name
+   * @throws TypeError when the value is not valid JSON
+   */
+  json<T = unknown>(name: string): T | undefined;
+}
+
+/**
+ * Read one environment variable, treating empty strings as unset.
+ *
+ * @param name - Environment variable name
+ */
+export function readEnv(name: string): string | undefined {
+  const value =
+    (typeof Bun !== "undefined" ? Bun.env[name] : undefined) ?? process.env[name] ?? undefined;
+  return value === undefined || value.length === 0 ? undefined : value;
+}
+
+/**
+ * Snapshot of every name passed to {@link vault.env.required} since the last
+ * reset. Boot turns the missing ones into {@link VaultGap}s.
+ */
+export function listRequiredEnvNames(): readonly string[] {
+  return requiredEnvRegistry.slice();
+}
+
+/**
+ * Clear the required-env registry (tests / fresh app adopt).
+ *
+ * @internal
+ */
+export function resetRequiredEnvNames(): void {
+  requiredEnvRegistry.length = 0;
+}
+
+/**
+ * @param name - Environment variable name
+ */
+function envValue(name: string): string | undefined {
+  if (!name) throw new TypeError("vault.env: name is required");
+  return readEnv(name);
+}
+
+/**
+ * @param name - Environment variable name
+ */
+function envRequired(name: string): string {
+  if (!name) throw new TypeError("vault.env.required: name is required");
+  if (!requiredEnvRegistry.includes(name)) requiredEnvRegistry.push(name);
+  const value = readEnv(name);
+  if (value === undefined) {
+    throw new TypeError(`vault.env.required: ${name} is not set`);
+  }
+  return value;
+}
+
+/**
+ * @param name - Environment variable name
+ * @param defaultValue - Used when the variable is unset
+ */
+function envInt(name: string, defaultValue?: number): number {
+  const raw = envValue(name);
+  if (raw === undefined) {
+    if (defaultValue === undefined) {
+      throw new TypeError(`vault.env.int: ${name} is not set and has no default`);
+    }
+    return defaultValue;
+  }
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed)) {
+    throw new TypeError(`vault.env.int: ${name} is not an integer`);
+  }
+  return parsed;
+}
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+const FALSE_VALUES = new Set(["0", "false", "no", "off"]);
+
+/**
+ * @param name - Environment variable name
+ * @param defaultValue - Used when the variable is unset
+ */
+function envBool(name: string, defaultValue?: boolean): boolean {
+  const raw = envValue(name);
+  if (raw === undefined) {
+    if (defaultValue === undefined) {
+      throw new TypeError(`vault.env.bool: ${name} is not set and has no default`);
+    }
+    return defaultValue;
+  }
+  const normalized = raw.trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) return true;
+  if (FALSE_VALUES.has(normalized)) return false;
+  throw new TypeError(`vault.env.bool: ${name} is not a boolean (got "${raw}")`);
+}
+
+/**
+ * @param name - Environment variable name
+ */
+function envJson<T = unknown>(name: string): T | undefined {
+  const raw = envValue(name);
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    throw new TypeError(`vault.env.json: ${name} is not valid JSON`);
+  }
+}
+
+/** Sync env helpers exposed as {@link vault.env}. */
+export const vaultEnvApi: VaultEnvApi = Object.assign(envValue, {
+  required: envRequired,
+  int: envInt,
+  bool: envBool,
+  json: envJson,
+});
+
 /**
  * Marker prefix for {@link vault.fromDocker} local fallbacks.
  * Resolved from `docker/.env.docker` by `oke dev --docker` / vault boot.
@@ -144,18 +301,22 @@ export function fromDockerRole(value: string): string {
 }
 
 /**
- * Vault element — `vault("NAME", opts)` · `vault.secret` · `vault.config`.
+ * Vault element — `vault("NAME", opts)` · `vault.secret` · `vault.config`
+ * · `vault.env`.
  *
  * A declaration is a contract, not a value. Values resolve at boot through
- * the configured driver chain.
+ * the configured driver chain. `vault.env` is the escape hatch for plain
+ * process configuration that needs no contract.
  */
 export const vault: {
   (name: string, options?: VaultSecretOptions): VaultSecretDecl;
   secret(name: string, options?: VaultSecretOptions): VaultSecretDecl;
   config(name: string, options?: VaultSecretOptions): VaultSecretDecl;
   fromDocker(role: string): string;
+  env: VaultEnvApi;
 } = Object.assign(declareSecret, {
   secret: declareSecret,
   config: declareConfig,
   fromDocker,
+  env: vaultEnvApi,
 });

package/src/elements/vault/errors.ts

@@ -0,0 +1,56 @@
+/**
+ * Vault error taxonomy — one class, one closed code union.
+ *
+ * `VaultError` deliberately never carries a `cause`. An underlying driver or
+ * Web Crypto error can hold key material, ciphertext, or plaintext in its
+ * message or attached buffers; re-throwing it would leak that material into
+ * logs and traces. Callers translate foreign errors into a code + a message
+ * they authored themselves.
+ */
+
+/** Closed set of Vault failure reasons. */
+export type VaultErrorCode =
+  | "SEALED"
+  | "NOT_INITIALIZED"
+  | "SECRET_NOT_FOUND"
+  | "INVALID_KEY"
+  | "ALREADY_INITIALIZED"
+  | "READONLY"
+  | "EXPIRED"
+  | "PERMISSION_DENIED"
+  | "BACKEND_ERROR"
+  | "INVALID_PATH"
+  | "UNSUPPORTED"
+  | "MISSING_PEER";
+
+/**
+ * Vault failure with a machine-readable {@link VaultErrorCode}.
+ *
+ * Never attach a `cause`: upstream crypto/driver errors may hold secret
+ * material. Author a safe message instead.
+ */
+export class VaultError extends Error {
+  /** Machine-readable reason. */
+  readonly code: VaultErrorCode;
+
+  /**
+   * @param code - Machine-readable reason
+   * @param message - Safe, secret-free description
+   */
+  constructor(code: VaultErrorCode, message: string) {
+    super(message);
+    this.name = "VaultError";
+    this.code = code;
+  }
+}
+
+/**
+ * Whether a value is a {@link VaultError} (optionally of a specific code).
+ *
+ * @param value - Candidate
+ * @param code - Narrow to a single code
+ */
+export function isVaultError(value: unknown, code?: VaultErrorCode): value is VaultError {
+  if (!(value instanceof VaultError)) return false;
+  return code === undefined || value.code === code;
+}

package/src/elements/vault/kms-unseal.test.ts

@@ -0,0 +1,76 @@
+/**
+ * KMS unseal — injected seams, key hygiene, and the missing-peer message.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { deriveVerifyHash, generateMasterKey, MASTER_KEY_BYTES } from "./crypto.ts";
+import { isVaultError } from "./errors.ts";
+import { createAwsKmsUnsealer, wrapMasterWithAwsKms } from "./kms-unseal.ts";
+
+const WRAPPED = Uint8Array.from([0xde, 0xad, 0xbe, 0xef]);
+
+describe("aws kms unseal", () => {
+  test("an injected decrypt yields a working unsealer", async () => {
+    const masterKey = generateMasterKey();
+    const unsealer = await createAwsKmsUnsealer({
+      keyId: "alias/oke-vault",
+      wrappedMaster: WRAPPED,
+      decryptFn: async (ciphertext) => {
+        expect([...ciphertext]).toEqual([...WRAPPED]);
+        return Uint8Array.from(masterKey);
+      },
+    });
+
+    expect(unsealer.sealed).toBe(false);
+    expect(await unsealer.verifyHash()).toBe(await deriveVerifyHash(masterKey));
+    unsealer.seal();
+    expect(unsealer.sealed).toBe(true);
+  });
+
+  test("the plaintext handed back by kms is zeroed after import", async () => {
+    const masterKey = generateMasterKey();
+    const plaintext = Uint8Array.from(masterKey);
+    const unsealer = await createAwsKmsUnsealer({
+      keyId: "alias/oke-vault",
+      wrappedMaster: WRAPPED,
+      decryptFn: async () => plaintext,
+    });
+
+    expect([...plaintext]).toEqual(new Array<number>(MASTER_KEY_BYTES).fill(0));
+    // The unsealer kept its own copy, so it still derives the real hash.
+    expect(await unsealer.verifyHash()).toBe(await deriveVerifyHash(masterKey));
+  });
+
+  test("a wrong-length plaintext is rejected", async () => {
+    const failure = await createAwsKmsUnsealer({
+      keyId: "alias/oke-vault",
+      wrappedMaster: WRAPPED,
+      decryptFn: async () => new Uint8Array(16),
+    }).catch((e: unknown) => e);
+
+    expect(isVaultError(failure, "INVALID_KEY")).toBe(true);
+  });
+
+  test("wrapMasterWithAwsKms uses the injected encrypt and checks key length", async () => {
+    const masterKey = generateMasterKey();
+    const blob = await wrapMasterWithAwsKms("alias/oke-vault", masterKey, {
+      encryptFn: async (plaintext) => Uint8Array.from([1, ...plaintext]),
+    });
+
+    expect(blob).toHaveLength(MASTER_KEY_BYTES + 1);
+    const failure = await wrapMasterWithAwsKms("alias/oke-vault", new Uint8Array(8), {
+      encryptFn: async (plaintext) => plaintext,
+    }).catch((e: unknown) => e);
+    expect(isVaultError(failure, "INVALID_KEY")).toBe(true);
+  });
+
+  test("without the optional peer the failure names the install command", async () => {
+    const failure = await createAwsKmsUnsealer({
+      keyId: "alias/oke-vault",
+      wrappedMaster: WRAPPED,
+    }).catch((e: unknown) => e);
+
+    expect(isVaultError(failure, "MISSING_PEER")).toBe(true);
+    expect((failure as Error).message).toContain("bun add @aws-sdk/client-kms");
+  });
+});

package/src/elements/vault/kms-unseal.ts

@@ -0,0 +1,181 @@
+/**
+ * AWS KMS unseal path — the master key never exists outside KMS at rest.
+ *
+ * At init the plaintext master key is sent to KMS `Encrypt` once; the
+ * returned ciphertext blob is what gets stored (`oke_vault_master.wrapped_master`).
+ * At boot the blob goes back to KMS `Decrypt` and the plaintext is handed
+ * straight to an {@link Unsealer}, then zeroed — it is never written to disk,
+ * an environment variable, or a log.
+ *
+ * `@aws-sdk/client-kms` is an optional peer, imported dynamically so a
+ * project that unseals from `env` or a file never pays for it. Tests inject
+ * `decryptFn` / `encryptFn` and skip the SDK entirely.
+ */
+
+import { MASTER_KEY_BYTES, zeroBytes } from "./crypto.ts";
+import { VaultError } from "./errors.ts";
+import { createEnvUnsealer, type Unsealer } from "./unseal.ts";
+
+/** Package name of the optional peer, resolved at call time. */
+const KMS_PACKAGE = "@aws-sdk/client-kms";
+
+/** Options for {@link createAwsKmsUnsealer}. */
+export interface CreateAwsKmsUnsealerOptions {
+  /** KMS key id, alias, or ARN that wrapped the master key. */
+  readonly keyId: string;
+  /** Ciphertext blob returned by {@link wrapMasterWithAwsKms}. */
+  readonly wrappedMaster: Uint8Array;
+  /** AWS region. Falls back to the SDK's own resolution chain. */
+  readonly region?: string;
+  /** Decrypt seam for tests — skips the SDK import entirely. */
+  readonly decryptFn?: (ciphertext: Uint8Array) => Promise<Uint8Array>;
+}
+
+/** Options for {@link wrapMasterWithAwsKms}. */
+export interface WrapMasterWithAwsKmsOptions {
+  /** AWS region. Falls back to the SDK's own resolution chain. */
+  readonly region?: string;
+  /** Encrypt seam for tests — skips the SDK import entirely. */
+  readonly encryptFn?: (plaintext: Uint8Array) => Promise<Uint8Array>;
+}
+
+/** KMS response fields this module reads. */
+interface KmsResult {
+  readonly Plaintext?: Uint8Array;
+  readonly CiphertextBlob?: Uint8Array;
+}
+
+/** Structural client interface — the SDK's `KMSClient` satisfies it. */
+interface KmsClientLike {
+  send(command: unknown): Promise<KmsResult>;
+  destroy?(): void;
+}
+
+/** Constructors pulled off the dynamically imported module. */
+interface KmsBindings {
+  readonly KMSClient: new (config: { region?: string }) => KmsClientLike;
+  readonly DecryptCommand: new (input: { KeyId: string; CiphertextBlob: Uint8Array }) => unknown;
+  readonly EncryptCommand: new (input: { KeyId: string; Plaintext: Uint8Array }) => unknown;
+}
+
+/**
+ * Unseal from a KMS-wrapped master key.
+ *
+ * @param opts - Key id, wrapped blob, region, and the test decrypt seam
+ * @throws VaultError `MISSING_PEER` when `@aws-sdk/client-kms` is absent
+ * @throws VaultError `INVALID_KEY` when KMS returns something other than 32 bytes
+ */
+export async function createAwsKmsUnsealer(opts: CreateAwsKmsUnsealerOptions): Promise<Unsealer> {
+  const decrypt = opts.decryptFn ?? (await bindDecrypt(opts.keyId, opts.region));
+  const plaintext = await decrypt(opts.wrappedMaster);
+  try {
+    if (plaintext.byteLength !== MASTER_KEY_BYTES) {
+      throw new VaultError(
+        "INVALID_KEY",
+        `vault: kms master key must be ${MASTER_KEY_BYTES} bytes`,
+      );
+    }
+    return createEnvUnsealer(plaintext);
+  } finally {
+    zeroBytes(plaintext);
+  }
+}
+
+/**
+ * Wrap a freshly generated master key with KMS for storage at init.
+ *
+ * The caller still owns `masterKey` and must zero it afterwards.
+ *
+ * @param keyId - KMS key id, alias, or ARN
+ * @param masterKey - Raw 32-byte master key
+ * @param opts - Region and the test encrypt seam
+ * @throws VaultError `MISSING_PEER` when `@aws-sdk/client-kms` is absent
+ */
+export async function wrapMasterWithAwsKms(
+  keyId: string,
+  masterKey: Uint8Array,
+  opts: WrapMasterWithAwsKmsOptions = {},
+): Promise<Uint8Array> {
+  if (masterKey.byteLength !== MASTER_KEY_BYTES) {
+    throw new VaultError("INVALID_KEY", `vault: master key must be ${MASTER_KEY_BYTES} bytes`);
+  }
+  if (opts.encryptFn) return opts.encryptFn(masterKey);
+
+  const { KMSClient, EncryptCommand } = await loadKms();
+  const client = new KMSClient(opts.region === undefined ? {} : { region: opts.region });
+  try {
+    const result = await client.send(new EncryptCommand({ KeyId: keyId, Plaintext: masterKey }));
+    const blob = result.CiphertextBlob;
+    if (!blob || blob.byteLength === 0) {
+      throw new VaultError("BACKEND_ERROR", "vault: kms returned an empty ciphertext blob");
+    }
+    return new Uint8Array(blob);
+  } catch (error) {
+    if (error instanceof VaultError) throw error;
+    // Never surface the SDK error: it can echo request payloads.
+    throw new VaultError("BACKEND_ERROR", "vault: kms encrypt failed");
+  } finally {
+    client.destroy?.();
+  }
+}
+
+/**
+ * Build a decrypt closure backed by a real KMS client.
+ *
+ * @param keyId - KMS key id, alias, or ARN
+ * @param region - AWS region
+ */
+async function bindDecrypt(
+  keyId: string,
+  region: string | undefined,
+): Promise<(ciphertext: Uint8Array) => Promise<Uint8Array>> {
+  const { KMSClient, DecryptCommand } = await loadKms();
+  return async (ciphertext: Uint8Array) => {
+    const client = new KMSClient(region === undefined ? {} : { region });
+    try {
+      const result = await client.send(
+        new DecryptCommand({ KeyId: keyId, CiphertextBlob: ciphertext }),
+      );
+      const plaintext = result.Plaintext;
+      if (!plaintext || plaintext.byteLength === 0) {
+        throw new VaultError("BACKEND_ERROR", "vault: kms returned an empty plaintext");
+      }
+      return new Uint8Array(plaintext);
+    } catch (error) {
+      if (error instanceof VaultError) throw error;
+      // Never surface the SDK error: it can echo key material or ciphertext.
+      throw new VaultError("BACKEND_ERROR", "vault: kms decrypt failed");
+    } finally {
+      client.destroy?.();
+    }
+  };
+}
+
+/**
+ * Import the optional `@aws-sdk/client-kms` peer.
+ *
+ * @throws VaultError `MISSING_PEER` with the exact install command
+ */
+async function loadKms(): Promise<KmsBindings> {
+  // Indirect specifier: the peer is optional, so it must not become a
+  // static dependency of the module graph.
+  const specifier: string = KMS_PACKAGE;
+  let mod: unknown;
+  try {
+    mod = await import(specifier);
+  } catch {
+    throw new VaultError("MISSING_PEER", `Install peer: bun add ${KMS_PACKAGE}`);
+  }
+  const bindings = mod as Partial<KmsBindings>;
+  if (!bindings.KMSClient || !bindings.DecryptCommand || !bindings.EncryptCommand) {
+    throw new VaultError(
+      "MISSING_PEER",
+      `vault: \`${KMS_PACKAGE}\` is installed but does not export KMSClient / DecryptCommand / EncryptCommand`,
+    );
+  }
+  return {
+    KMSClient: bindings.KMSClient,
+    DecryptCommand: bindings.DecryptCommand,
+    EncryptCommand: bindings.EncryptCommand,
+  };
+}

package/src/elements/vault/path.ts

@@ -0,0 +1,90 @@
+/**
+ * Vault path canonicalization.
+ *
+ * A path is a slash-separated key with **no** leading or trailing slash:
+ * `prod/api/stripe`. Canonicalization runs before every read, write, and
+ * audit row so the same logical secret always hashes into the same AAD.
+ */
+
+import { VaultError } from "./errors.ts";
+
+/** Maximum canonical path length in UTF-16 code units. */
+export const MAX_VAULT_PATH_LENGTH = 512;
+
+/**
+ * Normalize and validate a Vault path.
+ *
+ * Trims surrounding whitespace, strips leading/trailing slashes, and
+ * collapses duplicate separators. Rejects empty paths, `..` traversal,
+ * NUL bytes, backslashes, and anything longer than
+ * {@link MAX_VAULT_PATH_LENGTH}.
+ *
+ * @param input - Raw path from a caller
+ * @throws VaultError `INVALID_PATH` when the path cannot be canonicalized
+ */
+export function canonicalizePath(input: string): string {
+  if (typeof input !== "string") {
+    throw new VaultError("INVALID_PATH", "vault: path must be a string");
+  }
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new VaultError("INVALID_PATH", "vault: path must not be empty");
+  }
+  if (trimmed.length > MAX_VAULT_PATH_LENGTH) {
+    throw new VaultError("INVALID_PATH", `vault: path exceeds ${MAX_VAULT_PATH_LENGTH} characters`);
+  }
+  if (trimmed.includes("\0")) {
+    throw new VaultError("INVALID_PATH", "vault: path must not contain NUL bytes");
+  }
+  if (trimmed.includes("\\")) {
+    throw new VaultError("INVALID_PATH", "vault: path must not contain backslashes");
+  }
+
+  const segments: string[] = [];
+  for (const raw of trimmed.split("/")) {
+    const segment = raw.trim();
+    if (segment.length === 0) continue;
+    if (segment === ".") {
+      throw new VaultError("INVALID_PATH", 'vault: path must not contain "." segments');
+    }
+    if (segment === "..") {
+      throw new VaultError("INVALID_PATH", 'vault: path must not contain ".." segments');
+    }
+    segments.push(segment);
+  }
+
+  if (segments.length === 0) {
+    throw new VaultError("INVALID_PATH", "vault: path must contain at least one segment");
+  }
+
+  const canonical = segments.join("/");
+  if (canonical.length > MAX_VAULT_PATH_LENGTH) {
+    throw new VaultError("INVALID_PATH", `vault: path exceeds ${MAX_VAULT_PATH_LENGTH} characters`);
+  }
+  return canonical;
+}
+
+/**
+ * Canonicalize a prefix filter for list queries.
+ *
+ * Unlike {@link canonicalizePath}, an empty prefix is legal and means
+ * "every path".
+ *
+ * @param input - Raw prefix, or `undefined` for no filter
+ */
+export function canonicalizePrefix(input: string | undefined): string | undefined {
+  if (input === undefined) return undefined;
+  const trimmed = input.trim();
+  if (trimmed.length === 0 || trimmed === "/") return undefined;
+  return canonicalizePath(trimmed);
+}
+
+/**
+ * Whether a canonical path sits under a canonical prefix.
+ *
+ * @param path - Canonical path
+ * @param prefix - Canonical prefix
+ */
+export function pathHasPrefix(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}

package/src/elements/vault/resilience.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Unit tests for Vault SQL resilience (retry / no-retry).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  createResilientSqlExec,
+  DEFAULT_RETRY,
+  isRetryableError,
+  withResilience,
+  type RetryConfig,
+} from "./resilience.ts";
+import type { SqlExec } from "./storage.ts";
+
+const FAST: RetryConfig = {
+  ...DEFAULT_RETRY,
+  baseDelayMs: 1,
+  maxDelayMs: 2,
+};
+
+describe("isRetryableError", () => {
+  test("matches known connection codes", () => {
+    expect(isRetryableError({ code: "ECONNRESET" })).toBe(true);
+    expect(isRetryableError({ code: "08006" })).toBe(true);
+    expect(isRetryableError(new Error("connect ETIMEDOUT"))).toBe(true);
+  });
+
+  test("rejects business / unknown errors", () => {
+    expect(isRetryableError(new Error("INVALID_PATH"))).toBe(false);
+    expect(isRetryableError({ code: "42P01" })).toBe(false);
+    expect(isRetryableError(null)).toBe(false);
+  });
+});
+
+describe("withResilience", () => {
+  test("retries retryable failures then succeeds", async () => {
+    let attempts = 0;
+    const value = await withResilience(async () => {
+      attempts += 1;
+      if (attempts < 3) {
+        const err = new Error("connection reset");
+        (err as { code?: string }).code = "ECONNRESET";
+        throw err;
+      }
+      return "ok";
+    }, FAST);
+    expect(value).toBe("ok");
+    expect(attempts).toBe(3);
+  });
+
+  test("exhausts retries then fails", async () => {
+    let attempts = 0;
+    await expect(
+      withResilience(
+        async () => {
+          attempts += 1;
+          const err = new Error("gone");
+          (err as { code?: string }).code = "57P01";
+          throw err;
+        },
+        { ...FAST, maxRetries: 3 },
+      ),
+    ).rejects.toMatchObject({ code: "57P01" });
+    // First try + 3 retries.
+    expect(attempts).toBe(4);
+  });
+
+  test("non-retryable errors fail immediately", async () => {
+    let attempts = 0;
+    await expect(
+      withResilience(async () => {
+        attempts += 1;
+        throw new Error("INVALID_PATH");
+      }, FAST),
+    ).rejects.toThrow("INVALID_PATH");
+    expect(attempts).toBe(1);
+  });
+});
+
+describe("createResilientSqlExec", () => {
+  test("wraps query with the same retry policy", async () => {
+    let attempts = 0;
+    const raw: SqlExec = {
+      async query<T>() {
+        attempts += 1;
+        if (attempts === 1) {
+          const err = new Error("blip");
+          (err as { code?: string }).code = "ETIMEDOUT";
+          throw err;
+        }
+        return [{ id: 1 }] as T[];
+      },
+      async execute() {
+        /* unused */
+      },
+    };
+    const db = createResilientSqlExec(raw, FAST);
+    const rows = await db.query<{ id: number }>("SELECT 1");
+    expect(rows).toEqual([{ id: 1 }]);
+    expect(attempts).toBe(2);
+  });
+});