Versioning & CAS

Version Chains

Every update creates a new immutable version. Versions are linked through prev CID references:

v3 (tip) → v2 → v1 → null

Each version is stored in KV by its content hash (CID). The tip pointer in a Durable Object always points to the latest version.

Compare-And-Swap (CAS)

CAS prevents lost updates. Every update request must include expected_cid -- the CID you believe is the current tip.

Success flow:

1. Read entity: { cid: "abc", ver: 2, ... }
2. Update with expected_cid: "abc" -- succeeds, creates version 3

Conflict flow:

1. Read entity: { cid: "abc", ver: 2, ... }
2. Someone else updates: tip changes to "def"
3. Your update with expected_cid: "abc" -- fails with 409
4. Re-read, reapply changes, retry with expected_cid: "def"

IPLD-Style Links

Version links use the IPLD convention:

{
  "prev": { "/": "bafyreig..." }
}

This provides compatibility with content-addressed systems while storage is on Cloudflare infrastructure.

Traversing History

GET /entities/:id/versions

Returns all versions in reverse chronological order, following the prev chain.