fix: preserve offline synchronization invariants - #53
Conversation
✅ Deploy Preview for rdlabo-ionic-angular-library ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
|
|
||
| #beginFlush(explicitFull: boolean): Promise<void> { | ||
| const isPartial = !explicitFull && this.#foregroundScopePolicy !== null; | ||
| const isPartial = !explicitFull && !this.#coldReconciliationRequired && this.#foregroundScopePolicy !== null; |
There was a problem hiding this comment.
🟡 起動直後に必須の全体同期が行われず、明示的な全体同期要求も部分同期で置き換えられる
起動直後に全体同期が必要な状態でも、実際の同期処理（#runFlush の isPartial 判定 projects/kit/offline/src/lib/offline-sync.service.ts:622）はその必要性を見ずに前面スコープだけを取得したうえで必要フラグを消すため、取り残された更新の取り込みが永久に行われません。
Impact: 前回終了時に取り込めなかったサーバー側の変更が復元されず、画面に古いデータが残り続けることがあります。
#beginFlush と #runFlush で isPartial の判定条件が食い違う仕組み
#coldReconciliationRequired は repository が getReconciliationScopes を実装していない場合に true になり（projects/kit/offline/src/lib/offline-sync.service.ts:142）、#beginFlush ではこの値を見て isPartial=false（＝全体flush扱い）と記録します（projects/kit/offline/src/lib/offline-sync.service.ts:577）。しかし実処理の #runFlush では const isPartial = !explicitFull && this.#foregroundScopePolicy !== null; としか判定しないため（projects/kit/offline/src/lib/offline-sync.service.ts:622）、実際には部分pullしか行われません。さらに末尾で this.#coldReconciliationRequired = false; が実行されるので（projects/kit/offline/src/lib/offline-sync.service.ts:676）、以後も全体pullは発生しません。
加えて #partialFlushInFlight が false のまま記録されるため、その最中に呼ばれた明示的な flush()（全体）は実行中の部分flushのPromiseをそのまま返し（projects/kit/offline/src/lib/offline-sync.service.ts:578-599）、全体pullへチェーンされません。
Prompt for agents
#coldReconciliationRequired は「durableな再同期マーカーを復元できないrepositoryでは最低1回は全スコープpullが必要」を表す意図のフラグですが、実際にpull対象を決める #runFlush の isPartial 判定にはこのフラグが含まれていません。その結果、フラグが true でも部分pullが行われ、その直後にフラグがクリアされます。また #beginFlush 側だけがフラグを見ているため #partialFlushInFlight が実態(部分)と食い違い、実行中に呼ばれた明示的な全体 flush() が部分flushの完了で満たされてしまいます。#runFlush 側の判定にも同じ条件を反映し、フラグのクリアは実際に全体pullを完了した場合のみ行うよう整合させてください。
Was this helpful? React with 👍 or 👎 to provide feedback.
| #assertDiscardable(commands: readonly OfflineCommand[]): void { | ||
| const ambiguous = commands.filter((command) => command.state === 'sending' || command.serverCommitUnknown === true); | ||
| if (ambiguous.length > 0) { | ||
| throw new OfflineCommandInFlightError(ambiguous.map((command) => command.commandId)); | ||
| } | ||
| } |
There was a problem hiding this comment.
🟡 同期結果が不明なコマンドがあるとログアウト時の「破棄」操作が例外で失敗する
ログアウト時の破棄処理は、サーバー結果が不明なコマンドがあると例外を投げるようになった破棄APIを（#assertDiscardable at projects/kit/offline/src/lib/offline-sync.service.ts:561-566）例外処理なしで呼び続けるため、ログアウト操作自体がエラーで中断します。
Impact: 送信結果が確定していない変更が1件でも残っていると、ユーザーは「破棄してログアウト」を選んでもエラーになり操作が完了しません。
呼び出し側が新しい例外を扱っていない
OfflineCoordinatorService.prepareLogout は action === 'discard' のとき await this.#sync.discardAllPending(); return true; としており（projects/kit/offline/src/lib/offline-coordinator.service.ts:90-98）、false を返して「ログアウトできない」ことを伝える経路はあるものの、新設の OfflineCommandInFlightError（projects/kit/offline/src/lib/offline-sync.service.ts:100-106）は捕捉されずそのまま呼び出し元へ伝播します。また discardAllPending は1件でも曖昧なコマンドがあると全件の破棄を拒否するため、他の破棄可能なコマンドも削除されません。
Prompt for agents
discard()/discardAllPending() が新たに OfflineCommandInFlightError を投げるようになりましたが、リポジトリ内唯一の利用者である OfflineCoordinatorService.prepareLogout('discard') はこの例外を扱っておらず、boolean を返す契約が破れます。prepareLogout 側で例外を捕捉して false を返す（あるいは曖昧なコマンドの存在を呼び出し元へ伝える）等、ログアウトUIが破綻しない扱いを追加してください。
Was this helpful? React with 👍 or 👎 to provide feedback.
| async #markScopeReconciled(scope: OfflineScope, generation: number): Promise<void> { | ||
| if (!this.#isCurrent(generation)) return; | ||
| await this.#repository.transactReplica({ removeReconciliationScopes: [scope] }); | ||
| if (!this.#isCurrent(generation)) return; | ||
| this.#pendingPullScopes.delete(this.#scopeKey(scope)); | ||
| } |
There was a problem hiding this comment.
🟡 取得処理のたびにローカルデータ全体が無条件で書き戻され、書き込み量が倍増する
スコープ取得のたびに再同期マーカー削除のための永続トランザクションを無条件に実行するため（#markScopeReconciled の呼び出し projects/kit/offline/src/lib/offline-sync.service.ts:630）、マーカーが存在しない通常の取得でもローカル保存データ全体の再書き込みが発生します。
Impact: 同期のたびに端末ストレージへの書き込み量が増え、データ量の多い利用者で同期が遅くなります。
Web実装での書き込みコスト
#markScopeReconciled は対象スコープが #pendingPullScopes に含まれるかを確認せずに repository.transactReplica({ removeReconciliationScopes: [scope] }) を実行します（projects/kit/offline/src/lib/offline-sync.service.ts:1344-1349）。IonicOfflineRepository.#applyReplicaTransaction は変更対象が何であっても ROWS/OUTBOX/CURSORS/RECONCILIATION の4レコードを読み直して全件書き戻し、さらにジャーナルの set/remove も行います（projects/kit/offline/src/lib/offline-repository.ts:628-698）。pull自体でも同様の全件書き込みが起きるため、pullごとの書き込みが実質的に倍になります。#runFlush の事前pullループは既知スコープすべてに対してこれを実行します。
| async #markScopeReconciled(scope: OfflineScope, generation: number): Promise<void> { | |
| if (!this.#isCurrent(generation)) return; | |
| await this.#repository.transactReplica({ removeReconciliationScopes: [scope] }); | |
| if (!this.#isCurrent(generation)) return; | |
| this.#pendingPullScopes.delete(this.#scopeKey(scope)); | |
| } | |
| async #markScopeReconciled(scope: OfflineScope, generation: number): Promise<void> { | |
| if (!this.#isCurrent(generation)) return; | |
| if (!this.#pendingPullScopes.has(this.#scopeKey(scope))) return; | |
| await this.#repository.transactReplica({ removeReconciliationScopes: [scope] }); | |
| if (!this.#isCurrent(generation)) return; | |
| this.#pendingPullScopes.delete(this.#scopeKey(scope)); | |
| } |
Was this helpful? React with 👍 or 👎 to provide feedback.
| return cursor === undefined ? null : { ...scope, cursor }; | ||
| } | ||
|
|
||
| async getReconciliationScopes(userId: OfflinePrincipalId): Promise<OfflineScope[]> { |
There was a problem hiding this comment.
🟡 新規に追加した公開メソッドにJSDocコメントがない
新設した公開メソッド getReconciliationScopes（projects/kit/offline/src/lib/offline-repository.ts:355）にJSDocコメントが付いておらず、AGENTS.mdの「すべての公開クラス・関数・型にJSDocコメントを付ける」という必須ルールに違反しています。
Impact: 公開APIの説明が欠け、リポジトリの記述規約に反した状態で公開されます。
該当箇所
同じ違反が SqliteOfflineRepository.getReconciliationScopes（projects/kit/offline/src/lib/sqlite-offline-repository.ts:325-330）と OfflineRepository インターフェースの getReconciliationScopes?（projects/kit/offline/src/lib/offline-repository.ts:182）にもあります。AGENTS.md「When modifying this repo」3項を参照。
| async getReconciliationScopes(userId: OfflinePrincipalId): Promise<OfflineScope[]> { | |
| /** Returns scopes whose acknowledged server changes still require an authoritative pull. */ | |
| async getReconciliationScopes(userId: OfflinePrincipalId): Promise<OfflineScope[]> { |
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
What
Why
Offline commands could previously lose their required post-ACK pull after restart, race with discard while transport was active, or become permanently stuck after a response-loss attempt was later classified as conflict/rejected. Those paths could leave local history stale or make logout/discard unsafe.
Impact
The Outbox now treats replica state and reconciliation markers as one durable transaction. Commands whose server outcome is unknown cannot be discarded and remain recoverable through an explicit same-key retry. Known pre-transport failures remain discardable.
Root cause
Correctness state was split between durable commands and in-memory transport bookkeeping. Failure classification also replaced, rather than accumulated, uncertainty from earlier attempts.
Checks
npm test -- --project kit(43 files, 695 tests)npx ng lint kitnpx ng build kit --configuration=productiongit diff --check