docs(openspec): sync cloud control plane specs

2026-07-13 08:58:04 +08:00
parent ea9b15fce7
commit 70d15f8f0b
5 changed files with 265 additions and 11 deletions
@@ -47,3 +47,24 @@ The system SHALL allow looking up a single `PooledDevice` by `device_id` regardl
 - **WHEN** a caller requests a device by id that no host has ever synced
 - **THEN** the pool returns a not-found result (e.g. `None`) rather than raising an unhandled exception

+### Requirement: Authenticated network synchronization feeds the device pool
+The system SHALL expose an authenticated Host Agent operation that validates a host device snapshot and delegates it to the existing device-pool synchronization behavior.
+
+#### Scenario: Valid remote snapshot
+- **WHEN** an authenticated Host Agent submits a valid complete snapshot for its bound host id
+- **THEN** the device pool refreshes that host and its devices with the same replacement and staleness semantics as an in-process synchronization call
+
+#### Scenario: Invalid snapshot is rejected atomically
+- **WHEN** a Host Agent snapshot contains invalid device identifiers, driver types, statuses, or capability tags
+- **THEN** the control plane rejects the snapshot without partially replacing the host's previously stored devices
+
+### Requirement: Device identity ownership conflicts are explicit
+The device pool SHALL reject a snapshot that claims a `device_id` actively owned by a different non-stale host, rather than silently transferring ownership.
+
+#### Scenario: Two live hosts report the same device id
+- **WHEN** host B reports a device id currently owned by non-stale host A
+- **THEN** host B's conflicting snapshot is rejected with an ownership-conflict response and host A retains ownership
+
+#### Scenario: Previous owner is stale
+- **WHEN** a configured ownership-recovery policy permits takeover and the prior owning host is stale beyond the recovery threshold
+- **THEN** the new host may claim the device id and the ownership transition is recorded