fix(web): reconcile SDK folderTree sequence to stop deleted-file resurrection

[FSM1]

Summary

Fixes the deterministic web-e2e failure in recycle-bin TC08: permanent delete of versioned file reclaims all quota (reproduced on both runs of 1abceb4b8). After a file is replaced and then soft-deleted, the item is resurrected in the file list (and also moved to the bin), so waitForItemToDisappear times out.

Root cause

A two-store desync exposed by the new 409-merge (#488):

• The web app holds folder state in two places: the Zustand useFolderStore and the SDK client's internal folderTree.
• ensureFolderRegistered treats the folderTree as authoritative and no-ops once a folder is registered.
• A file replace (updateFile) publishes folder metadata directly via sdk-core, advancing the store's IPNS sequence and the child's modifiedAt — but the SDK folderTree is never told, so it stays at the old sequence and old modifiedAt.
• The subsequent deleteToBin reads the stale folderTree, so it:
  1. publishes the removal at a stale sequence → 409, then
  2. merges against a stale baseChildren (modifiedAt = t1) vs remote (modifiedAt = t2). The merge's edit-beats-delete branch (folder/merge.ts) sees remote.modifiedAt > base.modifiedAt and resurrects the just-deleted file.

The merge is correct given its inputs; the inputs (stale base/sequence) are the defect — so the fix is at the desync, not the merge.

Fix

• packages/sdk/src/client.ts — new reconcileFolderState(ipnsName, children, sequenceNumber): advances an already-tracked folder's children + sequence only when strictly newer (higher IPNS sequence), preserving keys. SDK-routed mutations stay authoritative.
• apps/web/src/lib/sdk-provider.ts — ensureFolderRegistered reconciles the folderTree forward to the store's state instead of no-opping when already registered.

With current state, the delete publishes at the correct sequence → no 409, no merge, file removed. Degrades safely: if the background replace-publish fails, the delete sequence still matches remote and no conflict arises.

Tests

• packages/sdk/src/__tests__/client-extended.test.ts — 4 unit tests for reconcileFolderState (adopts-newer, ignores equal/older, no-op-when-absent, copies-array). Full file: 30/30 pass.
• Web tsc --noEmit clean; ESLint clean on all changed files.

Validation

A web-e2e run is dispatched against this branch — since TC08 fails deterministically on the base commit, a green run is a definitive confirmation.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved folder state synchronization to prevent conflicts during updates.

• Tests

  • Added comprehensive test coverage for folder state reconciliation logic.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d630f5d6-f6a2-49c0-97c4-9e49f38ab9e7

📥 Commits

Reviewing files that changed from the base of the PR and between 1abceb4 and 567b6e0.

📒 Files selected for processing (3)

• apps/web/src/lib/sdk-provider.ts
• packages/sdk/src/__tests__/client-extended.test.ts
• packages/sdk/src/client.ts

---

Walkthrough

Adds CipherBoxClient.reconcileFolderState(ipnsName, children, sequenceNumber) to the SDK, which updates a tracked folder's children and sequence number only when the incoming IPNS sequence is strictly higher. Updates ensureFolderRegistered in the web SDK provider to call this method instead of returning early when the folder is already registered.

Changes

Folder State Reconciliation

Layer / File(s)	Summary
reconcileFolderState implementation and tests packages/sdk/src/client.ts, packages/sdk/src/__tests__/client-extended.test.ts	New public method on CipherBoxClient conditionally replaces children, sequenceNumber, and lastLoadedAt for a tracked folder when the incoming sequence is strictly greater; no-ops otherwise. Tests cover newer-sequence adoption with key preservation, equal/older rejection, unregistered-folder no-op, and defensive array copying.
ensureFolderRegistered reconciliation wiring apps/web/src/lib/sdk-provider.ts	The early-return branch in ensureFolderRegistered (triggered when client.hasFolder(ipnsName) is true) is replaced with a call to client.reconcileFolderState, forwarding the Zustand-observed children and sequenceNumber into the SDK before any subsequent mutation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

release:web:fix, release:sdk:fix

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a reconciliation mechanism to prevent deleted-file resurrection by syncing SDK folderTree sequence state.
Linked Issues check	✅ Passed	The PR implements the folder state management infrastructure required by issue #39, specifically ensuring the folderTree synchronization functions correctly during concurrent file operations.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the folder state desynchronization issue described in the objectives; no out-of-scope modifications are present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/folder-tree-desync-resurrects-deleted-file

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Release Preview

Package	Bump	Label	Source
sdk	patch	release:sdk:fix	Direct (fix commit)
web	minor	release:web:fix	Direct (fix commit)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.88%. Comparing base (1abceb4) to head (567b6e0).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #489      +/-   ##
==========================================
+ Coverage   62.82%   62.88%   +0.06%     
==========================================
  Files         139      139              
  Lines       10350    10359       +9     
  Branches     1123     1127       +4     
==========================================
+ Hits         6502     6514      +12     
+ Misses       3612     3609       -3     
  Partials      236      236              

Flag	Coverage Δ
api	84.78% <100.00%> (+0.07%)	⬆️
api-client	84.78% <100.00%> (+0.07%)	⬆️
core	84.78% <100.00%> (+0.07%)	⬆️
crypto	84.78% <100.00%> (+0.07%)	⬆️
sdk	84.78% <100.00%> (+0.07%)	⬆️
sdk-core	84.78% <100.00%> (+0.07%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/sdk/src/client.ts	81.07% <100.00%> (+0.45%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.