fix(integrations): reconcile journal deletion cleanup (carry of #3484)

[lidge-jun]

Summary

A successful journal prune left the stale failure marker in place (src/server/management/integration-routes.ts:379, where two sibling call sites already pair the clear), and the GUI did not reconcile a 404 on delete. This carry pairs the clear with the prune and lets the integrations pages reconcile a 404. GUI change is limited to state reconciliation on the existing integrations pages (original PR labelled gui-screenshot-waived).

Supersedes #3484 (maintainer carry: GitHub reports the original CONFLICTING after the tests/<domain>/ migration, while git merge-tree is clean; the carry is the PR head merged with origin/dev, no source edits).

Stack (wp1 merge train, independent layers — each targets dev):

#	PR	Layer	Review focus
1	this	carry of #3484	this PR's diff only

Unit: devlog/_plan/260905_open_work_closeout/ (010, 011).

Verification

• bun run typecheck — exit 0 on the carry head.
• bun test tests/server/management-integration-journal-delete.test.ts — tests/server/management-integration-journal-delete.test.ts — 13 pass / 0 fail.
• Original PR CI on 3484's exact head was full-matrix green; exact-head CI on this branch is the merge gate.

Checklist

• Targets dev
• Focused regression test present and green
• Original author credited via Co-authored-by trailer

Co-authored-by: Ingwannu 186453546+Ingwannu@users.noreply.github.com

Summary by CodeRabbit

• New Features

  • Added Management API documentation for listing and retiring client integration rollback journal entries, including validation, conflict handling, snapshot cleanup, and protected latest operations.
  • Documented rollback journal behavior across supported languages.

• Bug Fixes

  • Deleting an entry already removed elsewhere now closes the confirmation dialog and refreshes history without showing an unnecessary error.
  • Successful snapshot cleanup now clears previously recorded cleanup-failure status.

• Tests

  • Added coverage for concurrent journal deletion and cleanup-status recovery.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: bb707506-804f-4d9c-8044-7b1f2f5bbd36

📥 Commits

Reviewing files that changed from the base of the PR and between 980a9fb and d30b3c4.

📒 Files selected for processing (14)

• docs-site/src/content/docs/fr/reference/management-api.md
• docs-site/src/content/docs/ja/reference/management-api.md
• docs-site/src/content/docs/ko/reference/management-api.md
• docs-site/src/content/docs/reference/management-api.md
• docs-site/src/content/docs/ru/reference/management-api.md
• docs-site/src/content/docs/tr/reference/management-api.md
• docs-site/src/content/docs/zh-cn/reference/management-api.md
• docs-site/src/content/docs/zh-tw/reference/management-api.md
• gui/src/pages/integrations/FileIntegrationPage.tsx
• gui/src/pages/integrations/IntegrationsOverview.tsx
• gui/src/pages/integrations/integration-api.ts
• gui/tests/integrations-surfaces.test.tsx
• src/server/management/integration-routes.ts
• tests/server/management-integration-journal-delete.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The change improves client integration journal deletion handling. Successful snapshot pruning clears stale maintenance markers. The GUI reconciles entries deleted by another tab. Management API references document journal listing and deletion behavior in eight languages.

Changes

Client integration journal

Layer / File(s)	Summary
Journal cleanup state src/server/management/integration-routes.ts, tests/server/management-integration-journal-delete.test.ts	At src/server/management/integration-routes.ts:379-380, successful snapshot pruning now calls clearPruneFailure; failed pruning still records a failure. The test at tests/server/management-integration-journal-delete.test.ts:343-353 verifies snapshot removal and marker clearing.
Concurrent deletion reconciliation gui/src/pages/integrations/integration-api.ts, gui/src/pages/integrations/FileIntegrationPage.tsx, gui/src/pages/integrations/IntegrationsOverview.tsx, gui/tests/integrations-surfaces.test.tsx	isMissingJournalEntry recognizes the 404 integration_operation_not_found response at integration-api.ts:178-184. Both surfaces close the dialog and refresh history when another tab removed the entry. Tests at integrations-surfaces.test.tsx:51-117, 456-487, and 558-590 verify the request and refresh behavior.
Journal API documentation docs-site/src/content/docs/reference/management-api.md, docs-site/src/content/docs/*/reference/management-api.md	The references document journal listing and deletion endpoints, deletable, snapshotRemoved, validation and conflict errors, tombstones, deferred cleanup, and protection of each client’s latest operation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to d30b3

Journal deletion now clears stale successful-cleanup failure state and treats an already-deleted journal entry as reconciled across both integration views. The supplied coverage supports the intended behavior, with no remaining merge-blocking risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 6 files. (8 skipped: 8…	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 changes: journal deletion cleanup and reconciliation in integrations. The carry reference is additional but does not make the title unclear.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 6 files. (8 skipped: 8 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/260905-carry-3484

---

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.}

[lidge-jun]

리뷰 · 우선순위 66 / 80

설명

이 PR은 기여자 Ingwannu의 #3484를 현재 dev(HEAD 980a9fbed, Astra/Fast 가격 정렬 #3537 직후) 위에 다시 올린 메인테이너 캐리입니다. GitHub는 원본 #3484를 CONFLICTING으로 보여 주지만, 원인은 tests/<domain>/ 경로 이동 이후의 리포트 노이즈에 가깝고 git merge-tree는 깨끗하다고 본문에 적혀 있습니다. 그래서 소스 수정 없이 origin/dev와 머지한 헤드를 codex/260905-carry-3484로 올렸습니다.

고치는 버그는 두 겹입니다. 첫째, 서버 쪽입니다. 지금 dev의 src/server/management/integration-routes.ts 저널 DELETE 경로에서는 pruneSnapshots가 실패할 때만 markPruneFailure를 부르고, 성공해도 예전에 남은 실패 표시를 지우지 않습니다. 같은 저장소 안 src/integrations/journal.ts와 src/integrations/store.ts의 형제 호출은 이미 성공이면 clearPruneFailure를 같이 부릅니다. 그래서 한 번 정리에 실패한 뒤 다음 삭제로 정리가 성공해도, 관리 화면에 “예전에 청소가 실패했다”는 표시가 계속 남을 수 있습니다. 이 PR은 그 한 줄을 형제 호출과 같은 모양으로 맞춥니다.

둘째, GUI 쪽입니다. 다른 탭이 이미 같은 저널 행을 지운 뒤 이 탭에서 삭제하면 서버가 404와 코드 integration_operation_not_found를 줍니다. 지금은 확인 창이 열린 채로 에러만 보여 주고, 다시 눌러도 같은 404만 반복됩니다. gui/src/pages/integrations/integration-api.ts에 isMissingJournalEntry를 두고, FileIntegrationPage.tsx와 IntegrationsOverview.tsx의 삭제 catch에서 그 경우 창을 닫고 히스토리를 다시 불러오게 합니다. 사용자가 원한 끝 상태(그 행이 없음)는 이미 참이니, 실패가 아니라 화면만 맞추는 쪽이 맞습니다.

문서 8개 로케일 docs-site/.../reference/management-api.md에 GET/DELETE /api/client-integrations/journal 표가 추가되고, 서버 회귀 tests/server/management-integration-journal-delete.test.ts와 GUI gui/tests/integrations-surfaces.test.tsx에 동시 삭제·실패 표시 해제 케이스가 붙었습니다. gui-screenshot-waived 라벨이 이미 있고, 본문 검증은 typecheck + 해당 서버 테스트 13통과라고 합니다. 현재 dev가 최적화하는 Astra 카탈로그/가격 축과는 겹치지 않는 독립 버그픽스라, 머지 트레인에 끼워도 방향이 흐트러지지 않습니다.

라인 379 근처 (src/server/management/integration-routes.ts) - 지금 dev는 실패만 markPruneFailure하고 성공 시 clearPruneFailure가 빠져 있음. 이 PR의 if (pruned.ok) clear / else mark는 journal.ts 형제와 같아서 맞음.
경로 gui/.../integration-api.ts isMissingJournalEntry - 404 + integration_operation_not_found만 고른다. 일반 네트워크 오류까지 “이미 없음”으로 취급하지 않아서 안전하다.
경로 FileIntegrationPage.tsx / IntegrationsOverview.tsx - 404 재조정 후 setDeleting(null) + historyResource.refresh()만 하고 return. 확인 창이 404 재시도 루프에 갇히지 않게 한다.
경로 docs-site/*/reference/management-api.md (8로케일) - 저널 GET/DELETE 계약·툼스톤·최신 op 보호를 문서화. 코드 버그와 함께 가는 설명이라 범위는 크지만 내용 자체는 기계적이다.
경로 tests/server/management-integration-journal-delete.test.ts - 예전 실패 마커가 성공 prune 뒤 사라지는지 단언. 회귀를 잠근다.
심볼 원본 #3484 - GitHub mergeable=CONFLICTING/DIRTY로 열려 있음. 이 캐리가 그 내용을 가져오므로 머지 후 원본은 landed-via로 닫아야 한다.

메인테이너의 판단이 필요한 지점

• 이 캐리(fix(integrations): reconcile journal deletion cleanup (carry of #3484) #3540)를 머지한 뒤 원본 #3484에 Landed via #3540 at <commit> + landed-via-maintainer로 닫을지 (권장: 예).
• GUI 변경이 스크린샷 없이 gui-screenshot-waived만으로 충분한지 (이미 라벨 있음; 상태 재조정만이라 면제가 타당해 보임).
• 같은 시각에 열린 다른 open PR들과의 순서 — 이 패치는 integrations journal 축만 건드리므로 Astra/카탈로그 패치와 병렬 머지해도 충돌 가능성은 낮음.

너의 추천
CI가 이 캐리 헤드에서 초록이면 #3540을 dev에 머지하고, 이어서 #3484를 landed-via 코멘트·라벨로 닫아라. 코드 한 줄 정렬 + GUI 404 재조정 + 테스트가 한 세트라 우선순위 66으로 바로 착지해도 된다. types/config 분할에 무효화될 패치가 아니다.

이 댓글은 grok-bot이 작성했습니다

[lidge-jun]

Maintainer admin merge (ruleset bypass recorded per MAINTAINERS.md): carry of #3484, exact-head CI green on d30b3c4 (28 pass / 2 skipped / 0 fail). GUI change is state reconciliation only; the original carried gui-screenshot-waived. wp1 of the 260905 open-work closeout.