[P0-22] Add a backend-neutral KV lease-store protocol #30

New issue

Closed

opened 2026-07-22 00:13:57 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-22 00:13:57 +00:00

(Migrated from github.com)

Depends on

Distributed target lease and fencing semantics.

Objective

Keep target scheduling and HTTP APIs independent of a specific KV product while still exposing the atomic operations required for correctness.

Required protocol

Define operations equivalent to:

acquire-lease
renew-lease
release-lease
get-lease
list-leases
revoke-lease
backend-health
close-lease-store

Each operation must accept a deadline and request/idempotency id and return structured outcomes rather than booleans.

Requirements

Atomic acquire, compare-and-renew, compare-and-delete, and fencing-token increment.
Namespaced keys with deterministic canonical encoding.
Explicit serialization version.
Connection pool/resource lifecycle under the runtime object.
Backend unavailable, timeout, conflict, stale token, not owner, and expired outcomes.
Metrics and audit hooks.
In-memory deterministic backend for unit tests only.

Acceptance tests

A backend contract suite runs against every implementation.
Concurrent acquire permits one active owner.
Stale renew/release cannot affect a newer lease.
Closing the runtime closes the backend and rejects new operations.
No target actor or HTTP route imports backend-specific packages.

## Depends on Distributed target lease and fencing semantics. ## Objective Keep target scheduling and HTTP APIs independent of a specific KV product while still exposing the atomic operations required for correctness. ## Required protocol Define operations equivalent to: - `acquire-lease` - `renew-lease` - `release-lease` - `get-lease` - `list-leases` - `revoke-lease` - `backend-health` - `close-lease-store` Each operation must accept a deadline and request/idempotency id and return structured outcomes rather than booleans. ## Requirements - Atomic acquire, compare-and-renew, compare-and-delete, and fencing-token increment. - Namespaced keys with deterministic canonical encoding. - Explicit serialization version. - Connection pool/resource lifecycle under the runtime object. - Backend unavailable, timeout, conflict, stale token, not owner, and expired outcomes. - Metrics and audit hooks. - In-memory deterministic backend for unit tests only. ## Acceptance tests - A backend contract suite runs against every implementation. - Concurrent acquire permits one active owner. - Stale renew/release cannot affect a newer lease. - Closing the runtime closes the backend and rejects new operations. - No target actor or HTTP route imports backend-specific packages.