fix(rivetkit): defer initialized persist until state exists

[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]

• refactor(depot-client): split embedded depot transport #4970 : 2 dependent PRs (#4971 , #4972 )
• fix(rivetkit): decode legacy v4 actor schedule args #4976
• fix(engine): install rustls provider with pools #4975
• fix(rivetkit): defer initialized persist until state exists #4974 👈 (View in Graphite)
• test(rivetkit): cover failed preflight disconnect handling #4973
• fix(rivetkit): hide pending connections during preflight #4969
• WIP: more fuzz tests #4962
• fix(rivetkit): wrap onMigrate in savepoints #4960 : 1 other dependent PR (#4963 )
• fix(pegboard): align drain grace defaults with stop threshold #4958 : 1 other dependent PR (#4966 )
• fix(rivetkit): preserve bridge error messages #4959
• fix(rivetkit): fire abort signal on shutdown finalize #4957
• fix(rivetkit): use startup kv preload #4956
• fix(client): flatten skipReadyWait option #4955
• ci(publish): add manual preview publish flow #4954
• fix(depot): add ltx decode diagnostics #4953
• fix(universaldb): preserve plain set values #4952
• fix(universaldb): align versionstamp operand encoding #4951
• fix(rivetkit): export database provider types #4950
• wip: kitchen sink agentic loop finish #4949
• chore(rivetkit): note duplicate admission logic #4948
• test(rivetkit): cover bypass fetch header forwarding #4947
• feat(kitchen-sink): add actor probe controls #4946
• fix(gateway): split actor response wait errors #4945
• fix(guard): handle bypass preflight before query parse #4944
• feat(kitchen-sink): add mock agent event log copy #4943
• fix(kitchen-sink): default mock agent to local endpoint #4942
• test(rivetkit): enable driver lifecycle regressions #4941
• test(rivetkit): verify cached websocket db refs exceed grace #4940
• fix(rivetkit-core): keep sleeping actors reachable during grace #4939
• test(rivetkit): cover async websocket close db access #4938
• fix(rivetkit): keep actors awake until keepAwake work finishes #4937
• fix(rivetkit): persist native onSleep state on errors #4936
• fix(rivetkit-core): allow dispatch during sleep grace #4935
• fix(rivetkit): make duplicate sleep requests idempotent #4934
• main

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

[claude]

Code Review

Overview

This PR fixes a race condition where has_initialized was being persisted before a new actor's state was ready, specifically when the factory uses requires_manual_startup_ready(). The fix defers the initialization persist until after spawn_run_handle completes for new actors that gate on startup_ready. A companion change in the NAPI layer normalizes empty-byte snapshots to None for stateful actors (those with a create_state callback), treating them as new.

---

Issues

_ => fall-through in test enum match (tests/task.rs)

The test callback's event loop uses a wildcard arm:

_ => {}

Per CLAUDE.md conventions, _ => fall-throughs on Rust enums are prohibited so that adding a new variant forces a compile error. Either enumerate every ActorEvent variant explicitly, or use _ => unreachable!() if unhandled events are genuinely impossible in the test scenario.

---

Redundant PERSIST_DATA_KEY redefinition (rivetkit-napi/tests/napi_actor_events.rs)

const PERSIST_DATA_KEY: &[u8] = &[1];

This replaces an import that was removed. If the real key ever changes, this local copy will silently diverge and tests will pass against a stale key. Either keep the import from rivetkit_core::actor::state (even if it requires a pub(crate) visibility bump), or add a comment explaining why re-definition is intentional.

---

Suggestions

Missing comment on the deferred-init condition (task.rs, line ~1208)

if !is_new || !self.factory.requires_manual_startup_ready() {

The invariant — that initialization must not be persisted until the runtime's startup_ready handshake completes — is non-obvious. Per CLAUDE.md, this is exactly the case that warrants a short explanatory comment.

---

Consider documenting the fallback path after spawn_run_handle

if !self.ctx.persisted_actor().has_initialized {
    self.ctx.set_has_initialized(true);
}

The guard exists to avoid double-setting when the runtime callback already called set_has_initialized(true). A brief comment documenting this as the guaranteed fallback (not the expected path) would help future readers understand why the condition exists rather than an unconditional set.

---

normalize_startup_snapshot lacks a WHY comment

The logic of treating empty bytes as None only when has_create_state is true is subtle. An empty-bytes snapshot is not an obvious sentinel value. A one-line comment explaining the invariant (e.g. "an empty snapshot produced before create_state runs indicates the actor was interrupted mid-initialization") would satisfy the CLAUDE.md standard for non-obvious behavior.

---

Positives

• The test manual_startup_does_not_mark_initialized_before_runtime_preamble is well-structured and directly exercises the observable invariant (runtime sees has_initialized == false, then task persists it after startup_ready).
• startup_snapshot_recovery_only_treats_empty_stateful_snapshot_as_new covers all four cases cleanly as a pure unit test.
• Using oneshot::channel to observe the in-callback state is the right approach — no polling, deterministic ordering.