From 9766e5396e2c5a9f591b66c91aff203ef3686584 Mon Sep 17 00:00:00 2001 From: Mikhail Date: Sat, 22 Aug 2026 11:59:04 +0300 Subject: [PATCH] Add agent lease fencing contract --- contracts/work/lease.go | 22 ++++++++++++ dev/ACTIVE_TASK.json | 4 +-- dev/tasks/DEV-000116-agent-lease-fencing.json | 23 +++++++++++++ modules/work/domain/lease.go | 25 ++++++++++++++ tests/agent_execution/lease_test.go | 34 +++++++++++++++++++ 5 files changed, 106 insertions(+), 2 deletions(-) create mode 100644 contracts/work/lease.go create mode 100644 dev/tasks/DEV-000116-agent-lease-fencing.json create mode 100644 modules/work/domain/lease.go create mode 100644 tests/agent_execution/lease_test.go diff --git a/contracts/work/lease.go b/contracts/work/lease.go new file mode 100644 index 0000000..1406898 --- /dev/null +++ b/contracts/work/lease.go @@ -0,0 +1,22 @@ +package work + +import "time" + +type AgentLeaseID string +type AgentFencingToken uint64 +type AgentLeaseState string + +const ( + AgentLeaseActive AgentLeaseState = "ACTIVE" + AgentLeaseExpired AgentLeaseState = "EXPIRED" +) + +type AgentLease struct { + ID AgentLeaseID + RunID AgentRunID + WorkerID string + FencingToken AgentFencingToken + State AgentLeaseState + AcquiredAt time.Time + ExpiresAt time.Time +} diff --git a/dev/ACTIVE_TASK.json b/dev/ACTIVE_TASK.json index 5694a52..aad79b9 100644 --- a/dev/ACTIVE_TASK.json +++ b/dev/ACTIVE_TASK.json @@ -1,5 +1,5 @@ { - "task_file": "dev/tasks/DEV-000115-cognitive-admission-control.json", - "task_id": "DEV-000115", + "task_file": "dev/tasks/DEV-000116-agent-lease-fencing.json", + "task_id": "DEV-000116", "task_revision": 1 } diff --git a/dev/tasks/DEV-000116-agent-lease-fencing.json b/dev/tasks/DEV-000116-agent-lease-fencing.json new file mode 100644 index 0000000..4e037ec --- /dev/null +++ b/dev/tasks/DEV-000116-agent-lease-fencing.json @@ -0,0 +1,23 @@ +{ + "task_id": "DEV-000116", + "task_revision": 1, + "architecture_revision": "ADR-0018", + "base_repo_revision": "cb92f95", + "risk_tier": "E", + "intent": "Add typed durable-agent lease and fencing-token transitions for worker start/heartbeat without implementing a dispatcher or persistence adapter.", + "requirement_ids": ["WP-301", "Worker lease confirms actual start", "Heartbeat fencing"], + "allowed_change_scope": {"modules": ["work-agent-execution"], "paths": ["contracts/work/**", "modules/work/domain/**", "tests/agent_execution/**", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000116-agent-lease-fencing.json"]}, + "forbidden_change_scope": {"paths": ["architecture/**", "database/**", "migrations/**", "deploy/**", "security/**", "cmd/**", "runtime/**", "adapters/**", ".gitea/**"]}, + "allowed_architecture_delta": {"new_cross_module_dependencies": 0, "new_canonical_owners": 0, "new_privileges": 0, "new_third_party_dependencies": 0, "new_database_owner_roles": 0}, + "contracts": {"consume": ["ADR-0017 delegation/run ownership", "Proposed ADR-0020 Agent Execution Plane", "Existing Work AgentRun identity"], "may_change": ["Work agent lease/fencing contract"]}, + "semantic_owner": "work-agent-execution", + "canonical_state": [], + "state_transitions": ["dispatch -> lease acquired -> heartbeat renewed", "wrong worker/token/expired lease -> rejected callback"], + "side_effects_and_privileges": ["Pure transition helper; no queue, persistence, worker process, credential access or external mutation"], + "persistence_and_migrations": ["No schema or migration changes"], + "failure_retry_restart": ["Fencing token changes on a new lease; late old-token heartbeat is rejected"], + "assumptions": ["A durable repository will persist the lease atomically later", "Lease acquisition is separate from process-local execution", "Worker identity is authenticated by a later adapter boundary"], + "acceptance_scenarios": ["Valid worker acquires lease", "Matching worker renews before expiry", "Wrong worker/token rejected", "Expired lease cannot renew", "New token fences old run"], + "required_tests": ["go test ./...", "go vet ./...", "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-diff -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-architecture", "go run ./cmd/devctl/independent", "git diff --check", "agent lease tests"], + "terminal_gap_states": ["BLOCKED_BY_MISSING_CAPABILITY", "BLOCKED_BY_SPEC_GAP", "BLOCKED_BY_CONFLICT"] +} diff --git a/modules/work/domain/lease.go b/modules/work/domain/lease.go new file mode 100644 index 0000000..f1f34bb --- /dev/null +++ b/modules/work/domain/lease.go @@ -0,0 +1,25 @@ +package domain + +import ( + "errors" + "time" + + "git.cin.su/m/Assistant/contracts/work" +) + +var ErrLeaseRejected = errors.New("agent lease rejected") + +func AcquireAgentLease(runID work.AgentRunID, workerID string, token work.AgentFencingToken, now time.Time, ttl time.Duration) (work.AgentLease, error) { + if runID == "" || workerID == "" || token == 0 || now.IsZero() || ttl <= 0 { + return work.AgentLease{}, ErrLeaseRejected + } + return work.AgentLease{ID: work.AgentLeaseID(string(runID) + ":" + workerID), RunID: runID, WorkerID: workerID, FencingToken: token, State: work.AgentLeaseActive, AcquiredAt: now, ExpiresAt: now.Add(ttl)}, nil +} + +func RenewAgentLease(lease work.AgentLease, workerID string, token work.AgentFencingToken, now time.Time, ttl time.Duration) (work.AgentLease, error) { + if lease.State != work.AgentLeaseActive || lease.WorkerID != workerID || lease.FencingToken != token || now.IsZero() || !now.Before(lease.ExpiresAt) || ttl <= 0 { + return work.AgentLease{}, ErrLeaseRejected + } + lease.ExpiresAt = now.Add(ttl) + return lease, nil +} diff --git a/tests/agent_execution/lease_test.go b/tests/agent_execution/lease_test.go new file mode 100644 index 0000000..eb9a74d --- /dev/null +++ b/tests/agent_execution/lease_test.go @@ -0,0 +1,34 @@ +package agent_execution_test + +import ( + "testing" + "time" + + "git.cin.su/m/Assistant/contracts/work" + workdomain "git.cin.su/m/Assistant/modules/work/domain" +) + +func TestAgentLeaseFencesWorkerAndToken(t *testing.T) { + now := time.Unix(100, 0) + lease, err := workdomain.AcquireAgentLease("run-1", "worker-a", 7, now, time.Minute) + if err != nil || lease.State != work.AgentLeaseActive { + t.Fatalf("lease = %#v %v", lease, err) + } + if _, err := workdomain.RenewAgentLease(lease, "worker-b", 7, now.Add(time.Second), time.Minute); err == nil { + t.Fatal("expected worker fencing") + } + if _, err := workdomain.RenewAgentLease(lease, "worker-a", 8, now.Add(time.Second), time.Minute); err == nil { + t.Fatal("expected token fencing") + } + if renewed, err := workdomain.RenewAgentLease(lease, "worker-a", 7, now.Add(time.Second), time.Minute); err != nil || !renewed.ExpiresAt.After(lease.ExpiresAt) { + t.Fatalf("renewed = %#v %v", renewed, err) + } +} + +func TestExpiredLeaseCannotRenew(t *testing.T) { + now := time.Unix(100, 0) + lease, _ := workdomain.AcquireAgentLease("run-1", "worker-a", 1, now, time.Second) + if _, err := workdomain.RenewAgentLease(lease, "worker-a", 1, now.Add(time.Second), time.Second); err == nil { + t.Fatal("expected expired lease rejection") + } +}