@hotmeshio/hotmesh 0.14.5 → 0.14.6

package/build/modules/enums.d.ts

@@ -161,6 +161,42 @@ export declare const HMSH_BLOCK_TIME_MS: number;
 export declare const HMSH_XCLAIM_DELAY_MS: number;
 export declare const HMSH_XCLAIM_COUNT: number;
 export declare const HMSH_XPENDING_COUNT: number;
+export declare const HMSH_BATCH_SIZE: number;
+/**
+ * Postgres stream reservation timeout in seconds (default: 30).
+ *
+ * This is the **starting** reservation timeout for the Postgres stream
+ * consumer. When a consumer reserves a message from the stream, it must
+ * acknowledge it within this window. If processing takes longer, the
+ * message becomes available to other consumers — causing duplicate
+ * delivery, collation errors, and wasted CPU.
+ *
+ * **Adaptive behavior:** The router automatically adjusts this timeout
+ * at runtime based on stream depth. When the queue backs up (depth > 100),
+ * the timeout doubles (up to 600s). When the queue drains (depth < 10),
+ * it halves back toward this configured default. This prevents duplicate
+ * delivery under burst load without manual intervention.
+ *
+ * **When to increase this value:** If you see `process-event-*-error`
+ * warnings at `warn` level or `stream-reservation-timeout-adjusted` logs
+ * scaling up frequently, your baseline is too low for your workload.
+ * Setting a higher default reduces how aggressively the system must
+ * adapt during load spikes.
+ *
+ * **Symptoms of a value that is too low:**
+ *   - `collation-error` from `verifySyntheticInteger` (warn level)
+ *   - `process-event-collation-rate-exceeded` warning with guidance
+ *   - `stream-reservation-timeout-adjusted` logs showing rapid scaling
+ *   - Workflow stalls or timeouts under sustained concurrent load
+ *
+ * @example
+ * // Production with sustained high concurrency
+ * HMSH_RESERVATION_TIMEOUT_S=120
+ *
+ * // Low-latency environments with fast processing
+ * HMSH_RESERVATION_TIMEOUT_S=30  (default)
+ */
+export declare const HMSH_RESERVATION_TIMEOUT_S: number;
 export declare const HMSH_EXPIRE_DURATION: number;
 export declare const HMSH_FIDELITY_SECONDS: number;
 export declare const HMSH_SCOUT_INTERVAL_SECONDS: number;

package/build/modules/enums.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HMSH_ROUTER_SCOUT_INTERVAL_MS = exports.HMSH_ROUTER_SCOUT_INTERVAL_SECONDS = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_PENDING_SIGNAL_EXPIRE = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
-exports.HMSH_ROUTER_POLL_FALLBACK_INTERVAL = exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = void 0;
+exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_RESERVATION_TIMEOUT_S = exports.HMSH_BATCH_SIZE = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_PENDING_SIGNAL_EXPIRE = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
+exports.HMSH_ROUTER_POLL_FALLBACK_INTERVAL = exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_ROUTER_SCOUT_INTERVAL_MS = exports.HMSH_ROUTER_SCOUT_INTERVAL_SECONDS = void 0;
 /**
  * Determines the log level for the application. The default is 'info'.
  */
@@ -178,6 +178,42 @@ exports.HMSH_BLOCK_TIME_MS = process.env.HMSH_BLOCK_TIME_MS
 exports.HMSH_XCLAIM_DELAY_MS = parseInt(process.env.HMSH_XCLAIM_DELAY_MS, 10) || 1000 * 60;
 exports.HMSH_XCLAIM_COUNT = parseInt(process.env.HMSH_XCLAIM_COUNT, 10) || 3;
 exports.HMSH_XPENDING_COUNT = parseInt(process.env.HMSH_XPENDING_COUNT, 10) || 10;
