# Gate 1 Concurrency + Postgres Dependency Notes

## 1) Concurrency mechanics (implemented semantic)

- Semantic: **at-least-once delivery + idempotent dedup**
- Not claiming exactly-once.
- Idempotency key is required for all mutating endpoints.

### Projection concurrency choice

- Primary model: **single-writer projection consumer per tenant partition**.
- Hot-tenant strategy: sub-partition by `tenant_id + client_id hash` for whale tenants.
- Lost-update prevention:
  - append-only event store as source of truth
  - projection consumer processes ordered event stream
  - projection replay is deterministic

### Leader election technology

- Recommended in production:
  - Postgres advisory lock per partition (`pg_try_advisory_lock`) OR
  - queue-group consumer election (Kafka consumer group / managed equivalent)
- Gate 1 current implementation in this repo is API-level idempotent and append-only compatible, ready for external partition consumer orchestration.

## 2) Postgres dependencies (before migrations)

### Target version

- PostgreSQL 15+ (preferred 16 for partition and planner improvements)

### Required extensions

- `pgcrypto` (hash helpers / UUID if desired)
- `btree_gin` (optional, for mixed JSONB index workloads)
- `pg_stat_statements` (operational tuning)

### DBA / platform checks (must confirm upfront)

- Partition management strategy approval (monthly partitions + retention jobs)
- Advisory lock policy approved (if using DB-led election)
- RLS policies enabled cluster-wide
- WAL / IOPS sizing for append-heavy event ingestion
- Storage tiering path available (hot/warm/cold)

### Potential Supabase plan blockers

- High write throughput at burst (`10k/s`) may exceed lower tiers.
- Extended log retention and high cardinality metrics may require upgraded compute/storage add-ons.
- Confirm extension availability and RLS policy scale testing before production cutover.

## 3) Projection lag SLO for Gate 1 verification harness

- Normal sustained load target: **<= 5 seconds projection lag**
- Burst recovery target: **<= 30 seconds lag during/after burst**

Gate 1 verification must include tests asserting these bounds under:

- sustained `1000 debits/s`
- burst `10000 debits/s`