Define distributed target lease and fencing semantics #93

Merged

lost-rob0t merged 1 commit from agent/issue-29-target-lease-semantics into dev

2026-08-07 04:06:34 +00:00

lost-rob0t commented

2026-08-07 04:02:33 +00:00

(Migrated from github.com)

Root cause

Issue #26 added a strong KV lease authentication boundary, but it intentionally stopped at the trust/security boundary. The repository still lacked one backend-neutral contract for canonical lock identity, the complete lease record, legal state transitions, idempotent operations, finite acquisition deadlines, commit-time fencing, race outcomes, stable HTTP results, audit events, and split-brain recovery.

Contract defined

one seven-part canonical identity across tenant, program, target namespace/id, actor, workflow, and operation class
one versioned SHA-256/base64url lock-key derivation; callers never supply raw backend keys
the complete active lease record, including owner/client/instance, immutable per-lease fencing token, acquired/renewed/expiry time, TTL, maximum lifetime, execution/job/trace/request IDs, bounded metadata, and explicit state
active/expired/released/revoked transitions with conditional cleanup and no terminal-to-active transition
acquire-if-free, exact-owner renew/release, scoped inspect/list, force-release, and revoke contracts
request-id idempotency with digest mismatch rejection and outcome-unknown resolution
authoritative backend time, bounded TTL/lifetime, finite deadlines, and no indefinite blocking acquisition
mandatory fenced-write adapter and explicit enforcement points for CouchDB, publication, scheduler, jobs, and administrative invalidation
deterministic outcomes for acquisition, renewal, expiry, release, revoke, crash, partition, timeout, stale cleanup, and restore races
stable HTTP success/error envelopes and codes
complete audit and split-brain/recovery assumptions
a verification matrix that #30–#33 must implement

The existing authentication-boundary document now links to this semantics contract, and the documentation index identifies both as design-only.

Compatibility impact

This PR changes no runtime behavior or public API. Existing allowed lease routes continue to return the documented 501 backend-unavailable stub. It constrains future #30–#33 implementations: adapters that cannot provide linearizable atomic operations, durable monotonic fencing counters, finite deadlines, typed results, and fenced authoritative commits are not conforming.

Tests executed

New red/green source-contract test: 1/1 passed after initially failing because the semantics document did not exist.
python -m unittest discover -s tests -p 'test_*.py' -v: 10/10 passed.
nix run .#star-unit-tests: 105 discovered / 105 executed / 105 passed / 0 failed / 0 skipped.
nix run .#star-integration-tests: 35 discovered / 35 executed / 35 passed / 0 failed / 0 skipped.
- Real CouchDB view suite: 7/7 passed.
- HTTP API suite: 28/28 passed.
python scripts/check-starintel-schema-lock.py: passed 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

docs/target-lease-semantics.org (new normative design)
docs/http-auth-kv-lease-boundary.org
docs/index.org
tests/test_operational_salvage_contract.py

Remaining risks

This is intentionally design-only. The backend-neutral protocol (#30), Valkey atomic implementation (#31), authenticated APIs and execution enforcement (#32), and expiry/recovery/race evidence (#33) remain unimplemented. The fencing guarantee depends on those implementations preserving the defined commit linearization point; a read-check followed by an unconditional write is explicitly non-conforming.

Fixes #29

## Root cause Issue #26 added a strong KV lease authentication boundary, but it intentionally stopped at the trust/security boundary. The repository still lacked one backend-neutral contract for canonical lock identity, the complete lease record, legal state transitions, idempotent operations, finite acquisition deadlines, commit-time fencing, race outcomes, stable HTTP results, audit events, and split-brain recovery. ## Contract defined - one seven-part canonical identity across tenant, program, target namespace/id, actor, workflow, and operation class - one versioned SHA-256/base64url lock-key derivation; callers never supply raw backend keys - the complete active lease record, including owner/client/instance, immutable per-lease fencing token, acquired/renewed/expiry time, TTL, maximum lifetime, execution/job/trace/request IDs, bounded metadata, and explicit state - active/expired/released/revoked transitions with conditional cleanup and no terminal-to-active transition - acquire-if-free, exact-owner renew/release, scoped inspect/list, force-release, and revoke contracts - request-id idempotency with digest mismatch rejection and outcome-unknown resolution - authoritative backend time, bounded TTL/lifetime, finite deadlines, and no indefinite blocking acquisition - mandatory fenced-write adapter and explicit enforcement points for CouchDB, publication, scheduler, jobs, and administrative invalidation - deterministic outcomes for acquisition, renewal, expiry, release, revoke, crash, partition, timeout, stale cleanup, and restore races - stable HTTP success/error envelopes and codes - complete audit and split-brain/recovery assumptions - a verification matrix that #30–#33 must implement The existing authentication-boundary document now links to this semantics contract, and the documentation index identifies both as design-only. ## Compatibility impact This PR changes no runtime behavior or public API. Existing allowed lease routes continue to return the documented 501 backend-unavailable stub. It constrains future #30–#33 implementations: adapters that cannot provide linearizable atomic operations, durable monotonic fencing counters, finite deadlines, typed results, and fenced authoritative commits are not conforming. ## Tests executed - New red/green source-contract test: **1/1 passed** after initially failing because the semantics document did not exist. - `python -m unittest discover -s tests -p 'test_*.py' -v`: **10/10 passed**. - `nix run .#star-unit-tests`: **105 discovered / 105 executed / 105 passed / 0 failed / 0 skipped**. - `nix run .#star-integration-tests`: **35 discovered / 35 executed / 35 passed / 0 failed / 0 skipped**. - Real CouchDB view suite: **7/7 passed**. - HTTP API suite: **28/28 passed**. - `python scripts/check-starintel-schema-lock.py`: passed 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 - `docs/target-lease-semantics.org` (new normative design) - `docs/http-auth-kv-lease-boundary.org` - `docs/index.org` - `tests/test_operational_salvage_contract.py` ## Remaining risks This is intentionally design-only. The backend-neutral protocol (#30), Valkey atomic implementation (#31), authenticated APIs and execution enforcement (#32), and expiry/recovery/race evidence (#33) remain unimplemented. The fencing guarantee depends on those implementations preserving the defined commit linearization point; a read-check followed by an unconditional write is explicitly non-conforming. Fixes #29