+exports.HMSH_BATCH_SIZE = parseInt(process.env.HMSH_BATCH_SIZE, 10) || 10;
+/**
+ * Postgres stream reservation timeout in seconds (default: 30).
+ *
+ * This is the **starting** reservation timeout for the Postgres stream
+ * consumer. When a consumer reserves a message from the stream, it must
+ * acknowledge it within this window. If processing takes longer, the
+ * message becomes available to other consumers — causing duplicate
+ * delivery, collation errors, and wasted CPU.
+ *
+ * **Adaptive behavior:** The router automatically adjusts this timeout
+ * at runtime based on stream depth. When the queue backs up (depth > 100),
+ * the timeout doubles (up to 600s). When the queue drains (depth < 10),
+ * it halves back toward this configured default. This prevents duplicate
+ * delivery under burst load without manual intervention.
+ *
+ * **When to increase this value:** If you see `process-event-*-error`
+ * warnings at `warn` level or `stream-reservation-timeout-adjusted` logs
+ * scaling up frequently, your baseline is too low for your workload.
+ * Setting a higher default reduces how aggressively the system must
+ * adapt during load spikes.
+ *
+ * **Symptoms of a value that is too low:**
+ *   - `collation-error` from `verifySyntheticInteger` (warn level)
+ *   - `process-event-collation-rate-exceeded` warning with guidance
+ *   - `stream-reservation-timeout-adjusted` logs showing rapid scaling
+ *   - Workflow stalls or timeouts under sustained concurrent load
+ *
+ * @example
+ * // Production with sustained high concurrency
+ * HMSH_RESERVATION_TIMEOUT_S=120
+ *
+ * // Low-latency environments with fast processing
+ * HMSH_RESERVATION_TIMEOUT_S=30  (default)
+ */
+exports.HMSH_RESERVATION_TIMEOUT_S = parseInt(process.env.HMSH_RESERVATION_TIMEOUT_S, 10) || 30;
 // TASK WORKER
 exports.HMSH_EXPIRE_DURATION = parseInt(process.env.HMSH_EXPIRE_DURATION, 10) || 1;
 const BASE_FIDELITY_SECONDS = 5;

package/build/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.14.5",
+    "version": "0.14.6",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
-    "homepage": "https://github.com/hotmeshio/sdk-typescript/",
+    "homepage": "https://docs.hotmesh.io/",
     "publishConfig": {
         "access": "public"
     },
@@ -30,6 +30,7 @@
         "test:durable:postgres": "HMSH_LOGLEVEL=info vitest run tests/durable",
         "test:durable:basic": "HMSH_LOGLEVEL=info vitest run tests/durable/basic/postgres.test.ts",
         "test:durable:collision": "vitest run tests/durable/collision/postgres.test.ts",
+        "test:durable:contention": "vitest run tests/durable/contention/postgres.test.ts",
         "test:durable:fatal": "vitest run tests/durable/fatal",
         "test:durable:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/durable/goodbye/postgres.test.ts",
         "test:durable:interceptor": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts",

package/build/services/activities/activity/process.js

@@ -6,6 +6,11 @@ const errors_1 = require("../../../modules/errors");
 const collator_1 = require("../../collator");
 const telemetry_1 = require("../../telemetry");
 const stream_1 = require("../../../types/stream");
