better-ship 0.16.0 → 0.17.0

package/dist/cloudflare/kv-client.d.ts

@@ -0,0 +1,31 @@
+//#region src/infrastructure/cloudflare/kv-client.d.ts
+/** Text storage bridge with the same TTL behavior as KVClient. */
+export type KVSecondaryStorage = {
+  get: (key: string) => Promise<string | null>;
+  set: (key: string, value: string, ttl?: number) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+};
+/** KV access with Typist's automatic transient retries and final KVError conversion. */
+export declare class KVClient {
+  private readonly kv;
+  constructor(kv: KVNamespace);
+  /** Read text, or return null when the key does not exist. */
+  get(key: string): Promise<string | null>;
+  /** Read JSON without schema validation; the caller supplies its stored type. */
+  getJson<T>(key: string): Promise<T | null>;
+  /** Write text; positive TTL values pass to KV in seconds, and other TTL values omit expiration. */
+  put(key: string, value: string, options?: {
+    ttl?: number | undefined;
+  }): Promise<void>;
+  /** Serialize once before writing; serialization failures retain their original error. */
+  putJson(key: string, value: unknown, options?: {
+    ttl?: number | undefined;
+  }): Promise<void>;
+  /** Delete a key; a missing key succeeds, and transient failures retry automatically. */
+  delete(key: string): Promise<void>;
+  /** Expose Typist's three-method secondary storage bridge without changing KV semantics. */
+  asSecondaryStorage(): KVSecondaryStorage;
+  private run;
+}
+//#endregion
+//# sourceMappingURL=kv-client.d.ts.map

package/dist/cloudflare/kv-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-client.d.ts","names":[],"sources":["../../src/infrastructure/cloudflare/kv-client.ts"],"mappings":";;YAOY;EACV,MAAM,gBAAgB;EACtB,MAAM,aAAa,eAAe,iBAAiB;EACnD,SAAS,gBAAgB;;;qBAMd;mBACkB;EAA7B,YAA6B,IAAI;;EAG3B,IAAI,cAAc;;EAKlB,QAAQ,GAAG,cAAc,QAAQ;;EAKjC,IAAI,aAAa,eAAe;IAAY;MAA6B;;EASzE,QACJ,aAEA,gBACA;IAAY;MACX;;EAKG,OAAO,cAAc;;EAK3B,sBAAsB;UAQR"}

package/dist/cloudflare/kv-client.js

@@ -0,0 +1,62 @@
+import { c as exponentialDelayCapMs, u as spreadJitterMs } from "../core-ClSP5-V9.js";
+import { KVError, decideKVRetry, isKVPutRateLimitError } from "./kv-errors.js";
+import { Result } from "better-result";
+
+//#region src/infrastructure/cloudflare/kv-client.ts
+/** KV access with Typist's automatic transient retries and final KVError conversion. */
+var KVClient = class {
+	kv;
+	constructor(kv) {
+		this.kv = kv;
+	}
+	/** Read text, or return null when the key does not exist. */
+	async get(key) {
+		return await this.run("get", key, async () => this.kv.get(key));
+	}
+	/** Read JSON without schema validation; the caller supplies its stored type. */
+	async getJson(key) {
+		return await this.run("get", key, async () => this.kv.get(key, "json"));
+	}
+	/** Write text; positive TTL values pass to KV in seconds, and other TTL values omit expiration. */
+	async put(key, value, options) {
+		const kvOptions = {};
+		if (options?.ttl !== void 0 && options.ttl > 0) kvOptions.expirationTtl = options.ttl;
+		await this.run("put", key, async () => this.kv.put(key, value, kvOptions));
+	}
+	/** Serialize once before writing; serialization failures retain their original error. */
+	async putJson(key, value, options) {
+		await this.put(key, JSON.stringify(value), options);
+	}
+	/** Delete a key; a missing key succeeds, and transient failures retry automatically. */
+	async delete(key) {
+		await this.run("delete", key, async () => this.kv.delete(key));
+	}
+	/** Expose Typist's three-method secondary storage bridge without changing KV semantics. */
+	asSecondaryStorage() {
+		return {
+			get: (key) => this.get(key),
+			set: (key, value, ttl) => this.put(key, value, { ttl }),
+			delete: (key) => this.delete(key)
+		};
+	}
+	async run(operation, key, work) {
+		const result = await Result.tryPromise({
+			try: work,
+			catch: (cause) => cause
+		}, { retry: {
+			times: 2,
+			shouldRetry: (cause) => decideKVRetry(cause).retry,
+			delayMs: (cause, { attempt }) => (isKVPutRateLimitError(cause) ? 1e3 : 0) + spreadJitterMs(exponentialDelayCapMs(25, 3e3, attempt))
+		} });
+		if (result.isOk()) return result.value;
+		throw new KVError({
+			operation,
+			key,
+			cause: result.error
+		});
+	}
+};
+
+//#endregion
+export { KVClient };
+//# sourceMappingURL=kv-client.js.map

