Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 180 additions & 0 deletions docs/archive/specs/2026-11-01-cloud-workspace-reset.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
# Cloud Workspace Reset

Date: 2026-11-01
Status: Implemented and locally verified
Base: `243db4cc4272e7e4772355fcc7f8e06a84976259`
Task branch: `feat/cloud-reset`

## Outcome

Settings offers **Reset cloud data** next to the existing device recovery action.
After a confirmed cloud commit, the current device remains authenticated and bound
to the same private Gist, with the empty business state seen after first setup.
The action affects every device connected to that Gist.

Device reset remains a separate local operation. Cloud reset does not create or
delete a Gist, clear credentials, change Workspace identity, or erase GitHub
revision history. It does not offer browser backup/import, switching, local push,
merge, or force overwrite.

## Scope and ownership

Reset clears all live `nodes`, `subscriptions`, `aggregates`, `publishTargets`,
and `clientExports`. It removes existing output files only when current publication
metadata proves SubMan published them. An unowned file, an unpublished same-name
file, or a retained historical output without sufficient ownership evidence is
preserved and appears in the confirmation preview.

`subman.json` remains the authoritative Schema V2 document. The immutable
`subman.v1.backup.json`, external files, historical tombstones, processed mutation
journal, orphan browser queues, quarantine evidence, and fencing counters remain.
Existing bootstrap cleanup rules remain owned by the coordinator.
When a stale bootstrap marker is visible in the inventory, the reset preview
lists it for cleanup rather than promising to preserve it.

## Entry and confirmation

1. Show a separate destructive Settings section beside **Reset this device**.
2. Require authentication, an initialized automatic V2 binding, successful cloud
loading, and no active pending, blocked, or dead-letter queue. Refuse active
dispatcher leases. Existing reload/repair resolves pending evidence first.
3. Read only the originally bound Gist. Validate the cloud document, then safely
align the local baseline using the existing compare-and-swap refresh boundary.
4. Prepare a preview containing Gist ID, revision, reset revision, counts for all
five resource collections, files to remove, files to preserve, and the complete
local snapshot/binding/active-queue expectation.
Derive deletion names from the authoritative document, without filtering them
through a separately read Gist inventory that may predate a concurrent publish.
5. Use the shared accessible Dialog. Explain the cross-device impact and retained
files; require literal `RESET`. Cancellation sends no mutation.
6. Pin the preview's local expectation and cloud revision. A changed snapshot,
binding, queue, active lease, or cloud revision rejects this attempt and requires
a fresh preview and confirmation. Reset never automatically reprepares itself
against newer data.

## Coordinator mutation

Add browser-only `workspace.reset` with an empty payload to the internal mutation
protocol. The public Server API does not expose reset or change its request or
response contract.

The existing coordinator serializes the operation for `gist:<gist-id>`. It checks
identity, request hash, pending recovery, authorization, expected revision, and
reset boundary using the existing order and guarantees. It then:

- Appends tombstones for every live entity, retaining all earlier tombstones.
- Clears the five business collections.
- Advances revision by one and sets `lastMutationId` and commit timestamp normally.
- Sets `resetRevision` to this committed revision.
- Produces deletions only for provably published SubMan output files.
- Journals the candidate before sending one Gist PATCH containing the new
`subman.json` and all output deletions.
- Reads back and verifies the candidate and file effects before confirming it.

A repeated mutation ID with the same request hash returns its stored receipt
without executing reset again. Existing processed retries remain recoverable even
after later writes or resets. Unresolved pending recovery, invalid documents,
backup mismatch, and ambiguous upstream writes continue to fail closed.

## Reset boundary and compatibility

Schema V2 gains optional `resetRevision`; mutation envelopes gain optional
`expectedResetRevision`. Absence means zero for comparison. A new mutation is
accepted only if its observed reset revision equals the document's reset revision.
Ordinary mutations preserve the document boundary. Another reset advances it.

This supplements revision checks and tombstones: an old queued creation can have
an ID that never reached the cloud and therefore has no tombstone. Local CAS retry,
delayed actions, or compatibility reconcile must not silently repackage that old
intent with a new reset boundary.

