yield-injections

Inject synthetic yields and failures into Turso resumable state machines for deterministic concurrency testing.

24.1k|1.3k|Updated Aug 26, 2023
One-click install
npx skills add https://github.com/tursodatabase/turso --skill yield-injections
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: yield-injections
Source: https://github.com/tursodatabase/turso/tree/main/.claude/skills/yield-injections
Command: npx skills add https://github.com/tursodatabase/turso --skill yield-injections

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Testing resumable state machines in Turso (commits, checkpoints, cursors) against rare interleavings and abandonment scenarios is hard to reproduce; this Skill explains how to use the yield and failure injection machinery to force cooperative-yield boundaries deterministically in tests.

Core Features & Use Cases

  • Yield and Failure Injection: Use inject_transition_yield!, inject_io_yield!, and inject_transition_failure! macros with YieldPointMarker enums to force StepResult::Yield or LimboError at exact state-machine boundaries.
  • Fixed Test Injectors: Configure FixedYieldInjector and FixedFailureInjector on a connection to target specific points like commit LogRecordPrepared or checkpoint BeforeAcquireLock in unit tests.
  • Deterministic Simulator Plans: Understand how the concurrent simulator plans yields keyed by (instance_id, selection_key, point_count) so seeds remain reproducible.
  • Use Case: When adding a new yield point to the commit state machine, follow the checklist to append the enum variant without reordering, place the macro after the resumable state transition, and add an abandoned-statement test verifying cleanup invariants.

Quick Start

Ask the assistant to add a new yield point to the commit state machine with a deterministic fixed-injector regression test following the yield injection guide.

Frequently Asked Questions about yield-injections

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new yield point to a Turso state machine?

Append a variant to the appropriate YieldPoint enum without reordering existing variants, place the inject_transition_yield! macro after the transition that makes resume safe, and add a deterministic test with FixedYieldInjector. Reordering changes ordinals and breaks simulator seed reproducibility.

How do I test failure injection in Turso commit state machines?

Use FixedFailureInjector mapped to a CommitYieldPoint such as AfterRemoveTx, then verify transaction maps, connection slots, locks, and exclusive transaction atomics are not stranded. Failure injection only works for TransitionResult state machines; there is no inject_io_failure! macro.

Why does reordering YieldPointMarker enum variants break tests?

The ordinal is computed as self as u8 from source order, and simulator plans store raw ordinals rather than names. Reordering silently retargets existing seeds to different hooks, making CI seeds, bisects, and simulator coverage non-reproducible.

Can I use FixedYieldInjector in the concurrent simulator?

No, the concurrent simulator owns randomized deterministic injection through SimulatorYieldInjector keyed by instance_id, selection_key, and point_count. Fixed injectors are intended only for targeted unit tests on a connection.

What must be true before placing a yield hook in a state machine?

Re-entry must be safe: mutate the state machine into the resumable state before yielding, and avoid hooks before non-idempotent actions like pushes, counter increments, or lock acquisitions unless guarded. Dropping the statement at the yield must restore invariants through Drop or abort cleanup.