+// Per-instance collation error tracking for reservation timeout detection
+let collationErrorCount = 0;
+let collationWindowStart = Date.now();
+const COLLATION_WARN_THRESHOLD = 10;
+const COLLATION_WINDOW_MS = 60000;
 async function processEvent(instance, status = stream_1.StreamStatus.SUCCESS, code = 200, type = 'output') {
     instance.setLeg(2);
     const jid = instance.context.metadata.jid;
@@ -66,7 +71,32 @@ async function processEvent(instance, status = stream_1.StreamStatus.SUCCESS, co
     }
     catch (error) {
         if (error instanceof errors_1.CollationError) {
-            instance.logger.info(`process-event-${error.fault}-error`, { error });
+            // INACTIVE is legitimate duplicate detection — the Postgres atomic
+            // CTE (collateLeg2Entry) serializes via row locks, so the GUID
+            // ledger value is correct. Silent ack is the right behavior:
+            // the work was already done by a prior delivery of this message.
+            const now = Date.now();
+            if (now - collationWindowStart > COLLATION_WINDOW_MS) {
+                collationErrorCount = 0;
+                collationWindowStart = now;
+            }
+            collationErrorCount++;
+            if (collationErrorCount === COLLATION_WARN_THRESHOLD) {
+                instance.logger.warn('process-event-collation-rate-exceeded', {
+                    count: collationErrorCount,
+                    windowMs: COLLATION_WINDOW_MS,
+                    reservationTimeoutS: enums_1.HMSH_RESERVATION_TIMEOUT_S,
+                    message: `${COLLATION_WARN_THRESHOLD} collation errors in ${COLLATION_WINDOW_MS / 1000}s. ` +
+                        `This typically means HMSH_RESERVATION_TIMEOUT_S (currently ${enums_1.HMSH_RESERVATION_TIMEOUT_S}s) ` +
+                        `is too short for your workload — messages are being re-reserved before processing completes, ` +
+                        `causing duplicate delivery. Increase HMSH_RESERVATION_TIMEOUT_S.`,
+                });
+            }
+            instance.logger.warn(`process-event-${error.fault}-error`, {
+                jid: instance.context.metadata.jid,
+                aid: instance.metadata.aid,
+                error,
+            });
             return;
         }
         else if (error instanceof errors_1.InactiveJobError) {

package/build/services/router/config/index.d.ts

@@ -1,4 +1,4 @@
-import { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD } from '../../../modules/enums';
+import { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, HMSH_BATCH_SIZE, HMSH_RESERVATION_TIMEOUT_S, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD } from '../../../modules/enums';
 import { RouterConfig } from '../../../types/stream';
 export declare class RouterConfigManager {
     static validateThrottle(delayInMillis: number): void;
@@ -8,4 +8,4 @@ export declare class RouterConfigManager {
         readonly: boolean;
     };
 }
-export { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD, };
+export { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, HMSH_BATCH_SIZE, HMSH_RESERVATION_TIMEOUT_S, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD, };

package/build/services/router/config/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.MAX_DELAY = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_XCLAIM_COUNT = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_UNACKED = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.HMSH_BLOCK_TIME_MS = exports.RouterConfigManager = void 0;
+exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.MAX_DELAY = exports.HMSH_RESERVATION_TIMEOUT_S = exports.HMSH_BATCH_SIZE = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_XCLAIM_COUNT = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_UNACKED = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.HMSH_BLOCK_TIME_MS = exports.RouterConfigManager = void 0;
 const enums_1 = require("../../../modules/enums");
 Object.defineProperty(exports, "HMSH_BLOCK_TIME_MS", { enumerable: true, get: function () { return enums_1.HMSH_BLOCK_TIME_MS; } });
 Object.defineProperty(exports, "HMSH_MAX_RETRIES", { enumerable: true, get: function () { return enums_1.HMSH_MAX_RETRIES; } });
@@ -12,6 +12,8 @@ Object.defineProperty(exports, "HMSH_STATUS_UNKNOWN", { enumerable: true, get: f
 Object.defineProperty(exports, "HMSH_XCLAIM_COUNT", { enumerable: true, get: function () { return enums_1.HMSH_XCLAIM_COUNT; } });
 Object.defineProperty(exports, "HMSH_XCLAIM_DELAY_MS", { enumerable: true, get: function () { return enums_1.HMSH_XCLAIM_DELAY_MS; } });
 Object.defineProperty(exports, "HMSH_XPENDING_COUNT", { enumerable: true, get: function () { return enums_1.HMSH_XPENDING_COUNT; } });
+Object.defineProperty(exports, "HMSH_BATCH_SIZE", { enumerable: true, get: function () { return enums_1.HMSH_BATCH_SIZE; } });
+Object.defineProperty(exports, "HMSH_RESERVATION_TIMEOUT_S", { enumerable: true, get: function () { return enums_1.HMSH_RESERVATION_TIMEOUT_S; } });
 Object.defineProperty(exports, "MAX_DELAY", { enumerable: true, get: function () { return enums_1.MAX_DELAY; } });
 Object.defineProperty(exports, "MAX_STREAM_BACKOFF", { enumerable: true, get: function () { return enums_1.MAX_STREAM_BACKOFF; } });
 Object.defineProperty(exports, "INITIAL_STREAM_BACKOFF", { enumerable: true, get: function () { return enums_1.INITIAL_STREAM_BACKOFF; } });

package/build/services/router/consumption/index.d.ts

@@ -26,7 +26,20 @@ export declare class ConsumptionManager<S extends StreamService<ProviderClient,
     private set hasReachedMaxBackoff(value);
     private router;
     private retry;
+    private adaptiveReservationTimeout;
+    private lastDepthCheckAt;
+    private static readonly DEPTH_CHECK_INTERVAL_MS;
+    private static readonly DEPTH_SCALE_UP_THRESHOLD;
+    private static readonly DEPTH_SCALE_DOWN_THRESHOLD;
+    private static readonly RESERVATION_TIMEOUT_MAX_S;
     constructor(stream: S, logger: ILogger, throttleManager: ThrottleManager, errorHandler: ErrorHandler, lifecycleManager: LifecycleManager<S>, reclaimDelay: number, reclaimCount: number, appId: string, role: any, router: any, retry?: import('../../../types/stream').RetryPolicy);
+    /**
+     * Adjusts reservation timeout based on stream depth. Called periodically
+     * from the consume loop. When depth is high, messages take longer to
+     * process, so the reservation window must grow to prevent re-delivery.
+     * When depth drops, the timeout shrinks back toward the configured default.
+     */
+    private adjustReservationTimeout;
     createGroup(stream: string, group: string): Promise<void>;
     publishMessage(topic: string, streamData: StreamData | StreamDataResponse, transaction?: ProviderTransaction): Promise<string | ProviderTransaction>;
     consumeMessages(stream: string, group: string, consumer: string, callback: (streamData: StreamData) => Promise<StreamDataResponse | void>): Promise<void>;

package/build/services/router/consumption/index.js

@@ -17,6 +17,11 @@ class ConsumptionManager {
     get hasReachedMaxBackoff() { return this.router.hasReachedMaxBackoff; }
     set hasReachedMaxBackoff(v) { this.router.hasReachedMaxBackoff = v; }
     constructor(stream, logger, throttleManager, errorHandler, lifecycleManager, reclaimDelay, reclaimCount, appId, role, router, retry) {
+        // Adaptive reservation timeout — scales with stream depth to prevent
+        // duplicate message delivery under load. When the stream backs up,
+        // processing takes longer, so the reservation window must grow.
+        this.adaptiveReservationTimeout = config_1.HMSH_RESERVATION_TIMEOUT_S;
+        this.lastDepthCheckAt = 0;
         this.stream = stream;
         this.logger = logger;
         this.throttleManager = throttleManager;
@@ -29,6 +34,46 @@ class ConsumptionManager {
         this.router = router;
         this.retry = retry;
     }
+    /**
+     * Adjusts reservation timeout based on stream depth. Called periodically
+     * from the consume loop. When depth is high, messages take longer to
+     * process, so the reservation window must grow to prevent re-delivery.
+     * When depth drops, the timeout shrinks back toward the configured default.
+     */
+    async adjustReservationTimeout(stream) {
+        const now = Date.now();
+        if (now - this.lastDepthCheckAt < ConsumptionManager.DEPTH_CHECK_INTERVAL_MS) {
+            return;
+        }
+        this.lastDepthCheckAt = now;
+        try {
+            const depth = await this.stream.getStreamDepth(stream);
+            const prev = this.adaptiveReservationTimeout;
+            if (depth > ConsumptionManager.DEPTH_SCALE_UP_THRESHOLD) {
+                // Scale up: double the timeout, capped at max
+                this.adaptiveReservationTimeout = Math.min(this.adaptiveReservationTimeout * 2, ConsumptionManager.RESERVATION_TIMEOUT_MAX_S);
+            }
+            else if (depth < ConsumptionManager.DEPTH_SCALE_DOWN_THRESHOLD) {
+                // Scale down: halve toward the configured default
+                this.adaptiveReservationTimeout = Math.max(Math.floor(this.adaptiveReservationTimeout / 2), config_1.HMSH_RESERVATION_TIMEOUT_S);
+            }
+            if (this.adaptiveReservationTimeout !== prev) {
+                // Update the stream provider so notification-path fetches
+                // also use the adaptive timeout
+                this.stream.reservationTimeout = this.adaptiveReservationTimeout;
+                this.logger.info('stream-reservation-timeout-adjusted', {
+                    stream,
+                    depth,
+                    previousTimeoutS: prev,
+                    newTimeoutS: this.adaptiveReservationTimeout,
+                    configuredDefaultS: config_1.HMSH_RESERVATION_TIMEOUT_S,
+                });
+            }
+        }
+        catch {
+            // Stream depth check is best-effort; don't fail the consume loop
+        }
+    }
     async createGroup(stream, group) {
         try {
             await this.stream.createConsumerGroup(stream, group);
@@ -107,6 +152,8 @@ class ConsumptionManager {
             if (this.lifecycleManager.isStopped(group, consumer, stream)) {
                 return;
             }
+            // Adapt reservation timeout based on stream depth
+            await this.adjustReservationTimeout(stream);
             await this.throttleManager.customSleep(); // respect throttle
             if (this.lifecycleManager.isStopped(group, consumer, stream) ||
                 this.throttleManager.isPaused()) {
@@ -183,6 +230,7 @@ class ConsumptionManager {
                 enableNotifications: true,
                 notificationCallback,
                 blockTimeout: config_1.HMSH_BLOCK_TIME_MS,
+                reservationTimeout: config_1.HMSH_RESERVATION_TIMEOUT_S,
             });
             // Don't block here - let the worker initialization complete
             // The notification system will handle message processing asynchronously
@@ -225,14 +273,17 @@ class ConsumptionManager {
             const streamDuration = config_1.HMSH_BLOCK_TIME_MS + Math.round(config_1.HMSH_BLOCK_TIME_MS * Math.random());
             try {
                 let messages = [];
+                // Adapt reservation timeout based on stream depth
+                await this.adjustReservationTimeout(stream);
                 if (!this.hasReachedMaxBackoff) {
                     // Normal mode: try with backoff and finite retries
                     const features = this.stream.getProviderSpecificFeatures();
                     const isPostgres = features.supportsParallelProcessing;
-                    const batchSize = isPostgres ? 10 : 1; // Use batch size of 10 for PostgreSQL, 1 for others
+                    const batchSize = isPostgres ? config_1.HMSH_BATCH_SIZE : 1;
                     messages = await this.stream.consumeMessages(stream, group, consumer, {
                         blockTimeout: streamDuration,
                         batchSize,
+                        reservationTimeout: this.adaptiveReservationTimeout,
                         enableBackoff: true,
                         initialBackoff: config_1.INITIAL_STREAM_BACKOFF,
                         maxBackoff: config_1.MAX_STREAM_BACKOFF,
@@ -243,10 +294,11 @@ class ConsumptionManager {
                     // Fallback mode: just try once, no backoff
                     const features = this.stream.getProviderSpecificFeatures();
                     const isPostgres = features.supportsParallelProcessing;
-                    const batchSize = isPostgres ? 10 : 1; // Use batch size of 10 for PostgreSQL, 1 for others
+                    const batchSize = isPostgres ? config_1.HMSH_BATCH_SIZE : 1;
                     messages = await this.stream.consumeMessages(stream, group, consumer, {
                         blockTimeout: streamDuration,
                         batchSize,
+                        reservationTimeout: this.adaptiveReservationTimeout,
                         enableBackoff: false,
                         maxRetries: 1,
                     });
@@ -542,4 +594,8 @@ class ConsumptionManager {
         return Array.isArray(result) && Array.isArray(result[0]);
     }
 }
+ConsumptionManager.DEPTH_CHECK_INTERVAL_MS = 10000;
+ConsumptionManager.DEPTH_SCALE_UP_THRESHOLD = 100;
+ConsumptionManager.DEPTH_SCALE_DOWN_THRESHOLD = 10;
+ConsumptionManager.RESERVATION_TIMEOUT_MAX_S = 600;
 exports.ConsumptionManager = ConsumptionManager;

package/build/services/stream/index.d.ts

@@ -22,6 +22,7 @@ export declare abstract class StreamService<ClientProvider extends ProviderClien
         batchSize?: number;
         blockTimeout?: number;
         autoAck?: boolean;
+        reservationTimeout?: number;
         enableBackoff?: boolean;
         initialBackoff?: number;
         maxBackoff?: number;
@@ -41,6 +42,7 @@ export declare abstract class StreamService<ClientProvider extends ProviderClien
         maxRetries?: number;
         limit?: number;
     }): Promise<StreamMessage[]>;
+    reservationTimeout: number;
     abstract getStreamStats(streamName: string): Promise<StreamStats>;
     abstract getStreamDepth(streamName: string): Promise<number>;
     abstract getStreamDepths(streamName: {

package/build/services/stream/index.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamService = void 0;
 class StreamService {
     constructor(streamClient, storeClient, config = {}) {
+        // Adaptive reservation timeout — set by the consumption manager
+        // based on stream depth. Providers read this when reserving messages.
+        this.reservationTimeout = 30;
         this.streamClient = streamClient;
         this.storeClient = storeClient;
         this.config = config;

package/build/services/stream/providers/postgres/messages.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retryMessages = exports.deadLetterMessages = exports.ackAndDelete = exports.deleteMessages = exports.acknowledgeMessages = exports.fetchMessages = exports.buildPublishSQL = exports.publishMessages = void 0;
+const enums_1 = require("../../../../modules/enums");
 const utils_1 = require("../../../../modules/utils");
 /**
  * Publish messages to a stream. Can be used within a transaction.
@@ -205,7 +206,7 @@ async function fetchMessages(client, tableName, streamName, isEngine, consumerNa
         while (retries < maxRetries) {
             retries++;
             const batchSize = options?.batchSize || 1;
-            const reservationTimeout = options?.reservationTimeout || 30;
+            const reservationTimeout = options?.reservationTimeout || enums_1.HMSH_RESERVATION_TIMEOUT_S;
             const res = await client.query(`UPDATE ${tableName}
          SET reserved_at = NOW(), reserved_by = $3
          WHERE id IN (

package/build/services/stream/providers/postgres/postgres.js

@@ -79,12 +79,12 @@ class PostgresStreamService extends index_1.StreamService {
     }
     async checkForMissedMessages() {
         await this.notificationManager.checkForMissedMessages(async (instance, consumer) => {
-            return await instance.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, enableBackoff: false, maxRetries: 1 });
+            return await instance.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, reservationTimeout: instance.reservationTimeout, enableBackoff: false, maxRetries: 1 });
         });
     }
     async fetchAndDeliverMessages(consumer) {
         try {
-            const messages = await this.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, enableBackoff: false, maxRetries: 1 });
+            const messages = await this.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, reservationTimeout: this.reservationTimeout, enableBackoff: false, maxRetries: 1 });
             if (messages.length > 0) {
                 consumer.callback(messages);
             }

package/build/services/stream/providers/postgres/secured.js

@@ -8,6 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.publishMessagesSecured = exports.deadLetterMessagesSecured = exports.ackAndDeleteSecured = exports.fetchMessagesSecured = void 0;
+const enums_1 = require("../../../../modules/enums");
 const utils_1 = require("../../../../modules/utils");
 const utils_2 = require("../../../../modules/utils");
 /**
@@ -19,7 +20,7 @@ async function fetchMessagesSecured(client, schema, streamName, consumerName, op
     const maxBackoff = options?.maxBackoff ?? 3000;
     const maxRetries = options?.maxRetries ?? 3;
     const batchSize = options?.batchSize || 1;
-    const reservationTimeout = options?.reservationTimeout || 30;
+    const reservationTimeout = options?.reservationTimeout || enums_1.HMSH_RESERVATION_TIMEOUT_S;
     let backoff = initialBackoff;
     let retries = 0;
     try {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.14.5",
+  "version": "0.14.6",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
-  "homepage": "https://github.com/hotmeshio/sdk-typescript/",
+  "homepage": "https://docs.hotmesh.io/",
   "publishConfig": {
     "access": "public"
   },
@@ -30,6 +30,7 @@
     "test:durable:postgres": "HMSH_LOGLEVEL=info vitest run tests/durable",
     "test:durable:basic": "HMSH_LOGLEVEL=info vitest run tests/durable/basic/postgres.test.ts",
     "test:durable:collision": "vitest run tests/durable/collision/postgres.test.ts",
+    "test:durable:contention": "vitest run tests/durable/contention/postgres.test.ts",
     "test:durable:fatal": "vitest run tests/durable/fatal",
     "test:durable:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/durable/goodbye/postgres.test.ts",
     "test:durable:interceptor": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts",