chore(openspec): add cloud control plane proposal

2026-07-12 14:30:29 +08:00
parent c94b3efe87
commit 99ea1509ef
9 changed files with 511 additions and 0 deletions
@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Assignment and device reservation are atomic
+The scheduler SHALL atomically bind a queued task to one eligible device, create a bounded lease attempt, and reserve that device so no other active task can be assigned to it.
+
+#### Scenario: Scheduler assigns an idle device
+- **WHEN** a queued task matches an idle pooled device with no active reservation
+- **THEN** one transaction records the assigned task, owning host/device, incremented attempt, lease identifier, lease expiry, and device reservation
+
+#### Scenario: Later scheduler iteration sees stale idle snapshot
+- **WHEN** the host snapshot still reports a device idle but that device has an active assignment lease
+- **THEN** the scheduler excludes the device from candidates for every other queued task
+
+### Requirement: Host claim transitions assigned work to dispatched
+The scheduler repository SHALL allow only the authenticated owning host to atomically claim an unexpired assigned attempt and transition it to `dispatched`.
+
+#### Scenario: Owning host claims once
+- **WHEN** the owning host requests available work and an unexpired assigned attempt exists
+- **THEN** exactly one request receives the assignment and its status becomes dispatched
+
+#### Scenario: Concurrent claims race
+- **WHEN** multiple requests concurrently attempt to claim the same assignment
+- **THEN** at most one request succeeds and every other request receives no assignment or a conflict
+
+### Requirement: Expired attempts follow bounded retry policy
+The system SHALL detect expired assigned or dispatched leases and SHALL either requeue the task with its reservation released or mark it failed when the configured attempt limit is reached.
+
+#### Scenario: Lease expires with attempts remaining
+- **WHEN** an active lease expires before a terminal result and the task has remaining attempts
+- **THEN** the task returns to queued, the previous device reservation is released, and the expired attempt remains auditable
+
+#### Scenario: Lease expires at attempt limit
+- **WHEN** an active lease expires and the task has reached its maximum attempts
+- **THEN** the task becomes failed with a lease-expiry reason and its device reservation is released
+
+### Requirement: Terminal transitions validate the active lease
+The system SHALL accept a `done` or `failed` result only from the current active task attempt and lease and SHALL make repeated identical terminal reports idempotent.
+
+#### Scenario: Active lease reports completion
+- **WHEN** the active lease owner reports a terminal result
+- **THEN** the task transitions once to done or failed and releases its device reservation
+
+#### Scenario: Superseded lease reports completion
+- **WHEN** a result references a lease superseded by expiry and retry
+- **THEN** the result is rejected and cannot overwrite the current task attempt
+
+## REMOVED Requirements
+
+### Requirement: Remote assignments are rejected explicitly, not silently ignored
+**Reason**: Remote execution is now performed by the authenticated Host Agent that owns the assigned device, so rejecting every non-local assignment prevents the intended cloud execution loop.
+
+**Migration**: Direct callers may continue using `TaskDispatcher` for local assignments, but cross-host work SHALL be delivered through the Host Agent lease/claim protocol instead of calling a dispatcher in the control-plane process.