Skip to content

docs(codex-home): say which refusals still compensate after #4531 - #4552

Merged
lidge-jun merged 1 commit into
devfrom
codex/260914-history-preflight-doc-accuracy
Sep 13, 2026
Merged

lidge-jun merged 1 commit into
devfrom
codex/260914-history-preflight-doc-accuracy

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Sep 13, 2026 •

Copy link
Copy Markdown
Owner

Summary

Three accuracy leftovers from #4531, found by re-reading the owned docs and the stub-driven tests against what actually shipped.

  • structure/codex-home.md still said a detected migration "restores all three preimages before returning a structured refusal". That is now direction- and reason-dependent. On apply, history_paginated_requires_native_writer retires the relabel unit and the config/profile/journal write stands, because it is permanent and compensating it is exactly what left every current Codex home with no OpenCodex models. Every other reason on apply still compensates, and restore and removal compensate on all of them, because retiring a provider definition its thread rows still name would orphan them. The section also now records that an already-paginated home cannot yet be uninstalled through the product, and that apply keeps a [model_providers.opencodex] table the home already published.
  • tests/codex-integration/codex-sync-api.test.ts — the unattended-sync test stubbed injectCodexConfig returning success: false with history_paginated_requires_native_writer. The injector no longer produces that combination, so the test guarded an unreachable shape while still passing. It now stubs history_injection_preflight_unavailable, which is still a hard refusal, so the assertion means something again.
  • tests/codex-integration/codex-history-provider.test.ts — one test was named for preserving provider definitions, which is no longer what the apply direction does. It asserts which (providerTableMode, resumeHistory) target sets reach a paginated row; renamed to say that.

No source behaviour changes. src/ is untouched.

Verification

  • bun run typecheck — pass
  • bun run structure:check — pass (structure/ SSOT checks passed)
  • bun run privacy:scan — pass (Privacy scan passed)
  • The local suite was not run per standing maintainer instruction; CI is the gate. The only test edits are one stub value and one test name, both in files CI covers.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Summary by CodeRabbit

  • Documentation

    • Clarified migration compensation behavior for paginated history, including when configuration changes are retained or restored.
    • Documented limitations when uninstalling an external history writer from an already-paginated home.
    • Clarified that provider definitions remain available so existing paginated history continues to resolve correctly.
  • Tests

    • Updated integration coverage and descriptions for paginated-history refusals and unattended synchronization failures.

Three leftovers from scoping the history preflight, found by re-reading the
owned docs against the shipped behaviour.

`codex-home.md` still said a detected migration always restores all three
preimages before refusing. That is now direction- and reason-dependent: on apply
the paginated refusal retires the relabel unit and the write stands, because it
is permanent and compensating it produced a home with no OpenCodex models at
all. Every other reason there still compensates, and restore and removal
compensate on all of them, because retiring a provider definition its thread
rows still name would orphan them.

The unattended-sync test stubbed the injector returning a paginated refusal,
which it can no longer produce, so the test guarded an unreachable shape while
still passing. It now stubs an operational reason, which is still a hard refusal.

One preflight test claimed to assert that provider definitions are preserved;
it asserts which target sets reach a paginated row. Renamed to match.

Co-authored-by: Cursor <cursoragent@cursor.com>
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner September 13, 2026 19:50
@github-actions

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 13, 2026
@coderabbitai

coderabbitai Bot commented Sep 13, 2026 •

Copy link
Copy Markdown
Contributor

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: b57fd5d1-6b92-4890-b96f-24333c915fe9

📥 Commits

Reviewing files that changed from the base of the PR and between 866367a and f954c14.

📒 Files selected for processing (3)
  • structure/codex-home.md
  • tests/codex-integration/codex-history-provider.test.ts
  • tests/codex-integration/codex-sync-api.test.ts

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


📝 Walkthrough

Walkthrough

The change updates Codex-home migration-compensation documentation and aligns two integration test descriptions with current refusal reasons. Test logic and assertions remain unchanged.

Changes

History migration behavior

Layer / File(s) Summary
Refusal semantics and integration coverage
structure/codex-home.md, tests/codex-integration/codex-history-provider.test.ts, tests/codex-integration/codex-sync-api.test.ts
The documentation now describes refusal- and direction-dependent compensation. One test description identifies history_paginated_requires_native_writer for paginated rows. Another test uses history_injection_preflight_unavailable while preserving its existing assertions.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to f954c

