glide-mq 0.5.0 → 0.7.0

package/dist/functions/index.js

@@ -13,6 +13,7 @@ exports.resume = resume;
 exports.rateLimit = rateLimit;
 exports.checkConcurrency = checkConcurrency;
 exports.moveToActive = moveToActive;
+exports.promoteRateLimited = promoteRateLimited;
 exports.deferActive = deferActive;
 exports.removeJob = removeJob;
 exports.revokeJob = revokeJob;
@@ -20,7 +21,7 @@ exports.searchByName = searchByName;
 exports.addFlow = addFlow;
 exports.completeChild = completeChild;
 exports.LIBRARY_NAME = 'glidemq';
-exports.LIBRARY_VERSION = '16';
+exports.LIBRARY_VERSION = '19';
 // Consumer group name used by workers
 exports.CONSUMER_GROUP = 'workers';
 // Embedded Lua library source (from glidemq.lua)
@@ -76,19 +77,130 @@ local function markOrderingDone(jobKey, jobId)
   end
 end
 
-local function releaseGroupSlotAndPromote(jobKey, jobId)
+-- Refill token bucket using remainder accumulator for precision.
+-- tbRefillRate is in millitokens/second. Returns current millitokens after refill.
+-- Side effect: updates tbTokens, tbLastRefill, tbRefillRemainder on the group hash.
+local function tbRefill(groupHashKey, g, now)
+  local tbCapacity = tonumber(g.tbCapacity) or 0
+  if tbCapacity <= 0 then return 0 end
+  local tbTokens = tonumber(g.tbTokens) or tbCapacity
+  local tbRefillRate = tonumber(g.tbRefillRate) or 0
+  local tbLastRefill = tonumber(g.tbLastRefill) or now
+  local tbRefillRemainder = tonumber(g.tbRefillRemainder) or 0
+  local elapsed = now - tbLastRefill
+  if elapsed <= 0 or tbRefillRate <= 0 then return tbTokens end
+  -- Cap elapsed to prevent overflow in long-idle buckets
+  local maxElapsed = math.ceil(tbCapacity * 1000 / tbRefillRate)
+  if elapsed > maxElapsed then elapsed = maxElapsed end
+  local raw = elapsed * tbRefillRate + tbRefillRemainder
+  local added = math.floor(raw / 1000)
+  local newRemainder = raw % 1000
+  local newTokens = math.min(tbCapacity, tbTokens + added)
+  redis.call('HSET', groupHashKey,
+    'tbTokens', tostring(newTokens),
+    'tbLastRefill', tostring(now),
+    'tbRefillRemainder', tostring(newRemainder))
+  return newTokens
+end
+
+local function releaseGroupSlotAndPromote(jobKey, jobId, now)
   local gk = redis.call('HGET', jobKey, 'groupKey')
   if not gk or gk == '' then return end
   local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
   local groupHashKey = prefix .. 'group:' .. gk
-  local cur = tonumber(redis.call('HGET', groupHashKey, 'active')) or 0
+  -- Load all group fields in one call
+  local gFields = redis.call('HGETALL', groupHashKey)
+  local g = {}
+  for gf = 1, #gFields, 2 do g[gFields[gf]] = gFields[gf + 1] end
+  local cur = tonumber(g.active) or 0
+  local newActive = (cur > 0) and (cur - 1) or 0
   if cur > 0 then
-    redis.call('HSET', groupHashKey, 'active', tostring(cur - 1))
+    redis.call('HSET', groupHashKey, 'active', tostring(newActive))
   end
   local waitListKey = prefix .. 'groupq:' .. gk
-  local nextJobId = redis.call('LPOP', waitListKey)
-  if nextJobId then
-    local streamKey = prefix .. 'stream'
+  local waitLen = redis.call('LLEN', waitListKey)
+  if waitLen == 0 then return end
+  -- Concurrency gate: if still at or above max after decrement, do not promote
+  local maxConc = tonumber(g.maxConcurrency) or 0
+  if maxConc > 0 and newActive >= maxConc then return end
+  -- Rate limit gate (skip if now is nil or 0 for safe fallback)
+  -- Only blocks promotion; does NOT increment rateCount. moveToActive handles counting.
+  local rateMax = tonumber(g.rateMax) or 0
+  local rateRemaining = 0
+  local ts = tonumber(now) or 0
+  if ts > 0 and rateMax > 0 then
+    local rateDuration = tonumber(g.rateDuration) or 0
+    if rateDuration > 0 then
+      local rateWindowStart = tonumber(g.rateWindowStart) or 0
+      local rateCount = tonumber(g.rateCount) or 0
+      if ts - rateWindowStart < rateDuration then
+        if rateCount >= rateMax then
+          -- Window active and at capacity: do not promote, register for scheduler
+          local rateLimitedKey = prefix .. 'ratelimited'
+          redis.call('ZADD', rateLimitedKey, rateWindowStart + rateDuration, gk)
+          return
+        end
+        rateRemaining = rateMax - rateCount
+      end
+    end
+  end
+  -- Token bucket gate: check head job cost before promoting
+  local tbCap = tonumber(g.tbCapacity) or 0
+  if ts > 0 and tbCap > 0 then
+    local tbTokensCur = tbRefill(groupHashKey, g, ts)
+    -- Peek at head job, skipping tombstones and DLQ'd jobs (up to 10 iterations)
+    local tbCheckPasses = 0
+    local tbOk = false
+    while tbCheckPasses < 10 do
+      tbCheckPasses = tbCheckPasses + 1
+      local headJobId = redis.call('LINDEX', waitListKey, 0)
+      if not headJobId then break end
+      local headJobKey = prefix .. 'job:' .. headJobId
+      -- Tombstone guard: job hash deleted - pop and check next
+      if redis.call('EXISTS', headJobKey) == 0 then
+        redis.call('LPOP', waitListKey)
+      else
+        local headCost = tonumber(redis.call('HGET', headJobKey, 'cost')) or 1000
+        -- DLQ guard: cost > capacity - pop, fail, check next
+        if headCost > tbCap then
+          redis.call('LPOP', waitListKey)
+          redis.call('ZADD', prefix .. 'failed', ts, headJobId)
+          redis.call('HSET', headJobKey,
+            'state', 'failed',
+            'failedReason', 'cost exceeds token bucket capacity',
+            'finishedOn', tostring(ts))
+          emitEvent(prefix .. 'events', 'failed', headJobId, {'failedReason', 'cost exceeds token bucket capacity'})
+        elseif tbTokensCur < headCost then
+          -- Not enough tokens: register delay and skip promotion
+          local tbRateVal = tonumber(g.tbRefillRate) or 0
+          if tbRateVal <= 0 then break end
+          local tbDelayMs = math.ceil((headCost - tbTokensCur) * 1000 / tbRateVal)
+          local rateLimitedKey = prefix .. 'ratelimited'
+          redis.call('ZADD', rateLimitedKey, ts + tbDelayMs, gk)
+          return
+        else
+          tbOk = true
+          break
+        end
+      end
+    end
+    if not tbOk and tbCheckPasses >= 10 then return end
+  end
+  -- Calculate how many slots are available for promotion
+  local available = 1
+  if maxConc > 0 then
+    available = maxConc - newActive
+  else
+    available = math.min(waitLen, 1000)
+  end
+  -- Cap by rate limit remaining if a window is active
+  if rateRemaining > 0 then
+    available = math.min(available, rateRemaining)
+  end
+  local streamKey = prefix .. 'stream'
+  for p = 1, available do
+    local nextJobId = redis.call('LPOP', waitListKey)
+    if not nextJobId then break end
     redis.call('XADD', streamKey, '*', 'jobId', nextJobId)
     local nextJobKey = prefix .. 'job:' .. nextJobId
     redis.call('HSET', nextJobKey, 'state', 'waiting')
