feat: import/export actors

[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

[railway-app]

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

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Apr 23, 2026 at 12:02 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Apr 22, 2026 at 9:14 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Apr 22, 2026 at 9:13 am
kitchen-sink	❌ Build Failed (View Logs)	Web	Apr 22, 2026 at 9:12 am
ladle	❌ Build Failed (View Logs)	Web	Apr 13, 2026 at 8:26 am
mcp-hub	✅ Success (View Logs)	Web	Apr 13, 2026 at 5:55 am

[NathanFlurry]

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

• chore: rivetkit core/napi/typescript follow up review #4702
• chore: fix remaining issues with rivetkit-core #4701
• feat: import/export actors #4640 👈 (View in Graphite)
• chore: sqlite v1 to v2 data migration #4692
• chore: move rivetkit to task model #4680
• chore: rivetkit to rust #4679
• feat(rivetkit): sqlite vfs v2 #4673
• chore: rename sandbox -> kitchen sink #4671 : 1 other dependent PR (#4672 )
• chore: configure TLS trust roots for rustls clients #4667
• fix(rivetkit): update config to match envoys & remove manager references #4663
• chore(publish): pin docker base image refs #4652
• chore(engine): publish engine bases in ci #4649 : 2 other dependent PRs (#4650 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

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

[claude]

PR Review: feat: import/export actors

This is a well-structured feature with clear design intent. Here are my observations:

Correctness & Logic

Inconsistent actor existence check for keyless actors (potential slow path)
In import_export.rs, actor_exists_with_name_and_key has an asymmetry: when key is None, it paginates through all actors with that name checking for a null key. This is an O(N) scan and could be slow for namespaces with many same-named keyless actors. Worth documenting or bounding.

Test ID deduplication may pass for wrong reason
In actor_import_export_e2e.rs, the selector_accepts_actor_ids test creates two Id::new_v1(1) values and asserts ids.len() == 2. If new_v1 is time-based, the two calls produce different IDs, so the deduplication assertion in parse_selector never actually fires. The test should use explicitly identical IDs to prove deduplication works.

Architecture & Design

No actor quiescence before export
There is an explicit TODO noting that live actor KV state can change mid-export. A running actor during export will produce an inconsistent snapshot. This should be called out in docs or surfaced as a warning in the export response.

No archive cleanup / TTL
The archive_path is a server-local temp directory with no automatic garbage collection. If the caller fails to clean it up, temp directories accumulate permanently. Consider a background sweep or at minimum document the caller responsibility.

Import archive path is server-local
ImportRequest.archive_path is a raw filesystem path. This is fine for single-node operational use but should be documented as a constraint for multi-node deployments.

Code Quality

Duplicate default_true function
default_true() -> bool { true } is defined independently in both workflows/actor/mod.rs and workflows/actor2/mod.rs. Extract to a shared location or use serde_with.

CreateComplete reordering in actor2/mod.rs
CreateComplete is now sent before reschedule_actor is called (moved out of the from_v1 branch). If this is intentional for the start_immediately=false path, add a comment explaining the intent, as it changes observable behavior for existing subscribers.

Auth on admin endpoints
export and import use ctx.auth().await?, the same check as normal endpoints. Given they are described as dangerous operational tools, confirm whether a more privileged admin check is needed.

Documentation

The documentation checklist is unchecked. The new POST /admin/actors/export and POST /admin/actors/import endpoints and the start_immediately/create_ts create fields warrant documentation. Per CLAUDE.md, limit-relevant fields should also update website/src/content/docs/actors/limits.mdx.

Minor

• Archive format is versioned (version: 1) which is good for future migration.
• Atomic rename of the .tmp directory before returning the path is a solid choice.
• The 64-entry KV batch size is reasonable; consider a named constant instead of a magic number.

Overall this is a solid operational tool. The main concerns are the lack of consistency guarantees during live export and the missing documentation.