- Capture the initial Workspace identity and reset boundary when accepting an
action, before asynchronous preparation. Recheck after every persistence read
and bounded ordinary CAS retry. A boundary change rejects the old intent.
- A batch import pins one boundary for the whole batch. Stop on reset or any
non-remote outcome; retain its draft instead of submitting later rows as fresh
actions in the new generation.
- Persist envelopes with their originally observed boundary; never rewrite it at
dispatch time. Remote conflicts block the complete queue for explicit repair.
- Reject old-boundary reconcile/repair and delayed resolved snapshots. Cloud reload
may replace a complete old queue only through existing explicit confirmation.
- An already-committed old mutation may acknowledge its historical receipt and
hydrate the latest cloud state; remaining old queue entries stay blocked and
are not replayed into the new generation.
- Server API adapters capture the boundary from their own cloud read and place it
in their internal envelope. Public clients need no new field.

Keep optional fields absent in historical parsing, serialization, request hashes,
and document signatures. Do not inject zero into existing envelopes: that would
change the request hash for an original mutation ID. Include a nonzero reset
boundary in document signatures and preserve old pending-journal verification.
New documents first emit the boundary on actual reset. Older strict clients stop
on the unfamiliar field and must reload the updated application.

## Browser durability and presentation

Use the existing `WorkspacePersistence` root and transaction boundary. Reset's
original envelope, optimistic snapshot, and unchanged binding are committed
atomically before dispatch. Persistence also verifies the full preview expectation
and idle active queue/lease inside that transaction; a read-only preflight alone
is insufficient.

Await the operation completion. Only `remote-committed` allows **Cloud data reset**
success wording and finalization. Pending, peer-owned, retry-scheduled, blocked,
and acknowledgement-uncertain outcomes use the shared operation presenter and
retain the operation identity. Eligible upstream retries use existing bounded
backoff and the same mutation ID. Editing remains blocked while delivery is
pending. A post-commit local read or presentation failure cannot turn cloud success
into a fresh destructive attempt.

After confirmation, atomically settle the queue with the authoritative empty
snapshot and baseline. Keep Gist binding, authentication preference, and token.
Broadcast existing commit/state events as hints; correctness must survive missing
BroadcastChannel or Web Locks.

## Validation and acceptance

Add behavior tests before implementation in each affected layer:

| Layer | Required evidence |
| --- | --- |
| Document/mutation | Optional-field compatibility; unchanged old hashes/signatures; five collections cleared; tombstones retained/appended; monotonic revision; browser-only reset; output ownership |
| Coordinator | Single PATCH; immutable backup; duplicate request; timeout after actual commit; read-back recovery; competing write/reset rejects stale preview |
| Persistence | Preview CAS including snapshot/queue; active lease; rollback before commit; durable post-commit recovery; unchanged Gist identity and token exclusion |
| Browser actions | Old intents and unseen UUID creations cannot cross reset during asynchronous preparation or CAS retry; explicit reset never retries with a newer revision |
| Delivery/repair | Old queue conflict; historical receipt recovery; remaining old queue retained and blocked; safe explicit whole-queue cloud reload |
| Server API | Empty reads after reset; fresh writes succeed; pre-reset internal envelopes conflict; public OpenAPI contract unchanged |
| UI/E2E | Cancel sends zero writes; typed confirmation; resource/file preview; cloud confirmation precedes success; token/binding retained; pending outcome; desktop and Chinese mobile flow |

Run repository docs, unit, type, lint, build, Workers runtime, and relevant browser
checks with Bun 1.3.14. Use isolated worktree dependencies, Worker state, output,
browser state, and ports. Test GitHub through mocks, never a real user Gist.

## Delivery boundary

Implement and verify in the dedicated task worktree and create an atomic local
Conventional Commit. Push, PR creation, merge, Wiki publication, and production
deployment require authorization beyond this local implementation request.

## Local verification evidence

Verified with Bun 1.3.14 in the dedicated task worktree:

- 758 unit tests across 74 files passed.
- 10 Workers/SQLite integration tests passed, including reset receipt recovery
and stale-preview HTTP rejection.
- All 81 browser cases passed in isolated groups (41 + 20 + 20). The seven reset
cases passed again after the final confirmation layout adjustment.
- Desktop 1280 x 720 and Chinese mobile 390 x 844 confirmation flows were inspected.
The warning initially stays visible; the confirmation input remains fully in
view while editing, with no framework overlay or unexpected console errors in
the normal preview flow.
- Documentation, Svelte/type/generated Worker type checks, lint, build, sing-box
1.14 output validation, and deployment dry-run passed.
- Independent local review findings about first-read races, batch boundaries,
and incomplete deletion previews were reproduced and resolved with regression
tests. Removing the browser action guard in an isolated copy made all three
new guard regressions fail, confirming their effectiveness.

GitHub calls used test fixtures and mocks. No real Gist was accessed or changed,
and these checks do not claim production deployment or live GitHub acceptance.
11 changes: 11 additions & 0 deletions docs/wiki/Changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,17 @@ production deployment and real-provider acceptance require separate evidence.

## Unreleased

### 2026-11-01 - Confirmed cloud data reset

- Added a Settings preview and typed confirmation to clear cloud business data
while retaining the original Gist connection and authentication.
- Reset and proven published-output removal share one coordinator PATCH. External
files, immutable migration backup, tombstones, and recovery journals remain.
- Added reset revision fencing so old queues and delayed actions cannot replay
across reset; stale confirmations require a new preview. Public API shapes stay
unchanged and cloud confirmation remains the only success result.
- Recorded the [accepted implementation specification](../archive/specs/2026-11-01-cloud-workspace-reset.md).

### 2026-11-01 - Foreground cloud operation loading

- Keep saves, publication generation, and Gist refresh in a visible foreground
Expand Down
9 changes: 9 additions & 0 deletions docs/wiki/Changelog.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,15 @@

## 未发布

### 2026-11-01 - 确认后重置云端数据

- 设置页增加云端重置预览和输入确认,清空云端业务数据,同时保留原 Gist 连接与认证。
- 重置文档与删除有发布证据的输出使用同一次协调器 PATCH;保留外部文件、不可变迁移备份、
删除标记和恢复日志。
- 增加重置修订边界,旧队列和延迟操作不能跨重置重放,过期确认需重新预览;
公开 API 结构不变,仍只有云端确认才能报告成功。
- 记录[已确认的实现 SPEC](../archive/specs/2026-11-01-cloud-workspace-reset.md)。

### 2026-11-01 - 云端操作前台等待状态

- 保存、发布生成与 Gist 刷新统一显示前台 loading,等待期间禁止编辑背景内容或切换页面,
Expand Down
21 changes: 20 additions & 1 deletion docs/wiki/User-Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ empty Workspace, then recent resources and confirmed publication metadata.

| Page | Purpose |
| --- | --- |
| `/auth` | Connection, token, delivery status, cloud reload, device reset, migration, and diagnostics |
| `/auth` | Connection, token, delivery status, cloud reload, cloud/device reset, migration, and diagnostics |
| `/nodes` | Nodes and subscriptions, tags, search, filters, and batch import |
| `/aggregate` | Rule editing, preview ordering, publish targets, and publication |
| `/exports` | sing-box configuration preview, copy, download, and publication |
Expand Down Expand Up @@ -85,6 +85,25 @@ they do not export business data or credentials. There is no browser business
JSON backup/restore, local overwrite/merge, manual push, or Workspace switching.
For operator procedures, see [operations and repair](../workspace-v2-operations.md).

## Reset cloud data and keep your connection

In Settings, choose **Reset cloud data** to return the original Gist to an empty
business state while keeping your token and connection. This affects every device
using that Gist. Complete or repair pending delivery first, then review the latest
resource counts and files and type `RESET` to confirm.

Reset clears nodes, subscriptions, rules, publish targets, and client export
profiles. It removes outputs with confirmed SubMan publication metadata; the
preview lists preserved external files and migration backups. It preserves the
Gist itself and its GitHub history. Existing subscription links for removed
outputs stop serving those files; previously downloaded copies are unaffected.

Only cloud confirmation completes reset. If delivery is pending or uncertain,
retain the original operation and use existing retry/recovery controls. If data
changes during confirmation, review a new preview. Older devices cannot replay
pre-reset changes; confirm a complete-queue cloud reload before editing again.
Older application versions may need a page refresh after reset.