This documentation and test-alignment change introduces no established production behavior risk and is ready to merge.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly identifies the main change: documentation of which migration refusals still receive compensation in codex-home. It is concise and specific, and the reference to #4531 provides re…
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
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.
✨ 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 codex/260914-history-preflight-doc-accuracy

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

Comment @coderabbitai help to get the list of available commands.

@lidge-jun

Copy link
Copy Markdown
Owner Author

리뷰 · 우선순위 66 / 80

이 PR은 바로 전에 머지된 #4531의 문서·테스트 정확도 뒤처리입니다. #4531이 한 일은 이렇습니다. 지금 Codex home이 페이지네이션된 history를 쓰면, 예전에는 history_paginated_requires_native_writer 거절이 설정 쓰기 전체를 막아 버렸습니다. 그래서 model_catalog_json이 config.toml에 안 들어가고, 선택기는 내장 모델만 보였습니다. #4531은 그 거절을 apply 방향에서 대화 히스토리 relabel 유닛만 접고, config/profile/journal 쓰기는 남기도록 바꿨습니다. 그런데 structure/codex-home.md는 아직도 “감지된 migration이면 거절 전에 preimage 세 개를 전부 되돌린다”고 적혀 있었고, 테스트 한 개는 inject가 더 이상 만들지 않는 (success: false + history_paginated_requires_native_writer) 조합을 stub해서, 통과해도 의미가 없는 모양이 되었습니다.

지금 dev HEAD는 866367a6f이고 package.json은 2.55.0입니다. 방금 #4551로 버전 라인을 열어 둔 상태이고, #4531의 계약은 이미 src/codex/inject.ts에 들어가 있습니다. HISTORY_RELABEL_STANDS_DOWN은 history_paginated_requires_native_writer 하나뿐입니다. apply에서 이 이유만 나오면 observeHistoryRefusalOrThrow가 throw하지 않아서 compensation이 돌지 않고 쓰기가 남습니다. 다른 이유(상태 DB를 못 읽음, rollout 정체성 변경, preflight 자체가 실패)는 여전히 CodexHistoryPreflightRefusal로 hard refuse이고, catch에서 restoreCodexPreImages가 세 preimage를 되돌립니다. restore/remove 쪽 restoreCodexConfigInlineImpl은 history preflight 거절이면 여전히 failed로 돌아가고 compensation이 돕니다. 그래서 “이미 페이지네이션된 home은 제품으로 uninstall이 아직 안 된다”는 문장은 현재 코드와 맞습니다. apply가 [model_providers.opencodex] 테이블을 남기는 이유도 inject.ts 주석과 같습니다. 이미 opencodex로 태그된 thread가 provider id를 잃어버리지 않게 하려는 겁니다.

이 PR의 diff는 src/를 건드리지 않습니다. structure/codex-home.md 두 단락을 위 계약에 맞게 고치고, tests/codex-integration/codex-sync-api.test.ts의 unattended-sync stub을 history_injection_preflight_unavailable로 바꾸며, codex-history-provider.test.ts의 테스트 이름만 “provider 정의를 지킨다”가 아니라 “페이지네이션 row에 닿는 target set마다 paginated refusal을 보고한다”로 고칩니다. structure SSOT와 테스트가 실제 동작을 따라가게 하는 정리라서, 기능 버그 수정은 아니지만 #4531 직후엔 꼭 필요합니다. 잘못된 문서가 남으면 운영자가 “거절이면 항상 롤백된다”고 믿게 되고, 페이지네이션 home에서 모델이 사라진 사고의 반대편(보상하면 모델이 없다)을 다시 헷갈리게 합니다.

점수 66인 이유입니다. #4531(77)만큼 급한 사고 수정은 아니고, types.ts/config.ts 분할과도 무관합니다. 다만 structure는 이 저장소의 SSOT이고, stub이 닿을 수 없는 모양을 지키면 CI가 초록이어도 회귀를 못 잡습니다. 그래서 “문서만”이라 닫지 말고, tip CI 초록이면 바로 머지하는 편이 맞습니다. 지금 checks는 hygiene/label/changes/keyring 등은 이미 통과했고, gates·test shards·macos·CodeRabbit은 아직 pending입니다.

