alpaca-broker-reconciliation-idempotency
Keep local state correct against the Alpaca Broker API — idempotency keys, ID-keyed upserts, event snapshotting and dedup, polling rails that have no events, nightly reconciliation/heal jobs, status state-machine mapping, and handling eventual consistency and corrections. Use when designing the data-correctness layer of any Alpaca integration in any language.
npx skills add alpacahq/alpaca-skills --skill reconciliation-idempotency --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Alpaca — Reconciliation & Idempotency This is the skill that separates a demo from production. Alpaca is an **asynchronous, eventually-consistent** system: writes settle later, events can be missed or replayed, some rails emit no events at all, and "executed" can still be reversed. Your job is to make your local database a faithful, self-healing mirror of Alpaca's state. > Read `alpaca-broker-integration`, `alpaca-broker-sse-events`, and the relevant domain skills first. This skill is the architecture that ties them together. ## The core principle > **Treat Alpaca as the source of truth and your DB as a cache that must converge to it.** Every write is a request, not a fact. Every event is a hint, not a guarantee. Correctness comes from *idempotent* processing plus a *reconciliation* loop — never from assuming any single call or event succeeded exactly once. ## 1. Three layers of defense ``` Layer 1 — Idempotent writes : never create a duplicate when you retry Layer 2 — Idempotent event intake: never double-process a replayed/duplicate event Layer 3 — Reconciliation sweep : re-pull authoritative state and fix any drift ``` You need all three. Layer 1+2 keep you correct in the happ
- The core principle
- 1. Three layers of defense
- 2. Layer 1 — Idempotent writes
- 3. Layer 2 — Idempotent event intake
- 4. Layer 3 — Reconciliation / heal jobs
- 5. Polling the rails that have no events
- 6. Status state-machine mapping
- 7. Eventual-consistency hazards to design for
- 8. Anti-patterns (seen in the wild)
- 9. Putting it together
What does the alpaca-broker-reconciliation-idempotency skill do?
Keep local state correct against the Alpaca Broker API — idempotency keys, ID-keyed upserts, event snapshotting and dedup, polling rails that have no events, nightly reconciliation/heal jobs, status state-machine mapping, and handling eventual consistency and corrections. Use when designing the data-correctness layer of any Alpaca integration in any language.
How do I install it?
Run `npx skills add alpacahq/alpaca-skills --skill reconciliation-idempotency --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From alpacahq/alpaca-skills, a repository with 106 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.