fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars

[NathanFlurry]

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

[NathanFlurry]

• fix(pegboard): move sqlite v1 migration into actor workflow #4787 : 2 dependent PRs (#4797 , #4810 )
• test(rivetkit): cover c.db access from onWake/onSleep/onDestroy #4786
• fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars #4785 👈 (View in Graphite)
• refactor(rivetkit-core): merge ready+started into lifecycle_started, drop redundant napi calls #4784
• fix(rivetkit): drain native sleep side tasks reliably #4782 : 1 other dependent PR (#4783 )
• fix(rivetkit): route raw request fetches to actors #4781
• fix(pegboard): refresh runner config after envoy connect #4778 : 2 other dependent PRs (#4779 , #4798 )
• chore(kitchen-sink): configurable endpoint #4766 : 2 other dependent PRs (#4754 , #4777 )
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765
• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

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

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4785

All packages published as 0.0.0-pr.4785.3960118 with tag pr-4785.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-3960118
docker pull rivetdev/engine:full-3960118

Individual packages

npm install rivetkit@pr-4785
npm install @rivetkit/react@pr-4785
npm install @rivetkit/rivetkit-napi@pr-4785
npm install @rivetkit/workflow-engine@pr-4785

[claude]

PR Review: fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars

Summary

This PR fixes a lifecycle ordering bug in the NAPI receive-loop preamble (run_preamble). Previously, onMigrate ran after createState, onCreate, and createVars, meaning any DB schema set up by onMigrate was unavailable in those earlier hooks. The fix moves the onMigrate call to run first, aligning the NAPI preamble with the TypeScript actor instance in mod.ts where #setupDatabase (including migration) runs before all user-facing lifecycle hooks.

Corrected preamble order:

1. onMigrate
2. createState / onCreate (new actors) OR state + connection restore (existing actors)
3. createVars
4. onWake
5. onBeforeActorStart

---

Code Quality

The fix is minimal and surgical — a pure code movement with no logic changes. The comment added in the Rust file (// Run database migrations before any user lifecycle hook so c.db is usable from createState, onCreate, and createVars) correctly explains the why and follows CLAUDE.md style (complete sentence, lowercase unless mentioning code symbols).

All CLAUDE.md conventions are followed:

• Conventional commit format ✓
• No _ => fall-through arms ✓
• No vi.mock or module-level mocking ✓
• Comment style: complete sentences ✓

---

Potential Issues

Minor gap — wake path not tested. onMigrate now correctly runs before onWake and createVars\ on actor restart after sleep, but the test suite only exercises the new-actor path. The fix does apply to the wake path (since run_preamble is called on every startup, new or woken), but a sleep/wake test would give stronger confidence. Not a blocker.

Type assertions in fixtures. The fixture actors use as { ... } casts for c.state and c.vars. This is consistent with the existing fixture pattern and acceptable for test code.

---

Performance

No new per-request work. The migration callback runs once during actor startup (preamble), as before. The with_timeout("onMigrate", config.on_migrate_timeout, ...) wrapping is preserved unchanged.

---

Security

No trust boundary changes. This is a pure internal lifecycle ordering fix.

---

Test Coverage

The three new driver tests are well-structured:

• One test per affected hook (createState, onCreate, createVars)
• crypto.randomUUID() keys prevent cross-test contamination
• CREATE TABLE IF NOT EXISTS makes the migration idempotent
• Positive assertion: querying the table returns 0 (exists, no rows) vs -1 (table missing / query failed)
• dbTestTimeout: 180_000 is consistent with other DB fixtures

Minor gap: no test covers the wake path (verifying onMigrate runs before createVars/onWake after sleep). The fix does apply there, but a follow-up test would strengthen confidence.

---

Verdict

Correct, well-tested, minimal fix. Approve with the optional suggestion to add a wake-path test as a follow-up.