라인 250 근처 (structure/codex-home.md) - 옛 문장 “Detected migration restores all three preimages before returning a structured refusal”을 지우고, apply에서 paginated 거절만 쓰기를 남기고 다른 이유·restore/removal은 보상한다는 쪽으로 고쳤다. src/codex/inject.ts의 HISTORY_RELABEL_STANDS_DOWN / observeHistoryRefusalOrThrow / restoreCodexConfigInlineImpl과 맞다. 문제는 없다.
라인 (structure/codex-home.md, 이어지는 단락) - “already-paginated home cannot yet be uninstalled through the product”와 apply가 이미 공개된 [model_providers.opencodex] 테이블을 유지한다는 서술이 추가됐다. remove/restore가 paginated preflight에서 여전히 failed+보상인 현재 코드와 일치한다. 다만 uninstall 한계는 follow-up 이슈로 열려 있지 않으면 나중에 잊히기 쉽다.
라인 (codex-sync-api.test.ts, unattended sync) - stub을 history_paginated_requires_native_writer에서 history_injection_preflight_unavailable로 바꿨다. apply는 이제 paginated 이유로 success: false를 만들지 않으므로, 옛 stub은 도달 불가능한 모양이면서도 테스트가 통과했다. 새 stub은 historyPreflight() catch 경로의 실제 hard refuse 이유라서 주장이 다시 의미가 있다.
라인 (codex-history-provider.test.ts, 테스트 이름) - “preserves provider definitions” → “reports the paginated refusal for every target set that reaches a paginated row”. assert 내용은 그대로고 이름만 계약에 맞게 고쳤다. 동작 변경은 없다.
경로/심볼 - src/ 미변경 주장 - diff가 structure + 테스트 두 파일뿐이라 맞다. types/config 분할 캠페인에 무효화되지 않으니 close-don't-rebase 대상이 아니다.
경로/심볼 - tip CI - 로컬 suite는 의도적으로 안 돌렸고 CI가 게이트다. test/macos/gates가 아직 pending이므로 초록 확인 후 머지하면 된다.

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

  • tip Cross-platform CI(test/macos/gates) 초록이면 바로 merge할지 (권장: 예)
  • “paginated home uninstall 불가”를 별도 follow-up 이슈로 열어 둘지, structure 문장만으로 남길지
  • fix(codex): scope the history preflight to the relabel unit #4531 직후 문서·테스트 드리프트를 같은 릴리즈(2.54.0) 노트에 한 줄로 넣을지

너의 추천
CI 초록 확인 후 바로 merge하세요. src/ 변경 없는 SSOT·테스트 정확도 수정이고, #4531 계약을 문서/가드가 따라잡는 일입니다. uninstall 한계는 이 PR에 억지로 넣지 말고, 필요하면 짧은 follow-up 이슈만 여세요.

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

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-13T19:52:59.534481Z f954c14 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@lidge-jun
lidge-jun merged commit ab3bc19 into dev Sep 13, 2026
29 checks passed
@lidge-jun
lidge-jun deleted the codex/260914-history-preflight-doc-accuracy branch September 13, 2026 20:01
agentHits pushed a commit to agentHits/opencodex that referenced this pull request Sep 17, 2026
…#4531 (lidge-jun#4552)

Three leftovers from scoping the history preflight, found by re-reading the
owned docs against the shipped behaviour.

`codex-home.md` still said a detected migration always restores all three
preimages before refusing. That is now direction- and reason-dependent: on apply
the paginated refusal retires the relabel unit and the write stands, because it
is permanent and compensating it produced a home with no OpenCodex models at
all. Every other reason there still compensates, and restore and removal
compensate on all of them, because retiring a provider definition its thread
rows still name would orphan them.

The unattended-sync test stubbed the injector returning a paginated refusal,
which it can no longer produce, so the test guarded an unreachable shape while
still passing. It now stubs an operational reason, which is still a hard refusal.

One preflight test claimed to assert that provider definitions are preserved;
it asserts which target sets reach a paginated row. Renamed to match.

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant