version: "1.0.0" name: ydb-actor-development description: "Implement, debug, or review NActors event protocols, actor lifetime, coroutine handlers, and shutdown, including actor-based tablets. Use when these mechanisms are involved; ordinary business logic in an actor does not require this skill."

Actor Development

Use the actor system guide for runtime contracts. Tablets also have component-specific transaction and recovery rules; inspect the existing tablet fixture and neighboring code.

Select Context

Read the guide's invariants, then only the topic pages needed for the change:

• Construction, registration, dispatch, pool choice: lifecycle.
• Payloads, ownership, cookies, forwarding, timers, Interconnect: messaging.
• Death, cancellation, RAII, and forced teardown: shutdown.
• Stackless handlers: coroutines; load primitives for the relevant wait/combinator and integration for foreign threads or custom awaiters.
• Fixtures and behavioral coverage: testing.

Apply the Contract

Trace the changed event from sender through the handler to its reply and cleanup. For each event, buffer, coroutine frame, child actor, and subscription, identify its owner at each step and the code that releases or ends it. Treat every suspension as a point at which actor state can change. Distinguish a delivery notification from application completion.

For lifetime changes, account for late events while cancellation is pending and for cleanup during forced teardown. For a tablet, identify which state is durable and which state must be reconstructed after restart; actor serialization does not itself provide persistence.

Select tests from the affected component. Add runtime tests when changing runtime guarantees, and component tests when changing a component protocol. Follow active build instructions for the target.

Documentation Updates

Read linked documentation as context. During code changes, update documentation only when the change alters a documented contract or makes an existing statement inaccurate, or when the user explicitly requests documentation work. For contributor pages under ydb/docs/en/ or ydb/docs/ru/, update the corresponding path in the other language in the same change.

Delegate needed documentation updates to a subagent with forked conversation context (fork_turns: "all" when supported). Give it the affected paths, the final behavior change, and relevant validation results; scope its edits to documentation. Review its changes for accuracy and English/Russian consistency before completing the task.