glide-mq 0.4.3 → 0.6.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 = '15';
+exports.LIBRARY_VERSION = '19';
 // Consumer group name used by workers
 exports.CONSUMER_GROUP = 'workers';
 // Embedded Lua library source (from glidemq.lua)
@@ -76,6 +77,136 @@ local function markOrderingDone(jobKey, jobId)
   end
 end
 
+-- 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
+  -- 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(newActive))
+  end
+  local waitListKey = prefix .. 'groupq:' .. gk
+  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')
+  end
+end
+
 local function extractOrderingKeyFromOpts(optsJson)
   if not optsJson or optsJson == '' then
     return ''
@@ -95,6 +226,67 @@ local function extractOrderingKeyFromOpts(optsJson)
   return tostring(key)
 end
 
+local function extractGroupConcurrencyFromOpts(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 ordering = decoded['ordering']
+  if type(ordering) ~= 'table' then
+    return 0
+  end
+  local conc = ordering['concurrency']
+  if conc == nil then
+    return 0
+  end
+  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)
@@ -113,15 +305,80 @@ redis.register_function('glidemq_addJob', function(keys, args)
   local parentId = args[7] or ''
   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 or groupRateMax > 0 or tbCapacity > 0))
   local orderingSeq = 0
-  if orderingKey ~= '' then
+  if orderingKey ~= '' and not useGroupConcurrency then
     local orderingMetaKey = prefix .. 'ordering'
     orderingSeq = redis.call('HINCRBY', orderingMetaKey, orderingKey, 1)
   end
+  if useGroupConcurrency then
+    local groupHashKey = prefix .. 'group:' .. orderingKey
+    local curMax = tonumber(redis.call('HGET', groupHashKey, 'maxConcurrency')) or 0
+    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,
     'name', jobName,
@@ -133,12 +390,19 @@ redis.register_function('glidemq_addJob', function(keys, args)
     'priority', tostring(priority),
     'maxAttempts', tostring(maxAttempts)
   }
