Ingestion Protocol & CAS Concurrency

Machine agents (GrokBot and Mango) sync mutations from Notion into Cloudflare D1 via:

POST /v1/finances/changes

(Also available via the alias /v1/finanzas/cambios)

Payload Specification

Each payload contains a batch of up to 50 operations wrapped in an atomic envelope.

{
  "schema_version": 1,
  "request_id": "req-2026-11-10-001",
  "atomic": true,
  "events": [
    {
      "event_id": "evt-001",
      "entity_type": "movement",
      "entity_id": "mov-coto-101",
      "revision": 1,
      "operation": "upsert",
      "payload": {
        "kind": "expense",
        "status": "confirmed",
        "description": "Coto Supermercado",
        "occurred_on": "2026-11-10",
        "amount_minor": 4500000,
        "currency": "ARS",
        "category_id": "cat-super",
        "from_account_id": "acc-bbva-ars",
        "source_refs": [
          { "type": "notion", "ref": "page_notion_49182", "role": "capture" }
        ]
      }
    }
  ]
}

Durable Receipt Response

{
  "request_id": "req-2026-11-10-001",
  "committed": true,
  "processed_count": 1,
  "results": [
    {
      "event_id": "evt-001",
      "entity_type": "movement",
      "entity_id": "mov-coto-101",
      "status": "applied",
      "current_revision": 1
    }
  ]
}

CAS Concurrency & Idempotency Rules

1. Exact Idempotency Replay: Submitting an identical request_id with matching body hash returns the durable receipt directly with HTTP 200 without executing duplicate writes.
2. Request ID Collision: Submitting an identical request_id with altered content returns 409 Conflict.
3. Optimistic Locking (CAS):
   • If an entity exists at revision = N:
     • Ingesting revision < N returns status stale_rejected.
     • Ingesting revision = N with identical payload hash returns status duplicate.
     • Ingesting revision = N with altered content throws 409 Conflict.
     • Ingesting revision > N applies the update and updates the revision counter.
4. All-or-Nothing Batch Atomicity: If any single item in an atomic batch fails schema validation or database constraints, all operations within that batch are reverted without partial commits.