From 3c5f5509c21acd75b79368ed73289c3a8755c1fc Mon Sep 17 00:00:00 2001 From: Jerry Yan <792602257@qq.com> Date: Mon, 13 Jul 2026 07:59:56 +0800 Subject: [PATCH] docs(cloud): state deployment limitations --- docs/CLOUD_DEPLOYMENT.md | 21 +++++++++++++++++++ .../cloud-control-plane-integration/tasks.md | 2 +- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/CLOUD_DEPLOYMENT.md b/docs/CLOUD_DEPLOYMENT.md index 28d2ec7..3e909f9 100644 --- a/docs/CLOUD_DEPLOYMENT.md +++ b/docs/CLOUD_DEPLOYMENT.md @@ -109,6 +109,27 @@ For OpenAI, set `AI_PLANNER_PROVIDER=openai`, choose the deployed model through `AI_PLANNER_MODEL`, and provide `OPENAI_API_KEY`. Provider credentials belong only on the Host Agent; the Cloud API does not need them. +## Operational Limitations + +Run exactly one scheduler-enabled Cloud API process. SQLite supports only the +documented single-control-plane development mode. PostgreSQL row locking makes +assignment and claim transactions safe if requests overlap, but this release +does not implement scheduler leader election or claim active-active scheduler +operation. Starting multiple Cloud API replicas would start one scheduler loop +per replica and is outside the supported deployment topology. + +Device execution provides at-least-once side-effect semantics, not exactly-once +semantics. A device action can succeed immediately before the Host Agent loses +its lease or its result response, after which the control plane may retry the +task. Lease renewal and cooperative stop checks prevent later interruptible +actions where possible, but they cannot roll back an action already sent to a +device or safely terminate an in-progress synchronous driver call. + +Use bounded attempts, inspect task attempt and failure metadata, and design +device workflows to tolerate repeated actions when the target operation allows +it. Do not use this release for operations that require a transactional +exactly-once guarantee across the cloud database and an external device. + ## Shutdown And Rollback For a normal shutdown, stop Host Agents first so they stop polling, interrupt diff --git a/openspec/changes/cloud-control-plane-integration/tasks.md b/openspec/changes/cloud-control-plane-integration/tasks.md index 73ef7e0..2e2524a 100644 --- a/openspec/changes/cloud-control-plane-integration/tasks.md +++ b/openspec/changes/cloud-control-plane-integration/tasks.md @@ -67,7 +67,7 @@ - [x] 8.2 Add bearer authentication and typed authorization errors to `CloudClient` while preserving injectable HTTP clients for tests. - [x] 8.3 Add container definitions and example environment configuration for the cloud API, PostgreSQL, and Host Agent without committing secrets. - [x] 8.4 Document local SQLite startup, deployed PostgreSQL migration/startup, credential/scopes setup, Runtime AI Planner configuration, and shutdown/rollback procedures. -- [ ] 8.5 Document the single scheduler-enabled control-plane limitation and the at-least-once device-side-effect trade-off. +- [x] 8.5 Document the single scheduler-enabled control-plane limitation and the at-least-once device-side-effect trade-off. ## 9. Verification And Project Records