Implement backend-neutral lease store protocol #94

Merged

lost-rob0t merged 1 commit from agent/issue-30-lease-store-protocol into dev

2026-08-07 06:08:40 +00:00

lost-rob0t commented

2026-08-07 05:42:39 +00:00

(Migrated from github.com)

Root cause

Target-lease semantics were documented, but the server had no owned backend-neutral lease-store boundary. Callers had no stable contract for deterministic lock identity, typed outcomes, deadlines, idempotency, fencing, lifecycle, persistence shape, or operational hooks, which would have forced backend-specific behavior into actors and routes.

New protocol contract

Adds the star.leases package with backend-neutral acquire, renew, release, get, list, revoke, health, and close generic operations.
Uses normalized canonical lease identities and deterministic versioned SHA-256 lock keys.
Returns closed typed outcomes rather than booleans, including conflict, stale-token, not-owner, expired, timeout, backend-unavailable, and outcome-unknown.
Defines explicit deadline and request-id inputs, request-id idempotency, monotonic fencing, maximum-lifetime enforcement, and stale renew/release rejection.
Adds versioned lease-record JSON serialization with canonical key validation.
Makes the lease runtime own and close its backend.
Adds audit and metrics hooks at the backend operation boundary.
Supplies a deterministic in-memory contract backend for unit testing; production Valkey behavior remains isolated to #31.

Compatibility impact

No actor, target-dispatch, or HTTP route imports a memory-, Redis-, or Valkey-specific backend. Existing authorized lease HTTP operations retain their current 501 behavior until a production adapter is wired by later roadmap work. No existing public caller was changed.

Tests executed

nix run .#star-unit-tests: 113 discovered / 113 executed / 113 passed / 0 failed / 0 skipped
Lease backend contract suite: 8 discovered / 8 executed / 8 passed / 0 failed / 0 skipped
nix run .#star-integration-tests: 35 discovered / 35 executed / 35 passed / 0 failed / 0 skipped
- CouchDB view integration: 7/7
- HTTP API integration: 28/28
python -m pytest -q tests/test_operational_salvage_contract.py: 11 passed, 21 subtests passed
python scripts/check-starintel-schema-lock.py: verified StarIntel 0.9.0 schema at ff814ff63868286d68e21502122832802cd5e361
docker compose config --quiet: passed
./scripts/stack-test.sh: passed authenticated/scoped denial, FTS, restart, document persistence, and credential persistence checks
git diff --check: passed

Files changed

source/leases/package.lisp
source/leases/protocol.lisp
source/leases/memory-store.lisp
source/starintel-gserver.asd
starintel-gserver-tests.asd
t/lease-store-contract-test.lisp
t/run-tests.lisp
tests/test_operational_salvage_contract.py
docs/index.org

Remaining risks

The in-memory backend is intentionally a deterministic test implementation. Real distributed atomicity, authoritative TTL/server time, connection management, and Valkey failure behavior are deferred to #31 and must conform to this protocol without changing it merely for backend convenience.

Fixes #30

## Root cause Target-lease semantics were documented, but the server had no owned backend-neutral lease-store boundary. Callers had no stable contract for deterministic lock identity, typed outcomes, deadlines, idempotency, fencing, lifecycle, persistence shape, or operational hooks, which would have forced backend-specific behavior into actors and routes. ## New protocol contract - Adds the `star.leases` package with backend-neutral acquire, renew, release, get, list, revoke, health, and close generic operations. - Uses normalized canonical lease identities and deterministic versioned SHA-256 lock keys. - Returns closed typed outcomes rather than booleans, including conflict, stale-token, not-owner, expired, timeout, backend-unavailable, and outcome-unknown. - Defines explicit deadline and request-id inputs, request-id idempotency, monotonic fencing, maximum-lifetime enforcement, and stale renew/release rejection. - Adds versioned lease-record JSON serialization with canonical key validation. - Makes the lease runtime own and close its backend. - Adds audit and metrics hooks at the backend operation boundary. - Supplies a deterministic in-memory contract backend for unit testing; production Valkey behavior remains isolated to #31. ## Compatibility impact No actor, target-dispatch, or HTTP route imports a memory-, Redis-, or Valkey-specific backend. Existing authorized lease HTTP operations retain their current 501 behavior until a production adapter is wired by later roadmap work. No existing public caller was changed. ## Tests executed - `nix run .#star-unit-tests`: **113 discovered / 113 executed / 113 passed / 0 failed / 0 skipped** - Lease backend contract suite: **8 discovered / 8 executed / 8 passed / 0 failed / 0 skipped** - `nix run .#star-integration-tests`: **35 discovered / 35 executed / 35 passed / 0 failed / 0 skipped** - CouchDB view integration: 7/7 - HTTP API integration: 28/28 - `python -m pytest -q tests/test_operational_salvage_contract.py`: **11 passed, 21 subtests passed** - `python scripts/check-starintel-schema-lock.py`: verified StarIntel 0.9.0 schema at `ff814ff63868286d68e21502122832802cd5e361` - `docker compose config --quiet`: passed - `./scripts/stack-test.sh`: passed authenticated/scoped denial, FTS, restart, document persistence, and credential persistence checks - `git diff --check`: passed ## Files changed - `source/leases/package.lisp` - `source/leases/protocol.lisp` - `source/leases/memory-store.lisp` - `source/starintel-gserver.asd` - `starintel-gserver-tests.asd` - `t/lease-store-contract-test.lisp` - `t/run-tests.lisp` - `tests/test_operational_salvage_contract.py` - `docs/index.org` ## Remaining risks The in-memory backend is intentionally a deterministic test implementation. Real distributed atomicity, authoritative TTL/server time, connection management, and Valkey failure behavior are deferred to #31 and must conform to this protocol without changing it merely for backend convenience. Fixes #30