refactor(rivetkit): add typed event and queue schemas for actors by NathanFlurry · Pull Request #4209 · rivet-dev/rivet

NathanFlurry · 2026-02-16T19:50:12Z

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

My code follows the style guidelines of this project
I have performed a self-review of my code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes

railway-app · 2026-02-16T19:50:22Z

🚅 Deployed to the rivet-pr-4209 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
ladle	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 7:54 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	Feb 18, 2026 at 11:07 pm
website	😴 Sleeping (View Logs)	Web	Feb 18, 2026 at 10:17 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Feb 18, 2026 at 10:08 pm
mcp-hub	✅ Success (View Logs)	Web	Feb 16, 2026 at 7:51 pm

NathanFlurry · 2026-02-16T19:50:27Z

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

refactor(rivetkit): add typed event and queue schemas for actors #4209 : 2 dependent PRs (#4224 , #4229 ) 👈 (View in Graphite)
feat: configure rivetkit storage path #4233
chore(rivetkit): migrate file system driver to sqlite #4206
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 · 2026-02-16T19:54:16Z

PR Review: refactor(rivetkit): add typed event and queue schemas for actors

This PR adds typed event and queue schemas for actors using the Standard Schema interface. The overall design is clean and well-structured. Here is my analysis:

Bugs

1. Unvalidated data fallback in broadcast (actor context)

In src/actor/contexts/base/actor.ts, the last branch of broadcast uses the original args instead of the validated result.data:

After passing validation, the validated/transformed output should always be used, not the raw input. The same pattern appears in the send method in src/actor/conn/mod.ts - the eventArgs fallback case uses args instead of result.data when result.data is not an array.

Both fallbacks bypass schema transformation for the multi-arg case. Probably unreachable for well-typed usage today, but could silently break with schema libraries that transform/coerce data.

Breaking Changes Not Documented

2. QueueMessage.complete() and wait option removed

The PR removes:

QueueMessage.complete() method
The wait option on QueueReceiveOptions
QueueCompleteNotAllowed, QueueMessagePending, QueueAlreadyCompleted error classes

This is an API-breaking change not flagged in the PR description or checklist.

3. db.onDestroy cleanup removed from #callOnDestroy

The database cleanup block was removed entirely with no replacement. Database connections are no longer cleaned up when an actor is destroyed. Intentional?

4. activeKeepAwakeCount tracking removed from action execution

The increment/decrement around action execution was removed. This could affect sleep scheduling if actions were previously preventing premature sleep. Worth confirming onSleep behavior is unaffected during concurrent action execution.

Design Concerns

5. Multi-queue next loses per-queue type precision

When calling next(["queueA", "queueB"]), TypeScript infers K as "queueA" | "queueB", so the return type is QueueMessageOf<TypeA | TypeB>. This is expected behavior but callers still need to narrow on message.name to get the precise body type. A doc comment noting this would help.

6. Potentially unused imports in definition.ts

import { DeepMutable } from "@/utils" and import type { ActionContextOf, ActorContext } from "./contexts" are added but do not appear to be used. Leftover from refactoring?

7. zod import changed from "zod/v4" to "zod" in registry/config/index.ts

This change appears unrelated to the PR scope. Intentional?

Minor Notes

8. Missing behavioral tests

Only type-level tests were updated. Consider adding integration tests covering:

Schema validation pass/transform cases for events and queues
Schema validation rejection cases
The raw() escape hatch
Async schema rejection path in validateSchemaSync

9. promiseWithResolvers rejection handler removed

The old receive path passed a warning callback for unhandled rejections. Now removed without explanation. If safe to drop, a brief comment would clarify intent.

10. _type field on Raw<T> could use a phantom-type pattern

Since _type is never set at runtime, using declare _type: T or marking it readonly would more accurately reflect that this field only exists for type inference.

What Is Good

The Standard Schema integration is elegant and library-agnostic (works with Zod, Valibot, etc.) without coupling to any specific one.
The raw<T>() escape hatch is practical for opt-out typing without validation overhead.
The typed overload pattern (keyof TQueues extends never ? string : never) correctly restricts untyped string usage to unschematized actors.
Removing the in-flight/completion/redelivery complexity from QueueManager significantly simplifies the implementation.
Schema validation in enqueue correctly uses the validated body for both CBOR serialization and storage.

graphite-app · 2026-02-16T20:55:02Z

