[Feature]: extract the Codex history manifest contract into a shared leaf

[Ingwannu]

Area

Codex integration

What are you trying to accomplish?

Give the Codex history backup manifest one pure, shared schema-and-identity boundary that both restore and native-residue inspection consume.

What prevents this today?

The history provenance repair introduced by PR #2424 validates the same on-disk manifest contract independently in two places:

• src/codex/history-provider.ts validates the manifest before restore and mutation.
• src/codex/native-residue.ts repeats the version, database path, entry id, absolute rollout path, provider/source tuple, and hasUserEvent checks before deciding whether the manifest is managed residue.

The copies agree today, but they are already maintained through different constants and path-normalization code. A future source, provider tuple, or manifest version can therefore become restorable while the residue classifier rejects it, or vice versa. That would make the coordinator and restore path disagree about ownership of the same file.

This is also an ownership problem: the manifest format is a data contract, but its parsing rules currently live inside two larger state-transition modules. After #2424, history-provider.ts is approximately 1,569 lines and owns file patching, SQLite CAS, retries, rollout reconstruction, status probes, and manifest parsing together.

What should OpenCodex do?

Extract a small src/codex/history-manifest.ts leaf that owns only:

• the versioned manifest and entry types;
• platform-aware state-database path identity;
• pure validation from unknown data to a parsed manifest or a typed failure reason;
• the allowed provider/source provenance tuples;
• shared invalid-case fixtures or helpers used by both restore and residue tests.

Keep filesystem policy with the callers: regular-file checks, reads, fingerprints, atomic writes, deletion, rollout inspection, SQLite access, retries, and mutation must remain in their existing owners. history-provider.ts should map the shared typed validation result into its strict restore result, while native-residue.ts should map the same result into clean, residue, or indeterminate.

The extraction must preserve the current manifest bytes, accepted and rejected inputs, Windows path behavior, fail-closed restore behavior, and native-residue classification.

Example usage or interface

type HistoryManifestValidation =
  | { ok: true; manifest: CodexHistoryBackupManifest }
  | { ok: false; reason: "schema" | "foreign-database" };

validateCodexHistoryBackupManifest(raw, expectedStateDbPath);

Both current callers should use this result instead of maintaining separate field-by-field checks.

Alternatives or workarounds

Keeping the two validators synchronized through duplicated tests works only while every future format change updates both lists correctly. Importing the entire history provider from the residue classifier would remove textual duplication but would pull mutation, SQLite, retry, and rollout-writing ownership into a read-only startup inspection path.

The smallest durable boundary is a pure leaf module with no filesystem or database side effects.

Additional context

• Source of the duplicated contract: PR fix(codex): preserve routed history provenance on restore #2424.
• src/codex/history-provider.ts: strict restore-time manifest validation and state-database path comparison.
• src/codex/native-residue.ts: read-only manifest residue classification with a second copy of the same contract.
• CodeRabbit also identified the drift risk during fix(codex): preserve routed history provenance on restore #2424 review; it is intentionally a follow-up because the duplication does not invalidate the current provenance bug fix.
• This work must not reopen broad legacy relabeling or change the explicit ocx recover-history --legacy-openai --yes behavior.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.

[Ingwannu]

Implementation is now in PR #2437 at exact head 7e6e515. The extraction keeps manifest bytes and caller policies unchanged, centralizes the version/provenance/path contract, and shares the invalid fixture matrix across strict restore and native-residue tests. Local pinned Bun 1.4.0 verification: 129 caller tests plus 32 job/worker/composed tests passed; typecheck and diff check passed. Keeping this issue open until independent review and landing.

[lidge-jun]

리뷰 · 우선순위 38 / 80

설명: 이 이슈는 코덱스 기록 백업 명세를 복원과 찌꺼기 검사가 각자 검사해서, 나중에 한쪽만 고치면 같은 파일을 다르게 볼 수 있다고 한다. 지금 CURRENT dev HEAD 는 81461aabd 이다. 이번 시간에 origin/dev 는 43b2e26ee 에서 왔다. 새 머지는 2417 그림 별칭, 2424 기록 출처, 2413 사용량 제공자, 2408 관리 본문, 2402 앤트로픽 최소 세기 다섯 개다. package.json 은 2.27.0 이다. src/config.ts 는 3975줄이다. src/runtime 폴더는 지금 HEAD 에 없다. 2424 가 이번 시간에 착지한 바로 그 기록 출처 고침이다. src/codex/history-manifest.ts 는 지금 HEAD 에 없다. 작성자가 적은 약 1569줄은 내가 센 src/codex/history-provider.ts 1604줄과 가깝다.

지금 HEAD 의 src/codex/history-provider.ts 23줄 historyBackupPathFor 는 상태 데이터베이스 경로를 윈도우면 소문자로 맞춘 뒤 해시 앞 16자리로 백업 파일 이름을 만든다. 361줄 readBackupStrict 가 파일을 읽고 버전, 절대 경로, 항목 아이디, 롤아웃 절대 경로, 제공자/출처 짝, 사건 표시를 검사한다. 414줄은 다른 상태 데이터베이스면 외국으로 본다. 출처 짝은 오픈에이아이+cli/vscode 또는 오픈코덱스+exec 만 받는다. 그 복사는 복원이 데이터베이스나 롤아웃을 고치기 전에 쓴다.