package/dist/cloudflare/kv-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-client.js","names":[],"sources":["../../src/infrastructure/cloudflare/kv-client.ts"],"sourcesContent":["import { Result } from 'better-result'\n\nimport { exponentialDelayCapMs, spreadJitterMs } from '@/core'\n\nimport { decideKVRetry, isKVPutRateLimitError, KVError } from './kv-errors.ts'\n\n/** Text storage bridge with the same TTL behavior as KVClient. */\nexport type KVSecondaryStorage = {\n  get: (key: string) => Promise<string | null>\n  set: (key: string, value: string, ttl?: number) => Promise<void>\n  delete: (key: string) => Promise<void>\n}\n\ntype KVOperation = 'get' | 'put' | 'delete'\n\n/** KV access with Typist's automatic transient retries and final KVError conversion. */\nexport class KVClient {\n  constructor(private readonly kv: KVNamespace) {}\n\n  /** Read text, or return null when the key does not exist. */\n  async get(key: string): Promise<string | null> {\n    return await this.run('get', key, async () => this.kv.get(key))\n  }\n\n  /** Read JSON without schema validation; the caller supplies its stored type. */\n  async getJson<T>(key: string): Promise<T | null> {\n    return await this.run('get', key, async () => this.kv.get<T>(key, 'json'))\n  }\n\n  /** Write text; positive TTL values pass to KV in seconds, and other TTL values omit expiration. */\n  async put(key: string, value: string, options?: { ttl?: number | undefined }): Promise<void> {\n    const kvOptions: KVNamespacePutOptions = {}\n    if (options?.ttl !== undefined && options.ttl > 0) {\n      kvOptions.expirationTtl = options.ttl\n    }\n    await this.run('put', key, async () => this.kv.put(key, value, kvOptions))\n  }\n\n  /** Serialize once before writing; serialization failures retain their original error. */\n  async putJson(\n    key: string,\n    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Preserve the approved JSON serialization boundary and Typist's public signature.\n    value: unknown,\n    options?: { ttl?: number | undefined },\n  ): Promise<void> {\n    await this.put(key, JSON.stringify(value), options)\n  }\n\n  /** Delete a key; a missing key succeeds, and transient failures retry automatically. */\n  async delete(key: string): Promise<void> {\n    await this.run('delete', key, async () => this.kv.delete(key))\n  }\n\n  /** Expose Typist's three-method secondary storage bridge without changing KV semantics. */\n  asSecondaryStorage(): KVSecondaryStorage {\n    return {\n      get: (key) => this.get(key),\n      set: (key, value, ttl) => this.put(key, value, { ttl }),\n      delete: (key) => this.delete(key),\n    }\n  }\n\n  private async run<T>(operation: KVOperation, key: string, work: () => Promise<T>): Promise<T> {\n    const result = await Result.tryPromise(\n      { try: work, catch: (cause) => cause },\n      {\n        retry: {\n          times: 2,\n          shouldRetry: (cause) => decideKVRetry(cause).retry,\n          delayMs: (cause, { attempt }) =>\n            (isKVPutRateLimitError(cause) ? 1_000 : 0) +\n            spreadJitterMs(exponentialDelayCapMs(25, 3_000, attempt)),\n        },\n      },\n    )\n    if (result.isOk()) return result.value\n    throw new KVError({ operation, key, cause: result.error })\n  }\n}\n"],"mappings":";;;;;;AAgBA,IAAa,WAAb,MAAsB;CACS;CAA7B,YAAY,AAAiB,IAAiB;EAAjB;CAAkB;;CAG/C,MAAM,IAAI,KAAqC;EAC7C,OAAO,MAAM,KAAK,IAAI,OAAO,KAAK,YAAY,KAAK,GAAG,IAAI,GAAG,CAAC;CAChE;;CAGA,MAAM,QAAW,KAAgC;EAC/C,OAAO,MAAM,KAAK,IAAI,OAAO,KAAK,YAAY,KAAK,GAAG,IAAO,KAAK,MAAM,CAAC;CAC3E;;CAGA,MAAM,IAAI,KAAa,OAAe,SAAuD;EAC3F,MAAM,YAAmC,CAAC;EAC1C,IAAI,SAAS,QAAQ,UAAa,QAAQ,MAAM,GAC9C,UAAU,gBAAgB,QAAQ;EAEpC,MAAM,KAAK,IAAI,OAAO,KAAK,YAAY,KAAK,GAAG,IAAI,KAAK,OAAO,SAAS,CAAC;CAC3E;;CAGA,MAAM,QACJ,KAEA,OACA,SACe;EACf,MAAM,KAAK,IAAI,KAAK,KAAK,UAAU,KAAK,GAAG,OAAO;CACpD;;CAGA,MAAM,OAAO,KAA4B;EACvC,MAAM,KAAK,IAAI,UAAU,KAAK,YAAY,KAAK,GAAG,OAAO,GAAG,CAAC;CAC/D;;CAGA,qBAAyC;EACvC,OAAO;GACL,MAAM,QAAQ,KAAK,IAAI,GAAG;GAC1B,MAAM,KAAK,OAAO,QAAQ,KAAK,IAAI,KAAK,OAAO,EAAE,IAAI,CAAC;GACtD,SAAS,QAAQ,KAAK,OAAO,GAAG;EAClC;CACF;CAEA,MAAc,IAAO,WAAwB,KAAa,MAAoC;EAC5F,MAAM,SAAS,MAAM,OAAO,WAC1B;GAAE,KAAK;GAAM,QAAQ,UAAU;EAAM,GACrC,EACE,OAAO;GACL,OAAO;GACP,cAAc,UAAU,cAAc,KAAK,CAAC,CAAC;GAC7C,UAAU,OAAO,EAAE,eAChB,sBAAsB,KAAK,IAAI,MAAQ,KACxC,eAAe,sBAAsB,IAAI,KAAO,OAAO,CAAC;EAC5D,EACF,CACF;EACA,IAAI,OAAO,KAAK,GAAG,OAAO,OAAO;EACjC,MAAM,IAAI,QAAQ;GAAE;GAAW;GAAK,OAAO,OAAO;EAAM,CAAC;CAC3D;AACF"}

package/dist/cloudflare/kv-errors.d.ts

@@ -0,0 +1,52 @@
+import { $t as AppError, en as FailureClassification } from "../index-DvJUcSW1.js";
+//#region src/infrastructure/cloudflare/kv-errors.d.ts
+/** KV operations recognized in binding error messages. */
+export type KVOperation = 'get' | 'put' | 'delete' | 'list';
+/** KV failure kinds retained from Typist's binding tests. */
+export type KVErrorKind = 'invalid_key' | 'key_too_large' | 'invalid_expiration_ttl' | 'invalid_expiration' | 'invalid_cache_ttl' | 'invalid_list_limit' | 'value_too_large' | 'client_error' | 'rate_limited' | 'server_error';
+/** Evidence extracted from a KV error and its causes. */
+export interface KVErrorMeta {
+  kind: KVErrorKind;
+  message: string;
+  status?: number | undefined;
+  operation?: Uppercase<KVOperation> | undefined;
+}
+/** Extract Typist's verified KV message formats, including nested causes. */
+export declare function extractKVMeta(cause: unknown): KVErrorMeta | undefined;
+/** Identify recognized KV failures that another attempt cannot resolve. */
+export declare function isTerminalKVError(cause: unknown): boolean;
+/** Identify a PUT rate limit that requires at least one second before retrying. */
+export declare function isKVPutRateLimitError(cause: unknown): boolean;
+/** Identify PUT rate limits, server failures, and request timeouts. */
+export declare function isTransientKVError(cause: unknown): boolean;
+/** Apply Typist's KV, overload, platform, and transport checks in their original order. */
+export declare function isRetryableKVError(cause: unknown): boolean;
+/** Return the existing retry decision and minimum delay in milliseconds. */
+export declare function decideKVRetry(cause: unknown): {
+  retry: false;
+} | {
+  retry: true;
+  retryAfterMs: number;
+};
+/** A final KV failure with Typist's diagnostics and Better Ship's error classification. */
+export declare class KVError extends AppError {
+  readonly _tag = "KVError";
+  readonly classification: FailureClassification;
+  retryable: boolean;
+  readonly operation: KVOperation;
+  readonly key?: string | undefined;
+  readonly cause: unknown;
+  readonly kv?: KVErrorMeta | undefined;
+  readonly context: {
+    operation: KVOperation;
+    key?: string | undefined;
+    kv?: KVErrorMeta | undefined;
+  };
+  constructor(args: {
+    operation: KVOperation;
+    key?: string | undefined;
+    cause: unknown;
+  });
+}
+//#endregion
+//# sourceMappingURL=kv-errors.d.ts.map

package/dist/cloudflare/kv-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-errors.d.ts","names":[],"sources":["../../src/infrastructure/cloudflare/kv-errors.ts"],"mappings":";;;YASY;;YAGA;;iBAaK;EACf,MAAM;EACN;EACA;EACA,YAAY,UAAU;;;wBAIR,cAAc,iBAAiB;;wBAwC/B,kBAAkB;;wBASlB,sBAAsB;;wBAMtB,mBAAmB;;wBAOnB,mBAAmB;;wBAQnB,cACd;EACG;;EAAmB;EAAa;;;qBAMxB,gBAAgB;WAClB;WACA,gBAAgB;EACzB;WACS,WAAW;WACX;WACS;WACT,KAAK;WACL;IACP,WAAW;IACX;IACA,KAAK;;EAGP,YAAY;IAAQ,WAAW;IAAa;IAA0B"}

package/dist/cloudflare/kv-errors.js

@@ -0,0 +1,144 @@
+import { _ as isCloudflareRetryableError, b as isTransientTransportError, g as isCloudflareOverloadedError, rt as AppError } from "../core-ClSP5-V9.js";
+
+//#region src/infrastructure/cloudflare/kv-errors.ts
+/** Extract Typist's verified KV message formats, including nested causes. */
+function extractKVMeta(cause) {
+	const message = getDeepErrorMessage(cause);
+	if (!message) return void 0;
+	const statusMatch = message.match(/\bKV\s+(GET|PUT|DELETE|LIST)\s+failed:\s+(\d{3})\b/);
+	const operation = statusMatch?.[1];
+	const status = statusMatch ? Number(statusMatch[2]) : void 0;
+	if (/Key name cannot be empty/i.test(message)) return {
+		kind: "invalid_key",
+		message,
+		status,
+		operation
+	};
+	if (/exceeds key length limit/i.test(message)) return {
+		kind: "key_too_large",
+		message,
+		status,
+		operation
+	};
+	if (/Invalid expiration_ttl/i.test(message)) return {
+		kind: "invalid_expiration_ttl",
+		message,
+		status,
+		operation
+	};
+	if (/Invalid expiration of/i.test(message)) return {
+		kind: "invalid_expiration",
+		message,
+		status,
+		operation
+	};
+	if (/Invalid cache_ttl/i.test(message)) return {
+		kind: "invalid_cache_ttl",
+		message,
+		status,
+		operation
+	};
+	if (/Invalid key_count_limit/i.test(message)) return {
+		kind: "invalid_list_limit",
+		message,
+		status,
+		operation
+	};
+	if (/value.*(too large|exceeds)|exceeds.*value/i.test(message)) return {
+		kind: "value_too_large",
+		message,
+		status,
+		operation
+	};
+	if (status === 429) return {
+		kind: "rate_limited",
+		message,
+		status,
+		operation
+	};
+	if (status !== void 0 && status >= 500) return {
+		kind: "server_error",
+		message,
+		status,
+		operation
+	};
+	if (status !== void 0 && status >= 400) return {
+		kind: "client_error",
+		message,
+		status,
+		operation
+	};
+}
+/** Identify recognized KV failures that another attempt cannot resolve. */
+function isTerminalKVError(cause) {
+	const meta = extractKVMeta(cause);
+	if (!meta) return false;
+	if (meta.kind === "rate_limited" || meta.kind === "server_error") return false;
+	if (meta.status === 408) return false;
+	return true;
+}
+/** Identify a PUT rate limit that requires at least one second before retrying. */
+function isKVPutRateLimitError(cause) {
+	const meta = extractKVMeta(cause);
+	return meta?.operation === "PUT" && meta.kind === "rate_limited";
+}
+/** Identify PUT rate limits, server failures, and request timeouts. */
+function isTransientKVError(cause) {
+	const meta = extractKVMeta(cause);
+	if (!meta) return false;
+	return isKVPutRateLimitError(cause) || meta.kind === "server_error" || meta.status === 408;
+}
+/** Apply Typist's KV, overload, platform, and transport checks in their original order. */
+function isRetryableKVError(cause) {
+	if (isTerminalKVError(cause)) return false;
+	if (isTransientKVError(cause)) return true;
+	if (isCloudflareOverloadedError(cause)) return false;
+	return isCloudflareRetryableError(cause) || isTransientTransportError(cause);
+}
+/** Return the existing retry decision and minimum delay in milliseconds. */
+function decideKVRetry(cause) {
+	if (!isRetryableKVError(cause)) return { retry: false };
+	return {
+		retry: true,
+		retryAfterMs: isKVPutRateLimitError(cause) ? 1e3 : 0
+	};
+}
+/** A final KV failure with Typist's diagnostics and Better Ship's error classification. */
+var KVError = class extends AppError {
+	_tag = "KVError";
+	classification;
+	retryable;
+	operation;
+	key;
+	cause;
+	kv;
+	context;
+	constructor(args) {
+		const kv = extractKVMeta(args.cause);
+		const causeMessage = getDeepErrorMessage(args.cause) || String(args.cause);
+		const keyContext = args.key === void 0 ? "" : ` for key "${args.key}"`;
+		super(`KV ${args.operation} failed${keyContext}: ${causeMessage}`, { cause: args.cause });
+		this.operation = args.operation;
+		this.key = args.key;
+		this.cause = args.cause;
+		this.kv = kv;
+		this.context = {
+			operation: args.operation,
+			key: args.key,
+			kv
+		};
+		this.retryable = isRetryableKVError(args.cause);
+		this.classification = isTerminalKVError(args.cause) ? "terminal" : this.retryable ? "transient" : "unknown";
+	}
+};
+function getDeepErrorMessage(cause) {
+	if (typeof cause === "string") return cause;
+	if (cause === null || cause === void 0) return "";
+	if (typeof cause === "number" || typeof cause === "boolean" || typeof cause === "bigint") return String(cause);
+	if (typeof cause !== "object") return "";
+	return `${"message" in cause && typeof cause.message === "string" ? cause.message : ""} ${"cause" in cause ? getDeepErrorMessage(cause.cause) : ""}`.trim();
+}
+
+//#endregion
+export { KVError, decideKVRetry, extractKVMeta, isKVPutRateLimitError, isRetryableKVError, isTerminalKVError, isTransientKVError };
+//# sourceMappingURL=kv-errors.js.map

package/dist/cloudflare/kv-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-errors.js","names":[],"sources":["../../src/infrastructure/cloudflare/kv-errors.ts"],"sourcesContent":["import {\n  AppError,\n  isCloudflareOverloadedError,\n  isCloudflareRetryableError,\n  isTransientTransportError,\n  type FailureClassification,\n} from '@/core'\n\n/** KV operations recognized in binding error messages. */\nexport type KVOperation = 'get' | 'put' | 'delete' | 'list'\n\n/** KV failure kinds retained from Typist's binding tests. */\nexport type KVErrorKind =\n  | 'invalid_key'\n  | 'key_too_large'\n  | 'invalid_expiration_ttl'\n  | 'invalid_expiration'\n  | 'invalid_cache_ttl'\n  | 'invalid_list_limit'\n  | 'value_too_large'\n  | 'client_error'\n  | 'rate_limited'\n  | 'server_error'\n\n/** Evidence extracted from a KV error and its causes. */\nexport interface KVErrorMeta {\n  kind: KVErrorKind\n  message: string\n  status?: number | undefined\n  operation?: Uppercase<KVOperation> | undefined\n}\n\n/** Extract Typist's verified KV message formats, including nested causes. */\nexport function extractKVMeta(cause: unknown): KVErrorMeta | undefined {\n  const message = getDeepErrorMessage(cause)\n  if (!message) return undefined\n  const statusMatch = message.match(/\\bKV\\s+(GET|PUT|DELETE|LIST)\\s+failed:\\s+(\\d{3})\\b/)\n  // SAFETY: The regular expression permits only uppercase KV operation names in this capture.\n  const operation = statusMatch?.[1] as Uppercase<KVOperation> | undefined\n  const status = statusMatch ? Number(statusMatch[2]) : undefined\n\n  if (/Key name cannot be empty/i.test(message)) {\n    return { kind: 'invalid_key', message, status, operation }\n  }\n  if (/exceeds key length limit/i.test(message)) {\n    return { kind: 'key_too_large', message, status, operation }\n  }\n  if (/Invalid expiration_ttl/i.test(message)) {\n    return { kind: 'invalid_expiration_ttl', message, status, operation }\n  }\n  if (/Invalid expiration of/i.test(message)) {\n    return { kind: 'invalid_expiration', message, status, operation }\n  }\n  if (/Invalid cache_ttl/i.test(message)) {\n    return { kind: 'invalid_cache_ttl', message, status, operation }\n  }\n  if (/Invalid key_count_limit/i.test(message)) {\n    return { kind: 'invalid_list_limit', message, status, operation }\n  }\n  if (/value.*(too large|exceeds)|exceeds.*value/i.test(message)) {\n    return { kind: 'value_too_large', message, status, operation }\n  }\n  if (status === 429) return { kind: 'rate_limited', message, status, operation }\n  if (status !== undefined && status >= 500) {\n    return { kind: 'server_error', message, status, operation }\n  }\n  if (status !== undefined && status >= 400) {\n    return { kind: 'client_error', message, status, operation }\n  }\n  return undefined\n}\n\n/** Identify recognized KV failures that another attempt cannot resolve. */\nexport function isTerminalKVError(cause: unknown): boolean {\n  const meta = extractKVMeta(cause)\n  if (!meta) return false\n  if (meta.kind === 'rate_limited' || meta.kind === 'server_error') return false\n  if (meta.status === 408) return false\n  return true\n}\n\n/** Identify a PUT rate limit that requires at least one second before retrying. */\nexport function isKVPutRateLimitError(cause: unknown): boolean {\n  const meta = extractKVMeta(cause)\n  return meta?.operation === 'PUT' && meta.kind === 'rate_limited'\n}\n\n/** Identify PUT rate limits, server failures, and request timeouts. */\nexport function isTransientKVError(cause: unknown): boolean {\n  const meta = extractKVMeta(cause)\n  if (!meta) return false\n  return isKVPutRateLimitError(cause) || meta.kind === 'server_error' || meta.status === 408\n}\n\n/** Apply Typist's KV, overload, platform, and transport checks in their original order. */\nexport function isRetryableKVError(cause: unknown): boolean {\n  if (isTerminalKVError(cause)) return false\n  if (isTransientKVError(cause)) return true\n  if (isCloudflareOverloadedError(cause)) return false\n  return isCloudflareRetryableError(cause) || isTransientTransportError(cause)\n}\n\n/** Return the existing retry decision and minimum delay in milliseconds. */\nexport function decideKVRetry(\n  cause: unknown,\n): { retry: false } | { retry: true; retryAfterMs: number } {\n  if (!isRetryableKVError(cause)) return { retry: false }\n  return { retry: true, retryAfterMs: isKVPutRateLimitError(cause) ? 1_000 : 0 }\n}\n\n/** A final KV failure with Typist's diagnostics and Better Ship's error classification. */\nexport class KVError extends AppError {\n  readonly _tag = 'KVError'\n  readonly classification: FailureClassification\n  retryable: boolean\n  readonly operation: KVOperation\n  readonly key?: string | undefined\n  override readonly cause: unknown\n  readonly kv?: KVErrorMeta | undefined\n  readonly context: {\n    operation: KVOperation\n    key?: string | undefined\n    kv?: KVErrorMeta | undefined\n  }\n\n  constructor(args: { operation: KVOperation; key?: string | undefined; cause: unknown }) {\n    const kv = extractKVMeta(args.cause)\n    const causeMessage = getDeepErrorMessage(args.cause) || String(args.cause)\n    const keyContext = args.key === undefined ? '' : ` for key \"${args.key}\"`\n    super(`KV ${args.operation} failed${keyContext}: ${causeMessage}`, { cause: args.cause })\n    this.operation = args.operation\n    this.key = args.key\n    this.cause = args.cause\n    this.kv = kv\n    this.context = { operation: args.operation, key: args.key, kv }\n    this.retryable = isRetryableKVError(args.cause)\n    this.classification = isTerminalKVError(args.cause)\n      ? 'terminal'\n      : this.retryable\n        ? 'transient'\n        : 'unknown'\n  }\n}\n\n// oxlint-disable anti-slop/no-runtime-typeof -- Preserve Typist's primitive messages and nested causes at the raw binding boundary.\nfunction getDeepErrorMessage(cause: unknown): string {\n  if (typeof cause === 'string') return cause\n  if (cause === null || cause === undefined) return ''\n  if (typeof cause === 'number' || typeof cause === 'boolean' || typeof cause === 'bigint') {\n    return String(cause)\n  }\n  if (typeof cause !== 'object') return ''\n  const message = 'message' in cause && typeof cause.message === 'string' ? cause.message : ''\n  const causeMessage = 'cause' in cause ? getDeepErrorMessage(cause.cause) : ''\n  return `${message} ${causeMessage}`.trim()\n}\n// oxlint-enable anti-slop/no-runtime-typeof\n"],"mappings":"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"}

package/dist/cloudflare.d.ts

@@ -294,8 +294,13 @@ export declare class D1BatchTransaction<Schema extends DrizzleSchema> implements
 }
 //#endregion
 //#region src/infrastructure/cloudflare/d1-database-execution.d.ts
-/** Execute once without retries; convert recognized D1 failures and preserve other exceptions unchanged. */
-export declare function executeDatabase<T>(operation: string, work: () => PromiseLike<T>): Promise<T>;
+/**
+ * Convert database failures and preserve other exceptions. The default executes once.
+ * Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.
+ */
+export declare function executeDatabase<T>(operation: string, work: () => PromiseLike<T>, options?: {
+  readonly retry?: 'never' | 'transient';
+}): Promise<T>;
 //#endregion
 //#region src/infrastructure/cloudflare/d1-outbox-repository.d.ts
 /**

package/dist/cloudflare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","names":[],"sources":["../src/infrastructure/cloudflare/d1-database-types.ts","../src/infrastructure/cloudflare/base-d1-repository.ts","../src/infrastructure/cloudflare/classify-d1-error.ts","../src/infrastructure/cloudflare/d1-message-store.ts","../src/infrastructure/cloudflare/d1-schema.ts","../src/infrastructure/cloudflare/d1-batch-transaction.ts","../src/infrastructure/cloudflare/d1-database-execution.ts","../src/infrastructure/cloudflare/d1-outbox-repository.ts"],"mappings":";;;;;;;KAKY,eAAe;;KAGf,KAAK,eAAe,iBAAiB,kBAAkB;;KAGvD,SAAS,eAAe,iBAAiB,KACnD,KAAK;;KAKK,KAAK,eAAe;WACrB,IAAI,KAAK;;;;;UCRH;EACf,iBAAiB,cAAc;EAC/B;;;;;;8BAOoB,iBAAiB,eAAe;qBACrB,IAAI,KAAK;EAAxC,YAA+B,IAAI,KAAK;;YAG9B,MAAM,WAAW;;YAKjB,KAAK,GAAG,mBAAmB,aAAa,YAAY,KAAK,QAAQ;;YAKjE,eAAe,WAAW;;;;;;;;wBCVtB,gBAAgB,gBAAgB,qBAAyB;;;;qBCb5D,eAAe,eAAe,uBACjC,iBAAiB,mBACd;EAEL,MAAM,WAAW,YAAY;EAc7B,cAAc,QAAQ,cAAc,eAAe;;;;;qBCtB9C,qDAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAAjB;;;;;;;;;;;;;;;;qBAYA,iDAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBCPb,mBAAmB,eAAe,0BAA0B,aACvE,KAAK;mBAEwB;EAA7B,YAA6B,IAAI,KAAK;EAEhC,YAAY,GAAG,OAAO,IAAI,KAAK,YAAY,QAAQ,KAAK,QAAQ;;;;;wBCblD,gBAAgB,GACpC,mBACA,YAAY,YAAY,KACvB,QAAQ;;;;;;;qBCYE,mBAAmB,eAAe,0BAA0B;mBAIpD;mBAEA;mBALF;EAEjB,YACmB,IAAI,KAAK,SAC1B,UAAS,yBACQ,YAAW;;EAMxB,aAAa,oBAAoB,QAAQ;;EAmDzC,cAAc,OAAO,aAAa,UAAU,cAAc,iBAAiB;;EAgB3E,aAAa,OAAO,aAAa,UAAU,cAAc,iBAAiB;;EA6B1E,WACJ,OAAO,aACP,UAAU,cAAc,gBACxB,QAAQ,kBACR,uBACC;;EAqBG,sBAAsB,QAAQ,MAAM,oBAAoB;;EAqBxD,mBAAmB,QAAQ,MAAM,oBAAoB;;EAqBrD,qBAAqB,QAAQ,MAAM,oBAAoB"}
+{"version":3,"file":"cloudflare.d.ts","names":[],"sources":["../src/infrastructure/cloudflare/d1-database-types.ts","../src/infrastructure/cloudflare/base-d1-repository.ts","../src/infrastructure/cloudflare/classify-d1-error.ts","../src/infrastructure/cloudflare/d1-message-store.ts","../src/infrastructure/cloudflare/d1-schema.ts","../src/infrastructure/cloudflare/d1-batch-transaction.ts","../src/infrastructure/cloudflare/d1-database-execution.ts","../src/infrastructure/cloudflare/d1-outbox-repository.ts"],"mappings":";;;;;;;KAKY,eAAe;;KAGf,KAAK,eAAe,iBAAiB,kBAAkB;;KAGvD,SAAS,eAAe,iBAAiB,KACnD,KAAK;;KAKK,KAAK,eAAe;WACrB,IAAI,KAAK;;;;;UCRH;EACf,iBAAiB,cAAc;EAC/B;;;;;;8BAOoB,iBAAiB,eAAe;qBACrB,IAAI,KAAK;EAAxC,YAA+B,IAAI,KAAK;;YAG9B,MAAM,WAAW;;YAKjB,KAAK,GAAG,mBAAmB,aAAa,YAAY,KAAK,QAAQ;;YAKjE,eAAe,WAAW;;;;;;;;wBCVtB,gBAAgB,gBAAgB,qBAAyB;;;;qBCb5D,eAAe,eAAe,uBACjC,iBAAiB,mBACd;EAEL,MAAM,WAAW,YAAY;EAc7B,cAAc,QAAQ,cAAc,eAAe;;;;;qBCtB9C,qDAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAAjB;;;;;;;;;;;;;;;;qBAYA,iDAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBCPb,mBAAmB,eAAe,0BAA0B,aACvE,KAAK;mBAEwB;EAA7B,YAA6B,IAAI,KAAK;EAEhC,YAAY,GAAG,OAAO,IAAI,KAAK,YAAY,QAAQ,KAAK,QAAQ;;;;;;;;wBCNlD,gBAAgB,GACpC,mBACA,YAAY,YAAY,IACxB;WAAoB;IACnB,QAAQ;;;;;;;qBCIE,mBAAmB,eAAe,0BAA0B;mBAIpD;mBAEA;mBALF;EAEjB,YACmB,IAAI,KAAK,SAC1B,UAAS,yBACQ,YAAW;;EAMxB,aAAa,oBAAoB,QAAQ;;EAmDzC,cAAc,OAAO,aAAa,UAAU,cAAc,iBAAiB;;EAgB3E,aAAa,OAAO,aAAa,UAAU,cAAc,iBAAiB;;EA6B1E,WACJ,OAAO,aACP,UAAU,cAAc,gBACxB,QAAQ,kBACR,uBACC;;EAqBG,sBAAsB,QAAQ,MAAM,oBAAoB;;EAqBxD,mBAAmB,QAAQ,MAAM,oBAAoB;;EAqBrD,qBAAqB,QAAQ,MAAM,oBAAoB"}

package/dist/cloudflare.js

@@ -1,6 +1,7 @@
 import { c as exponentialDelayCapMs, k as DatabaseError, rt as AppError } from "./core-ClSP5-V9.js";
 import { o as MessageAlreadyProcessedError } from "./application-Cf9SER-i.js";
 import { a as stageD1Statement, i as runWithUnitOfWorkContext, n as collectD1Statements, r as eventCollector, t as OUTBOX_REPOSITORY_DEFAULTS } from "./outbox-repository-options-ICOF8g2h.js";
+import { Result } from "better-result";
 import { DrizzleQueryError } from "drizzle-orm/errors";
 import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from "drizzle-orm";
 import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
@@ -68,13 +69,23 @@ function classificationOf(message) {
 
 //#endregion
 //#region src/infrastructure/cloudflare/d1-database-execution.ts
-/** Execute once without retries; convert recognized D1 failures and preserve other exceptions unchanged. */
-async function executeDatabase(operation, work) {
-	try {
-		return await work();
-	} catch (cause) {
-		throw classifyD1Error(cause, operation) ?? cause;
-	}
+/**
+* Convert database failures and preserve other exceptions. The default executes once.
+* Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.
+*/
+async function executeDatabase(operation, work, options = {}) {
+	const result = await Result.tryPromise({
+		try: async () => await work(),
+		catch: (cause) => classifyD1Error(cause, operation) ?? cause
+	}, { retry: {
+		times: options.retry === "transient" ? 2 : 0,
+		delayMs: 250,
+		backoff: "exponential",
+		jitter: true,
+		shouldRetry: (error) => error instanceof DatabaseError && error.classification === "transient"
+	} });
+	if (result.isErr()) throw result.error;
+	return result.value;
 }
 
 //#endregion

package/dist/cloudflare.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.js","names":[],"sources":["../src/infrastructure/cloudflare/classify-d1-error.ts","../src/infrastructure/cloudflare/d1-database-execution.ts","../src/infrastructure/cloudflare/base-d1-repository.ts","../src/infrastructure/cloudflare/d1-schema.ts","../src/infrastructure/cloudflare/d1-message-store.ts","../src/infrastructure/cloudflare/d1-batch-transaction.ts","../src/infrastructure/cloudflare/d1-outbox-repository.ts"],"sourcesContent":["import { DrizzleQueryError } from 'drizzle-orm/errors'\n\nimport { AppError, DatabaseError, type D1ConstraintKind, type FailureClassification } from '@/core'\n\nconst KIND_BY_CODE: ReadonlyMap<string, D1ConstraintKind> = new Map([\n  ['SQLITE_CONSTRAINT_PRIMARYKEY', 'unique'],\n  ['SQLITE_CONSTRAINT_UNIQUE', 'unique'],\n  ['SQLITE_CONSTRAINT_NOTNULL', 'not_null'],\n  ['SQLITE_CONSTRAINT_FOREIGNKEY', 'foreign_key'],\n  ['SQLITE_CONSTRAINT_CHECK', 'check'],\n])\n\nconst KIND_BY_PROSE: ReadonlyArray<readonly [string, D1ConstraintKind]> = [\n  ['UNIQUE constraint failed', 'unique'],\n  ['NOT NULL constraint failed', 'not_null'],\n  ['FOREIGN KEY constraint failed', 'foreign_key'],\n  ['CHECK constraint failed', 'check'],\n]\n\n/**\n * Recognize D1 failures and preserve the original cause. Unrecognized callback exceptions remain unchanged.\n * D1 exposes error codes and constraint locations in text, so parsing stays at this boundary.\n */\nexport function classifyD1Error(cause: unknown, operation = 'D1 query'): DatabaseError | undefined {\n  if (cause instanceof AppError || (cause instanceof Error && cause.name === 'AbortError'))\n    return undefined\n  const message = messagesOf(cause)\n  const kind = kindOf(message)\n  const classification = kind === undefined ? classificationOf(message) : 'terminal'\n  const code = message.match(/\\b(?:SQLITE_[A-Z_]+|D1_[A-Z_]+)\\b/)?.[0]\n  if (code === undefined && classification === 'unknown' && !(cause instanceof DrizzleQueryError))\n    return undefined\n  // A composite unique constraint must not be mistaken for the processed-message primary key.\n  const location = message.match(/constraint failed: (\\w+)\\.(\\w+)(?=\\s*(?::\\s*SQLITE_|$|\\n))/)\n  const check = kind === 'check' ? message.match(/CHECK constraint failed: ([A-Za-z_]\\w*)/) : null\n  return new DatabaseError(\n    operation,\n    classification,\n    {\n      database: 'd1',\n      code,\n      kind,\n      table: location?.[1],\n      column: location?.[2],\n      constraintName: check?.[1],\n    },\n    { cause },\n  )\n}\n\nfunction kindOf(message: string): D1ConstraintKind | undefined {\n  const code = message.match(/SQLITE_CONSTRAINT_\\w+/)?.[0]\n  if (code !== undefined) return KIND_BY_CODE.get(code)\n  return KIND_BY_PROSE.find(([prose]) => message.includes(prose))?.[1]\n}\n\n// Drizzle query messages contain SQL and values, which are not evidence about the database failure.\nfunction messagesOf(cause: unknown): string {\n  const messages: string[] = []\n  const seen = new Set<unknown>()\n  let current = cause\n  while (current instanceof Error && !seen.has(current)) {\n    seen.add(current)\n    if (!(current instanceof DrizzleQueryError)) messages.push(current.message)\n    current = current.cause\n  }\n  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- D1 can expose a raw string cause; this boundary accepts only that representation.\n  if (typeof current === 'string') messages.push(current)\n  return messages.join('\\n')\n}\n\n// Cloudflare documents these conditions separately from transient storage resets.\nconst TERMINAL_FAILURE =\n  /\\bSQLITE_(?:ERROR|MISMATCH|TOOBIG|FULL|AUTH|PERM|READONLY)\\b|\\bD1_(?:TYPE_ERROR|COLUMN_NOTFOUND)\\b|no such (?:table|column|function)|syntax error|datatype mismatch|exceeded (?:timeout|its memory limit|its CPU time limit|maximum DB size)|maximum account storage limit|free tier daily row (?:read|write) limit/i\nconst TRANSIENT_FAILURE =\n  /Network connection lost\\.|Replica disconnected from primary\\.|D1 DB reset because its code was updated\\.|Internal error (?:while starting up|in) D1 DB storage caused object to be reset\\.|Cannot resolve D1 DB due to transient issue on remote node\\.|Can't read from request stream because client disconnected\\./i\n\nfunction classificationOf(message: string): FailureClassification {\n  if (TERMINAL_FAILURE.test(message)) return 'terminal'\n  if (TRANSIENT_FAILURE.test(message)) return 'transient'\n  return 'unknown'\n}\n","import { classifyD1Error } from './classify-d1-error.ts'\n\n/** Execute once without retries; convert recognized D1 failures and preserve other exceptions unchanged. */\nexport async function executeDatabase<T>(\n  operation: string,\n  work: () => PromiseLike<T>,\n): Promise<T> {\n  try {\n    return await work()\n  } catch (cause) {\n    throw classifyD1Error(cause, operation) ?? cause\n  }\n}\n","import type { BatchItem } from 'drizzle-orm/batch'\n\nimport type { DomainEvent } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { eventCollector, stageD1Statement } from '../unit-of-work-context.ts'\nimport { executeDatabase } from './d1-database-execution.ts'\nimport type { D1Db } from './d1-database-types.ts'\n\n/** A domain aggregate that accumulates events for the unit of work to drain. */\nexport interface AggregateEvents {\n  collectEvents(): ReadonlyArray<DomainEvent>\n  clearEvents(): void\n}\n\n/**\n * Shared plumbing for a repository that writes inside a D1 unit of work.\n * Writes are staged, never run; the boundary commits them as one batch. Reads run on `db` now.\n */\nexport abstract class BaseD1Repository<Schema extends DrizzleSchema> {\n  constructor(protected readonly db: D1Db<Schema>) {}\n\n  /** Add a statement to the current D1 batch without executing it. */\n  protected stage(statement: BatchItem<'sqlite'>): void {\n    stageD1Statement(statement)\n  }\n\n  /** Execute one read with database error conversion and no automatic retries. */\n  protected read<T>(operation: string, query: () => PromiseLike<T>): Promise<T> {\n    return executeDatabase(operation, query)\n  }\n\n  /** Drain an aggregate's pending events into the active boundary. */\n  protected dispatchEvents(aggregate: AggregateEvents): void {\n    const events = aggregate.collectEvents()\n    if (events.length === 0) return\n    for (const event of events) eventCollector.emit(event)\n    aggregate.clearEvents()\n  }\n}\n","import { sql } from 'drizzle-orm'\nimport { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'\n\nimport type { DomainEvent } from '@/core'\n\n/** One row per committed message. The primary key is the idempotency claim. */\nexport const processedMessages = sqliteTable(\n  'processed_messages',\n  {\n    messageId: text('message_id').primaryKey(),\n    processedAt: integer('processed_at', { mode: 'timestamp' })\n      .notNull()\n      .$defaultFn(() => new Date()),\n  },\n  (table) => [index('idx_processed_messages_processed_at').on(table.processedAt)],\n)\n\n/** Events committed with their state change, waiting for the relay to deliver them. */\nexport const messageOutbox = sqliteTable(\n  'message_outbox',\n  {\n    id: text('id').primaryKey(),\n    payload: text('payload', { mode: 'json' }).$type<DomainEvent>().notNull(),\n    createdAt: integer('created_at', { mode: 'timestamp' })\n      .notNull()\n      .$defaultFn(() => new Date()),\n    availableAt: integer('available_at', { mode: 'timestamp' })\n      .notNull()\n      .$defaultFn(() => new Date()),\n    attempts: integer('attempts').notNull().default(0),\n    claimToken: text('claim_token'),\n    claimExpiresAt: integer('claim_expires_at', { mode: 'timestamp' }),\n    publishedAt: integer('published_at', { mode: 'timestamp' }),\n    failedAt: integer('failed_at', { mode: 'timestamp' }),\n    lastError: text('last_error'),\n  },\n  (table) => [\n    index('idx_message_outbox_due')\n      .on(table.availableAt, table.createdAt)\n      .where(sql`${table.publishedAt} IS NULL`),\n    index('idx_message_outbox_claim_token').on(table.claimToken),\n  ],\n)\n","import { eq } from 'drizzle-orm'\n\nimport { MessageAlreadyProcessedError, type IMessageStore, type MessageId } from '@/application'\nimport type { DomainEvent } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { BaseD1Repository } from './base-d1-repository.ts'\nimport { messageOutbox, processedMessages } from './d1-schema.ts'\n\n/** Processed messages and outbox events share one D1 batch; the primary key prevents concurrent duplicate commits. */\nexport class D1MessageStore<Schema extends DrizzleSchema>\n  extends BaseD1Repository<Schema>\n  implements IMessageStore\n{\n  async claim(messageId: MessageId): Promise<void> {\n    const processed = await this.read('claim message', () =>\n      this.db\n        .select({ messageId: processedMessages.messageId })\n        .from(processedMessages)\n        .where(eq(processedMessages.messageId, messageId))\n        .get(),\n    )\n    if (processed !== undefined) throw new MessageAlreadyProcessedError(messageId)\n\n    // Concurrent deliveries can pass the read; the primary key enforces the claim at commit.\n    this.stage(this.db.insert(processedMessages).values({ messageId }))\n  }\n\n  async persistEvents(events: ReadonlyArray<DomainEvent>): Promise<void> {\n    if (events.length === 0) return\n    this.stage(\n      this.db\n        .insert(messageOutbox)\n        .values(events.map((event) => ({ id: event.id, payload: event }))),\n    )\n  }\n}\n","import type { ITransaction } from '@/application'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { collectD1Statements, runWithUnitOfWorkContext } from '../unit-of-work-context.ts'\nimport { executeDatabase } from './d1-database-execution.ts'\nimport type { D1Db, D1Tx } from './d1-database-types.ts'\n\n/**\n * The D1 transaction boundary: every write is staged during `work` and committed as one\n * `db.batch()`. A throw inside `work` means the batch never runs.\n */\nexport class D1BatchTransaction<Schema extends DrizzleSchema> implements ITransaction<\n  D1Tx<Schema>\n> {\n  constructor(private readonly db: D1Db<Schema>) {}\n\n  async transaction<T>(work: (tx: D1Tx<Schema>) => Promise<T>): Promise<T> {\n    return runWithUnitOfWorkContext('d1', async () => {\n      const value = await work({ db: this.db })\n      const [first, ...rest] = collectD1Statements()\n      if (first !== undefined) {\n        await executeDatabase('commit unit of work', () => this.db.batch([first, ...rest]))\n      }\n      return value\n    })\n  }\n}\n","import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from 'drizzle-orm'\n\nimport type { DeadLetterReason, IOutboxRepository, OutboxClaim, OutboxMessage } from '@/application'\nimport { exponentialDelayCapMs } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport {\n  OUTBOX_REPOSITORY_DEFAULTS,\n  type OutboxRepositoryOptions,\n} from '../outbox-repository-options.ts'\nimport { executeDatabase } from './d1-database-execution.ts'\nimport type { D1Db } from './d1-database-types.ts'\nimport { messageOutbox, processedMessages } from './d1-schema.ts'\n\n/**\n * Typist's atomic D1 claims on a plain connection, outside a unit of work.\n * Every write runs once; lease expiry and the scheduled sweep recover interrupted operations.\n */\nexport class D1OutboxRepository<Schema extends DrizzleSchema> implements IOutboxRepository {\n  private readonly options: Required<OutboxRepositoryOptions>\n\n  constructor(\n    private readonly db: D1Db<Schema>,\n    options: OutboxRepositoryOptions = {},\n    private readonly now: () => Date = () => new Date(),\n  ) {\n    this.options = { ...OUTBOX_REPOSITORY_DEFAULTS, ...options }\n  }\n\n  /** Lease due rows in one statement; increment attempts even when reclaiming an expired lease. */\n  async claimPending(batchSize: number): Promise<OutboxClaim> {\n    const token = crypto.randomUUID()\n    const now = this.now()\n    const rows = await executeDatabase('claim pending outbox messages', () =>\n      this.db\n        .update(messageOutbox)\n        .set({\n          claimToken: token,\n          claimExpiresAt: deadline(now.getTime() + this.options.leaseMs),\n          attempts: sql`${messageOutbox.attempts} + 1`,\n        })\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(\n                and(\n                  isNull(messageOutbox.publishedAt),\n                  isNull(messageOutbox.failedAt),\n                  lte(messageOutbox.availableAt, now),\n                  or(isNull(messageOutbox.claimExpiresAt), lte(messageOutbox.claimExpiresAt, now)),\n                ),\n              )\n              .orderBy(\n                asc(messageOutbox.availableAt),\n                asc(messageOutbox.createdAt),\n                asc(messageOutbox.id),\n              )\n              .limit(batchSize),\n          ),\n        )\n        .returning({\n          payload: messageOutbox.payload,\n          attempts: messageOutbox.attempts,\n          availableAt: messageOutbox.availableAt,\n          createdAt: messageOutbox.createdAt,\n        }),\n    )\n    // UPDATE RETURNING does not preserve the selection order.\n    rows.sort(\n      (a, b) =>\n        a.availableAt.getTime() - b.availableAt.getTime() ||\n        a.createdAt.getTime() - b.createdAt.getTime() ||\n        a.payload.id.localeCompare(b.payload.id),\n    )\n    return { token, messages: rows.map(({ payload, attempts }) => ({ payload, attempts })) }\n  }\n\n  /** Mark only supplied rows that still hold this token as published. */\n  async markPublished(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {\n    if (messages.length === 0) return\n    await executeDatabase('mark outbox messages published', () =>\n      this.db\n        .update(messageOutbox)\n        .set({ publishedAt: this.now(), claimToken: null, claimExpiresAt: null })\n        .where(\n          and(\n            inArray(messageOutbox.id, outboxIds(messages)),\n            eq(messageOutbox.claimToken, claim.token),\n          ),\n        ),\n    )\n  }\n\n  /** Release supplied rows with per-row backoff; a stale token cannot change a newer claim. */\n  async releaseClaim(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {\n    const now = this.now()\n    for (const attempts of new Set(messages.map((row) => row.attempts))) {\n      const rows = messages.filter((row) => row.attempts === attempts)\n      const delay = exponentialDelayCapMs(\n        this.options.retryBaseDelayMs,\n        this.options.retryMaxDelayMs,\n        attempts,\n      )\n      // oxlint-disable-next-line no-await-in-loop -- Stop releasing rows on the first database failure.\n      await executeDatabase('release outbox claim', () =>\n        this.db\n          .update(messageOutbox)\n          .set({\n            availableAt: deadline(now.getTime() + delay),\n            claimToken: null,\n            claimExpiresAt: null,\n          })\n          .where(\n            and(\n              inArray(messageOutbox.id, outboxIds(rows)),\n              eq(messageOutbox.claimToken, claim.token),\n            ),\n          ),\n      )\n    }\n  }\n\n  /** Retain the full payload and record a closed reason with a readable error message. */\n  async deadLetter(\n    claim: OutboxClaim,\n    messages: ReadonlyArray<OutboxMessage>,\n    reason: DeadLetterReason,\n    errorMessage: string,\n  ): Promise<void> {\n    if (messages.length === 0) return\n    await executeDatabase('dead-letter outbox messages', () =>\n      this.db\n        .update(messageOutbox)\n        .set({\n          failedAt: this.now(),\n          lastError: `${reason}: ${errorMessage}`,\n          claimToken: null,\n          claimExpiresAt: null,\n        })\n        .where(\n          and(\n            inArray(messageOutbox.id, outboxIds(messages)),\n            eq(messageOutbox.claimToken, claim.token),\n          ),\n        ),\n    )\n  }\n\n  /** Delete at most batchSize published rows, strictly before the cutoff. */\n  async deletePublishedBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete published outbox messages', () =>\n      this.db\n        .delete(messageOutbox)\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(lt(messageOutbox.publishedAt, cutoff))\n              .orderBy(asc(messageOutbox.publishedAt), asc(messageOutbox.id))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ id: messageOutbox.id }),\n    )\n    return rows.length\n  }\n\n  /** Delete at most batchSize failed rows; pending and published rows remain untouched. */\n  async deleteFailedBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete failed outbox messages', () =>\n      this.db\n        .delete(messageOutbox)\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(and(isNull(messageOutbox.publishedAt), lt(messageOutbox.failedAt, cutoff)))\n              .orderBy(asc(messageOutbox.failedAt), asc(messageOutbox.id))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ id: messageOutbox.id }),\n    )\n    return rows.length\n  }\n\n  /** Delete at most batchSize receipts, strictly before the cutoff. */\n  async deleteReceiptsBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete message receipts', () =>\n      this.db\n        .delete(processedMessages)\n        .where(\n          inArray(\n            processedMessages.messageId,\n            this.db\n              .select({ messageId: processedMessages.messageId })\n              .from(processedMessages)\n              .where(lt(processedMessages.processedAt, cutoff))\n              .orderBy(asc(processedMessages.processedAt), asc(processedMessages.messageId))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ messageId: processedMessages.messageId }),\n    )\n    return rows.length\n  }\n}\n\n// One JSON parameter keeps large claims below D1's 100-parameter limit.\nfunction outboxIds(messages: ReadonlyArray<OutboxMessage>) {\n  return sql`(select value from json_each(${JSON.stringify(messages.map((row) => row.payload.id))}))`\n}\n\n// D1 timestamps repository seconds; round future deadlines up so a lease or delay never ends early.\nfunction deadline(ms: number): Date {\n  return new Date(Math.ceil(ms / 1_000) * 1_000)\n}\n"],"mappings":"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"}
+{"version":3,"file":"cloudflare.js","names":[],"sources":["../src/infrastructure/cloudflare/classify-d1-error.ts","../src/infrastructure/cloudflare/d1-database-execution.ts","../src/infrastructure/cloudflare/base-d1-repository.ts","../src/infrastructure/cloudflare/d1-schema.ts","../src/infrastructure/cloudflare/d1-message-store.ts","../src/infrastructure/cloudflare/d1-batch-transaction.ts","../src/infrastructure/cloudflare/d1-outbox-repository.ts"],"sourcesContent":["import { DrizzleQueryError } from 'drizzle-orm/errors'\n\nimport { AppError, DatabaseError, type D1ConstraintKind, type FailureClassification } from '@/core'\n\nconst KIND_BY_CODE: ReadonlyMap<string, D1ConstraintKind> = new Map([\n  ['SQLITE_CONSTRAINT_PRIMARYKEY', 'unique'],\n  ['SQLITE_CONSTRAINT_UNIQUE', 'unique'],\n  ['SQLITE_CONSTRAINT_NOTNULL', 'not_null'],\n  ['SQLITE_CONSTRAINT_FOREIGNKEY', 'foreign_key'],\n  ['SQLITE_CONSTRAINT_CHECK', 'check'],\n])\n\nconst KIND_BY_PROSE: ReadonlyArray<readonly [string, D1ConstraintKind]> = [\n  ['UNIQUE constraint failed', 'unique'],\n  ['NOT NULL constraint failed', 'not_null'],\n  ['FOREIGN KEY constraint failed', 'foreign_key'],\n  ['CHECK constraint failed', 'check'],\n]\n\n/**\n * Recognize D1 failures and preserve the original cause. Unrecognized callback exceptions remain unchanged.\n * D1 exposes error codes and constraint locations in text, so parsing stays at this boundary.\n */\nexport function classifyD1Error(cause: unknown, operation = 'D1 query'): DatabaseError | undefined {\n  if (cause instanceof AppError || (cause instanceof Error && cause.name === 'AbortError'))\n    return undefined\n  const message = messagesOf(cause)\n  const kind = kindOf(message)\n  const classification = kind === undefined ? classificationOf(message) : 'terminal'\n  const code = message.match(/\\b(?:SQLITE_[A-Z_]+|D1_[A-Z_]+)\\b/)?.[0]\n  if (code === undefined && classification === 'unknown' && !(cause instanceof DrizzleQueryError))\n    return undefined\n  // A composite unique constraint must not be mistaken for the processed-message primary key.\n  const location = message.match(/constraint failed: (\\w+)\\.(\\w+)(?=\\s*(?::\\s*SQLITE_|$|\\n))/)\n  const check = kind === 'check' ? message.match(/CHECK constraint failed: ([A-Za-z_]\\w*)/) : null\n  return new DatabaseError(\n    operation,\n    classification,\n    {\n      database: 'd1',\n      code,\n      kind,\n      table: location?.[1],\n      column: location?.[2],\n      constraintName: check?.[1],\n    },\n    { cause },\n  )\n}\n\nfunction kindOf(message: string): D1ConstraintKind | undefined {\n  const code = message.match(/SQLITE_CONSTRAINT_\\w+/)?.[0]\n  if (code !== undefined) return KIND_BY_CODE.get(code)\n  return KIND_BY_PROSE.find(([prose]) => message.includes(prose))?.[1]\n}\n\n// Drizzle query messages contain SQL and values, which are not evidence about the database failure.\nfunction messagesOf(cause: unknown): string {\n  const messages: string[] = []\n  const seen = new Set<unknown>()\n  let current = cause\n  while (current instanceof Error && !seen.has(current)) {\n    seen.add(current)\n    if (!(current instanceof DrizzleQueryError)) messages.push(current.message)\n    current = current.cause\n  }\n  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- D1 can expose a raw string cause; this boundary accepts only that representation.\n  if (typeof current === 'string') messages.push(current)\n  return messages.join('\\n')\n}\n\n// Cloudflare documents these conditions separately from transient storage resets.\nconst TERMINAL_FAILURE =\n  /\\bSQLITE_(?:ERROR|MISMATCH|TOOBIG|FULL|AUTH|PERM|READONLY)\\b|\\bD1_(?:TYPE_ERROR|COLUMN_NOTFOUND)\\b|no such (?:table|column|function)|syntax error|datatype mismatch|exceeded (?:timeout|its memory limit|its CPU time limit|maximum DB size)|maximum account storage limit|free tier daily row (?:read|write) limit/i\nconst TRANSIENT_FAILURE =\n  /Network connection lost\\.|Replica disconnected from primary\\.|D1 DB reset because its code was updated\\.|Internal error (?:while starting up|in) D1 DB storage caused object to be reset\\.|Cannot resolve D1 DB due to transient issue on remote node\\.|Can't read from request stream because client disconnected\\./i\n\nfunction classificationOf(message: string): FailureClassification {\n  if (TERMINAL_FAILURE.test(message)) return 'terminal'\n  if (TRANSIENT_FAILURE.test(message)) return 'transient'\n  return 'unknown'\n}\n","import { Result } from 'better-result'\n\nimport { DatabaseError } from '@/core'\n\nimport { classifyD1Error } from './classify-d1-error.ts'\n\n/**\n * Convert database failures and preserve other exceptions. The default executes once.\n * Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.\n */\nexport async function executeDatabase<T>(\n  operation: string,\n  work: () => PromiseLike<T>,\n  options: { readonly retry?: 'never' | 'transient' } = {},\n): Promise<T> {\n  const result = await Result.tryPromise(\n    {\n      try: async () => await work(),\n      catch: (cause) => classifyD1Error(cause, operation) ?? cause,\n    },\n    {\n      retry: {\n        times: options.retry === 'transient' ? 2 : 0,\n        delayMs: 250,\n        backoff: 'exponential',\n        jitter: true,\n        shouldRetry: (error) =>\n          error instanceof DatabaseError && error.classification === 'transient',\n      },\n    },\n  )\n  if (result.isErr()) throw result.error\n  return result.value\n}\n","import type { BatchItem } from 'drizzle-orm/batch'\n\nimport type { DomainEvent } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { eventCollector, stageD1Statement } from '../unit-of-work-context.ts'\nimport { executeDatabase } from './d1-database-execution.ts'\nimport type { D1Db } from './d1-database-types.ts'\n\n/** A domain aggregate that accumulates events for the unit of work to drain. */\nexport interface AggregateEvents {\n  collectEvents(): ReadonlyArray<DomainEvent>\n  clearEvents(): void\n}\n\n/**\n * Shared plumbing for a repository that writes inside a D1 unit of work.\n * Writes are staged, never run; the boundary commits them as one batch. Reads run on `db` now.\n */\nexport abstract class BaseD1Repository<Schema extends DrizzleSchema> {\n  constructor(protected readonly db: D1Db<Schema>) {}\n\n  /** Add a statement to the current D1 batch without executing it. */\n  protected stage(statement: BatchItem<'sqlite'>): void {\n    stageD1Statement(statement)\n  }\n\n  /** Execute one read with database error conversion and no automatic retries. */\n  protected read<T>(operation: string, query: () => PromiseLike<T>): Promise<T> {\n    return executeDatabase(operation, query)\n  }\n\n  /** Drain an aggregate's pending events into the active boundary. */\n  protected dispatchEvents(aggregate: AggregateEvents): void {\n    const events = aggregate.collectEvents()\n    if (events.length === 0) return\n    for (const event of events) eventCollector.emit(event)\n    aggregate.clearEvents()\n  }\n}\n","import { sql } from 'drizzle-orm'\nimport { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'\n\nimport type { DomainEvent } from '@/core'\n\n/** One row per committed message. The primary key is the idempotency claim. */\nexport const processedMessages = sqliteTable(\n  'processed_messages',\n  {\n    messageId: text('message_id').primaryKey(),\n    processedAt: integer('processed_at', { mode: 'timestamp' })\n      .notNull()\n      .$defaultFn(() => new Date()),\n  },\n  (table) => [index('idx_processed_messages_processed_at').on(table.processedAt)],\n)\n\n/** Events committed with their state change, waiting for the relay to deliver them. */\nexport const messageOutbox = sqliteTable(\n  'message_outbox',\n  {\n    id: text('id').primaryKey(),\n    payload: text('payload', { mode: 'json' }).$type<DomainEvent>().notNull(),\n    createdAt: integer('created_at', { mode: 'timestamp' })\n      .notNull()\n      .$defaultFn(() => new Date()),\n    availableAt: integer('available_at', { mode: 'timestamp' })\n      .notNull()\n      .$defaultFn(() => new Date()),\n    attempts: integer('attempts').notNull().default(0),\n    claimToken: text('claim_token'),\n    claimExpiresAt: integer('claim_expires_at', { mode: 'timestamp' }),\n    publishedAt: integer('published_at', { mode: 'timestamp' }),\n    failedAt: integer('failed_at', { mode: 'timestamp' }),\n    lastError: text('last_error'),\n  },\n  (table) => [\n    index('idx_message_outbox_due')\n      .on(table.availableAt, table.createdAt)\n      .where(sql`${table.publishedAt} IS NULL`),\n    index('idx_message_outbox_claim_token').on(table.claimToken),\n  ],\n)\n","import { eq } from 'drizzle-orm'\n\nimport { MessageAlreadyProcessedError, type IMessageStore, type MessageId } from '@/application'\nimport type { DomainEvent } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { BaseD1Repository } from './base-d1-repository.ts'\nimport { messageOutbox, processedMessages } from './d1-schema.ts'\n\n/** Processed messages and outbox events share one D1 batch; the primary key prevents concurrent duplicate commits. */\nexport class D1MessageStore<Schema extends DrizzleSchema>\n  extends BaseD1Repository<Schema>\n  implements IMessageStore\n{\n  async claim(messageId: MessageId): Promise<void> {\n    const processed = await this.read('claim message', () =>\n      this.db\n        .select({ messageId: processedMessages.messageId })\n        .from(processedMessages)\n        .where(eq(processedMessages.messageId, messageId))\n        .get(),\n    )\n    if (processed !== undefined) throw new MessageAlreadyProcessedError(messageId)\n\n    // Concurrent deliveries can pass the read; the primary key enforces the claim at commit.\n    this.stage(this.db.insert(processedMessages).values({ messageId }))\n  }\n\n  async persistEvents(events: ReadonlyArray<DomainEvent>): Promise<void> {\n    if (events.length === 0) return\n    this.stage(\n      this.db\n        .insert(messageOutbox)\n        .values(events.map((event) => ({ id: event.id, payload: event }))),\n    )\n  }\n}\n","import type { ITransaction } from '@/application'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { collectD1Statements, runWithUnitOfWorkContext } from '../unit-of-work-context.ts'\nimport { executeDatabase } from './d1-database-execution.ts'\nimport type { D1Db, D1Tx } from './d1-database-types.ts'\n\n/**\n * The D1 transaction boundary: every write is staged during `work` and committed as one\n * `db.batch()`. A throw inside `work` means the batch never runs.\n */\nexport class D1BatchTransaction<Schema extends DrizzleSchema> implements ITransaction<\n  D1Tx<Schema>\n> {\n  constructor(private readonly db: D1Db<Schema>) {}\n\n  async transaction<T>(work: (tx: D1Tx<Schema>) => Promise<T>): Promise<T> {\n    return runWithUnitOfWorkContext('d1', async () => {\n      const value = await work({ db: this.db })\n      const [first, ...rest] = collectD1Statements()\n      if (first !== undefined) {\n        await executeDatabase('commit unit of work', () => this.db.batch([first, ...rest]))\n      }\n      return value\n    })\n  }\n}\n","import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from 'drizzle-orm'\n\nimport type { DeadLetterReason, IOutboxRepository, OutboxClaim, OutboxMessage } from '@/application'\nimport { exponentialDelayCapMs } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport {\n  OUTBOX_REPOSITORY_DEFAULTS,\n  type OutboxRepositoryOptions,\n} from '../outbox-repository-options.ts'\nimport { executeDatabase } from './d1-database-execution.ts'\nimport type { D1Db } from './d1-database-types.ts'\nimport { messageOutbox, processedMessages } from './d1-schema.ts'\n\n/**\n * Typist's atomic D1 claims on a plain connection, outside a unit of work.\n * Every write runs once; lease expiry and the scheduled sweep recover interrupted operations.\n */\nexport class D1OutboxRepository<Schema extends DrizzleSchema> implements IOutboxRepository {\n  private readonly options: Required<OutboxRepositoryOptions>\n\n  constructor(\n    private readonly db: D1Db<Schema>,\n    options: OutboxRepositoryOptions = {},\n    private readonly now: () => Date = () => new Date(),\n  ) {\n    this.options = { ...OUTBOX_REPOSITORY_DEFAULTS, ...options }\n  }\n\n  /** Lease due rows in one statement; increment attempts even when reclaiming an expired lease. */\n  async claimPending(batchSize: number): Promise<OutboxClaim> {\n    const token = crypto.randomUUID()\n    const now = this.now()\n    const rows = await executeDatabase('claim pending outbox messages', () =>\n      this.db\n        .update(messageOutbox)\n        .set({\n          claimToken: token,\n          claimExpiresAt: deadline(now.getTime() + this.options.leaseMs),\n          attempts: sql`${messageOutbox.attempts} + 1`,\n        })\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(\n                and(\n                  isNull(messageOutbox.publishedAt),\n                  isNull(messageOutbox.failedAt),\n                  lte(messageOutbox.availableAt, now),\n                  or(isNull(messageOutbox.claimExpiresAt), lte(messageOutbox.claimExpiresAt, now)),\n                ),\n              )\n              .orderBy(\n                asc(messageOutbox.availableAt),\n                asc(messageOutbox.createdAt),\n                asc(messageOutbox.id),\n              )\n              .limit(batchSize),\n          ),\n        )\n        .returning({\n          payload: messageOutbox.payload,\n          attempts: messageOutbox.attempts,\n          availableAt: messageOutbox.availableAt,\n          createdAt: messageOutbox.createdAt,\n        }),\n    )\n    // UPDATE RETURNING does not preserve the selection order.\n    rows.sort(\n      (a, b) =>\n        a.availableAt.getTime() - b.availableAt.getTime() ||\n        a.createdAt.getTime() - b.createdAt.getTime() ||\n        a.payload.id.localeCompare(b.payload.id),\n    )\n    return { token, messages: rows.map(({ payload, attempts }) => ({ payload, attempts })) }\n  }\n\n  /** Mark only supplied rows that still hold this token as published. */\n  async markPublished(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {\n    if (messages.length === 0) return\n    await executeDatabase('mark outbox messages published', () =>\n      this.db\n        .update(messageOutbox)\n        .set({ publishedAt: this.now(), claimToken: null, claimExpiresAt: null })\n        .where(\n          and(\n            inArray(messageOutbox.id, outboxIds(messages)),\n            eq(messageOutbox.claimToken, claim.token),\n          ),\n        ),\n    )\n  }\n\n  /** Release supplied rows with per-row backoff; a stale token cannot change a newer claim. */\n  async releaseClaim(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {\n    const now = this.now()\n    for (const attempts of new Set(messages.map((row) => row.attempts))) {\n      const rows = messages.filter((row) => row.attempts === attempts)\n      const delay = exponentialDelayCapMs(\n        this.options.retryBaseDelayMs,\n        this.options.retryMaxDelayMs,\n        attempts,\n      )\n      // oxlint-disable-next-line no-await-in-loop -- Stop releasing rows on the first database failure.\n      await executeDatabase('release outbox claim', () =>\n        this.db\n          .update(messageOutbox)\n          .set({\n            availableAt: deadline(now.getTime() + delay),\n            claimToken: null,\n            claimExpiresAt: null,\n          })\n          .where(\n            and(\n              inArray(messageOutbox.id, outboxIds(rows)),\n              eq(messageOutbox.claimToken, claim.token),\n            ),\n          ),\n      )\n    }\n  }\n\n  /** Retain the full payload and record a closed reason with a readable error message. */\n  async deadLetter(\n    claim: OutboxClaim,\n    messages: ReadonlyArray<OutboxMessage>,\n    reason: DeadLetterReason,\n    errorMessage: string,\n  ): Promise<void> {\n    if (messages.length === 0) return\n    await executeDatabase('dead-letter outbox messages', () =>\n      this.db\n        .update(messageOutbox)\n        .set({\n          failedAt: this.now(),\n          lastError: `${reason}: ${errorMessage}`,\n          claimToken: null,\n          claimExpiresAt: null,\n        })\n        .where(\n          and(\n            inArray(messageOutbox.id, outboxIds(messages)),\n            eq(messageOutbox.claimToken, claim.token),\n          ),\n        ),\n    )\n  }\n\n  /** Delete at most batchSize published rows, strictly before the cutoff. */\n  async deletePublishedBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete published outbox messages', () =>\n      this.db\n        .delete(messageOutbox)\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(lt(messageOutbox.publishedAt, cutoff))\n              .orderBy(asc(messageOutbox.publishedAt), asc(messageOutbox.id))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ id: messageOutbox.id }),\n    )\n    return rows.length\n  }\n\n  /** Delete at most batchSize failed rows; pending and published rows remain untouched. */\n  async deleteFailedBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete failed outbox messages', () =>\n      this.db\n        .delete(messageOutbox)\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(and(isNull(messageOutbox.publishedAt), lt(messageOutbox.failedAt, cutoff)))\n              .orderBy(asc(messageOutbox.failedAt), asc(messageOutbox.id))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ id: messageOutbox.id }),\n    )\n    return rows.length\n  }\n\n  /** Delete at most batchSize receipts, strictly before the cutoff. */\n  async deleteReceiptsBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete message receipts', () =>\n      this.db\n        .delete(processedMessages)\n        .where(\n          inArray(\n            processedMessages.messageId,\n            this.db\n              .select({ messageId: processedMessages.messageId })\n              .from(processedMessages)\n              .where(lt(processedMessages.processedAt, cutoff))\n              .orderBy(asc(processedMessages.processedAt), asc(processedMessages.messageId))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ messageId: processedMessages.messageId }),\n    )\n    return rows.length\n  }\n}\n\n// One JSON parameter keeps large claims below D1's 100-parameter limit.\nfunction outboxIds(messages: ReadonlyArray<OutboxMessage>) {\n  return sql`(select value from json_each(${JSON.stringify(messages.map((row) => row.payload.id))}))`\n}\n\n// D1 timestamps repository seconds; round future deadlines up so a lease or delay never ends early.\nfunction deadline(ms: number): Date {\n  return new Date(Math.ceil(ms / 1_000) * 1_000)\n}\n"],"mappings":"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"}

package/dist/postgres.d.ts

@@ -278,8 +278,13 @@ export declare class PostgresTransaction<Schema extends DrizzleSchema> implement
 }
 //#endregion
 //#region src/infrastructure/postgres/postgres-database-execution.d.ts
-/** Execute once without retries; convert recognized Postgres failures and preserve other exceptions unchanged. */
-export declare function executeDatabase<T>(operation: string, work: () => PromiseLike<T>): Promise<T>;
+/**
+ * Convert database failures and preserve other exceptions. The default executes once.
+ * Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.
+ */
+export declare function executeDatabase<T>(operation: string, work: () => PromiseLike<T>, options?: {
+  readonly retry?: 'never' | 'transient';
+}): Promise<T>;
 //#endregion
 //#region src/infrastructure/postgres/classify-postgres-error.d.ts
 /** Read SQLSTATE or driver codes; unknown callback exceptions remain unchanged. */

package/dist/postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.d.ts","names":[],"sources":["../src/infrastructure/postgres/postgres-database-types.ts","../src/infrastructure/postgres/base-postgres-repository.ts","../src/infrastructure/postgres/postgres-message-store.ts","../src/infrastructure/postgres/postgres-schema.ts","../src/infrastructure/postgres/postgres-transaction.ts","../src/infrastructure/postgres/postgres-database-execution.ts","../src/infrastructure/postgres/classify-postgres-error.ts","../src/infrastructure/postgres/postgres-outbox-repository.ts"],"mappings":";;;;;;;KAMY,qBAAqB,kBAAkB;;KAGvC,WAAW,eAAe,iBAAiB,mBAAmB;;KAG9D,eAAe,eAAe,iBAAiB,KACzD,WAAW;;KAKD,sBAAsB,eAAe,iBAAiB,sBAChE,QACA,2BAA2B;;KAIjB,WAAW,eAAe;WAC3B,IAAI,sBAAsB;;;;;UCjBpB;EACf,iBAAiB,cAAc;EAC/B;;;8BAIoB,uBAAuB,eAAe;qBAC3B,IAAI,sBAAsB;EAAzD,YAA+B,IAAI,sBAAsB;;YAG/C,KAAK,GAAG,mBAAmB,aAAa,YAAY,KAAK,QAAQ;;YAKjE,eAAe,WAAW;;;;;qBCfzB,qBAAqB,eAAe,0BAA0B;mBAC5C;EAA7B,YAA6B,IAAI,sBAAsB;EAEjD,MAAM,WAAW,YAAY;EAU7B,cAAc,QAAQ,cAAc,eAAe;;;;;qBCf9C,iDAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;YAAjB;;;;;;;;;;;;;;;;qBAMA,6CAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBCDb,oBAAoB,eAAe,0BAA0B,aACxE,WAAW;mBAEkB;EAA7B,YAA6B,IAAI,WAAW;EAE5C,YAAY,GAAG,OAAO,IAAI,WAAW,YAAY,QAAQ,KAAK,QAAQ;;;;;wBCblD,gBAAgB,GACpC,mBACA,YAAY,YAAY,KACvB,QAAQ;;;;wBC2BK,sBACd,gBACA,oBACC;;;;;;;qBClBU,oCAAoC;mBAI5B;mBAEA;mBALF;EAEjB,YACmB,IAAI,WAAW,gBAChC,UAAS,yBACQ,YAAW;;EAMxB,aAAa,oBAAoB,QAAQ;;EAoDzC,cAAc,OAAO,aAAa,UAAU,cAAc,iBAAiB;;EAmB3E,aAAa,OAAO,aAAa,UAAU,cAAc,iBAAiB;;EAwB1E,WACJ,OAAO,aACP,UAAU,cAAc,gBACxB,QAAQ,kBACR,uBACC;;EAwBG,sBAAsB,QAAQ,MAAM,oBAAoB;;EAqBxD,mBAAmB,QAAQ,MAAM,oBAAoB;;EAqBrD,qBAAqB,QAAQ,MAAM,oBAAoB"}
+{"version":3,"file":"postgres.d.ts","names":[],"sources":["../src/infrastructure/postgres/postgres-database-types.ts","../src/infrastructure/postgres/base-postgres-repository.ts","../src/infrastructure/postgres/postgres-message-store.ts","../src/infrastructure/postgres/postgres-schema.ts","../src/infrastructure/postgres/postgres-transaction.ts","../src/infrastructure/postgres/postgres-database-execution.ts","../src/infrastructure/postgres/classify-postgres-error.ts","../src/infrastructure/postgres/postgres-outbox-repository.ts"],"mappings":";;;;;;;KAMY,qBAAqB,kBAAkB;;KAGvC,WAAW,eAAe,iBAAiB,mBAAmB;;KAG9D,eAAe,eAAe,iBAAiB,KACzD,WAAW;;KAKD,sBAAsB,eAAe,iBAAiB,sBAChE,QACA,2BAA2B;;KAIjB,WAAW,eAAe;WAC3B,IAAI,sBAAsB;;;;;UCjBpB;EACf,iBAAiB,cAAc;EAC/B;;;8BAIoB,uBAAuB,eAAe;qBAC3B,IAAI,sBAAsB;EAAzD,YAA+B,IAAI,sBAAsB;;YAG/C,KAAK,GAAG,mBAAmB,aAAa,YAAY,KAAK,QAAQ;;YAKjE,eAAe,WAAW;;;;;qBCfzB,qBAAqB,eAAe,0BAA0B;mBAC5C;EAA7B,YAA6B,IAAI,sBAAsB;EAEjD,MAAM,WAAW,YAAY;EAU7B,cAAc,QAAQ,cAAc,eAAe;;;;;qBCf9C,iDAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;YAAjB;;;;;;;;;;;;;;;;qBAMA,6CAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBCDb,oBAAoB,eAAe,0BAA0B,aACxE,WAAW;mBAEkB;EAA7B,YAA6B,IAAI,WAAW;EAE5C,YAAY,GAAG,OAAO,IAAI,WAAW,YAAY,QAAQ,KAAK,QAAQ;;;;;;;;wBCNlD,gBAAgB,GACpC,mBACA,YAAY,YAAY,IACxB;WAAoB;IACnB,QAAQ;;;;wBCmBK,sBACd,gBACA,oBACC;;;;;;;qBClBU,oCAAoC;mBAI5B;mBAEA;mBALF;EAEjB,YACmB,IAAI,WAAW,gBAChC,UAAS,yBACQ,YAAW;;EAMxB,aAAa,oBAAoB,QAAQ;;EAoDzC,cAAc,OAAO,aAAa,UAAU,cAAc,iBAAiB;;EAmB3E,aAAa,OAAO,aAAa,UAAU,cAAc,iBAAiB;;EAwB1E,WACJ,OAAO,aACP,UAAU,cAAc,gBACxB,QAAQ,kBACR,uBACC;;EAwBG,sBAAsB,QAAQ,MAAM,oBAAoB;;EAqBxD,mBAAmB,QAAQ,MAAM,oBAAoB;;EAqBrD,qBAAqB,QAAQ,MAAM,oBAAoB"}

package/dist/postgres.js

@@ -1,6 +1,7 @@
 import { c as exponentialDelayCapMs, k as DatabaseError, rt as AppError } from "./core-ClSP5-V9.js";
 import { o as MessageAlreadyProcessedError } from "./application-Cf9SER-i.js";
 import { i as runWithUnitOfWorkContext, r as eventCollector, t as OUTBOX_REPOSITORY_DEFAULTS } from "./outbox-repository-options-ICOF8g2h.js";
+import { Result } from "better-result";
 import { DrizzleQueryError } from "drizzle-orm/errors";
 import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from "drizzle-orm";
 import { index, integer, jsonb, pgTable, text, timestamp } from "drizzle-orm/pg-core";
@@ -77,13 +78,23 @@ function classificationOf(code) {
 
 //#endregion
 //#region src/infrastructure/postgres/postgres-database-execution.ts
-/** Execute once without retries; convert recognized Postgres failures and preserve other exceptions unchanged. */
-async function executeDatabase(operation, work) {
-	try {
-		return await work();
-	} catch (cause) {
-		throw classifyPostgresError(cause, operation) ?? cause;
-	}
+/**
+* Convert database failures and preserve other exceptions. The default executes once.
+* Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.
+*/
+async function executeDatabase(operation, work, options = {}) {
+	const result = await Result.tryPromise({
+		try: async () => await work(),
+		catch: (cause) => classifyPostgresError(cause, operation) ?? cause
+	}, { retry: {
+		times: options.retry === "transient" ? 2 : 0,
+		delayMs: 250,
+		backoff: "exponential",
+		jitter: true,
+		shouldRetry: (error) => error instanceof DatabaseError && error.classification === "transient"
+	} });
+	if (result.isErr()) throw result.error;
+	return result.value;
 }
 
 //#endregion

package/dist/postgres.js.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.js","names":[],"sources":["../src/infrastructure/postgres/classify-postgres-error.ts","../src/infrastructure/postgres/postgres-database-execution.ts","../src/infrastructure/postgres/base-postgres-repository.ts","../src/infrastructure/postgres/postgres-schema.ts","../src/infrastructure/postgres/postgres-message-store.ts","../src/infrastructure/postgres/postgres-transaction.ts","../src/infrastructure/postgres/postgres-outbox-repository.ts"],"sourcesContent":["import { DrizzleQueryError } from 'drizzle-orm/errors'\n\nimport { AppError, DatabaseError, type FailureClassification } from '@/core'\n\nconst TRANSIENT_CODES = new Set([\n  '40001',\n  '40P01',\n  '08000',\n  '08001',\n  '08003',\n  '08006',\n  '57P01',\n  '57P02',\n  '57P03',\n  'CONNECT_TIMEOUT',\n  'CONNECTION_CLOSED',\n  'ECONNRESET',\n  'ECONNREFUSED',\n  'EPIPE',\n  'ETIMEDOUT',\n  'EAI_AGAIN',\n])\nconst TERMINAL_CODES = new Set(['57014', 'CONNECTION_ENDED', 'CONNECTION_DESTROYED', 'ECANCELED'])\nconst DRIVER_CODES = new Set([\n  'CONNECT_TIMEOUT',\n  'CONNECTION_CLOSED',\n  'CONNECTION_ENDED',\n  'CONNECTION_DESTROYED',\n])\nconst TERMINAL_CLASSES = new Set(['0A', '22', '23', '25', '28', '3D', '3F', '42', '54'])\n\n/* oxlint-disable anti-slop/no-runtime-typeof -- Raw driver exceptions have no shared schema; this boundary validates the fields it exposes. */\n/** Read SQLSTATE or driver codes; unknown callback exceptions remain unchanged. */\nexport function classifyPostgresError(\n  cause: unknown,\n  operation: string,\n): DatabaseError | undefined {\n  let error = cause\n  const seen = new Set<unknown>()\n  while (error instanceof DrizzleQueryError && !seen.has(error)) {\n    seen.add(error)\n    error = error.cause\n  }\n  if (error instanceof AppError || (error instanceof Error && error.name === 'AbortError'))\n    return undefined\n  const code =\n    error instanceof Error && 'code' in error && typeof error.code === 'string'\n      ? error.code\n      : undefined\n  const serverError =\n    error instanceof Error &&\n    error.name === 'PostgresError' &&\n    code !== undefined &&\n    /^[0-9A-Z]{5}$/.test(code)\n  const driverError = code !== undefined && DRIVER_CODES.has(code)\n  if (!(cause instanceof DrizzleQueryError) && !serverError && !driverError) return undefined\n\n  return new DatabaseError(\n    operation,\n    classificationOf(code),\n    {\n      database: 'postgres',\n      code,\n      table_name:\n        error instanceof Error && 'table_name' in error && typeof error.table_name === 'string'\n          ? error.table_name\n          : undefined,\n      column_name:\n        error instanceof Error && 'column_name' in error && typeof error.column_name === 'string'\n          ? error.column_name\n          : undefined,\n      constraint_name:\n        error instanceof Error &&\n        'constraint_name' in error &&\n        typeof error.constraint_name === 'string'\n          ? error.constraint_name\n          : undefined,\n    },\n    { cause },\n  )\n}\n\n/* oxlint-enable anti-slop/no-runtime-typeof */\n\nfunction classificationOf(code: string | undefined): FailureClassification {\n  if (code === undefined) return 'unknown'\n  if (TRANSIENT_CODES.has(code)) return 'transient'\n  if (TERMINAL_CODES.has(code) || TERMINAL_CLASSES.has(code.slice(0, 2))) return 'terminal'\n  return 'unknown'\n}\n","import { classifyPostgresError } from './classify-postgres-error.ts'\n\n/** Execute once without retries; convert recognized Postgres failures and preserve other exceptions unchanged. */\nexport async function executeDatabase<T>(\n  operation: string,\n  work: () => PromiseLike<T>,\n): Promise<T> {\n  try {\n    return await work()\n  } catch (cause) {\n    throw classifyPostgresError(cause, operation) ?? cause\n  }\n}\n","import type { DomainEvent } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { eventCollector } from '../unit-of-work-context.ts'\nimport { executeDatabase } from './postgres-database-execution.ts'\nimport type { PostgresDbTransaction } from './postgres-database-types.ts'\n\n/** A domain aggregate that accumulates events for the unit of work to drain. */\nexport interface AggregateEvents {\n  collectEvents(): ReadonlyArray<DomainEvent>\n  clearEvents(): void\n}\n\n/** Shared plumbing for a repository that writes inside a Postgres unit of work. */\nexport abstract class BasePostgresRepository<Schema extends DrizzleSchema> {\n  constructor(protected readonly db: PostgresDbTransaction<Schema>) {}\n\n  /** Execute one read with database error conversion and no automatic retries. */\n  protected read<T>(operation: string, query: () => PromiseLike<T>): Promise<T> {\n    return executeDatabase(operation, query)\n  }\n\n  /** Drain an aggregate's pending events into the active boundary. */\n  protected dispatchEvents(aggregate: AggregateEvents): void {\n    const events = aggregate.collectEvents()\n    if (events.length === 0) return\n    for (const event of events) eventCollector.emit(event)\n    aggregate.clearEvents()\n  }\n}\n","import { isNull } from 'drizzle-orm'\nimport { index, integer, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core'\n\nimport type { DomainEvent } from '@/core'\n\n/** One row per committed message. The primary key is the idempotency claim. */\nexport const processedMessages = pgTable('processed_messages', {\n  messageId: text('message_id').primaryKey(),\n  processedAt: timestamp('processed_at', { withTimezone: true }).notNull().defaultNow(),\n})\n\n/** Events committed with their state change, waiting for the relay to deliver them. */\nexport const messageOutbox = pgTable(\n  'message_outbox',\n  {\n    id: text('id').primaryKey(),\n    payload: jsonb('payload').$type<DomainEvent>().notNull(),\n    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n    availableAt: timestamp('available_at', { withTimezone: true }).notNull().defaultNow(),\n    attempts: integer('attempts').notNull().default(0),\n    claimToken: text('claim_token'),\n    claimExpiresAt: timestamp('claim_expires_at', { withTimezone: true }),\n    publishedAt: timestamp('published_at', { withTimezone: true }),\n    failedAt: timestamp('failed_at', { withTimezone: true }),\n    lastError: text('last_error'),\n  },\n  (table) => [\n    index('idx_message_outbox_due')\n      .on(table.availableAt, table.createdAt)\n      .where(isNull(table.publishedAt)),\n    index('idx_message_outbox_claim_token').on(table.claimToken),\n  ],\n)\n","import { MessageAlreadyProcessedError, type IMessageStore, type MessageId } from '@/application'\nimport type { DomainEvent } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport type { PostgresDbTransaction } from './postgres-database-types.ts'\nimport { messageOutbox, processedMessages } from './postgres-schema.ts'\n\n/** Processed messages and outbox events share the active Postgres transaction; the insert result establishes the claim. */\nexport class PostgresMessageStore<Schema extends DrizzleSchema> implements IMessageStore {\n  constructor(private readonly db: PostgresDbTransaction<Schema>) {}\n\n  async claim(messageId: MessageId): Promise<void> {\n    const claimed = await this.db\n      .insert(processedMessages)\n      .values({ messageId })\n      .onConflictDoNothing()\n      .returning({ messageId: processedMessages.messageId })\n    // Thrown inside the transaction, so drizzle rolls back everything written before the claim.\n    if (claimed.length === 0) throw new MessageAlreadyProcessedError(messageId)\n  }\n\n  async persistEvents(events: ReadonlyArray<DomainEvent>): Promise<void> {\n    if (events.length === 0) return\n    await this.db\n      .insert(messageOutbox)\n      .values(events.map((event) => ({ id: event.id, payload: event })))\n  }\n}\n","import type { ITransaction } from '@/application'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { runWithUnitOfWorkContext } from '../unit-of-work-context.ts'\nimport { executeDatabase } from './postgres-database-execution.ts'\nimport type { PostgresDb, PostgresTx } from './postgres-database-types.ts'\n\n/**\n * The Postgres transaction boundary uses native Drizzle transactions through postgres.js.\n * Drizzle commits when `work` returns and rolls back when it throws.\n */\nexport class PostgresTransaction<Schema extends DrizzleSchema> implements ITransaction<\n  PostgresTx<Schema>\n> {\n  constructor(private readonly db: PostgresDb<Schema>) {}\n\n  transaction<T>(work: (tx: PostgresTx<Schema>) => Promise<T>): Promise<T> {\n    return runWithUnitOfWorkContext('postgres', () =>\n      executeDatabase('unit of work transaction', () => this.db.transaction((db) => work({ db }))),\n    )\n  }\n}\n","import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from 'drizzle-orm'\n\nimport type { DeadLetterReason, IOutboxRepository, OutboxClaim, OutboxMessage } from '@/application'\nimport { exponentialDelayCapMs } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport {\n  OUTBOX_REPOSITORY_DEFAULTS,\n  type OutboxRepositoryOptions,\n} from '../outbox-repository-options.ts'\nimport { executeDatabase } from './postgres-database-execution.ts'\nimport type { PostgresDb } from './postgres-database-types.ts'\nimport { messageOutbox, processedMessages } from './postgres-schema.ts'\n\n/**\n * Typist's lease protocol with riposte's SKIP LOCKED selection on a plain connection, outside a unit of work.\n * Every write runs once; lease expiry and the scheduled sweep recover interrupted operations.\n */\nexport class PostgresOutboxRepository implements IOutboxRepository {\n  private readonly options: Required<OutboxRepositoryOptions>\n\n  constructor(\n    private readonly db: PostgresDb<DrizzleSchema>,\n    options: OutboxRepositoryOptions = {},\n    private readonly now: () => Date = () => new Date(),\n  ) {\n    this.options = { ...OUTBOX_REPOSITORY_DEFAULTS, ...options }\n  }\n\n  /** Lease due rows in one statement; increment attempts even when reclaiming an expired lease. */\n  async claimPending(batchSize: number): Promise<OutboxClaim> {\n    const token = crypto.randomUUID()\n    const now = this.now()\n    const rows = await executeDatabase('claim pending outbox messages', () =>\n      this.db\n        .update(messageOutbox)\n        .set({\n          claimToken: token,\n          claimExpiresAt: new Date(now.getTime() + this.options.leaseMs),\n          attempts: sql`${messageOutbox.attempts} + 1`,\n        })\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(\n                and(\n                  isNull(messageOutbox.publishedAt),\n                  isNull(messageOutbox.failedAt),\n                  lte(messageOutbox.availableAt, now),\n                  or(isNull(messageOutbox.claimExpiresAt), lte(messageOutbox.claimExpiresAt, now)),\n                ),\n              )\n              .orderBy(\n                asc(messageOutbox.availableAt),\n                asc(messageOutbox.createdAt),\n                asc(messageOutbox.id),\n              )\n              .limit(batchSize)\n              .for('update', { skipLocked: true }),\n          ),\n        )\n        .returning({\n          payload: messageOutbox.payload,\n          attempts: messageOutbox.attempts,\n          availableAt: messageOutbox.availableAt,\n          createdAt: messageOutbox.createdAt,\n        }),\n    )\n    // UPDATE RETURNING does not preserve the selection order.\n    rows.sort(\n      (a, b) =>\n        a.availableAt.getTime() - b.availableAt.getTime() ||\n        a.createdAt.getTime() - b.createdAt.getTime() ||\n        a.payload.id.localeCompare(b.payload.id),\n    )\n    return { token, messages: rows.map(({ payload, attempts }) => ({ payload, attempts })) }\n  }\n\n  /** Mark only supplied rows that still hold this token as published. */\n  async markPublished(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {\n    if (messages.length === 0) return\n    await executeDatabase('mark outbox messages published', () =>\n      this.db\n        .update(messageOutbox)\n        .set({ publishedAt: this.now(), claimToken: null, claimExpiresAt: null })\n        .where(\n          and(\n            inArray(\n              messageOutbox.id,\n              messages.map((row) => row.payload.id),\n            ),\n            eq(messageOutbox.claimToken, claim.token),\n          ),\n        ),\n    )\n  }\n\n  /** Release supplied rows with per-row backoff; a stale token cannot change a newer claim. */\n  async releaseClaim(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {\n    const now = this.now()\n    for (const attempts of new Set(messages.map((row) => row.attempts))) {\n      const ids = messages.filter((row) => row.attempts === attempts).map((row) => row.payload.id)\n      const delay = exponentialDelayCapMs(\n        this.options.retryBaseDelayMs,\n        this.options.retryMaxDelayMs,\n        attempts,\n      )\n      // oxlint-disable-next-line no-await-in-loop -- Stop releasing rows on the first database failure.\n      await executeDatabase('release outbox claim', () =>\n        this.db\n          .update(messageOutbox)\n          .set({\n            availableAt: new Date(now.getTime() + delay),\n            claimToken: null,\n            claimExpiresAt: null,\n          })\n          .where(and(inArray(messageOutbox.id, ids), eq(messageOutbox.claimToken, claim.token))),\n      )\n    }\n  }\n\n  /** Retain the full payload and record a closed reason with a readable error message. */\n  async deadLetter(\n    claim: OutboxClaim,\n    messages: ReadonlyArray<OutboxMessage>,\n    reason: DeadLetterReason,\n    errorMessage: string,\n  ): Promise<void> {\n    if (messages.length === 0) return\n    await executeDatabase('dead-letter outbox messages', () =>\n      this.db\n        .update(messageOutbox)\n        .set({\n          failedAt: this.now(),\n          lastError: `${reason}: ${errorMessage}`,\n          claimToken: null,\n          claimExpiresAt: null,\n        })\n        .where(\n          and(\n            inArray(\n              messageOutbox.id,\n              messages.map((row) => row.payload.id),\n            ),\n            eq(messageOutbox.claimToken, claim.token),\n          ),\n        ),\n    )\n  }\n\n  /** Delete at most batchSize published rows, strictly before the cutoff. */\n  async deletePublishedBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete published outbox messages', () =>\n      this.db\n        .delete(messageOutbox)\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(lt(messageOutbox.publishedAt, cutoff))\n              .orderBy(asc(messageOutbox.publishedAt), asc(messageOutbox.id))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ id: messageOutbox.id }),\n    )\n    return rows.length\n  }\n\n  /** Delete at most batchSize failed rows; pending and published rows remain untouched. */\n  async deleteFailedBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete failed outbox messages', () =>\n      this.db\n        .delete(messageOutbox)\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(and(isNull(messageOutbox.publishedAt), lt(messageOutbox.failedAt, cutoff)))\n              .orderBy(asc(messageOutbox.failedAt), asc(messageOutbox.id))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ id: messageOutbox.id }),\n    )\n    return rows.length\n  }\n\n  /** Delete at most batchSize receipts, strictly before the cutoff. */\n  async deleteReceiptsBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete message receipts', () =>\n      this.db\n        .delete(processedMessages)\n        .where(\n          inArray(\n            processedMessages.messageId,\n            this.db\n              .select({ messageId: processedMessages.messageId })\n              .from(processedMessages)\n              .where(lt(processedMessages.processedAt, cutoff))\n              .orderBy(asc(processedMessages.processedAt), asc(processedMessages.messageId))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ messageId: processedMessages.messageId }),\n    )\n    return rows.length\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"postgres.js","names":[],"sources":["../src/infrastructure/postgres/classify-postgres-error.ts","../src/infrastructure/postgres/postgres-database-execution.ts","../src/infrastructure/postgres/base-postgres-repository.ts","../src/infrastructure/postgres/postgres-schema.ts","../src/infrastructure/postgres/postgres-message-store.ts","../src/infrastructure/postgres/postgres-transaction.ts","../src/infrastructure/postgres/postgres-outbox-repository.ts"],"sourcesContent":["import { DrizzleQueryError } from 'drizzle-orm/errors'\n\nimport { AppError, DatabaseError, type FailureClassification } from '@/core'\n\nconst TRANSIENT_CODES = new Set([\n  '40001',\n  '40P01',\n  '08000',\n  '08001',\n  '08003',\n  '08006',\n  '57P01',\n  '57P02',\n  '57P03',\n  'CONNECT_TIMEOUT',\n  'CONNECTION_CLOSED',\n  'ECONNRESET',\n  'ECONNREFUSED',\n  'EPIPE',\n  'ETIMEDOUT',\n  'EAI_AGAIN',\n])\nconst TERMINAL_CODES = new Set(['57014', 'CONNECTION_ENDED', 'CONNECTION_DESTROYED', 'ECANCELED'])\nconst DRIVER_CODES = new Set([\n  'CONNECT_TIMEOUT',\n  'CONNECTION_CLOSED',\n  'CONNECTION_ENDED',\n  'CONNECTION_DESTROYED',\n])\nconst TERMINAL_CLASSES = new Set(['0A', '22', '23', '25', '28', '3D', '3F', '42', '54'])\n\n/* oxlint-disable anti-slop/no-runtime-typeof -- Raw driver exceptions have no shared schema; this boundary validates the fields it exposes. */\n/** Read SQLSTATE or driver codes; unknown callback exceptions remain unchanged. */\nexport function classifyPostgresError(\n  cause: unknown,\n  operation: string,\n): DatabaseError | undefined {\n  let error = cause\n  const seen = new Set<unknown>()\n  while (error instanceof DrizzleQueryError && !seen.has(error)) {\n    seen.add(error)\n    error = error.cause\n  }\n  if (error instanceof AppError || (error instanceof Error && error.name === 'AbortError'))\n    return undefined\n  const code =\n    error instanceof Error && 'code' in error && typeof error.code === 'string'\n      ? error.code\n      : undefined\n  const serverError =\n    error instanceof Error &&\n    error.name === 'PostgresError' &&\n    code !== undefined &&\n    /^[0-9A-Z]{5}$/.test(code)\n  const driverError = code !== undefined && DRIVER_CODES.has(code)\n  if (!(cause instanceof DrizzleQueryError) && !serverError && !driverError) return undefined\n\n  return new DatabaseError(\n    operation,\n    classificationOf(code),\n    {\n      database: 'postgres',\n      code,\n      table_name:\n        error instanceof Error && 'table_name' in error && typeof error.table_name === 'string'\n          ? error.table_name\n          : undefined,\n      column_name:\n        error instanceof Error && 'column_name' in error && typeof error.column_name === 'string'\n          ? error.column_name\n          : undefined,\n      constraint_name:\n        error instanceof Error &&\n        'constraint_name' in error &&\n        typeof error.constraint_name === 'string'\n          ? error.constraint_name\n          : undefined,\n    },\n    { cause },\n  )\n}\n\n/* oxlint-enable anti-slop/no-runtime-typeof */\n\nfunction classificationOf(code: string | undefined): FailureClassification {\n  if (code === undefined) return 'unknown'\n  if (TRANSIENT_CODES.has(code)) return 'transient'\n  if (TERMINAL_CODES.has(code) || TERMINAL_CLASSES.has(code.slice(0, 2))) return 'terminal'\n  return 'unknown'\n}\n","import { Result } from 'better-result'\n\nimport { DatabaseError } from '@/core'\n\nimport { classifyPostgresError } from './classify-postgres-error.ts'\n\n/**\n * Convert database failures and preserve other exceptions. The default executes once.\n * Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.\n */\nexport async function executeDatabase<T>(\n  operation: string,\n  work: () => PromiseLike<T>,\n  options: { readonly retry?: 'never' | 'transient' } = {},\n): Promise<T> {\n  const result = await Result.tryPromise(\n    {\n      try: async () => await work(),\n      catch: (cause) => classifyPostgresError(cause, operation) ?? cause,\n    },\n    {\n      retry: {\n        times: options.retry === 'transient' ? 2 : 0,\n        delayMs: 250,\n        backoff: 'exponential',\n        jitter: true,\n        shouldRetry: (error) =>\n          error instanceof DatabaseError && error.classification === 'transient',\n      },\n    },\n  )\n  if (result.isErr()) throw result.error\n  return result.value\n}\n","import type { DomainEvent } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { eventCollector } from '../unit-of-work-context.ts'\nimport { executeDatabase } from './postgres-database-execution.ts'\nimport type { PostgresDbTransaction } from './postgres-database-types.ts'\n\n/** A domain aggregate that accumulates events for the unit of work to drain. */\nexport interface AggregateEvents {\n  collectEvents(): ReadonlyArray<DomainEvent>\n  clearEvents(): void\n}\n\n/** Shared plumbing for a repository that writes inside a Postgres unit of work. */\nexport abstract class BasePostgresRepository<Schema extends DrizzleSchema> {\n  constructor(protected readonly db: PostgresDbTransaction<Schema>) {}\n\n  /** Execute one read with database error conversion and no automatic retries. */\n  protected read<T>(operation: string, query: () => PromiseLike<T>): Promise<T> {\n    return executeDatabase(operation, query)\n  }\n\n  /** Drain an aggregate's pending events into the active boundary. */\n  protected dispatchEvents(aggregate: AggregateEvents): void {\n    const events = aggregate.collectEvents()\n    if (events.length === 0) return\n    for (const event of events) eventCollector.emit(event)\n    aggregate.clearEvents()\n  }\n}\n","import { isNull } from 'drizzle-orm'\nimport { index, integer, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core'\n\nimport type { DomainEvent } from '@/core'\n\n/** One row per committed message. The primary key is the idempotency claim. */\nexport const processedMessages = pgTable('processed_messages', {\n  messageId: text('message_id').primaryKey(),\n  processedAt: timestamp('processed_at', { withTimezone: true }).notNull().defaultNow(),\n})\n\n/** Events committed with their state change, waiting for the relay to deliver them. */\nexport const messageOutbox = pgTable(\n  'message_outbox',\n  {\n    id: text('id').primaryKey(),\n    payload: jsonb('payload').$type<DomainEvent>().notNull(),\n    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n    availableAt: timestamp('available_at', { withTimezone: true }).notNull().defaultNow(),\n    attempts: integer('attempts').notNull().default(0),\n    claimToken: text('claim_token'),\n    claimExpiresAt: timestamp('claim_expires_at', { withTimezone: true }),\n    publishedAt: timestamp('published_at', { withTimezone: true }),\n    failedAt: timestamp('failed_at', { withTimezone: true }),\n    lastError: text('last_error'),\n  },\n  (table) => [\n    index('idx_message_outbox_due')\n      .on(table.availableAt, table.createdAt)\n      .where(isNull(table.publishedAt)),\n    index('idx_message_outbox_claim_token').on(table.claimToken),\n  ],\n)\n","import { MessageAlreadyProcessedError, type IMessageStore, type MessageId } from '@/application'\nimport type { DomainEvent } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport type { PostgresDbTransaction } from './postgres-database-types.ts'\nimport { messageOutbox, processedMessages } from './postgres-schema.ts'\n\n/** Processed messages and outbox events share the active Postgres transaction; the insert result establishes the claim. */\nexport class PostgresMessageStore<Schema extends DrizzleSchema> implements IMessageStore {\n  constructor(private readonly db: PostgresDbTransaction<Schema>) {}\n\n  async claim(messageId: MessageId): Promise<void> {\n    const claimed = await this.db\n      .insert(processedMessages)\n      .values({ messageId })\n      .onConflictDoNothing()\n      .returning({ messageId: processedMessages.messageId })\n    // Thrown inside the transaction, so drizzle rolls back everything written before the claim.\n    if (claimed.length === 0) throw new MessageAlreadyProcessedError(messageId)\n  }\n\n  async persistEvents(events: ReadonlyArray<DomainEvent>): Promise<void> {\n    if (events.length === 0) return\n    await this.db\n      .insert(messageOutbox)\n      .values(events.map((event) => ({ id: event.id, payload: event })))\n  }\n}\n","import type { ITransaction } from '@/application'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport { runWithUnitOfWorkContext } from '../unit-of-work-context.ts'\nimport { executeDatabase } from './postgres-database-execution.ts'\nimport type { PostgresDb, PostgresTx } from './postgres-database-types.ts'\n\n/**\n * The Postgres transaction boundary uses native Drizzle transactions through postgres.js.\n * Drizzle commits when `work` returns and rolls back when it throws.\n */\nexport class PostgresTransaction<Schema extends DrizzleSchema> implements ITransaction<\n  PostgresTx<Schema>\n> {\n  constructor(private readonly db: PostgresDb<Schema>) {}\n\n  transaction<T>(work: (tx: PostgresTx<Schema>) => Promise<T>): Promise<T> {\n    return runWithUnitOfWorkContext('postgres', () =>\n      executeDatabase('unit of work transaction', () => this.db.transaction((db) => work({ db }))),\n    )\n  }\n}\n","import { and, asc, eq, inArray, isNull, lt, lte, or, sql } from 'drizzle-orm'\n\nimport type { DeadLetterReason, IOutboxRepository, OutboxClaim, OutboxMessage } from '@/application'\nimport { exponentialDelayCapMs } from '@/core'\n\nimport type { DrizzleSchema } from '../drizzle-schema.ts'\nimport {\n  OUTBOX_REPOSITORY_DEFAULTS,\n  type OutboxRepositoryOptions,\n} from '../outbox-repository-options.ts'\nimport { executeDatabase } from './postgres-database-execution.ts'\nimport type { PostgresDb } from './postgres-database-types.ts'\nimport { messageOutbox, processedMessages } from './postgres-schema.ts'\n\n/**\n * Typist's lease protocol with riposte's SKIP LOCKED selection on a plain connection, outside a unit of work.\n * Every write runs once; lease expiry and the scheduled sweep recover interrupted operations.\n */\nexport class PostgresOutboxRepository implements IOutboxRepository {\n  private readonly options: Required<OutboxRepositoryOptions>\n\n  constructor(\n    private readonly db: PostgresDb<DrizzleSchema>,\n    options: OutboxRepositoryOptions = {},\n    private readonly now: () => Date = () => new Date(),\n  ) {\n    this.options = { ...OUTBOX_REPOSITORY_DEFAULTS, ...options }\n  }\n\n  /** Lease due rows in one statement; increment attempts even when reclaiming an expired lease. */\n  async claimPending(batchSize: number): Promise<OutboxClaim> {\n    const token = crypto.randomUUID()\n    const now = this.now()\n    const rows = await executeDatabase('claim pending outbox messages', () =>\n      this.db\n        .update(messageOutbox)\n        .set({\n          claimToken: token,\n          claimExpiresAt: new Date(now.getTime() + this.options.leaseMs),\n          attempts: sql`${messageOutbox.attempts} + 1`,\n        })\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(\n                and(\n                  isNull(messageOutbox.publishedAt),\n                  isNull(messageOutbox.failedAt),\n                  lte(messageOutbox.availableAt, now),\n                  or(isNull(messageOutbox.claimExpiresAt), lte(messageOutbox.claimExpiresAt, now)),\n                ),\n              )\n              .orderBy(\n                asc(messageOutbox.availableAt),\n                asc(messageOutbox.createdAt),\n                asc(messageOutbox.id),\n              )\n              .limit(batchSize)\n              .for('update', { skipLocked: true }),\n          ),\n        )\n        .returning({\n          payload: messageOutbox.payload,\n          attempts: messageOutbox.attempts,\n          availableAt: messageOutbox.availableAt,\n          createdAt: messageOutbox.createdAt,\n        }),\n    )\n    // UPDATE RETURNING does not preserve the selection order.\n    rows.sort(\n      (a, b) =>\n        a.availableAt.getTime() - b.availableAt.getTime() ||\n        a.createdAt.getTime() - b.createdAt.getTime() ||\n        a.payload.id.localeCompare(b.payload.id),\n    )\n    return { token, messages: rows.map(({ payload, attempts }) => ({ payload, attempts })) }\n  }\n\n  /** Mark only supplied rows that still hold this token as published. */\n  async markPublished(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {\n    if (messages.length === 0) return\n    await executeDatabase('mark outbox messages published', () =>\n      this.db\n        .update(messageOutbox)\n        .set({ publishedAt: this.now(), claimToken: null, claimExpiresAt: null })\n        .where(\n          and(\n            inArray(\n              messageOutbox.id,\n              messages.map((row) => row.payload.id),\n            ),\n            eq(messageOutbox.claimToken, claim.token),\n          ),\n        ),\n    )\n  }\n\n  /** Release supplied rows with per-row backoff; a stale token cannot change a newer claim. */\n  async releaseClaim(claim: OutboxClaim, messages: ReadonlyArray<OutboxMessage>): Promise<void> {\n    const now = this.now()\n    for (const attempts of new Set(messages.map((row) => row.attempts))) {\n      const ids = messages.filter((row) => row.attempts === attempts).map((row) => row.payload.id)\n      const delay = exponentialDelayCapMs(\n        this.options.retryBaseDelayMs,\n        this.options.retryMaxDelayMs,\n        attempts,\n      )\n      // oxlint-disable-next-line no-await-in-loop -- Stop releasing rows on the first database failure.\n      await executeDatabase('release outbox claim', () =>\n        this.db\n          .update(messageOutbox)\n          .set({\n            availableAt: new Date(now.getTime() + delay),\n            claimToken: null,\n            claimExpiresAt: null,\n          })\n          .where(and(inArray(messageOutbox.id, ids), eq(messageOutbox.claimToken, claim.token))),\n      )\n    }\n  }\n\n  /** Retain the full payload and record a closed reason with a readable error message. */\n  async deadLetter(\n    claim: OutboxClaim,\n    messages: ReadonlyArray<OutboxMessage>,\n    reason: DeadLetterReason,\n    errorMessage: string,\n  ): Promise<void> {\n    if (messages.length === 0) return\n    await executeDatabase('dead-letter outbox messages', () =>\n      this.db\n        .update(messageOutbox)\n        .set({\n          failedAt: this.now(),\n          lastError: `${reason}: ${errorMessage}`,\n          claimToken: null,\n          claimExpiresAt: null,\n        })\n        .where(\n          and(\n            inArray(\n              messageOutbox.id,\n              messages.map((row) => row.payload.id),\n            ),\n            eq(messageOutbox.claimToken, claim.token),\n          ),\n        ),\n    )\n  }\n\n  /** Delete at most batchSize published rows, strictly before the cutoff. */\n  async deletePublishedBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete published outbox messages', () =>\n      this.db\n        .delete(messageOutbox)\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(lt(messageOutbox.publishedAt, cutoff))\n              .orderBy(asc(messageOutbox.publishedAt), asc(messageOutbox.id))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ id: messageOutbox.id }),\n    )\n    return rows.length\n  }\n\n  /** Delete at most batchSize failed rows; pending and published rows remain untouched. */\n  async deleteFailedBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete failed outbox messages', () =>\n      this.db\n        .delete(messageOutbox)\n        .where(\n          inArray(\n            messageOutbox.id,\n            this.db\n              .select({ id: messageOutbox.id })\n              .from(messageOutbox)\n              .where(and(isNull(messageOutbox.publishedAt), lt(messageOutbox.failedAt, cutoff)))\n              .orderBy(asc(messageOutbox.failedAt), asc(messageOutbox.id))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ id: messageOutbox.id }),\n    )\n    return rows.length\n  }\n\n  /** Delete at most batchSize receipts, strictly before the cutoff. */\n  async deleteReceiptsBefore(cutoff: Date, batchSize: number): Promise<number> {\n    const rows = await executeDatabase('delete message receipts', () =>\n      this.db\n        .delete(processedMessages)\n        .where(\n          inArray(\n            processedMessages.messageId,\n            this.db\n              .select({ messageId: processedMessages.messageId })\n              .from(processedMessages)\n              .where(lt(processedMessages.processedAt, cutoff))\n              .orderBy(asc(processedMessages.processedAt), asc(processedMessages.messageId))\n              .limit(batchSize),\n          ),\n        )\n        .returning({ messageId: processedMessages.messageId }),\n    )\n    return rows.length\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -26,6 +26,8 @@
     "./cloudflare/auth-secondary-storage": "./dist/cloudflare/auth-secondary-storage.js",
     "./cloudflare/durable-object-client": "./dist/cloudflare/durable-object-client.js",
     "./cloudflare/durable-object-errors": "./dist/cloudflare/durable-object-errors.js",
+    "./cloudflare/kv-client": "./dist/cloudflare/kv-client.js",
+    "./cloudflare/kv-errors": "./dist/cloudflare/kv-errors.js",
     "./cloudflare/queue": "./dist/cloudflare/queue.js",
     "./cloudflare/scheduled": "./dist/cloudflare/scheduled.js",
     "./core": "./dist/core.js",

package/src/infrastructure/cloudflare/d1-database-execution.ts

@@ -1,13 +1,34 @@
+import { Result } from 'better-result'
+
+import { DatabaseError } from '@/core'
+
 import { classifyD1Error } from './classify-d1-error.ts'
 
-/** Execute once without retries; convert recognized D1 failures and preserve other exceptions unchanged. */
+/**
+ * Convert database failures and preserve other exceptions. The default executes once.
+ * Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.
+ */
 export async function executeDatabase<T>(
   operation: string,
   work: () => PromiseLike<T>,
+  options: { readonly retry?: 'never' | 'transient' } = {},
 ): Promise<T> {
-  try {
-    return await work()
-  } catch (cause) {
-    throw classifyD1Error(cause, operation) ?? cause
-  }
+  const result = await Result.tryPromise(
+    {
+      try: async () => await work(),
+      catch: (cause) => classifyD1Error(cause, operation) ?? cause,
+    },
+    {
+      retry: {
+        times: options.retry === 'transient' ? 2 : 0,
+        delayMs: 250,
+        backoff: 'exponential',
+        jitter: true,
+        shouldRetry: (error) =>
+          error instanceof DatabaseError && error.classification === 'transient',
+      },
+    },
+  )
+  if (result.isErr()) throw result.error
+  return result.value
 }

package/src/infrastructure/cloudflare/kv-client.ts

@@ -0,0 +1,79 @@
+import { Result } from 'better-result'
+
+import { exponentialDelayCapMs, spreadJitterMs } from '@/core'
+
+import { decideKVRetry, isKVPutRateLimitError, KVError } from './kv-errors.ts'
+
+/** Text storage bridge with the same TTL behavior as KVClient. */
+export type KVSecondaryStorage = {
+  get: (key: string) => Promise<string | null>
+  set: (key: string, value: string, ttl?: number) => Promise<void>
+  delete: (key: string) => Promise<void>
+}
+
+type KVOperation = 'get' | 'put' | 'delete'
+
+/** KV access with Typist's automatic transient retries and final KVError conversion. */
+export class KVClient {
+  constructor(private readonly kv: KVNamespace) {}
+
+  /** Read text, or return null when the key does not exist. */
+  async get(key: string): Promise<string | null> {
+    return await this.run('get', key, async () => this.kv.get(key))
+  }
+
+  /** Read JSON without schema validation; the caller supplies its stored type. */
+  async getJson<T>(key: string): Promise<T | null> {
+    return await this.run('get', key, async () => this.kv.get<T>(key, 'json'))
+  }
+
+  /** Write text; positive TTL values pass to KV in seconds, and other TTL values omit expiration. */
+  async put(key: string, value: string, options?: { ttl?: number | undefined }): Promise<void> {
+    const kvOptions: KVNamespacePutOptions = {}
+    if (options?.ttl !== undefined && options.ttl > 0) {
+      kvOptions.expirationTtl = options.ttl
+    }
+    await this.run('put', key, async () => this.kv.put(key, value, kvOptions))
+  }
+
+  /** Serialize once before writing; serialization failures retain their original error. */
+  async putJson(
+    key: string,
+    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Preserve the approved JSON serialization boundary and Typist's public signature.
+    value: unknown,
+    options?: { ttl?: number | undefined },
+  ): Promise<void> {
+    await this.put(key, JSON.stringify(value), options)
+  }
+
+  /** Delete a key; a missing key succeeds, and transient failures retry automatically. */
+  async delete(key: string): Promise<void> {
+    await this.run('delete', key, async () => this.kv.delete(key))
+  }
+
+  /** Expose Typist's three-method secondary storage bridge without changing KV semantics. */
+  asSecondaryStorage(): KVSecondaryStorage {
+    return {
+      get: (key) => this.get(key),
+      set: (key, value, ttl) => this.put(key, value, { ttl }),
+      delete: (key) => this.delete(key),
+    }
+  }
+
+  private async run<T>(operation: KVOperation, key: string, work: () => Promise<T>): Promise<T> {
+    const result = await Result.tryPromise(
+      { try: work, catch: (cause) => cause },
+      {
+        retry: {
+          times: 2,
+          shouldRetry: (cause) => decideKVRetry(cause).retry,
+          delayMs: (cause, { attempt }) =>
+            (isKVPutRateLimitError(cause) ? 1_000 : 0) +
+            spreadJitterMs(exponentialDelayCapMs(25, 3_000, attempt)),
+        },
+      },
+    )
+    if (result.isOk()) return result.value
+    throw new KVError({ operation, key, cause: result.error })
+  }
+}

package/src/infrastructure/cloudflare/kv-errors.ts

@@ -0,0 +1,157 @@
+import {
+  AppError,
+  isCloudflareOverloadedError,
+  isCloudflareRetryableError,
+  isTransientTransportError,
+  type FailureClassification,
+} from '@/core'
+
+/** KV operations recognized in binding error messages. */
+export type KVOperation = 'get' | 'put' | 'delete' | 'list'
+
+/** KV failure kinds retained from Typist's binding tests. */
+export type KVErrorKind =
+  | 'invalid_key'
+  | 'key_too_large'
+  | 'invalid_expiration_ttl'
+  | 'invalid_expiration'
+  | 'invalid_cache_ttl'
+  | 'invalid_list_limit'
+  | 'value_too_large'
+  | 'client_error'
+  | 'rate_limited'
+  | 'server_error'
+
+/** Evidence extracted from a KV error and its causes. */
+export interface KVErrorMeta {
+  kind: KVErrorKind
+  message: string
+  status?: number | undefined
+  operation?: Uppercase<KVOperation> | undefined
+}
+
+/** Extract Typist's verified KV message formats, including nested causes. */
+export function extractKVMeta(cause: unknown): KVErrorMeta | undefined {
+  const message = getDeepErrorMessage(cause)
+  if (!message) return undefined
+  const statusMatch = message.match(/\bKV\s+(GET|PUT|DELETE|LIST)\s+failed:\s+(\d{3})\b/)
+  // SAFETY: The regular expression permits only uppercase KV operation names in this capture.
+  const operation = statusMatch?.[1] as Uppercase<KVOperation> | undefined
+  const status = statusMatch ? Number(statusMatch[2]) : undefined
+
+  if (/Key name cannot be empty/i.test(message)) {
+    return { kind: 'invalid_key', message, status, operation }
+  }
+  if (/exceeds key length limit/i.test(message)) {
+    return { kind: 'key_too_large', message, status, operation }
+  }
+  if (/Invalid expiration_ttl/i.test(message)) {
+    return { kind: 'invalid_expiration_ttl', message, status, operation }
+  }
+  if (/Invalid expiration of/i.test(message)) {
+    return { kind: 'invalid_expiration', message, status, operation }
+  }
+  if (/Invalid cache_ttl/i.test(message)) {
+    return { kind: 'invalid_cache_ttl', message, status, operation }
+  }
+  if (/Invalid key_count_limit/i.test(message)) {
+    return { kind: 'invalid_list_limit', message, status, operation }
+  }
+  if (/value.*(too large|exceeds)|exceeds.*value/i.test(message)) {
+    return { kind: 'value_too_large', message, status, operation }
+  }
+  if (status === 429) return { kind: 'rate_limited', message, status, operation }
+  if (status !== undefined && status >= 500) {
+    return { kind: 'server_error', message, status, operation }
+  }
+  if (status !== undefined && status >= 400) {
+    return { kind: 'client_error', message, status, operation }
+  }
+  return undefined
+}
+
+/** Identify recognized KV failures that another attempt cannot resolve. */
+export function isTerminalKVError(cause: unknown): boolean {
+  const meta = extractKVMeta(cause)
+  if (!meta) return false
+  if (meta.kind === 'rate_limited' || meta.kind === 'server_error') return false
+  if (meta.status === 408) return false
+  return true
+}
+
+/** Identify a PUT rate limit that requires at least one second before retrying. */
+export function isKVPutRateLimitError(cause: unknown): boolean {
+  const meta = extractKVMeta(cause)
+  return meta?.operation === 'PUT' && meta.kind === 'rate_limited'
+}
+
+/** Identify PUT rate limits, server failures, and request timeouts. */
+export function isTransientKVError(cause: unknown): boolean {
+  const meta = extractKVMeta(cause)
+  if (!meta) return false
+  return isKVPutRateLimitError(cause) || meta.kind === 'server_error' || meta.status === 408
+}
+
+/** Apply Typist's KV, overload, platform, and transport checks in their original order. */
+export function isRetryableKVError(cause: unknown): boolean {
+  if (isTerminalKVError(cause)) return false
+  if (isTransientKVError(cause)) return true
+  if (isCloudflareOverloadedError(cause)) return false
+  return isCloudflareRetryableError(cause) || isTransientTransportError(cause)
+}
+
+/** Return the existing retry decision and minimum delay in milliseconds. */
+export function decideKVRetry(
+  cause: unknown,
+): { retry: false } | { retry: true; retryAfterMs: number } {
+  if (!isRetryableKVError(cause)) return { retry: false }
+  return { retry: true, retryAfterMs: isKVPutRateLimitError(cause) ? 1_000 : 0 }
+}
+
+/** A final KV failure with Typist's diagnostics and Better Ship's error classification. */
+export class KVError extends AppError {
+  readonly _tag = 'KVError'
+  readonly classification: FailureClassification
+  retryable: boolean
+  readonly operation: KVOperation
+  readonly key?: string | undefined
+  override readonly cause: unknown
+  readonly kv?: KVErrorMeta | undefined
+  readonly context: {
+    operation: KVOperation
+    key?: string | undefined
+    kv?: KVErrorMeta | undefined
+  }
+
+  constructor(args: { operation: KVOperation; key?: string | undefined; cause: unknown }) {
+    const kv = extractKVMeta(args.cause)
+    const causeMessage = getDeepErrorMessage(args.cause) || String(args.cause)
+    const keyContext = args.key === undefined ? '' : ` for key "${args.key}"`
+    super(`KV ${args.operation} failed${keyContext}: ${causeMessage}`, { cause: args.cause })
+    this.operation = args.operation
+    this.key = args.key
+    this.cause = args.cause
+    this.kv = kv
+    this.context = { operation: args.operation, key: args.key, kv }
+    this.retryable = isRetryableKVError(args.cause)
+    this.classification = isTerminalKVError(args.cause)
+      ? 'terminal'
+      : this.retryable
+        ? 'transient'
+        : 'unknown'
+  }
+}
+
+// oxlint-disable anti-slop/no-runtime-typeof -- Preserve Typist's primitive messages and nested causes at the raw binding boundary.
+function getDeepErrorMessage(cause: unknown): string {
+  if (typeof cause === 'string') return cause
+  if (cause === null || cause === undefined) return ''
+  if (typeof cause === 'number' || typeof cause === 'boolean' || typeof cause === 'bigint') {
+    return String(cause)
+  }
+  if (typeof cause !== 'object') return ''
+  const message = 'message' in cause && typeof cause.message === 'string' ? cause.message : ''
+  const causeMessage = 'cause' in cause ? getDeepErrorMessage(cause.cause) : ''
+  return `${message} ${causeMessage}`.trim()
+}
+// oxlint-enable anti-slop/no-runtime-typeof

package/src/infrastructure/postgres/postgres-database-execution.ts

@@ -1,13 +1,34 @@
+import { Result } from 'better-result'
+
+import { DatabaseError } from '@/core'
+
 import { classifyPostgresError } from './classify-postgres-error.ts'
 
-/** Execute once without retries; convert recognized Postgres failures and preserve other exceptions unchanged. */
+/**
+ * Convert database failures and preserve other exceptions. The default executes once.
+ * Opt-in transient retries allow three attempts with full jitter and backoff caps of 250 ms and 500 ms.
+ */
 export async function executeDatabase<T>(
   operation: string,
   work: () => PromiseLike<T>,
+  options: { readonly retry?: 'never' | 'transient' } = {},
 ): Promise<T> {
-  try {
-    return await work()
-  } catch (cause) {
-    throw classifyPostgresError(cause, operation) ?? cause
-  }
+  const result = await Result.tryPromise(
+    {
+      try: async () => await work(),
+      catch: (cause) => classifyPostgresError(cause, operation) ?? cause,
+    },
+    {
+      retry: {
+        times: options.retry === 'transient' ? 2 : 0,
+        delayMs: 250,
+        backoff: 'exponential',
+        jitter: true,
+        shouldRetry: (error) =>
+          error instanceof DatabaseError && error.classification === 'transient',
+      },
+    },
+  )
+  if (result.isErr()) throw result.error
+  return result.value
 }