## Start again after removing your Gist

Disconnect removes your token but keeps this device's Workspace binding and
Expand Down
16 changes: 15 additions & 1 deletion docs/wiki/User-Guide.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ SubMan 查找描述为 `SubMan-Data`、包含权威文档 `subman.json` 的私

| 页面 | 用途 |
| --- | --- |
| `/auth` | 连接、Token、发送状态、云端重载、设备重置、迁移和诊断 |
| `/auth` | 连接、Token、发送状态、云端重载、云端/设备重置、迁移和诊断 |
| `/nodes` | 节点与订阅、标签、搜索、过滤、批量导入 |
| `/aggregate` | 规则编辑、预览排序、发布目标与发布 |
| `/exports` | sing-box 配置预览、复制、下载和发布 |
Expand Down Expand Up @@ -64,6 +64,20 @@ SubMan 查找描述为 `SubMan-Data`、包含权威文档 `subman.json` 的私
浏览器不提供业务 JSON 备份/恢复、本地覆盖/合并、手动推送或工作区切换。
操作人员的修复步骤见[运维与恢复](../workspace-v2-operations.zh-CN.md)。

## 保留连接并重置云端数据

在设置中选择**重置云端数据**,可将原 Gist 恢复为空的业务状态,同时保留 Token 和连接。
这会影响使用该 Gist 的所有设备。先完成或修复待发送操作,再检查最新的资源数量和文件列表,
输入 `RESET` 确认。

重置会清空节点、订阅、规则、发布目标和客户端导出配置,并删除存在 SubMan 发布确认记录的
输出;确认窗口列出保留的外部文件和迁移备份。Gist 本身及其 GitHub 历史仍保留。
被删除输出的订阅链接将不再提供这些文件,已下载到客户端的副本不受影响。

只有云端确认后才完成重置。发送待处理或结果不确定时,保留原操作,使用现有重试/恢复入口。
确认期间数据发生变化时,需要查看新预览。其他设备不能重新发送重置前的变更,
应确认丢弃完整旧队列并重载云端后再编辑。旧版应用可能需要刷新页面升级。

## 删除 Gist 后重新开始

断开连接只清除 Token,保留此设备的工作区绑定和待确认变更。重新连接仍会读取原 Gist,
Expand Down
29 changes: 29 additions & 0 deletions docs/workspace-v2-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,35 @@ discarded browser cache is never uploaded as business authority. Safe historical
queue evidence remains in Sync recovery and is never automatically rebound or
delivered.

## Cloud Data Reset With The Original Connection

Settings **Reset cloud data** requires a ready automatic V2 binding, authentication,
an idle active queue, and no active delivery lease. It reads the original Gist,
previews resource counts and file ownership, and requires typed `RESET` confirmation.
The snapshot, binding, complete queue, and cloud revision are pinned; changed state
requires a fresh confirmation rather than automatic re-preparation.

The internal browser-only `workspace.reset` mutation clears all five business
collections and removes only outputs with publication evidence in one coordinator
Gist PATCH. It retains the original Gist/token/binding, immutable V1 backup,
external files, earlier tombstones, processed journal, and browser recovery
evidence. Removed entities gain tombstones; revision continues increasing.

Optional document `resetRevision` records the last reset's committed revision.
Internal envelopes carry `expectedResetRevision` from the original action's
baseline; absent fields compare as zero and retain historical hash/serialization
shape. Ordinary CAS retries, compatibility reconcile, and Server API adapters
must preserve this boundary. The coordinator rejects a mismatched boundary as
`revision_conflict`. A historical committed receipt remains recoverable without
re-executing it. Old queues require explicit complete-queue cloud reload, never
automatic rebase across reset. Older strict clients must refresh their app.

Only `remote-committed` completes reset. Retry/uncertain results retain the
original mutation ID; cloud success followed by local acknowledgement failure
must not create a second reset. Reset does not erase GitHub history or repair
invalid documents, backup mismatch, or unresolved coordinator pending records.
See the [accepted specification](archive/specs/2026-11-01-cloud-workspace-reset.md).

## Leases, Retry, And Upstream Failures

Each Workspace dispatcher acquires a persisted lease with a random owner ID,
Expand Down
Loading
Loading