feat(engine): enqueue fast path; skip the queue under certain conditions

[ericallam]

Summary

Currently, every triggered run follows a two-step path through Redis:

1. Enqueue — A Lua script atomically adds the message to a queue sorted set (ordered by priority-adjusted timestamp)
2. Dequeue — A debounced processQueueForWorkerQueue job fires ~500ms later, checks concurrency limits, removes the message from the sorted set, and pushes it to a worker queue (Redis list) where workers pick it up via BLPOP

This means every run pays at least ~500ms of latency between being triggered and being available for a worker to execute, even when the queue is empty and concurrency is wide open.

What changed

The enqueue Lua scripts now atomically decide whether to skip the queue sorted set entirely and push directly to the worker queue. This happens inside the same Lua script that handles normal enqueue, so the decision is atomic with respect to concurrency bookkeeping.

A run takes the fast path when all of these are true:

• Fast path is enabled for this worker queue (gated per WorkerInstanceGroup)
• No available messages in the queue (ZRANGEBYSCORE finds nothing with score ≤ now) — this respects priority ordering and allows fast path even when the queue has future-scored messages (e.g. nacked retries with delay)
• Environment concurrency has capacity
• Queue concurrency has capacity (including per-concurrency-key limits for CK queues)

When the fast path is taken:

• The message is stored and pushed directly to the worker queue (RPUSH)
• Concurrency slots are claimed (SADD to the same sets used by the normal dequeue path)
• The processQueueForWorkerQueue job is not scheduled (no work to do)
• TTL sorted set is skipped (the expireRun worker job handles TTL independently)

When any condition fails, the existing slow path runs unchanged.

Rollout gating

• Development environments: Fast path is always enabled
• Production environments: Gated by a new enableFastPath boolean on WorkerInstanceGroup (defaults to false), allowing region-by-region rollout

Rolling deploy safety

Each process registers its own Lua scripts via defineCommand (identified by SHA hash). Old and new processes never share scripts. The Redis data structures are fully compatible in both directions — ack, nack, and release operations work identically regardless of which path a message took.

Test plan

• Fast path taken when queue is empty and concurrency available
• Slow path when enableFastPath is false
• Slow path when queue has available messages (respects priority ordering)
• Fast path when queue only has future-scored messages
• Slow path when env concurrency is full
• Fast-path message can be acknowledged correctly
• Fast-path message can be nacked and re-enqueued to the queue sorted set
• Run all existing run-queue tests (ack, nack, CK, concurrency sweeper, dequeue) to verify no regressions
• Typecheck passes for run-engine and webapp

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6fb759a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 24b5bd6d-e977-46f7-922b-d90f3a64441d

📥 Commits

Reviewing files that changed from the base of the PR and between c8a4e24 and 6fb759a.

📒 Files selected for processing (1)

• .server-changes/enqueue-fast-path.md

---

Walkthrough

A new boolean field enableFastPath was added to the WorkerInstanceGroup model and migration. Queue manager APIs now return { masterQueue, enableFastPath } instead of a raw queue name. The run-engine TriggerParams, EnqueueSystem, RunQueue, and related Redis Lua enqueue commands/typings were extended to accept and propagate enableFastPath. RunQueue logic and tests were updated to implement and verify a fast-path that can push directly to worker queues when concurrency allows. Development environments default enableFastPath to true.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	No pull request description was provided by the author, leaving all template sections (Testing, Changelog, Checklist) blank.	Add a comprehensive description including testing steps, changelog entry, and confirmation of the contributing guide checklist to help reviewers understand the changes.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main feature being implemented: adding an enqueue fast path that allows skipping the queue under certain conditions.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/tri-8305-implement-enqueue-fast-path

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ericallam]

@cubic-dev-ai please review

[cubic-dev-ai]

@cubic-dev-ai please review

@ericallam I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 10 files