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]

Workflow Engine Implementation Review

This is a comprehensive implementation of a durable workflow execution engine for TypeScript. The code is well-architected and thoroughly documented.

Strengths

Architecture & Design

• Excellent isolation model with per-workflow KV namespaces
• Smart location-based history tracking with NameIndex optimization
• Well-thought-out replay mechanism with dirty tracking
• Comprehensive documentation (QUICKSTART.md and architecture.md)

Code Quality

• Strong type safety with discriminated unions
• Clean separation of concerns
• Clear error handling hierarchy
• Proper binary key encoding with fdb-tuple

Testing

• Good test coverage across all features
• Correctly marked sequential to avoid race conditions

Issues & Recommendations

1. Missing Validation (context.ts:472)

// TODO: Add validation for commitInterval (must be > 0)

Should add: if (commitInterval <= 0) throw new Error(...)

2. Type Safety in Loop Config (context.ts:408-425)
Using as cast bypasses type checking. Add runtime validation for the string overload case.

3. Console.warn in Production (context.ts:1379)
Direct console use prevents users from controlling logging. Consider adding a logger interface to EngineDriver.

4. Error Serialization Limited (index.ts:340-354)
Arrays and nested objects are silently dropped. Use JSON.stringify with try-catch to preserve more context.

5. Missing Input Validation

• listen/listenN: No check that limit > 0
• sleep/sleepUntil: No validation of duration/timestamp
• step: No check that name is non-empty

6. Potential Timeout Window (context.ts:380-403)
The finally block correctly clears the timeout, but document that the underlying operation continues running (Promises cannot be cancelled).

Best Practices

Good

• Dirty tracking minimizes writes
• Exponential backoff without jitter (determinism)
• Proper AbortController usage
• Comprehensive documentation

Could Improve

• Add JSDoc comments to all exported functions
• Document replay guarantees (exactly-once vs at-least-once)
• Consider configurable limits (history size, signal queue, loop iterations)
• Add performance benchmarks

Documentation Suggestions

1. Add "Common Pitfalls" section to QUICKSTART.md
2. Add state machine diagrams to architecture.md
3. Document crash-recovery semantics explicitly
4. Add JSDoc specifying atomicity requirements and yield points

Security Considerations

• Signal injection: External systems can write signals - ensure validation
• DoS: No limits on history/signal queue size
• Data persistence: Handle sensitive data appropriately

Conclusion

This is a high-quality implementation with excellent architecture. The issues identified are mostly minor refinements.

Priority Fixes:

1. Add commitInterval validation
2. Add input validation to public APIs
3. Replace console.warn with proper logging
4. Improve error serialization

Great work! The workflow engine demonstrates strong engineering principles and should serve as a solid foundation for durable execution in Rivet.

---

Review by Claude Code