@@ -133,6 +245,48 @@ local function extractGroupConcurrencyFromOpts(optsJson)
   return tonumber(conc) or 0
 end
 
+local function extractGroupRateLimitFromOpts(optsJson)
+  if not optsJson or optsJson == '' then
+    return 0, 0
+  end
+  local ok, decoded = pcall(cjson.decode, optsJson)
+  if not ok or type(decoded) ~= 'table' then
+    return 0, 0
+  end
+  local ordering = decoded['ordering']
+  if type(ordering) ~= 'table' then
+    return 0, 0
+  end
+  local rl = ordering['rateLimit']
+  if type(rl) ~= 'table' then
+    return 0, 0
+  end
+  local max = tonumber(rl['max']) or 0
+  local duration = tonumber(rl['duration']) or 0
+  return max, duration
+end
+
+local function extractTokenBucketFromOpts(optsJson)
+  if not optsJson or optsJson == '' then return 0, 0 end
+  local ok, decoded = pcall(cjson.decode, optsJson)
+  if not ok or type(decoded) ~= 'table' then return 0, 0 end
+  local ordering = decoded['ordering']
+  if type(ordering) ~= 'table' then return 0, 0 end
+  local tb = ordering['tokenBucket']
+  if type(tb) ~= 'table' then return 0, 0 end
+  local capacity = tonumber(tb['capacity']) or 0
+  local refillRate = tonumber(tb['refillRate']) or 0
+  return math.floor(capacity * 1000), math.floor(refillRate * 1000)
+end
+
+local function extractCostFromOpts(optsJson)
+  if not optsJson or optsJson == '' then return 0 end
+  local ok, decoded = pcall(cjson.decode, optsJson)
+  if not ok or type(decoded) ~= 'table' then return 0 end
+  local cost = tonumber(decoded['cost']) or 0
+  return math.floor(cost * 1000)
+end
+
 redis.register_function('glidemq_version', function(keys, args)
   return '${exports.LIBRARY_VERSION}'
 end)
