OpenParable
Skip to content
← Back to skills

Async State Safety

Development
async-state-safety

Async State Safety is an Agent Skill for development published in the spacedriveapp/spacebot repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

This skill should be used when the user asks to change "worker lifecycle", "cancellation", "retrigger behavior", "state machine", "delivery receipts", "timeouts", or "race conditions". Enforces explicit async/state invariants and targeted race-safe verification.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/spacedriveapp/spacebot/blob/HEAD/.agents/skills/async-state-safety/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/async-state-safety, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Async State Safety

Goal

Prevent race regressions in async and stateful paths.

Required Invariants

  • Define valid terminal states before coding.
  • Define allowed state transitions before coding.
  • Keep terminal transitions idempotent.
  • Ensure duplicate events cannot double-apply terminal effects.
  • Ensure retries do not corrupt state.

Race Checklist

  • Cancellation racing completion
  • Timeout racing completion
  • Retry racing ack/receipt update
  • Concurrent updates to the same worker/channel record
  • Missing-handle and stale-handle behavior

Implementation Checklist

  • Add or update transition guards.
  • Keep error handling explicit and structured.
  • Preserve status/event emission on all terminal branches.
  • Document why each race path converges safely.

Verification Checklist

  • Run targeted tests for each touched race path.
  • Add at least one negative-path test for terminal convergence.
  • Add at least one idempotency test where applicable.
  • Run broad gate checks after targeted checks pass.

Handoff Requirements

  • Terminal states and transition matrix
  • Race windows analyzed
  • Targeted commands and outcomes
  • Residual risks and follow-up tests