chore(gas): add overview and history docs

[MasterPtato]

No description provided.

[MasterPtato]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(pegboard): cache none runner pool errors too #3899
• fix(engine-runner): handle shutdown close codes correctly #3896
• chore(gas): add overview and history docs #3879 👈 (View in Graphite)
• fix(otel): enrich http traces #3878
• fix(guard): clean up guard #3862
• fix: add ready_chunks to worker bumps, bumps per tick metric #3855
• fix(epoxy): add metrics #3847
• chore: clean up errors #3846
• fix(pb): have restart policy actors sleep after pending for too long #3837
• fix: set failure reason regardless of crash policy #3835
• feat: add metrics to pb, guard #3815
• fix: clear all pending signals after workflow complete #3798
• fix: remove pending actors metric, fix actor error tracker, engine runner error print #3797
• chore(engine): add support for epoxy debugging #3794
• 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.

[pkg-pr-new]

More templates

• actor-actions
• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-cloudflare-workers-inline-client
• cross-actor-actions
• example-cursors
• example-cursors-raw-websocket
• custom-serverless
• example-sqlite
• example-elysia
• example-experimental-durable-streams-ai-agent
• hello-world
• example-hono
• hono-react
• example-kitchen-sink
• multi-region
• native-websockets
• next-js
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• scheduling
• state
• example-stream
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3879

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3879

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3879

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3879

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3879

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3879

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3879

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@3879

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3879

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3879

commit: 5889ab3

[claude]

PR Review: Add Gasoline Overview and History Documentation

Overall, this is a valuable documentation contribution that helps explain the Gasoline workflow engine. The documentation is well-structured and provides good explanations of complex concepts like workflow history locations and versioning.

✅ Strengths

1. Clear Structure: The reorganization from a single GASOLINE.md file into multiple focused documents (OVERVIEW.md, WORKFLOW_HISTORY.md, etc.) improves maintainability and navigation.

2. Comprehensive Coverage: The WORKFLOW_HISTORY.md provides excellent detail on the location system with concrete examples.

3. Practical Examples: The idempotency example in OVERVIEW.md (showing bad activity composition) is helpful for developers.

4. Code Examples: The version check example with Rust code in WORKFLOW_HISTORY.md effectively demonstrates the concept.

📝 Suggestions for Improvement

1. Terminology Consistency (docs/engine/GASOLINE/OVERVIEW.md:6-10)

The description of Activities vs Operations could be clearer about their differences. Both are described as "thin wrappers around native rust functions," which is confusing. Consider elaborating on the distinction:

• Activities: Durable, retriable execution steps within workflows
• Operations: Non-durable helpers for interoperability

2. Grammar and Clarity (docs/engine/GASOLINE/OVERVIEW.md:14)

Line 14: "rewoken" → "awakened" or "restored"

When a workflow is awakened from database back into memory...

Also: "to database" → "to the database" (appears multiple times)

3. Location Notation Ambiguity (docs/engine/GASOLINE/WORKFLOW_HISTORY.md:13)

The notation {0.1} could be misinterpreted as a decimal number. Consider explicitly stating that the period (.) is a separator, not a decimal point:

- `{0.1}` - the first inserted event before the first event (note: `.` is a separator, not a decimal)

4. Missing Context for "Coordinates" vs "Ordinates" (docs/engine/GASOLINE/WORKFLOW_HISTORY.md:7)

The distinction between coordinates and ordinates is introduced but could use a clearer explanation. Consider adding:

Each __coordinate__ is a set of __ordinates__ which are positive integers. For example, in location `{2, 11, 4}`, there are 3 coordinates, each containing a single ordinate (2, 11, and 4 respectively).

5. Example Enhancement (docs/engine/GASOLINE/WORKFLOW_HISTORY.md:67-85)

The version check example uses ... placeholders which makes it less concrete. Consider showing what actual activity calls might look like, or at least use more descriptive placeholder names.

6. Typo Fix Already Applied ✅

Good catch on the typo fix in HIBERNATING_WS.md:25 ("hiberating" → "hibernating").

7. Comment Clarity (engine/packages/gasoline/src/db/kv/mod.rs:980)

The updated comment is slightly clearer but could be more precise:

/// Returns the first incomplete workflow with the given name and tags. "First" means the one with the
/// lowest ID value when sorted by the internal byte representation used in the KV store. Due to KV store
/// limitations, only the first matching workflow can be retrieved.

🔍 Technical Concerns

Minor: Documentation vs Implementation Drift

The documentation should include a note about when it was last updated relative to the codebase to help readers understand if the docs might be stale. Consider adding version info or last-updated dates to the doc headers.

✨ Nice Touches

1. The reference to WORKFLOW_HISTORY.md from OVERVIEW.md creates good cross-document navigation.
2. The "bad composition" pseudocode example effectively illustrates the idempotency requirement.
3. The tag ordering optimization tip (most unique to least unique) is a practical detail that could prevent performance issues.

📋 TODO Items

The PR creates stubs for:

• DESIGN_GUIDE.md
• GOTCHAS.md
• OPERATIONS.md

These are marked as TODO, which is fine for this PR, but consider opening follow-up issues to track completion of these documentation sections.

🎯 Summary

This is a solid documentation improvement that makes Gasoline more accessible to developers. The main areas for enhancement are:

• Minor grammar/wording improvements
• Clarifying terminology (Activities vs Operations)
• Adding more concrete examples in the Rust code snippets

The code change in db/kv/mod.rs is appropriate and improves comment clarity.

Recommendation: Approve with minor suggestions for follow-up improvements.

[abcxff]

Nice how it explains a bit more of how it actually works. Might be good to say blatanlty how signals are the only form of durable/guaranteed communication and they’re consumption is guaranteed ( is it?)

[MasterPtato]

Updated to say "only". Signal consumption is not guaranteed, the wf needs to listen to the signals to receive them

[abcxff]

Is this Gotchas worthy?

[MasterPtato]

Definitely