@@ -152,11 +306,16 @@ redis.register_function('glidemq_addJob', function(keys, args)
   local maxAttempts = tonumber(args[8]) or 0
   local orderingKey = args[9] or ''
   local groupConcurrency = tonumber(args[10]) or 0
+  local groupRateMax = tonumber(args[11]) or 0
+  local groupRateDuration = tonumber(args[12]) or 0
+  local tbCapacity = tonumber(args[13]) or 0
+  local tbRefillRate = tonumber(args[14]) or 0
+  local jobCost = tonumber(args[15]) or 0
   local jobId = redis.call('INCR', idKey)
   local jobIdStr = tostring(jobId)
   local prefix = string.sub(idKey, 1, #idKey - 2)
   local jobKey = prefix .. 'job:' .. jobIdStr
-  local useGroupConcurrency = (orderingKey ~= '' and groupConcurrency > 1)
+  local useGroupConcurrency = (orderingKey ~= '' and (groupConcurrency > 1 or groupRateMax > 0 or tbCapacity > 0))
   local orderingSeq = 0
   if orderingKey ~= '' and not useGroupConcurrency then
     local orderingMetaKey = prefix .. 'ordering'
@@ -168,6 +327,57 @@ redis.register_function('glidemq_addJob', function(keys, args)
     if curMax ~= groupConcurrency then
       redis.call('HSET', groupHashKey, 'maxConcurrency', tostring(groupConcurrency))
     end
+    -- When rate limit or token bucket forces group path but concurrency is 0 or 1, ensure maxConcurrency >= 1
+    if curMax == 0 and groupConcurrency <= 1 then
+      redis.call('HSET', groupHashKey, 'maxConcurrency', '1')
+    end
+    -- Upsert rate limit fields on group hash
+    if groupRateMax > 0 then
+      local curRateMax = tonumber(redis.call('HGET', groupHashKey, 'rateMax')) or 0
+      if curRateMax ~= groupRateMax then
+        redis.call('HSET', groupHashKey, 'rateMax', tostring(groupRateMax))
+      end
+      local curRateDuration = tonumber(redis.call('HGET', groupHashKey, 'rateDuration')) or 0
+      if curRateDuration ~= groupRateDuration then
+        redis.call('HSET', groupHashKey, 'rateDuration', tostring(groupRateDuration))
+      end
+    else
+      -- Clear stale rate limit fields if group was previously rate-limited
+      local oldRateMax = tonumber(redis.call('HGET', groupHashKey, 'rateMax')) or 0
+      if oldRateMax > 0 then
+        redis.call('HDEL', groupHashKey, 'rateMax', 'rateDuration', 'rateWindowStart', 'rateCount')
+      end
+    end
+    -- Upsert token bucket fields on group hash
+    if tbCapacity > 0 then
+      local curTbCap = tonumber(redis.call('HGET', groupHashKey, 'tbCapacity')) or 0
+      if curTbCap ~= tbCapacity then
+        redis.call('HSET', groupHashKey, 'tbCapacity', tostring(tbCapacity))
+      end
+      local curTbRate = tonumber(redis.call('HGET', groupHashKey, 'tbRefillRate')) or 0
+      if curTbRate ~= tbRefillRate then
+        redis.call('HSET', groupHashKey, 'tbRefillRate', tostring(tbRefillRate))
+      end
+      -- Initialize tokens on first setup
+      if curTbCap == 0 then
+        redis.call('HSET', groupHashKey,
+          'tbTokens', tostring(tbCapacity),
+          'tbLastRefill', tostring(timestamp),
+          'tbRefillRemainder', '0')
+      end
+      -- Validate cost <= capacity at enqueue
+      -- Validate cost (explicit or default 1000 millitokens) against capacity
+      local effectiveCost = (jobCost > 0) and jobCost or 1000
+      if effectiveCost > tbCapacity then
+        return 'ERR:COST_EXCEEDS_CAPACITY'
+      end
+    else
+      -- Clear stale tb fields
+      local oldTbCap = tonumber(redis.call('HGET', groupHashKey, 'tbCapacity')) or 0
+      if oldTbCap > 0 then
+        redis.call('HDEL', groupHashKey, 'tbCapacity', 'tbRefillRate', 'tbTokens', 'tbLastRefill', 'tbRefillRemainder')
+      end
+    end
   end
   local hashFields = {
     'id', jobIdStr,
@@ -189,6 +399,10 @@ redis.register_function('glidemq_addJob', function(keys, args)
     hashFields[#hashFields + 1] = 'orderingSeq'
     hashFields[#hashFields + 1] = tostring(orderingSeq)
   end
+  if jobCost > 0 then
+    hashFields[#hashFields + 1] = 'cost'
+    hashFields[#hashFields + 1] = tostring(jobCost)
+  end
   if parentId ~= '' then
     hashFields[#hashFields + 1] = 'parentId'
     hashFields[#hashFields + 1] = parentId
@@ -280,7 +494,7 @@ redis.register_function('glidemq_complete', function(keys, args)
     'finishedOn', tostring(timestamp)
   )
   markOrderingDone(jobKey, jobId)
-  releaseGroupSlotAndPromote(jobKey, jobId)
+  releaseGroupSlotAndPromote(jobKey, jobId, timestamp)
   emitEvent(eventsKey, 'completed', jobId, {'returnvalue', returnvalue})
   local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
   if removeMode == 'true' then
@@ -362,7 +576,7 @@ redis.register_function('glidemq_completeAndFetchNext', function(keys, args)
     'finishedOn', tostring(timestamp)
   )
   markOrderingDone(jobKey, jobId)
-  releaseGroupSlotAndPromote(jobKey, jobId)
+  releaseGroupSlotAndPromote(jobKey, jobId, timestamp)
   emitEvent(eventsKey, 'completed', jobId, {'returnvalue', returnvalue})
   local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
 
@@ -433,8 +647,13 @@ redis.register_function('glidemq_completeAndFetchNext', function(keys, args)
   local nextGroupKey = redis.call('HGET', nextJobKey, 'groupKey')
   if nextGroupKey and nextGroupKey ~= '' then
     local nextGroupHashKey = prefix .. 'group:' .. nextGroupKey
-    local nextMaxConc = tonumber(redis.call('HGET', nextGroupHashKey, 'maxConcurrency')) or 0
-    local nextActive = tonumber(redis.call('HGET', nextGroupHashKey, 'active')) or 0
+    -- Load all group fields in one call
+    local nGrpFields = redis.call('HGETALL', nextGroupHashKey)
+    local nGrp = {}
+    for nf = 1, #nGrpFields, 2 do nGrp[nGrpFields[nf]] = nGrpFields[nf + 1] end
+    local nextMaxConc = tonumber(nGrp.maxConcurrency) or 0
+    local nextActive = tonumber(nGrp.active) or 0
+    -- Concurrency gate first (avoids burning rate/token slots on parked jobs)
     if nextMaxConc > 0 and nextActive >= nextMaxConc then
       redis.call('XACK', streamKey, group, nextEntryId)
       redis.call('XDEL', streamKey, nextEntryId)
@@ -443,6 +662,73 @@ redis.register_function('glidemq_completeAndFetchNext', function(keys, args)
       redis.call('HSET', nextJobKey, 'state', 'group-waiting')
       return cjson.encode({completed = jobId, next = false})
     end
+    -- Token bucket gate (read-only)
+    local nextTbCapacity = tonumber(nGrp.tbCapacity) or 0
+    local nextTbBlocked = false
+    local nextTbDelay = 0
+    local nextTbTokens = 0
+    local nextJobCostVal = 0
+    if nextTbCapacity > 0 then
+      nextTbTokens = tbRefill(nextGroupHashKey, nGrp, tonumber(timestamp))
+      nextJobCostVal = tonumber(redis.call('HGET', nextJobKey, 'cost')) or 1000
+      -- DLQ guard: cost > capacity
+      if nextJobCostVal > nextTbCapacity then
+        redis.call('XACK', streamKey, group, nextEntryId)
+        redis.call('XDEL', streamKey, nextEntryId)
+        redis.call('ZADD', prefix .. 'failed', tonumber(timestamp), nextJobId)
+        redis.call('HSET', nextJobKey,
+          'state', 'failed',
+          'failedReason', 'cost exceeds token bucket capacity',
+          'finishedOn', tostring(timestamp))
+        emitEvent(prefix .. 'events', 'failed', nextJobId, {'failedReason', 'cost exceeds token bucket capacity'})
+        return cjson.encode({completed = jobId, next = false})
+      end
+      if nextTbTokens < nextJobCostVal then
+        nextTbBlocked = true
+        local nextTbRefillRateVal = math.max(tonumber(nGrp.tbRefillRate) or 0, 1)
+        nextTbDelay = math.ceil((nextJobCostVal - nextTbTokens) * 1000 / nextTbRefillRateVal)
+      end
+    end
+    -- Sliding window gate (read-only)
+    local nextRateMax = tonumber(nGrp.rateMax) or 0
+    local nextRlBlocked = false
+    local nextRlDelay = 0
+    if nextRateMax > 0 then
+      local nextRateDuration = tonumber(nGrp.rateDuration) or 0
+      local nextRateWindowStart = tonumber(nGrp.rateWindowStart) or 0
+      local nextRateCount = tonumber(nGrp.rateCount) or 0
+      if nextRateDuration > 0 and timestamp - nextRateWindowStart < nextRateDuration and nextRateCount >= nextRateMax then
+        nextRlBlocked = true
+        nextRlDelay = (nextRateWindowStart + nextRateDuration) - timestamp
+      end
+    end
+    -- If ANY gate blocked: park + register
+    if nextTbBlocked or nextRlBlocked then
+      redis.call('XACK', streamKey, group, nextEntryId)
+      redis.call('XDEL', streamKey, nextEntryId)
+      local nextWaitListKey = prefix .. 'groupq:' .. nextGroupKey
+      redis.call('RPUSH', nextWaitListKey, nextJobId)
+      redis.call('HSET', nextJobKey, 'state', 'group-waiting')
+      local nextMaxDelay = math.max(nextTbDelay, nextRlDelay)
+      local rateLimitedKey = prefix .. 'ratelimited'
+      redis.call('ZADD', rateLimitedKey, tonumber(timestamp) + nextMaxDelay, nextGroupKey)
+      return cjson.encode({completed = jobId, next = false})
+    end
+    -- All gates passed: mutate state
+    if nextTbCapacity > 0 then
+      redis.call('HINCRBY', nextGroupHashKey, 'tbTokens', -nextJobCostVal)
+    end
+    if nextRateMax > 0 then
+      local nextRateDuration = tonumber(nGrp.rateDuration) or 0
+      if nextRateDuration > 0 then
+        local nextRateWindowStart = tonumber(nGrp.rateWindowStart) or 0
+        if timestamp - nextRateWindowStart >= nextRateDuration then
+          redis.call('HSET', nextGroupHashKey, 'rateWindowStart', tostring(timestamp), 'rateCount', '1')
+        else
+          redis.call('HINCRBY', nextGroupHashKey, 'rateCount', 1)
+        end
+      end
+    end
     redis.call('HINCRBY', nextGroupHashKey, 'active', 1)
   end
   redis.call('HSET', nextJobKey, 'state', 'active', 'processedOn', tostring(timestamp), 'lastActive', tostring(timestamp))
@@ -479,7 +765,7 @@ redis.register_function('glidemq_fail', function(keys, args)
       'failedReason', failedReason,
       'processedOn', tostring(timestamp)
     )
-    releaseGroupSlotAndPromote(jobKey, jobId)
+    releaseGroupSlotAndPromote(jobKey, jobId, timestamp)
     emitEvent(eventsKey, 'retrying', jobId, {
       'failedReason', failedReason,
       'attemptsMade', tostring(attemptsMade),
@@ -495,7 +781,7 @@ redis.register_function('glidemq_fail', function(keys, args)
       'processedOn', tostring(timestamp)
     )
     markOrderingDone(jobKey, jobId)
-    releaseGroupSlotAndPromote(jobKey, jobId)
+    releaseGroupSlotAndPromote(jobKey, jobId, timestamp)
     emitEvent(eventsKey, 'failed', jobId, {'failedReason', failedReason})
     local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
     if removeMode == 'true' then
@@ -583,7 +869,7 @@ redis.register_function('glidemq_reclaimStalled', function(keys, args)
           'finishedOn', tostring(timestamp)
         )
         markOrderingDone(jobKey, jobId)
-        releaseGroupSlotAndPromote(jobKey, jobId)
+        releaseGroupSlotAndPromote(jobKey, jobId, timestamp)
         emitEvent(eventsKey, 'failed', jobId, {
           'failedReason', 'job stalled more than maxStalledCount'
         })
@@ -633,6 +919,11 @@ redis.register_function('glidemq_dedup', function(keys, args)
   local maxAttempts = tonumber(args[11]) or 0
   local orderingKey = args[12] or ''
   local groupConcurrency = tonumber(args[13]) or 0
+  local groupRateMax = tonumber(args[14]) or 0
+  local groupRateDuration = tonumber(args[15]) or 0
+  local tbCapacity = tonumber(args[16]) or 0
+  local tbRefillRate = tonumber(args[17]) or 0
+  local jobCost = tonumber(args[18]) or 0
   local prefix = string.sub(idKey, 1, #idKey - 2)
   local existing = redis.call('HGET', dedupKey, dedupId)
   if mode == 'simple' then
@@ -678,7 +969,7 @@ redis.register_function('glidemq_dedup', function(keys, args)
   local jobId = redis.call('INCR', idKey)
   local jobIdStr = tostring(jobId)
   local jobKey = prefix .. 'job:' .. jobIdStr
-  local useGroupConcurrency = (orderingKey ~= '' and groupConcurrency > 1)
+  local useGroupConcurrency = (orderingKey ~= '' and (groupConcurrency > 1 or groupRateMax > 0 or tbCapacity > 0))
   local orderingSeq = 0
   if orderingKey ~= '' and not useGroupConcurrency then
     local orderingMetaKey = prefix .. 'ordering'
@@ -690,6 +981,54 @@ redis.register_function('glidemq_dedup', function(keys, args)
     if curMax ~= groupConcurrency then
       redis.call('HSET', groupHashKey, 'maxConcurrency', tostring(groupConcurrency))
     end
+    if curMax == 0 and groupConcurrency <= 1 then
+      redis.call('HSET', groupHashKey, 'maxConcurrency', '1')
+    end
+    if groupRateMax > 0 then
+      local curRateMax = tonumber(redis.call('HGET', groupHashKey, 'rateMax')) or 0
+      if curRateMax ~= groupRateMax then
+        redis.call('HSET', groupHashKey, 'rateMax', tostring(groupRateMax))
+      end
+      local curRateDuration = tonumber(redis.call('HGET', groupHashKey, 'rateDuration')) or 0
+      if curRateDuration ~= groupRateDuration then
+        redis.call('HSET', groupHashKey, 'rateDuration', tostring(groupRateDuration))
+      end
+    else
+      local oldRateMax = tonumber(redis.call('HGET', groupHashKey, 'rateMax')) or 0
+      if oldRateMax > 0 then
+        redis.call('HDEL', groupHashKey, 'rateMax', 'rateDuration', 'rateWindowStart', 'rateCount')
+      end
+    end
+    -- Upsert token bucket fields on group hash
+    if tbCapacity > 0 then
+      local curTbCap = tonumber(redis.call('HGET', groupHashKey, 'tbCapacity')) or 0
+      if curTbCap ~= tbCapacity then
+        redis.call('HSET', groupHashKey, 'tbCapacity', tostring(tbCapacity))
+      end
+      local curTbRate = tonumber(redis.call('HGET', groupHashKey, 'tbRefillRate')) or 0
+      if curTbRate ~= tbRefillRate then
+        redis.call('HSET', groupHashKey, 'tbRefillRate', tostring(tbRefillRate))
+      end
+      -- Initialize tokens on first setup
+      if curTbCap == 0 then
+        redis.call('HSET', groupHashKey,
+          'tbTokens', tostring(tbCapacity),
+          'tbLastRefill', tostring(timestamp),
+          'tbRefillRemainder', '0')
+      end
+      -- Validate cost <= capacity at enqueue
+      -- Validate cost (explicit or default 1000 millitokens) against capacity
+      local effectiveCost = (jobCost > 0) and jobCost or 1000
+      if effectiveCost > tbCapacity then
+        return 'ERR:COST_EXCEEDS_CAPACITY'
+      end
+    else
+      -- Clear stale tb fields
+      local oldTbCap = tonumber(redis.call('HGET', groupHashKey, 'tbCapacity')) or 0
+      if oldTbCap > 0 then
+        redis.call('HDEL', groupHashKey, 'tbCapacity', 'tbRefillRate', 'tbTokens', 'tbLastRefill', 'tbRefillRemainder')
+      end
+    end
   end
   local hashFields = {
     'id', jobIdStr,
@@ -711,6 +1050,10 @@ redis.register_function('glidemq_dedup', function(keys, args)
     hashFields[#hashFields + 1] = 'orderingSeq'
     hashFields[#hashFields + 1] = tostring(orderingSeq)
   end
+  if jobCost > 0 then
+    hashFields[#hashFields + 1] = 'cost'
+    hashFields[#hashFields + 1] = tostring(jobCost)
+  end
   if parentId ~= '' then
     hashFields[#hashFields + 1] = 'parentId'
     hashFields[#hashFields + 1] = parentId
@@ -743,6 +1086,12 @@ redis.register_function('glidemq_rateLimit', function(keys, args)
   local maxPerWindow = tonumber(args[1])
   local windowDuration = tonumber(args[2])
   local now = tonumber(args[3])
+  -- Fallback: read rate limit config from meta if not provided inline
+  if maxPerWindow <= 0 then
+    maxPerWindow = tonumber(redis.call('HGET', metaKey, 'rateLimitMax')) or 0
+    windowDuration = tonumber(redis.call('HGET', metaKey, 'rateLimitDuration')) or 0
+    if maxPerWindow <= 0 then return 0 end
+  end
   local windowStart = tonumber(redis.call('HGET', rateKey, 'windowStart')) or 0
   local count = tonumber(redis.call('HGET', rateKey, 'count')) or 0
   if now - windowStart >= windowDuration then
@@ -757,6 +1106,87 @@ redis.register_function('glidemq_rateLimit', function(keys, args)
   return 0
 end)
 
+redis.register_function('glidemq_promoteRateLimited', function(keys, args)
+  local rateLimitedKey = keys[1]
+  local streamKey = keys[2]
+  local now = tonumber(args[1])
+  -- Derive prefix from the server-validated key instead of caller-supplied arg
+  local prefix = string.sub(rateLimitedKey, 1, #rateLimitedKey - #'ratelimited')
+  local expired = redis.call('ZRANGEBYSCORE', rateLimitedKey, '0', string.format('%.0f', now), 'LIMIT', 0, 100)
+  if not expired or #expired == 0 then return 0 end
+  local promoted = 0
+  for i = 1, #expired do
+    local gk = expired[i]
+    redis.call('ZREM', rateLimitedKey, gk)
+    local groupHashKey = prefix .. 'group:' .. gk
+    local waitListKey = prefix .. 'groupq:' .. gk
+    -- Load all group fields in one call for rate limit + token bucket checks
+    local prGrpFields = redis.call('HGETALL', groupHashKey)
+    local prGrp = {}
+    for pf = 1, #prGrpFields, 2 do prGrp[prGrpFields[pf]] = prGrpFields[pf + 1] end
+    local rateMax = tonumber(prGrp.rateMax) or 0
+    local maxConc = tonumber(prGrp.maxConcurrency) or 0
+    local active = tonumber(prGrp.active) or 0
+    -- Token bucket pre-check: peek head job cost before promoting
+    local prTbCap = tonumber(prGrp.tbCapacity) or 0
+    local tbCheckPassed = true
+    if prTbCap > 0 then
+      local prTbTokens = tbRefill(groupHashKey, prGrp, now)
+      local headJobId = redis.call('LINDEX', waitListKey, 0)
+      if headJobId then
+        local headJobKey = prefix .. 'job:' .. headJobId
+        -- Tombstone guard
+        if redis.call('EXISTS', headJobKey) == 0 then
+          redis.call('LPOP', waitListKey)
+          tbCheckPassed = false
+        end
+        if tbCheckPassed then
+          local headCost = tonumber(redis.call('HGET', headJobKey, 'cost')) or 1000
+          -- DLQ guard: cost > capacity
+          if headCost > prTbCap then
+            redis.call('LPOP', waitListKey)
+            redis.call('ZADD', prefix .. 'failed', now, headJobId)
+            redis.call('HSET', headJobKey,
+              'state', 'failed',
+              'failedReason', 'cost exceeds token bucket capacity',
+              'finishedOn', tostring(now))
+            emitEvent(prefix .. 'events', 'failed', headJobId, {'failedReason', 'cost exceeds token bucket capacity'})
+            tbCheckPassed = false
+          end
+          if tbCheckPassed and prTbTokens < headCost then
+            -- Not enough tokens: re-register with calculated delay
+            local prTbRate = math.max(tonumber(prGrp.tbRefillRate) or 0, 1)
+            local prTbDelay = math.ceil((headCost - prTbTokens) * 1000 / prTbRate)
+            redis.call('ZADD', rateLimitedKey, now + prTbDelay, gk)
+            tbCheckPassed = false
+          end
+        end
+      end
+    end
+    if tbCheckPassed then
+      -- Promote up to min(rateMax, available concurrency) jobs.
+      -- Do NOT touch rateCount/rateWindowStart here - moveToActive handles
+      -- window reset and counting when the worker picks up the promoted jobs.
+      local canPromote = 1000
+      if rateMax > 0 then
+        canPromote = math.min(canPromote, rateMax)
+      end
+      if maxConc > 0 then
+        canPromote = math.min(canPromote, math.max(0, maxConc - active))
+      end
+      for j = 1, canPromote do
+        local nextJobId = redis.call('LPOP', waitListKey)
+        if not nextJobId then break end
+        redis.call('XADD', streamKey, '*', 'jobId', nextJobId)
+        local nextJobKey = prefix .. 'job:' .. nextJobId
+        redis.call('HSET', nextJobKey, 'state', 'waiting')
+        promoted = promoted + 1
+      end
+    end
+  end
+  return promoted
+end)
+
 redis.register_function('glidemq_checkConcurrency', function(keys, args)
   local metaKey = keys[1]
   local streamKey = keys[2]
@@ -793,8 +1223,13 @@ redis.register_function('glidemq_moveToActive', function(keys, args)
   if groupKey and groupKey ~= '' then
     local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
     local groupHashKey = prefix .. 'group:' .. groupKey
-    local maxConc = tonumber(redis.call('HGET', groupHashKey, 'maxConcurrency')) or 0
-    local active = tonumber(redis.call('HGET', groupHashKey, 'active')) or 0
+    -- Load all group fields in one call
+    local grpFields = redis.call('HGETALL', groupHashKey)
+    local grp = {}
+    for f = 1, #grpFields, 2 do grp[grpFields[f]] = grpFields[f + 1] end
+    local maxConc = tonumber(grp.maxConcurrency) or 0
+    local active = tonumber(grp.active) or 0
+    -- Concurrency gate (checked first to avoid burning rate/token slots on parked jobs)
     if maxConc > 0 and active >= maxConc then
       if streamKey ~= '' and entryId ~= '' and group ~= '' then
         redis.call('XACK', streamKey, group, entryId)
@@ -805,6 +1240,81 @@ redis.register_function('glidemq_moveToActive', function(keys, args)
       redis.call('HSET', jobKey, 'state', 'group-waiting')
       return 'GROUP_FULL'
     end
+    -- Token bucket gate (read-only)
+    local tbCapacity = tonumber(grp.tbCapacity) or 0
+    local tbBlocked = false
+    local tbDelay = 0
+    local tbTokens = 0
+    local jobCostVal = 0
+    if tbCapacity > 0 then
+      tbTokens = tbRefill(groupHashKey, grp, tonumber(timestamp))
+      jobCostVal = tonumber(redis.call('HGET', jobKey, 'cost')) or 1000
+      -- DLQ guard: cost > capacity
+      if jobCostVal > tbCapacity then
+        if streamKey ~= '' and entryId ~= '' and group ~= '' then
+          redis.call('XACK', streamKey, group, entryId)
+          redis.call('XDEL', streamKey, entryId)
+        end
+        redis.call('ZADD', prefix .. 'failed', tonumber(timestamp), jobId)
+        redis.call('HSET', jobKey,
+          'state', 'failed',
+          'failedReason', 'cost exceeds token bucket capacity',
+          'finishedOn', timestamp)
+        emitEvent(prefix .. 'events', 'failed', jobId, {'failedReason', 'cost exceeds token bucket capacity'})
+        return 'ERR:COST_EXCEEDS_CAPACITY'
+      end
+      if tbTokens < jobCostVal then
+        tbBlocked = true
+        local tbRefillRateVal = tonumber(grp.tbRefillRate) or 0
+        if tbRefillRateVal <= 0 then tbRefillRateVal = 1 end
+        tbDelay = math.ceil((jobCostVal - tbTokens) * 1000 / tbRefillRateVal)
+      end
+    end
+    -- Sliding window gate (read-only)
+    local rateMax = tonumber(grp.rateMax) or 0
+    local rlBlocked = false
+    local rlDelay = 0
+    if rateMax > 0 then
+      local rateDuration = tonumber(grp.rateDuration) or 0
+      local rateWindowStart = tonumber(grp.rateWindowStart) or 0
+      local rateCount = tonumber(grp.rateCount) or 0
+      local now = tonumber(timestamp)
+      if rateDuration > 0 and now - rateWindowStart < rateDuration and rateCount >= rateMax then
+        rlBlocked = true
+        rlDelay = (rateWindowStart + rateDuration) - now
+      end
+    end
+    -- If ANY gate blocked: park + register
+    if tbBlocked or rlBlocked then
+      if streamKey ~= '' and entryId ~= '' and group ~= '' then
+        redis.call('XACK', streamKey, group, entryId)
+        redis.call('XDEL', streamKey, entryId)
+      end
+      local waitListKey = prefix .. 'groupq:' .. groupKey
+      redis.call('RPUSH', waitListKey, jobId)
+      redis.call('HSET', jobKey, 'state', 'group-waiting')
+      local maxDelay = math.max(tbDelay, rlDelay)
+      local rateLimitedKey = prefix .. 'ratelimited'
+      redis.call('ZADD', rateLimitedKey, tonumber(timestamp) + maxDelay, groupKey)
+      if tbBlocked then return 'GROUP_TOKEN_LIMITED' end
+      return 'GROUP_RATE_LIMITED'
+    end
+    -- All gates passed: mutate state
+    if tbCapacity > 0 then
+      redis.call('HINCRBY', groupHashKey, 'tbTokens', -jobCostVal)
+    end
+    if rateMax > 0 then
+      local rateDuration = tonumber(grp.rateDuration) or 0
+      if rateDuration > 0 then
+        local rateWindowStart = tonumber(grp.rateWindowStart) or 0
+        local now = tonumber(timestamp)
+        if now - rateWindowStart >= rateDuration then
+          redis.call('HSET', groupHashKey, 'rateWindowStart', tostring(now), 'rateCount', '1')
+        else
+          redis.call('HINCRBY', groupHashKey, 'rateCount', 1)
+        end
+      end
+    end
     redis.call('HINCRBY', groupHashKey, 'active', 1)
   end
   redis.call('HSET', jobKey, 'state', 'active', 'processedOn', timestamp, 'lastActive', timestamp)
@@ -849,8 +1359,12 @@ redis.register_function('glidemq_addFlow', function(keys, args)
   local depsKey = parentPrefix .. 'deps:' .. parentJobIdStr
   local parentOrderingKey = extractOrderingKeyFromOpts(parentOpts)
   local parentGroupConc = extractGroupConcurrencyFromOpts(parentOpts)
+  local parentRateMax, parentRateDuration = extractGroupRateLimitFromOpts(parentOpts)
+  local parentTbCapacity, parentTbRefillRate = extractTokenBucketFromOpts(parentOpts)
+  local parentCost = extractCostFromOpts(parentOpts)
+  local parentUseGroup = (parentOrderingKey ~= '' and (parentGroupConc > 1 or parentRateMax > 0 or parentTbCapacity > 0))
   local parentOrderingSeq = 0
-  if parentOrderingKey ~= '' and parentGroupConc <= 1 then
+  if parentOrderingKey ~= '' and not parentUseGroup then
     local parentOrderingMetaKey = parentPrefix .. 'ordering'
     parentOrderingSeq = redis.call('HINCRBY', parentOrderingMetaKey, parentOrderingKey, 1)
   end
@@ -866,22 +1380,52 @@ redis.register_function('glidemq_addFlow', function(keys, args)
     'maxAttempts', tostring(parentMaxAttempts),
     'state', 'waiting-children'
   }
-  if parentOrderingKey ~= '' and parentGroupConc > 1 then
+  if parentUseGroup then
     parentHash[#parentHash + 1] = 'groupKey'
     parentHash[#parentHash + 1] = parentOrderingKey
     local groupHashKey = parentPrefix .. 'group:' .. parentOrderingKey
-    redis.call('HSET', groupHashKey, 'maxConcurrency', tostring(parentGroupConc))
+    redis.call('HSET', groupHashKey, 'maxConcurrency', tostring(parentGroupConc > 1 and parentGroupConc or 1))
     redis.call('HSETNX', groupHashKey, 'active', '0')
+    if parentRateMax > 0 then
+      redis.call('HSET', groupHashKey, 'rateMax', tostring(parentRateMax))
+      redis.call('HSET', groupHashKey, 'rateDuration', tostring(parentRateDuration))
+    end
+    if parentTbCapacity > 0 then
+      if parentCost > 0 and parentCost > parentTbCapacity then
+        return 'ERR:COST_EXCEEDS_CAPACITY'
+      end
+      redis.call('HSET', groupHashKey, 'tbCapacity', tostring(parentTbCapacity), 'tbRefillRate', tostring(parentTbRefillRate))
+      redis.call('HSETNX', groupHashKey, 'tbTokens', tostring(parentTbCapacity))
+      redis.call('HSETNX', groupHashKey, 'tbLastRefill', tostring(timestamp))
+      redis.call('HSETNX', groupHashKey, 'tbRefillRemainder', '0')
+    end
   elseif parentOrderingKey ~= '' then
     parentHash[#parentHash + 1] = 'orderingKey'
     parentHash[#parentHash + 1] = parentOrderingKey
     parentHash[#parentHash + 1] = 'orderingSeq'
     parentHash[#parentHash + 1] = tostring(parentOrderingSeq)
   end
+  if parentCost > 0 then
+    parentHash[#parentHash + 1] = 'cost'
+    parentHash[#parentHash + 1] = tostring(parentCost)
+  end
   redis.call('HSET', parentJobKey, unpack(parentHash))
-  local childIds = {}
+  -- Pre-validate all children's cost vs capacity before any child writes
   local childArgOffset = 8
   local childKeyOffset = 4
+  for i = 1, numChildren do
+    local base = childArgOffset + (i - 1) * 8
+    local preChildOpts = args[base + 3]
+    local preChildTbCap, _ = extractTokenBucketFromOpts(preChildOpts)
+    if preChildTbCap > 0 then
+      local preChildCost = extractCostFromOpts(preChildOpts)
+      local preEffective = (preChildCost > 0) and preChildCost or 1000
+      if preEffective > preChildTbCap then
+        return 'ERR:COST_EXCEEDS_CAPACITY'
+      end
+    end
+  end
+  local childIds = {}
   for i = 1, numChildren do
     local base = childArgOffset + (i - 1) * 8
     local childName = args[base + 1]
@@ -903,8 +1447,12 @@ redis.register_function('glidemq_addFlow', function(keys, args)
     local childJobKey = childPrefix .. 'job:' .. childJobIdStr
     local childOrderingKey = extractOrderingKeyFromOpts(childOpts)
     local childGroupConc = extractGroupConcurrencyFromOpts(childOpts)
+    local childRateMax, childRateDuration = extractGroupRateLimitFromOpts(childOpts)
+    local childTbCapacity, childTbRefillRate = extractTokenBucketFromOpts(childOpts)
+    local childCost = extractCostFromOpts(childOpts)
+    local childUseGroup = (childOrderingKey ~= '' and (childGroupConc > 1 or childRateMax > 0 or childTbCapacity > 0))
     local childOrderingSeq = 0
-    if childOrderingKey ~= '' and childGroupConc <= 1 then
+    if childOrderingKey ~= '' and not childUseGroup then
       local childOrderingMetaKey = childPrefix .. 'ordering'
       childOrderingSeq = redis.call('HINCRBY', childOrderingMetaKey, childOrderingKey, 1)
     end
@@ -921,18 +1469,32 @@ redis.register_function('glidemq_addFlow', function(keys, args)
       'parentId', parentJobIdStr,
       'parentQueue', childParentQueue
     }
-    if childOrderingKey ~= '' and childGroupConc > 1 then
+    if childUseGroup then
       childHash[#childHash + 1] = 'groupKey'
       childHash[#childHash + 1] = childOrderingKey
       local childGroupHashKey = childPrefix .. 'group:' .. childOrderingKey
-      redis.call('HSETNX', childGroupHashKey, 'maxConcurrency', tostring(childGroupConc))
+      redis.call('HSETNX', childGroupHashKey, 'maxConcurrency', tostring(childGroupConc > 1 and childGroupConc or 1))
       redis.call('HSETNX', childGroupHashKey, 'active', '0')
+      if childRateMax > 0 then
+        redis.call('HSET', childGroupHashKey, 'rateMax', tostring(childRateMax))
+        redis.call('HSET', childGroupHashKey, 'rateDuration', tostring(childRateDuration))
+      end
+      if childTbCapacity > 0 then
+        redis.call('HSET', childGroupHashKey, 'tbCapacity', tostring(childTbCapacity), 'tbRefillRate', tostring(childTbRefillRate))
+        redis.call('HSETNX', childGroupHashKey, 'tbTokens', tostring(childTbCapacity))
+        redis.call('HSETNX', childGroupHashKey, 'tbLastRefill', tostring(timestamp))
+        redis.call('HSETNX', childGroupHashKey, 'tbRefillRemainder', '0')
+      end
     elseif childOrderingKey ~= '' then
       childHash[#childHash + 1] = 'orderingKey'
       childHash[#childHash + 1] = childOrderingKey
       childHash[#childHash + 1] = 'orderingSeq'
       childHash[#childHash + 1] = tostring(childOrderingSeq)
     end
+    if childCost > 0 then
+      childHash[#childHash + 1] = 'cost'
+      childHash[#childHash + 1] = tostring(childCost)
+    end
     if childDelay > 0 or childPriority > 0 then
       childHash[#childHash + 1] = 'state'
       childHash[#childHash + 1] = childDelay > 0 and 'delayed' or 'prioritized'
@@ -1004,7 +1566,7 @@ redis.register_function('glidemq_removeJob', function(keys, args)
   local groupKey = redis.call('HGET', jobKey, 'groupKey')
   if groupKey and groupKey ~= '' then
     if state == 'active' then
-      releaseGroupSlotAndPromote(jobKey, jobId)
+      releaseGroupSlotAndPromote(jobKey, jobId, 0)
     elseif state == 'group-waiting' then
       local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
       local waitListKey = prefix .. 'groupq:' .. groupKey
@@ -1127,7 +1689,7 @@ end)
  * Add a job to the queue atomically.
  * Returns the new job ID (string).
  */
-async function addJob(client, k, jobName, data, opts, timestamp, delay, priority, parentId, maxAttempts, orderingKey = '', groupConcurrency = 0) {
+async function addJob(client, k, jobName, data, opts, timestamp, delay, priority, parentId, maxAttempts, orderingKey = '', groupConcurrency = 0, groupRateMax = 0, groupRateDuration = 0, tbCapacity = 0, tbRefillRate = 0, jobCost = 0) {
     const result = await client.fcall('glidemq_addJob', [k.id, k.stream, k.scheduled, k.events], [
         jobName,
         data,
@@ -1139,6 +1701,11 @@ async function addJob(client, k, jobName, data, opts, timestamp, delay, priority
         maxAttempts.toString(),
         orderingKey,
         groupConcurrency.toString(),
+        groupRateMax.toString(),
+        groupRateDuration.toString(),
+        tbCapacity.toString(),
+        tbRefillRate.toString(),
+        jobCost.toString(),
     ]);
     return result;
 }
@@ -1146,7 +1713,7 @@ async function addJob(client, k, jobName, data, opts, timestamp, delay, priority
  * Add a job with deduplication. Checks the dedup hash and either skips or adds the job.
  * Returns "skipped" if deduplicated, otherwise the new job ID (string).
  */
-async function dedup(client, k, dedupId, ttlMs, mode, jobName, data, opts, timestamp, delay, priority, parentId, maxAttempts, orderingKey = '', groupConcurrency = 0) {
+async function dedup(client, k, dedupId, ttlMs, mode, jobName, data, opts, timestamp, delay, priority, parentId, maxAttempts, orderingKey = '', groupConcurrency = 0, groupRateMax = 0, groupRateDuration = 0, tbCapacity = 0, tbRefillRate = 0, jobCost = 0) {
     const result = await client.fcall('glidemq_dedup', [k.dedup, k.id, k.stream, k.scheduled, k.events], [
         dedupId,
         ttlMs.toString(),
@@ -1161,6 +1728,11 @@ async function dedup(client, k, dedupId, ttlMs, mode, jobName, data, opts, times
         maxAttempts.toString(),
         orderingKey,
         groupConcurrency.toString(),
+        groupRateMax.toString(),
+        groupRateDuration.toString(),
+        tbCapacity.toString(),
+        tbRefillRate.toString(),
+        jobCost.toString(),
     ]);
     return result;
 }
@@ -1322,10 +1894,14 @@ async function checkConcurrency(client, k, group = exports.CONSUMER_GROUP) {
  * Reads the full job hash, checks revoked flag, sets state=active + processedOn + lastActive.
  * For group-concurrency jobs, checks if the group has capacity. If not, parks the job
  * in the group wait list and returns 'GROUP_FULL'.
+ * For rate-limited groups, parks the job and returns 'GROUP_RATE_LIMITED'.
  * Returns:
  * - null if job hash doesn't exist
  * - 'REVOKED' if the job's revoked flag is set
  * - 'GROUP_FULL' if the job's group is at max concurrency (job was parked)
+ * - 'GROUP_RATE_LIMITED' if the job's group exceeded its rate limit (job was parked)
+ * - 'GROUP_TOKEN_LIMITED' if the job's group has insufficient tokens (job was parked)
+ * - 'ERR:COST_EXCEEDS_CAPACITY' if the job cost exceeds token bucket capacity (job was failed)
  * - Record<string, string> with all job fields otherwise
  */
 async function moveToActive(client, k, jobId, timestamp, streamKey = '', entryId = '', group = '') {
@@ -1343,6 +1919,12 @@ async function moveToActive(client, k, jobId, timestamp, streamKey = '', entryId
         return 'REVOKED';
     if (str === 'GROUP_FULL')
         return 'GROUP_FULL';
+    if (str === 'GROUP_RATE_LIMITED')
+        return 'GROUP_RATE_LIMITED';
+    if (str === 'GROUP_TOKEN_LIMITED')
+        return 'GROUP_TOKEN_LIMITED';
+    if (str === 'ERR:COST_EXCEEDS_CAPACITY')
+        return 'ERR:COST_EXCEEDS_CAPACITY';
     // Parse the cjson.encode output: [field1, value1, field2, value2, ...]
     const arr = JSON.parse(str);
     const hash = {};
@@ -1351,6 +1933,15 @@ async function moveToActive(client, k, jobId, timestamp, streamKey = '', entryId
     }
     return hash;
 }
+/**
+ * Promote rate-limited groups whose window has expired.
+ * Moves waiting jobs from the group queue back into the stream.
+ * Returns the number of jobs promoted.
+ */
+async function promoteRateLimited(client, k, timestamp) {
+    const result = await client.fcall('glidemq_promoteRateLimited', [k.ratelimited, k.stream], [timestamp.toString()]);
+    return Number(result) || 0;
+}
 /**
  * Defers an active job back to waiting by acknowledging + deleting the current
  * stream entry and re-enqueuing the same jobId to the stream tail.