rivetkit-typescript/packages/rivetkit/package.json

 		"@rivetkit/sqlite-vfs": "workspace:*",
 		"@rivetkit/traces": "workspace:*",
 		"@rivetkit/virtual-websocket": "workspace:*",
+		"@standard-schema/spec": "^1.0.0",


This line adds a new dependency '@standard-schema/spec' but the pnpm-lock.yaml file wasn't updated. Run 'pnpm install' locally to update the lockfile and commit both the package.json and the updated pnpm-lock.yaml file together.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-02-16T21:06:49Z

rivetkit-typescript/packages/rivetkit/src/registry/config/index.ts

+import { z } from "zod";
 import { getRunMetadata } from "@/actor/config";
+import type { ActorDefinition, AnyActorDefinition } from "@/actor/definition";


The imports are not properly sorted. The import for ActorDefinition should come before the getRunMetadata import to maintain alphabetical order.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-02-17T20:21:37Z

rivetkit-typescript/packages/rivetkit/src/actor/schema.ts

+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { Unsupported } from "./errors";


Imports should be sorted alphabetically. Move the StandardSchemaV1 import after the Unsupported import.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-02-17T20:21:49Z

rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts

+import type { OtlpExportTraceServiceRequestJson } from "@rivetkit/traces";
 import {
 	createTraces,
 	type SpanHandle,
 	type SpanStatusInput,
 	type Traces,
 } from "@rivetkit/traces";
-import type { OtlpExportTraceServiceRequestJson } from "@rivetkit/traces";
+import invariant from "invariant";


Imports should be sorted alphabetically. The OtlpExportTraceServiceRequestJson import should come after the invariant import, and the ActorTracesDriver import should be moved up with the other imports.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-02-18T22:10:10Z

rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts

+			const client = await this.#config.db.createClient({
+				getDatabase: () => this.driver.getDatabase(this.#actorId),
+			});
+			this.#rLog.info({ msg: "database migration starting" });
+			await this.#config.db.onMigrate?.(client);
+			this.#rLog.info({ msg: "database migration complete" });
+			this.#db = client;


This code is causing the CI to fail because it's calling this.driver.getDatabase(this.#actorId), but the ActorDriver interface doesn't have a getDatabase method defined. The database provider interfaces need to be updated to include this method, or this code needs to be adjusted to use the existing interface methods.

Spotted by Graphite Agent (based on CI logs)

Is this helpful? React 👍 or 👎 to let us know.

graphite-app · 2026-02-19T22:44:01Z

Merge activity

