Interface AdcpStateStore

Get a document by collection and id. Returns null if not found.

Create or replace a document (upsert semantics).

Merge fields into an existing document. Creates the document if it doesn't exist. Only top-level fields are merged — nested objects are replaced, not deep-merged.

Delete a document. Returns true if it existed.

List documents in a collection with optional filtering and pagination.

Convenience method for built-in stores: returns a session-scoped view. Optional on the interface so custom AdcpStateStore implementations aren't forced to implement it — callers who need the wrapper on any store should use scopedStore instead, which handles the fallback.

Read a document with its current row version. Returns null if the row doesn't exist. Optional on the interface — custom stores that don't track versions don't have to implement it. Use patchWithRetry to guard against read-modify-write races without calling this directly.

Atomic compare-and-swap write. Succeeds only if the row's current version equals expectedVersion (or if the row doesn't exist and expectedVersion is null). On conflict, returns the version the store actually has so the caller can re-read and retry.

Optional on the interface — custom stores that can't implement CAS don't have to. Use patchWithRetry for the common "update a field with retry on conflict" case.