Write Batch

Batch write up to 100 memory atoms.

Idempotency

Supports the Stripe-style Idempotency-Key header. Clients that retry the same logical write after a network failure (including the 2026-04-13 Cloudflare 524 / ghost-write scenario) can pass the same key and get back the exact response the server cached on the first successful processing, rather than double-writing atoms. The cache TTL is 24 hours (see migrations/versions/004_idempotency.py).

The key is scoped per operation and per organization by _scoped_idempotency_key so two tenants cannot collide on the same raw UUID. The org fragment is a SHA-256 hash prefix, not the raw org_id, to make the key delimiter-safe regardless of what characters the upstream auth layer produces.

⚠️ Sequential retries only

This implementation protects sequential retries (client waits for the first request to return or time out, then retries with the same key). Concurrent retries are NOT serialized: if two retries of the same key land while the first processing is still in flight, both will observe a cache miss and both will call engine.write(). In practice MCP clients retry with exponential backoff so this race is rare, but if the dashboards surface it as a real signal we will add a processing-sentinel row inserted with ON CONFLICT DO NOTHING at the top of the handler (tracked as Step 2c.1 in the observability sprint plan). Documented so a future reader does not assume the current code is fully race-safe.

Failure modes

• Missing or empty header → no caching, behaves as before.
• Header > 240 chars → 400 VALIDATION_ERROR (table column is 255).
• Cache lookup DB error → falls through to normal processing (we prefer a duplicate write over a hard failure on the retry path).
• Cache store DB error → the response is still returned to the client; we log the cache failure and move on so the successful write is not lost.