Rule engine

The rule engine is the heart of Hatched. Every event you send goes through the same pipeline; every effect the buddy accumulates is the output of that pipeline.

The two-phase contract

1. Compute phase — read-only. Given the current buddy state and the incoming event, the engine computes what would change: coin increments, skill increments, badges newly eligible, token deltas, streak ticks.
2. Apply phase — transactional. Opens a single database transaction, takes a pessimistic_write lock on the buddy row, writes every computed effect, commits atomically. If any step throws, everything rolls back.
3. Post-transaction — non-atomic side effects: progression counters, evolution readiness check, webhook emission.

Why this split

Two properties fall out of the contract:

• Idempotency — the same event_id produces exactly one effect even if retried.
• Race-freedom — concurrent events for the same buddy serialise on the row lock, so two overlapping lessons don't both award the same badge.

Two ingestion paths — by design

• POST /events — standard ingestion. The rule engine owns the decision.
• POST /buddies/{buddy_id}/coins, POST /buddies/{buddy_id}/coins/spend, POST /buddies/{buddy_id}/tokens, PATCH /buddies/{id}/skills, POST /buddies/{buddy_id}/badges (badge to award is badge_key in the body) — administrative override. Every write still funnels through the same transactional services, so ledger invariants are preserved.

This is intentional. Don't try to collapse them into a single endpoint.

Unknown events

Events not declared on the customer's config version:

• Every event type — declared or not — is recorded in buddy_progression_metrics.custom_counters via a jsonb_set update, keyed by the event's own name. There are no reserved event names and no hardcoded counter columns. Downstream handlers still evaluate, and an undeclared type also emits a warning log. Never dropped.

Observability

Every event carries a requestId that follows it through the rule engine, into effect ledger entries, and out into webhooks. Keep the requestId from API responses and webhook payloads when contacting support; Hatched uses that value to trace a specific event through retries, ledgers, and webhook delivery without asking you to expose secret keys or raw database state.

Related

• Config versions — the immutable rulebook the engine loads per buddy.
• Coins, Skills, Badges — the effects the engine produces.
• Send events — what to send, with stable eventIds.