같은 HEAD 의 src/codex/native-residue.ts 585줄 historyBackupPath 가 같은 해시를 한 번 더 만든다. 593줄 classifyHistoryBackup 이 버전, 경로, 항목 모양, 출처 짝을 다시 검사한다. 항목이 객체가 아니면 모양을 모른다, 출처가 틀리면 출처 메타가 잘못됐다, 다른 데이터베이스면 다른 상태 데이터베이스라고 적는다. 지금은 두 복사가 같은 답을 준다. 그런데 상수 이름과 경로 맞추기 코드가 파일마다 있다. 나중에 새 출처를 한쪽만 넣으면 복원은 받고 찌꺼기 검사는 거절할 수 있다. 그러면 코디네이터와 복원이 같은 파일의 소유를 다르게 본다.

이건 요청 동작을 바꾸라는 이슈가 아니다. 파일 읽기, 롤아웃 보기, 에스큐라이트, 재시도, 쓰기는 호출 쪽에 남기라고 적혀 있다. 고치는 풀 리퀘스트 2437 이 준비 상태로 올라왔다. 착지 전에는 이 이슈를 닫지 않는다. 2434 가져오기 잎 복사는 다른 길이다. 지금 HEAD 의 fetch-helpers 복사 import 도 그대로다. 2426 코덱스 웹소켓 나가는 크기 가드도 이 이슈만으로 닫지 않는다. 2431 의 빈 에스에스와 410 구멍도 다른 길이다. 2433 은 그 콤보 구멍을 고치는 준비된 풀 리퀘스트인데 이번 시간에 착지하지 않았다. src/server/responses/combo-stream-preflight.ts 는 지금 HEAD 에 없다.

사용자 길이로는 복원과 찌꺼기 검사가 같은 명세를 두 곳에서 들고 있어서, 나중에 어긋나면 같은 파일을 다르게 소유하는 구멍이라서 38. 카탈로그 팁은 Ox Alpha x-preview-f-free + deepseek-v4-flash-vision-exp. Cursor 정적 카탈로그는 opus-4-8-fast / opus-5-fast. 2334 CursorCredentialRouter 는 여전히 src/providers/cursor-pool.ts 모듈+테스트만 있고 어댑터에 연결되지 않았다. 2332 H2 는 discovery 전용. 2320 overflow + 2342 는 이미 dev. 2188 사이드카는 이미 dev. 2382 데스크톱 앱 재시작은 이미 dev. 2292 는 아직 연다.

src/codex/history-provider.ts 라인 23 - 백업 파일 이름을 이 파일이 자체 해시로 만든다
src/codex/history-provider.ts 라인 361 - 복원 전 명세 검사가 여기 있다. 외국과 스키마를 이 함수가 나눈다
src/codex/history-provider.ts 라인 414 - 다른 상태 데이터베이스면 외국이다. 경로 맞추기도 이 파일 안에 있다
src/codex/native-residue.ts 라인 585 - 같은 해시를 한 번 더 만든다. 상수 이름이 다르다
src/codex/native-residue.ts 라인 593 - 찌꺼기 검사가 같은 계약을 복사한다. 모양과 출처 글을 따로 남긴다
src/codex/history-manifest.ts - 지금 HEAD 에 없다. 공유 잎이 아직 없다
PR 2437 - 고치는 준비된 풀 리퀘스트다. 착지 전에는 이 이슈를 닫지 않는다

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

• 2437 이 착지하면 이 이슈를 그 PR 로 닫을지. 지금은 열어 두는 편이 맞다
• 공유 잎이 파일 읽기나 에스큐라이트를 가져가면 안 된다. 호출 쪽 소유를 유지할 것
• 2426 웹소켓 크기 가드와 2431 콤보 구멍을 이 잎 정리에 섞지 말 것. 길이 다르다
• 2424 착지를 이 이슈만으로 되돌리지 말 것. 출처 고침은 이미 dev 다

너의 추천
이슈는 열어 둔다. 2437 이 착지하면 그 PR 로 닫는다. 명세 바이트와 복원 동작은 그대로 둔다. 복사한 검증만 한 잎으로 모은다. 2426 과 2431 과 2434 와 2210 은 닫지 않는다. 호출 길을 넓히지 말 것. 라벨은 그대로 둔다. 프리뷰 배포가 아니다.

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

[Ingwannu]

Final exact-head CI completed successfully for PR #2437 at f177483 after the last rebase onto dev@bf8bcfd3c.

All Linux shards, macOS, storage/API/gates, keyring, npm-global, hygiene, target, CodeRabbit, and aggregate CI checks passed or were intentionally skipped. Local pinned Bun 1.4.0 verification remains 161 passed / 0 failed, with typecheck and diff check passing.

The issue remains open and the PR remains unmerged until independent maintainer approval.

[lidge-jun]

Closed by #2437, squash-merged to dev as 8147425.

The manifest types, provenance validation, path identity, and backup IDs now live in a pure builtin-only leaf, and both callers keep their filesystem, SQLite, mutation, and diagnostic responsibilities. Independent review found no dropped export, no import cycle, and no change to the core/Lab boundary; tests/codex-history-provider.test.ts, tests/codex-native-residue.test.ts, and tests/core-lab-boundary.test.ts ran 142 pass / 0 fail.

Closing by hand because PRs here target dev, so GitHub does not auto-close.

[lidge-jun]

Landed via #2437 at 8147425