feat(rivetkit): workflows

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

4 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
rivet-cloud	Ignored		Jan 2, 2026 8:07pm
rivet-inspector	Ignored	Preview	Jan 2, 2026 8:07pm
rivet-site	Ignored	Preview	Jan 2, 2026 8:07pm
rivetkit-serverless	Skipped		Jan 2, 2026 8:07pm

[NathanFlurry]

• feat(rivetkit): workflows #3734 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: RivetKit Workflow Engine

This is an impressive implementation of a durable execution engine for TypeScript. The code is well-architected with clear separation of concerns. Below is my detailed feedback:

---

✅ Strengths

1. Excellent Architecture

   • Clean separation between storage, context, and driver layers
   • The location-based entry system with NameIndex optimization is elegant
   • Isolation model is well-documented and correctly implemented
   • Dirty tracking minimizes unnecessary writes

2. Comprehensive Documentation

   • The QUICKSTART.md and architecture.md are exceptionally thorough
   • Code comments explain non-obvious behavior (e.g., timeout limitations, signal delivery model)
   • Clear examples throughout

3. Robust Error Handling

   • Well-structured error hierarchy with specific error types
   • Proper distinction between retryable, critical, and yield errors
   • Good use of StepFailedError cause chain

4. Testing

   • Comprehensive test coverage for core features
   • Tests validate replay behavior, retries, parallel execution, etc.

---

🔍 Code Quality Issues

High Priority

1. Race Condition in Signal Consumption (storage.ts:298-317)

   • consumeSignal deletes from driver first, then removes from memory
   • If process crashes between driver deletion and memory update, signal is lost
   • Recommendation: Consider adding a transaction log or using idempotency tokens

2. Incomplete Error Handling (context.ts:363-403)

   • executeWithTimeout doesn't handle cleanup if the promise rejects after timeout
   • The underlying operation continues running with no way to observe its completion
   • Recommendation: Document this limitation more prominently or consider tracking orphaned promises

3. Missing Validation (context.ts:472)

   • TODO comment indicates commitInterval validation is missing
   • Zero or negative values would cause infinite loops or division by zero
   • Fix: Add validation before loop execution:

   if (commitInterval <= 0) {
     throw new Error("commitInterval must be greater than 0");
   }

4. Potential Memory Leak (context.ts:203-217)

   • waitForEviction creates a promise with an abort listener
   • While { once: true } helps, if this is called multiple times the comment suggests concern
   • Recommendation: Track if listener is already attached or document why multiple calls are safe

Medium Priority

5. Inconsistent Null Handling (storage.ts:241-258)

   • Output comparison uses !== but error comparison checks multiple fields
   • Recommendation: Use consistent comparison strategy (structural equality helper?)

6. Missing Type Safety (context.ts:260, 719, 827, etc.)

   • Multiple type assertions like as T without runtime validation
   • If serialization/deserialization corrupts data, errors won't be caught until runtime
   • Recommendation: Consider adding runtime type validation or using a schema library

7. Unsafe Array Access (context.ts:550-553)

   • Assumes loopLocation[loopLocation.length - 1] is a number
   • Throws error if assumption violated, but earlier validation might be clearer
   • Recommendation: Add assertion at loop creation time

8. Console.warn in Production (context.ts:1378-1383)

   • Uses console.warn for late race errors
   • No structured logging integration
   • Recommendation: Use proper logging interface that can be injected

Low Priority

9. Magic Numbers

   • Retry interval (304): 100ms hardcoded
   • Should reference DEFAULT_RETRY_BACKOFF_BASE or make configurable

10. Code Duplication

    • executeListenN and executeListenNUntilImpl share significant logic for signal recording
    • Recommendation: Extract shared logic into helper function

---

🔒 Security Concerns

1. Unbounded Storage Growth

   • Signal queue can grow unbounded if signals are sent faster than consumed
   • No limits on history size or name registry
   • Recommendation: Add configurable limits with warnings/errors when approached

2. Serialization Safety

   • BARE schema usage appears safe, but no validation that deserialized data matches expected types
   • Recommendation: Add schema version checks and validation

3. No Access Control

   • Driver interface has no authentication/authorization
   • Workflow IDs appear to be trusted input
   • Recommendation: Document security model and recommend ID generation strategy

---

⚡ Performance Considerations

1. O(n) Signal Lookup (storage.ts:337-342)

   • consumeSignals does linear scan of signal array
   • For high signal volumes, consider Map<signalName, Signal[]>

2. Unbatched Metadata Deletes (storage.ts:397)

   • Deletes metadata serially in Promise.all
   • Could use driver.batch() for better performance

3. Full History Scan (context.ts:169-187)

   • validateComplete scans entire history for every branch
   • For deep workflows, this could be expensive
   • Recommendation: Consider caching visited keys per branch

4. Repeated Name Registry Access

   • locationToKey called frequently with repeated lookups
   • Consider caching resolved keys

---

🧪 Test Coverage Gaps

1. Missing Edge Cases

   • No test for workflow with empty input
   • No test for extremely deep nesting
   • No test for very large loop iterations (forgetting logic)
   • No test for concurrent signal delivery

2. Error Path Coverage

   • HistoryDivergedError paths not fully exercised
   • Partial failure scenarios in consumeSignals not tested
   • Race condition where all branches fail not tested with concurrent failures

3. Driver Contract

   • No tests validating driver sorting requirements
   • No tests for driver batch atomicity failures

---

📝 Documentation Improvements

1. Driver Implementation Guide

   • Should include example implementations
   • Clarify atomicity requirements for batch()
   • Document sort order requirements more explicitly

2. Migration Guide

   • ctx.removed() is mentioned but migration workflow not fully explained
   • How to handle breaking changes in workflow signature?

3. Operational Guide Missing

   • How to monitor workflow health?
   • How to debug stuck workflows?
   • What metrics should be collected?

---

🎯 Recommendations

Must Fix Before Merge:

1. Add commitInterval validation (context.ts:472)
2. Fix or document signal consumption race condition
3. Add basic input validation tests

Should Fix Soon:

1. Improve type safety with runtime validation
2. Add structured logging interface
3. Document security model
4. Add operational/debugging guide

Nice to Have:

1. Performance optimizations for signal lookup
2. Add more edge case tests
3. Extract duplicated code

---

🎉 Conclusion

This is a solid, well-thought-out implementation of a complex system. The core architecture is sound and the documentation is excellent. The issues identified are primarily around edge cases, error handling robustness, and operational concerns rather than fundamental design problems.

Recommendation: Approve with minor changes - Fix the validation issue and document the known limitations, then this is ready to merge.

Great work on this feature! The workflow engine will be a powerful addition to RivetKit.