-  if orderingKey ~= '' then
+  if useGroupConcurrency then
+    hashFields[#hashFields + 1] = 'groupKey'
+    hashFields[#hashFields + 1] = orderingKey
+  elseif orderingKey ~= '' then
     hashFields[#hashFields + 1] = 'orderingKey'
     hashFields[#hashFields + 1] = orderingKey
     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
@@ -230,6 +494,7 @@ redis.register_function('glidemq_complete', function(keys, args)
     'finishedOn', tostring(timestamp)
   )
   markOrderingDone(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
@@ -311,6 +576,7 @@ redis.register_function('glidemq_completeAndFetchNext', function(keys, args)
     'finishedOn', tostring(timestamp)
   )
   markOrderingDone(jobKey, jobId)
+  releaseGroupSlotAndPromote(jobKey, jobId, timestamp)
   emitEvent(eventsKey, 'completed', jobId, {'returnvalue', returnvalue})
   local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
 
@@ -378,6 +644,93 @@ redis.register_function('glidemq_completeAndFetchNext', function(keys, args)
   if revoked == '1' then
     return cjson.encode({completed = jobId, next = 'REVOKED', nextJobId = nextJobId, nextEntryId = nextEntryId})
   end
+  local nextGroupKey = redis.call('HGET', nextJobKey, 'groupKey')
+  if nextGroupKey and nextGroupKey ~= '' then
+    local nextGroupHashKey = prefix .. 'group:' .. nextGroupKey
+    -- 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)
+      local nextWaitListKey = prefix .. 'groupq:' .. nextGroupKey
+      redis.call('RPUSH', nextWaitListKey, nextJobId)
+      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))
   local nextHash = redis.call('HGETALL', nextJobKey)
   return cjson.encode({completed = jobId, next = nextHash, nextJobId = nextJobId, nextEntryId = nextEntryId})
@@ -412,6 +765,7 @@ redis.register_function('glidemq_fail', function(keys, args)
       'failedReason', failedReason,
       'processedOn', tostring(timestamp)
     )
+    releaseGroupSlotAndPromote(jobKey, jobId, timestamp)
     emitEvent(eventsKey, 'retrying', jobId, {
       'failedReason', failedReason,
       'attemptsMade', tostring(attemptsMade),
@@ -427,6 +781,7 @@ redis.register_function('glidemq_fail', function(keys, args)
       'processedOn', tostring(timestamp)
     )
     markOrderingDone(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
@@ -514,6 +869,7 @@ redis.register_function('glidemq_reclaimStalled', function(keys, args)
           'finishedOn', tostring(timestamp)
         )
         markOrderingDone(jobKey, jobId)
+        releaseGroupSlotAndPromote(jobKey, jobId, timestamp)
         emitEvent(eventsKey, 'failed', jobId, {
           'failedReason', 'job stalled more than maxStalledCount'
         })
@@ -562,6 +918,12 @@ redis.register_function('glidemq_dedup', function(keys, args)
   local parentId = args[10] or ''
   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
@@ -607,11 +969,67 @@ 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 or groupRateMax > 0 or tbCapacity > 0))
   local orderingSeq = 0
-  if orderingKey ~= '' then
+  if orderingKey ~= '' and not useGroupConcurrency then
     local orderingMetaKey = prefix .. 'ordering'
     orderingSeq = redis.call('HINCRBY', orderingMetaKey, orderingKey, 1)
   end
+  if useGroupConcurrency then
+    local groupHashKey = prefix .. 'group:' .. orderingKey
+    local curMax = tonumber(redis.call('HGET', groupHashKey, 'maxConcurrency')) or 0
+    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,
     'name', jobName,
@@ -623,12 +1041,19 @@ redis.register_function('glidemq_dedup', function(keys, args)
     'priority', tostring(priority),
     'maxAttempts', tostring(maxAttempts)
   }
-  if orderingKey ~= '' then
+  if useGroupConcurrency then
+    hashFields[#hashFields + 1] = 'groupKey'
+    hashFields[#hashFields + 1] = orderingKey
+  elseif orderingKey ~= '' then
     hashFields[#hashFields + 1] = 'orderingKey'
     hashFields[#hashFields + 1] = orderingKey
     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
@@ -661,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
@@ -675,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]
@@ -694,7 +1206,11 @@ end)
 
 redis.register_function('glidemq_moveToActive', function(keys, args)
   local jobKey = keys[1]
+  local streamKey = keys[2] or ''
   local timestamp = args[1]
+  local entryId = args[2] or ''
+  local group = args[3] or ''
+  local jobId = args[4] or ''
   local exists = redis.call('EXISTS', jobKey)
   if exists == 0 then
     return ''
@@ -703,6 +1219,104 @@ redis.register_function('glidemq_moveToActive', function(keys, args)
   if revoked == '1' then
     return 'REVOKED'
   end
+  local groupKey = redis.call('HGET', jobKey, 'groupKey')
+  if groupKey and groupKey ~= '' then
+    local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
+    local groupHashKey = prefix .. 'group:' .. groupKey
+    -- 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)
+        redis.call('XDEL', streamKey, entryId)
+      end
+      local waitListKey = prefix .. 'groupq:' .. groupKey
+      redis.call('RPUSH', waitListKey, jobId)
+      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)
   local fields = redis.call('HGETALL', jobKey)
   return cjson.encode(fields)
@@ -744,8 +1358,13 @@ redis.register_function('glidemq_addFlow', function(keys, args)
   local parentJobKey = parentPrefix .. 'job:' .. parentJobIdStr
   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 ~= '' then
+  if parentOrderingKey ~= '' and not parentUseGroup then
     local parentOrderingMetaKey = parentPrefix .. 'ordering'
     parentOrderingSeq = redis.call('HINCRBY', parentOrderingMetaKey, parentOrderingKey, 1)
   end
@@ -761,16 +1380,52 @@ redis.register_function('glidemq_addFlow', function(keys, args)
     'maxAttempts', tostring(parentMaxAttempts),
     'state', 'waiting-children'
   }
-  if parentOrderingKey ~= '' then
+  if parentUseGroup then
+    parentHash[#parentHash + 1] = 'groupKey'
+    parentHash[#parentHash + 1] = parentOrderingKey
+    local groupHashKey = parentPrefix .. 'group:' .. parentOrderingKey
+    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]
@@ -791,8 +1446,13 @@ redis.register_function('glidemq_addFlow', function(keys, args)
     local childPrefix = string.sub(childIdKey, 1, #childIdKey - 2)
     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 ~= '' then
+    if childOrderingKey ~= '' and not childUseGroup then
       local childOrderingMetaKey = childPrefix .. 'ordering'
       childOrderingSeq = redis.call('HINCRBY', childOrderingMetaKey, childOrderingKey, 1)
     end
@@ -809,12 +1469,32 @@ redis.register_function('glidemq_addFlow', function(keys, args)
       'parentId', parentJobIdStr,
       'parentQueue', childParentQueue
     }
-    if childOrderingKey ~= '' then
+    if childUseGroup then
+      childHash[#childHash + 1] = 'groupKey'
+      childHash[#childHash + 1] = childOrderingKey
+      local childGroupHashKey = childPrefix .. 'group:' .. childOrderingKey
+      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'
@@ -882,6 +1562,17 @@ redis.register_function('glidemq_removeJob', function(keys, args)
   if exists == 0 then
     return 0
   end
+  local state = redis.call('HGET', jobKey, 'state')
+  local groupKey = redis.call('HGET', jobKey, 'groupKey')
+  if groupKey and groupKey ~= '' then
+    if state == 'active' then
+      releaseGroupSlotAndPromote(jobKey, jobId, 0)
+    elseif state == 'group-waiting' then
+      local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
+      local waitListKey = prefix .. 'groupq:' .. groupKey
+      redis.call('LREM', waitListKey, 1, jobId)
+    end
+  end
   redis.call('ZREM', scheduledKey, jobId)
   redis.call('ZREM', completedKey, jobId)
   redis.call('ZREM', failedKey, jobId)
@@ -907,6 +1598,22 @@ redis.register_function('glidemq_revoke', function(keys, args)
   end
   redis.call('HSET', jobKey, 'revoked', '1')
   local state = redis.call('HGET', jobKey, 'state')
+  if state == 'group-waiting' then
+    local gk = redis.call('HGET', jobKey, 'groupKey')
+    if gk and gk ~= '' then
+      local prefix = string.sub(jobKey, 1, #jobKey - #('job:' .. jobId))
+      local waitListKey = prefix .. 'groupq:' .. gk
+      redis.call('LREM', waitListKey, 1, jobId)
+    end
+    redis.call('ZADD', failedKey, timestamp, jobId)
+    redis.call('HSET', jobKey,
+      'state', 'failed',
+      'failedReason', 'revoked',
+      'finishedOn', tostring(timestamp)
+    )
+    emitEvent(eventsKey, 'revoked', jobId, nil)
+    return 'revoked'
+  end
   if state == 'waiting' or state == 'delayed' or state == 'prioritized' then
     redis.call('ZREM', scheduledKey, jobId)
     local entries = redis.call('XRANGE', streamKey, '-', '+')
@@ -982,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 = '') {
+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,
@@ -993,6 +1700,12 @@ async function addJob(client, k, jobName, data, opts, timestamp, delay, priority
         parentId,
         maxAttempts.toString(),
         orderingKey,
+        groupConcurrency.toString(),
+        groupRateMax.toString(),
+        groupRateDuration.toString(),
+        tbCapacity.toString(),
+        tbRefillRate.toString(),
+        jobCost.toString(),
     ]);
     return result;
 }
@@ -1000,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 = '') {
+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(),
@@ -1014,6 +1727,12 @@ async function dedup(client, k, dedupId, ttlMs, mode, jobName, data, opts, times
         parentId,
         maxAttempts.toString(),
         orderingKey,
+        groupConcurrency.toString(),
+        groupRateMax.toString(),
+        groupRateDuration.toString(),
+        tbCapacity.toString(),
+        tbRefillRate.toString(),
+        jobCost.toString(),
     ]);
     return result;
 }
@@ -1173,20 +1892,39 @@ async function checkConcurrency(client, k, group = exports.CONSUMER_GROUP) {
 /**
  * Move a job to active state in a single round trip.
  * 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
- *
- * Replaces: HGETALL + revoked check + HSET lastActive (3 round trips -> 1)
  */
-async function moveToActive(client, k, jobId, timestamp) {
-    const result = await client.fcall('glidemq_moveToActive', [k.job(jobId)], [timestamp.toString()]);
+async function moveToActive(client, k, jobId, timestamp, streamKey = '', entryId = '', group = '') {
+    const keys = [k.job(jobId)];
+    const args = [timestamp.toString()];
+    if (streamKey) {
+        keys.push(streamKey);
+        args.push(entryId, group, jobId);
+    }
+    const result = await client.fcall('glidemq_moveToActive', keys, args);
     const str = String(result);
     if (str === '' || str === 'null')
         return null;
     if (str === 'REVOKED')
         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 = {};
@@ -1195,6 +1933,15 @@ async function moveToActive(client, k, jobId, timestamp) {
     }
     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.