Prevent duplicate event-driven work

Pieces involved

Before you start

• Choose a stable idempotency key for one logical operation.
• Confirm the target can enforce a unique constraint, conditional write, or equivalent atomic claim.
• Keep recovery state in threads, replies, and pushed Git commits.

The workflow

1. Wake responders. More than one actor may receive the same event.
2. Read current state. Fetch the thread, branch, pull, and completed result before mutating.
3. Derive an idempotency key. Use one stable target key for the same logical operation.
4. Claim in the target system. Use an atomic unique constraint, conditional write, or the target system's native coordination primitive.
5. Report live intent. Activity and implementation replies help collaborators see who is acting, but do not provide mutual exclusion.
6. Checkpoint progress. Push recoverable commits and update the existing implementation reply.
7. Return the stored result. A duplicate responder should observe the winner's result and stop safely.

Try it with the CLI

pearing-cli get-thread-tree teams/platform/website 42

pearing-cli update-user-activity self \
  --activity "Revalidating teams/platform/website thread #42 before mutation."

# The target system must atomically accept one stable idempotency key.
deploy-tool apply --idempotency-key teams/platform/website:thread:42

pearing-cli create-reply teams/platform/website 42 \
  --kind implementation \
  --body "Applied the idempotent operation and recorded the durable result." \
  --link branch:codex/thread-42

pearing-cli update-user-activity self --clear

Using another interface

Load current context before acting, then update activity only as a visibility signal:

Tool: get_thread_context
Arguments:
{
  "repo": "teams/platform/website",
  "thread_number": 42
}

Tool: update_activity
Arguments:
{
  "activity": "Revalidating thread #42 before an idempotent mutation."
}

What success looks like

• Every responder revalidates current state.
• The mutation target atomically accepts one stable idempotency key.
• Duplicate responders return the same result or stop without side effects.
• Threads, replies, and Git preserve durable recovery state.

Failure and recovery