Feb 19, 10:44 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
Feb 19, 10:45 PM UTC: CI is running for this pull request on a draft pull request (#4238) due to your merge queue CI optimization settings.
Feb 19, 10:45 PM UTC: Merged by the Graphite merge queue via draft PR: #4238.

# Description Please include a summary of the changes and the related issue. Please also include relevant motivation and context. ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] This change requires a documentation update ## How Has This Been Tested? Please describe the tests that you ran to verify your changes. ## Checklist: - [ ] My code follows the style guidelines of this project - [ ] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes

railway-app bot temporarily deployed to rivet-frontend / rivet-pr-4209 February 16, 2026 19:50 Destroyed

NathanFlurry marked this pull request as ready for review February 16, 2026 19:54

NathanFlurry force-pushed the feat-add-typed-event-and-queue-schemas-for-actors branch from 8a8c7d9 to 64bb333 Compare February 16, 2026 19:58

railway-app bot temporarily deployed to rivet-frontend / rivet-pr-4209 February 16, 2026 19:58 Destroyed

NathanFlurry changed the title ~~feat(rivetkit): add actor run handler~~ refactor(rivetkit): add typed event and queue schemas for actors Feb 16, 2026

graphite-app bot reviewed Feb 16, 2026

View reviewed changes

NathanFlurry force-pushed the feat-add-typed-event-and-queue-schemas-for-actors branch from 64bb333 to 5511321 Compare February 17, 2026 20:12

railway-app bot temporarily deployed to rivet-frontend / rivet-pr-4209 February 17, 2026 20:12 Destroyed

graphite-app bot reviewed Feb 17, 2026

View reviewed changes

abcxff force-pushed the feat-add-typed-event-and-queue-schemas-for-actors branch from 5511321 to 87740eb Compare February 18, 2026 15:47

railway-app bot temporarily deployed to rivet-frontend / rivet-pr-4209 February 18, 2026 15:47 Destroyed

abcxff mentioned this pull request Feb 18, 2026

chore: pkg pr new bump #4224

Closed

11 tasks

NathanFlurry force-pushed the feat-add-typed-event-and-queue-schemas-for-actors branch from 87740eb to fb17656 Compare February 18, 2026 22:06

railway-app bot temporarily deployed to rivet-frontend / rivet-pr-4209 February 18, 2026 22:06 Destroyed

graphite-app bot reviewed Feb 18, 2026

View reviewed changes

NathanFlurry changed the base branch from main to graphite-base/4209 February 19, 2026 19:40

NathanFlurry force-pushed the feat-add-typed-event-and-queue-schemas-for-actors branch from fb17656 to 8da1c60 Compare February 19, 2026 19:40

railway-app bot temporarily deployed to rivet-frontend / rivet-pr-4209 February 19, 2026 19:40 Destroyed

NathanFlurry changed the base branch from graphite-base/4209 to 02-17-feat_configure_rivetkit_storage_path February 19, 2026 19:41

This was referenced Feb 19, 2026

chore(rivetkit): migrate file system driver to sqlite #4206

Closed

feat: configure rivetkit storage path #4233

Closed

refactor: simplify actor queue to single queue

a1f946a

NathanFlurry force-pushed the feat-add-typed-event-and-queue-schemas-for-actors branch from 8da1c60 to a1f946a Compare February 19, 2026 19:54

NathanFlurry force-pushed the 02-17-feat_configure_rivetkit_storage_path branch from 49bf396 to 35e2bc0 Compare February 19, 2026 19:54

railway-app bot temporarily deployed to rivet-frontend / rivet-pr-4209 February 19, 2026 19:54 Destroyed

NathanFlurry changed the base branch from 02-17-feat_configure_rivetkit_storage_path to graphite-base/4209 February 19, 2026 22:11

NathanFlurry mentioned this pull request Feb 19, 2026

feat(rivetkit): canInvoke #4237

Closed

11 tasks

NathanFlurry changed the base branch from graphite-base/4209 to 02-17-feat_configure_rivetkit_storage_path February 19, 2026 22:40

graphite-app bot closed this Feb 19, 2026

graphite-app bot deleted the feat-add-typed-event-and-queue-schemas-for-actors branch February 19, 2026 22:45

NathanFlurry mentioned this pull request Feb 19, 2026

fix(rivetkit): fix run workflow teardown #4239

Closed

11 tasks

claude bot mentioned this pull request Feb 19, 2026

[Graphite MQ] Draft PR GROUP:spec_875ba8 (PRs 4206, 4233, 4209, 4229, 4230, 4231) #4238

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(rivetkit): add typed event and queue schemas for actors#4209

refactor(rivetkit): add typed event and queue schemas for actors#4209
NathanFlurry wants to merge 1 commit into02-17-feat_configure_rivetkit_storage_pathfrom
feat-add-typed-event-and-queue-schemas-for-actors

NathanFlurry commented Feb 16, 2026

Uh oh!

railway-app bot commented Feb 16, 2026 •

edited

Loading

Uh oh!

NathanFlurry commented Feb 16, 2026 •

edited

Loading

Uh oh!

claude bot commented Feb 16, 2026 •

edited

Loading

Uh oh!

graphite-app bot Feb 16, 2026

Uh oh!

graphite-app bot Feb 16, 2026

Uh oh!

graphite-app bot Feb 17, 2026

Uh oh!

graphite-app bot Feb 17, 2026

Uh oh!

graphite-app bot Feb 18, 2026

Uh oh!

graphite-app bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		import type { StandardSchemaV1 } from "@standard-schema/spec";
		import { Unsupported } from "./errors";

Conversation

NathanFlurry commented Feb 16, 2026

Description

Type of change

How Has This Been Tested?

Checklist:

Uh oh!

railway-app bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NathanFlurry commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

claude bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: refactor(rivetkit): add typed event and queue schemas for actors

Bugs

Breaking Changes Not Documented

Design Concerns

Minor Notes

What Is Good

Uh oh!

graphite-app bot Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

railway-app bot commented Feb 16, 2026 •

edited

Loading

NathanFlurry commented Feb 16, 2026 •

edited

Loading

claude bot commented Feb 16, 2026 •

edited

Loading

graphite-app bot commented Feb 19, 2026 •

edited

Loading