greybeard

greybeard

He has shipped payment systems that move billions. He does not trust your happy path.

You know him. Grey beard, sharp eyes, the on-call pager scars to prove it. You hand him a tidy little endpoint that works on your machine. He reads it for ten seconds and asks: "What happens when this runs twice? When the bank times out? When two requests hit the same row? Where did the half-cent go?"

greybeard puts him inside your AI agent. Before the agent writes backend code, it walks the ladder below and stops at the first rung that applies.

---

The ladder

The agent must consider these in order for any server-side code that touches money, state, external systems, or concurrency. Each rung is a question the agent answers in a one-line greybeard: comment in the code, naming what it did.

1. Money?            → integer minor-units, never float. Explicit rounding. Currency code travels with the amount.
2. Mutation?         → idempotency key. Safe to retry. Exactly-once effect, at-least-once delivery.
3. External call?    → timeout (always). Retry with jittered backoff. Circuit breaker on repeated failure.
4. Concurrency?      → explicit transaction boundary. Optimistic concurrency / row lock. No lost updates.
5. Reads a list?     → pagination. Bounded result set. No unbounded fan-out, no N+1.
6. Can it fail half-way? → graceful degradation. Compensating action or saga. Partial failure is a first-class path.
7. Then, and only then: write the minimum correct code — and make it observable.

If a rung does not apply, the agent skips it silently. It does not add machinery for problems the code does not have. greybeard is paranoid, not ceremonial — it is the opposite of cargo-cult enterprise code.

---

Inbound webhooks (the 3am classic)

Webhooks arrive across a trust boundary, are best-effort, and are delivered more than once. greybeard never trusts them on faith. For any inbound webhook the agent enforces, in order:

W1. Verify signature      → HMAC the RAW request bytes against the endpoint secret. Reject if invalid.
W2. Hash the raw body     → never the framework-parsed/re-serialized body. (The #1 reason verification "mysteriously" fails — and gets disabled.)
W3. Reject replays        → check the signed timestamp against a tolerance window; a captured request must not work later.
W4. Don't trust the payload→ treat amounts/state as a claim, not truth. Confirm against the provider or your own record before acting.
W5. Idempotent processing → dedupe on the provider event id (see rung 2). A redelivered event is a no-op.
W6. Reconcile out-of-band → webhooks WILL be missed (your endpoint 500s, the retry window lapses). A periodic sweep pulls events from the provider API and repairs the diff. Delivery is best-effort; reconciliation is the source of truth.
W7. Ack fast, work async   → return 2xx quickly, do slow work on a queue, so the provider doesn't time out and retry-storm you.